Challenge of Upgrading Template Apps

This is a general problem of compositional apps or template apps.

Applies both to Flowershow and DMS (where we have template app for e.g. the frontend).

NB: there's both an upgrade problem and a related creation problem.

Upgrade problem: once i've installed my "app" it is very painful to upgrade it - requires manual diffing/copy-pasting. Why? because have made changes for configuration and extension - thus cannot cleanly copy in new stuff.

Creation problem: i have a menu of N different features of which i want some subset M. Either i have to have preconfigured a template with just those M features (which implies $|P(N)|$ templates) or user has to create what they want from examples of each of N features (current approach of nextjs).

Problem illustrated

challenge-of-upgrading-template-app-2022-05-09.excalidraw

Examples of it happening elsewhere

timlrx/nextjs-starter-blog

See this issue happening for nextjs-starter blog: https://github.com/timlrx/tailwind-nextjs-starter-blog/issues/454

See also author's comment about new version: https://github.com/timlrx/tailwind-nextjs-starter-blog/issues/486

They are solving it using https://github.com/timlrx/pliny

Svelte-add

Same problem arises for svelte-kit. There is a project addressing this: https://github.com/svelte-add/svelte-add - though almost entirely focused on creation not upgrading (and creation is also limited to creation at the start).

As they eloquently explain:

This is a community project to easily add integrations and other functionality to Svelte apps. Its goal is to solve the problems with downloading templates to start your app from:

You have to want all the functionality a template includes—no more, no less.

svelte-add has app initializers that let you select the exact integrations wanted: npm init @svelte-add/kit@latest

You have to fall back on following a third party tutorial that could be outdated or take a lot of work to add things missing from that template.

svelte-add's "tutorials" are one step: npx --yes svelte-add@latest graphql-server

You have to rely on the maintainer keeping the template updated as the tools it uses change and the official Svelte app template it was built on changes.

svelte-add's app initializers are always built on top of the latest version of the official Svelte app templates. Of course it still needs to be maintained as tools change (like Tailwind JIT or the future rewrite of mdsvex), but because it is in a central location and contributed to by many people, problems are found quickly, and fixes are for everyone—not just one specific template.

How to solve

What's the source of the problem?

In short: coupling. Different features both involve code in same files (in e.g. nextjs) so installing means overlap which makes automated installation and upgrade hard.

3 things involved here:

Content / Data
Core app (cms)
Extra functionality

Classically we solve by separating these three.

Content and data => database with clean API
App => under control of original author and can be upgraded by install new version
- Do content / data upgrades automatically
Extra functionality: via plugins etc

NTS

Issue in nextjs is you often have to do something in _app.js to to get the result you need. This isn't upgradeable / scalable (things start to interfere). Easiest way to solve would be some kind of plugin hook around key activities there.
Otherwise, in theory, one could go a component route ?? (so install a lib)

How to solve

May not be fully solvable but can be made a lot better.

Cleanly separate content and data => walk back from putting your content in pages directory if at all possible
- TODO: no way round this for js content. But all markdown and other content should be outside of pages. Plus mark core CMS-related js pages as "untouchable"
- this also suggests for content heavy projects that the the cms part is hidden in subdirectory
Make everything components and libraries that you can
API-ify / plugin-ify key connection points e.g. the config file and make it upgradeable

You can also go radical and just make stuff much less tweakable - which may mean bloating the core app but so be it.

Advantage of this route is stuff "just works". Downside is it really doesn't scale in features - so either features need to be able to stay pretty reasonably limited => a relatively fixed product usecase.