Upgrading the app-platform to support multiple react versions

[Mohammer5]

This is still a draft! I want to write down what I have in my head before discussing this on Tuesday with @varl and @amcgee

Terminology:

• App
  • In single-react-version environment: The contents of the src directory,
    with an entry point, specified in the d2.config.js
  • In multi-react-versions environment: Every folder inside src that has
    its own package.json
• Container
  • In single-react-version environment: The app-shell in .d2/shell; Has a
    dependecy to react & react-dom
  • In multi-react-versions environment: Probably another variant of
    app-shell; Must not have react/react-dom dependencies
• modern app
  • Only in multi-react-versions environment: The app with the latest react
    version (the one that calls reactDOM.render(..))

How does the multi-version approach work in general

• The <root>/package.json does not have any react/react-dom dependencies
  (version would be ambiguous)
• The individual react versions have to be defined in
  <root>/src/*/package.json (or deeper, but I assume that we should consider
  that bad practice)
• The <root>/src/index.js imports the index.js of the latest react version,
  e. g. import './modern/index.js'. It doesn't have to do anything else
• The index.js of the latest react version calls reactDOM.render(...)
• The legacy react version apps must provide a function that helps to lazy load
  the component and bridge contexts
• The modern app lazy-loads the legacy react versions, has to use a custom lazy
  loading helper that provides the context values to the functions provided by
  the legacy apps

Current issues with our setup

• We don't support package.jsons in the src folder

Possibilities I've discovered so far

What needs to be figured out:

• Do we want to support more than two versions? Or do we want to consider that
  bad practice and allowing it might result in projects more
  complicated/complex than we want to
• How do we want people to use this approach?
  • There is the approach we want to use in the maintenance app: Replace
    section by section
  • Another way to use this, is to import only specific components from
    legacy apps; React recommends to try to narrow down the required code for
    older react-versions as it's generally discourages to have multiple
    versions
• How to initialize contexts (Contexts can't be created in the container, as
  the react version would be ambiguous)
• How to create the lazyLegacyRoot & createLegacyApp helpers
  • These are important for forwarding the contexts. If an app has
    additional, custom contexts, these must be forwarded as well, so this
    can't be generic
• How to call reactDOM.render as that needs to be done in the app with the
  latest react version

Possiblility 1 - The app-platform can differentiate between single- and multi-version projects

For multi-version, the app-platform must:

• recognize package.json files in the individual apps
• cd into the app directories and run yarn install
• copy src/shared into the individual app directories
• watch the src/shared directory to replace previous copies on change

How to detect single/multi version project:

• Scan project for src/*/package.json
  • If found => multi version
  • If not found => single version

Possibility 2 - The app-shell already has the setup for multiple versions and has the app with react@17

• If the actual app has no src/*/package.json, then the src folder can be
  copied into the app-shell
• If an older version exists
  • it must have its own package.json
  • the package.json of the main package does not contain a react dependency;
    The package.json will be merged into the default package.json of the
    app-shell

Possibility 3 - We turn app-shell into a library with a single component and clone create-react-app

EDIT: We turn app-shell into a library - This is already done by the app-adapter, there's not much we have to change there

In this approach, instead of having our own app-platform, we reduce the
complexity of the app-platform by getting rid of it, the build steps, etc.
Instead of using a d2.config.js, we use d2.config.json. CRA supports
importing .json files, no need to alter the webpack/build configuration.

d2 app scripts init becomes an alias for create-react-app [...args] --scripts-version @dhis2/create-react-app

The env vars set in the build script could be moved to .env.production,
.env.development and could be overwritten with .env.production.local or
.env.development.local (which should be git-ignored). Others could be moved
to the @dhis2/app-shell component, i. e. the component could read the
standalone config from the env vars, which would allow us to move
setAppParameters to the app-shell component.

Why consider this approach?

• First of all, we will have to put in some work into making multiple versions
  work. Right now I can't tell what would be more work: Extending our setup in
  a way that deviates from CRA, possibly causing us to deviate more and more
  from CRA over time, which might bite us in the future. There's a possibility
  that cloning CRA requires less work, reduces complexity and could allow us to
  delete code that we wouldn't have to support anymore. IMO at least worth
  investigating this option.
• Drop some of the commands in @dhis2/cli-app-scripts
  • No custom test script that has some discrepencies with CRA's test script
  • Depending on the setup, we might be able to drop build and start
    (leaving us with a command for generating i18n files)
• Leverage on react-scripts standard behavior.
  • When facebook changes the library, we need to rebase and handle merge
    conflicts
  • But we don't have to implement anything that's already been implemented
    or will be implemented in the future (e. g. multiple react versions)
• Supports all kinds of additions, e. g. SSR (with next.js)
• The @dhis2/app-shell could be used in the src/App.js or
  src/modern/App.js
• Supports all variations of multiple react versions (side by side apps,
  individual legacy components)

[ismay]

Interesting. Option 3 sounds like an interesting one to explore a little further to me. Moving towards instead of away from the standard (i.e. react-scripts) always seems like the more appealing option to me in general.

[amcgee]

@ismay if you want to explore why option 3 doesn't work for us, let's set up a separate call :-)

[ismay]

No worries, if it doesn't work for us that's all right by me 👍

[amcgee]

Thanks @Mohammer5 !

I don't think we can consider option 3 as described, since it breaks the whole purpose of app platform abstraction, would require all current platform apps to revert to CRA apps, and would block us from implementing some critical roadmap features like (1) global shell, (2) dynamic modules, (3) standardized routing, (4) granular per-app permissions, and (5) out-of-the-box SSR and SSG.

Similarly, we should avoid package.json and node_modules within the src directory... this should be possible with workspaces, as @varl has suggested, each with its own copy of React

I think there is probably a variant on 2 which would be ideal here - the shell should be either a thin bootstrap script and HTML (a la single-spa's root config) with a React micro-frontend each for app and for headerbar/login modal/etc or (probably easier initially without dynamic modules) the shell should initialize a modern React 17+ root and provide that to the app. The app could optionally create sub-roots (using single-spa Parcel-like render delegation) which make use of different React versions. For example:

• Shell (React 17)
  • App (React 17 peer dependency)
    • LegacyApp (React 15)

The shell could be exactly as it is now but with ReactDOM.createRoot. The file structure of the app would be the following:

• Workspace Root (React 17 dependency)
  • App (React 17 peer dependency) type: "app"
  • LegacyApp (React 15) type: "lib"

Within the LegacyApp, which has a React 15 dependency and its own node_modules, the entrypoint could expose an API similar to single-spa parcels with mount and unmount functions which call the proper ReactDOM 15 lifecycle methods.

[amcgee]

@Mohammer5 I made a quick example of the multi-react workspace / multiple package approach here - multi-react-app, legacy-react-lib

Not tested (ran into an unrelated yarn issue and didn't have a chance to debug) but that's the general idea. There are certainly drawbacks to building a lib rather than an app (i.e. .css doesn't work out-of-the-box) but I think it's preferable to breaking apart the existing app-platform patterns we've established.

In the glorious future apps (and components) should be self-contained with the ability to share compatible-version dependencies (this is the dynamic modules approach, see dhis2/app-platform#529) so that apps or parts of apps could even use vue or angular.

[varl]

Meeting notes, 2021-09-21

• Ignore nested node_modules in src folders, then we may be able to use the "standard" approach.
• Dynamic modules (App Platform) could be used to run multiple React versions.
• Spend more time on the Workspace approach, getting additional brain power on it.
• @Mohammer5 will share the workspace he's working on and get some input on that.

Follow-ups

• Consistent DX "on the inside" that should align with expectations of a React developer.