refactor: [DHIS2-18801] upgrade capture app to use vite and react 18 #4375

simonadomnisoru · 2025-09-10T08:37:09Z

DHIS2-18801

This pull request migrates the project from Create React App to Vite, following the official migration guide

Key changes introduced during the migration:

Upgrade @dhis2/cli-app-scripts, @dhis2/ui and @dhis2/app-runtime
Remove environment variables deprecated prefix
Replace deprecated ReactDOM.render with createRoot (e.g. DeleteControl.component.tsx)
Use static imports for the date-fns locale
Replace Material-UI with Emotion:

Added custom withStyles and withTheme HOCs that replicate the logic of Material-UI’s ones. The HOCs implementation takes a pragmatic approach, with the goal of removing Material-UI and migrating to Emotion as smoothly as possible.
Introduced a new theme object (leverage the theme object already done in Replace the HOCs #3811)
Removed the classnames library and replaced it with Emotion’s cx helper.
The following functionality was tested to confirm compatibility with Emotion:
- Using className={class.name} on both plain HTML elements and UI library components
- Styles imported from our own *.module.css files or external css files (e.g. leaflet, virtualized-select, etc.)
- Classes passed down from the parent component (e.g. IconButton.component.tsx)
- Combining multiple class names (e.g. IndicatorsSection.component.tsx)
- Applying conditional class names (e.g. BreadcrumbItem.tsx)

Removed the leaflet CDN dependency and imported the styles (chore: Remove leaflet CDN dependencies #4001)
Vite/Rollup handle module resolution differently from Create React App/Webpack. Using both alias and relative imports can cause the same module to be included multiple times in the bundle, leading to issues with async code and shared state (e.g 8443af9). This is the intended Rollup behavior. To address this issue, I ensured consistent use of absolute imports and add an ESlint rule to enforce this convention in 16580d3.
Upgraded react-query to v4, the first version compatible with React 18. One notable change affecting Capture app is the useage of isInitialLoading for disabled queries.
In dev mode, the app is slower to completely load the first time. This is expected due to Vite’s architecture as files aren’t pre-bundled to enable fast startup and Hot Module Replacement. The HMR allows for instant updates without a full reload, but it results in a longer initial load, as the browser requests many small modules. I’ve added some scripts to serve the app in prod mode locally (yarn build:standalone and yarn serve), useful for running Cypress tests or inspecting the production bundle.

…ined

…nent & use it in NoSelectionsInfoBox

github-actions · 2025-09-17T13:54:19Z

🚀 Deployed on https://deploy-preview-4375.capture.netlify.dhis2.org

…function

…le to enforce this convention

simonadomnisoru · 2025-11-05T14:07:41Z

Amazing work, @simonadomnisoru! You’ve upgraded the app and migrated it to use Vite really smoothly. I added two comments with some minor points I’m a bit uncertain about.

In addition, I noticed we’re still using some lifecycle methods with the UNSAFE_ prefix, such as UNSAFE_componentWillReceiveProps. It works fine for now, but perhaps this would be a good time to replace those methods to ensure full React 18 compatibility going forward.

@henrikmv Thank you for your review! I’ve now removed and refactored most of the deprecated UNSAFE_ lifecycle methods. Only two remain in FormBuilder.component and OrgUnitTree.component, as their logic is more complex and requires a deeper dive to ensure all edge cases are handled correctly. There is already an open ticket for this DHIS2-16685, and I think it’s safer to address the remaining two components separately under that task.

Let me know if you have any additional feedback. Thanks!

eirikhaugstulen

Hey @simonadomnisoru - really great work on this! 🎉

Left some small comments, mostly NITs, but have a look and let me know if you disagree!

eirikhaugstulen · 2025-11-04T10:59:43Z

scripts/startAppForCypress.js


 const allEnvVariables = {
    ...envFromCypressFiles,
    ...(process.env || {}),


Haven't tried to run this myself, so it might work - but should this be import.meta.env instead?

https://vite.dev/guide/env-and-mode

process.env still works correctly and Cypress runs successfully both locally and in GitHub workflows. Feel free to try it in your local environment as well if you’d like to confirm. Thanks!

src/components/AppLoader/getDateFnLocale.ts

src/core_modules/capture-core-utils/styles/withStyles.tsx

...tries/common/TEIAndEnrollment/useMetadataForRegistrationForm/hooks/useDataEntryFormConfig.ts

src/core_modules/capture-core/components/FormFields/withInternalChangeHandler.tsx

.../components/PossibleDuplicatesDialog/ReviewDialogContents/ReviewDialogContents.component.tsx

eirikhaugstulen · 2025-11-05T14:00:49Z

src/core_modules/capture-core/storageControllers/mainStorageController.ts

@@ -17,7 +17,7 @@ const computeServerCacheVersion = ({ minor, patch, tag }) =>
    computeTagVersionPart(tag);

 const computeAppCacheVersion = () => {
-    const appCacheVersionAsString = process.env.REACT_APP_CACHE_VERSION;
+    const appCacheVersionAsString = process.env.DHIS2_CACHE_VERSION;


Should this be import.meta.env.DHIS2_CACHE_VERSION or is the app-shell doing some magic here?

The app-shell is doing some magic, and according to the migration guide, process.env is well supported and a more widely-used pattern. Refactoring to import.meta.env would require extra effort, as Jest doesn’t support it by default. Therefore, continuing to use process.env seems reasonable to me.

d2.config.js

package.json

eirikhaugstulen

Great work @simonadomnisoru - this is a big improvement!

henrikmv

Brilliant work!

JoakimSM

Looks quite good! Let me spend some more time on this tomorrow, just wanted to give some initial comments.

JoakimSM · 2025-11-10T11:18:04Z

src/core_modules/capture-core-utils/styles/withStyles.tsx

+            const rawStyles = stylesOrCreator && typeof stylesOrCreator === 'function'
+                ? stylesOrCreator(theme as T)
+                : stylesOrCreator;
+
+            // Transform the raw style object with Emotion’s css() so that className={classes.label} continues to work as before
+            const classes = Object.keys(rawStyles).reduce((acc, key) => {
+                acc[key] = css(rawStyles[key] as any);
+                return acc;
+            }, {} as any);


Nice!

Given we have this code in a "centralized" place, maybe we can wrap in useMemo for a minor perf. improvement?

Suggested change

const rawStyles = stylesOrCreator && typeof stylesOrCreator === 'function'

? stylesOrCreator(theme as T)

: stylesOrCreator;

// Transform the raw style object with Emotion’s css() so that className={classes.label} continues to work as before

const classes = Object.keys(rawStyles).reduce((acc, key) => {

acc[key] = css(rawStyles[key] as any);

return acc;

}, {} as any);

const classes = useMemo(() => {

const rawStyles = stylesOrCreator && typeof stylesOrCreator === 'function'

? stylesOrCreator(theme as T)

: stylesOrCreator;

// Transform the raw style object with Emotion’s css() so that className={classes.label} continues to work as before

return Object.keys(rawStyles).reduce((acc, key) => {

acc[key] = css(rawStyles[key] as any);

return acc;

}, {} as any);

}, []);

Great suggestion! I added it, thanks.

JoakimSM · 2025-11-10T12:24:47Z

package.json

    "workspaces": [
        "packages/rules-engine"
    ],
    "dependencies": {


In general, I do think we should explicitly list the dependencies we use directly. if not, the depedency graph becomes ambiguous. Not sure we should make an exception here? I understand we will have to make sure we use the same version as app-runtime, but at least another dep update won't suddenly change the version we are using.

JoakimSM · 2025-11-10T16:16:57Z

src/components/AppLoader/init.ts


    return new Promise<void>((resolve) => {
-        import(`moment/locale/${locale}`)
+        import(`moment/dist/locale/${locale}`)


Looked at your solution for dateFns and it seems like we have a problem with moment as well. The moment locale is not being properly set from what I can see (have a look at the weekdays variable in the setLocaleDataAsync function in this file, still resolves to english even if the ui-language is something else).

These dynamic imports are quite confusing, not going to lie. Tried the import.meta.glob thing a bit, wasn't able to make it work. Let's talk about this tomorrow.

@JoakimSM I’ve removed the dynamic import and use the switch statement for moment as well. Could you please take another look? Thanks!

JoakimSM · 2025-11-11T09:42:38Z

src/components/AppStart/AppStart.component.tsx

-                </MuiThemeProvider>
-            </JSSProviderShell>
-        </React.Fragment>
+        <QueryClientProvider client={queryClient}>


Do we really need this? I think this is already inserted by the App shell / runtime?

It looks like we do need it. When I remove it and restart the server, the app breaks with the error No QueryClient set, use QueryClientProvider to set one useQueryClient.

Had a look and the problem is that we are adding multiple versions of react-query to the bundle and the app and app-runtime are using different versions (if you have a look in yarn.lock, you will see react-query listed twice). I fixed it by doing this:

yarn add @tanstack/react-query@^4.42.0 -W npx yarn-deduplicate --packages @tanstack/react-query

you should end up with something like this in yarn.lock:

"@tanstack/react-query@^4.42.0", "@tanstack/react-query@^4.40.0": version "4.42.0" resolved "https://registry.yarnpkg.com/@tanstack/react-query/-/react-query-4.42.0.tgz#a4d2527713e841c71a4a4b3f9412bb98ea5eec59" integrity sha512-j0tiofkzE3CSrYKmVRaKuwGgvCE+P2OOEDlhmfjeZf5ufcuFHwYwwgw3j08n4WYPVZ+OpsHblcFYezhKA3jDwg== dependencies: "@tanstack/query-core" "4.41.0" use-sync-external-store "^1.2.0"

Amazing, yes running the deduplicate fixed the issue. Thanks for the suggestion! 🙌

JoakimSM · 2025-11-11T12:10:33Z

src/core_modules/capture-core-utils/styles/withStyles.tsx

+export type WithStyles<S extends Record<string, any> | ((t: typeof theme) => S)> = {
+    classes: Record<string, any>;
+};


It seems like we have a job to do on the types in this file, ok to leave that for later though. But can we change the WithStyles to the following suggestion:

Suggested change

export type WithStyles<S extends Record<string, any> | ((t: typeof theme) => S)> = {

classes: Record<string, any>;

};

type Style = Record<string, string | number>

export type WithStyles<T extends Record<string, Style> | ((t: typeof theme) => Record<string, Style>)> = {

classes: { [K in keyof (T extends (args: unknown) => unknown ? ReturnType<T> : T)]: string }

}

Let me know if something breaks, but I think it should be an improvement.

Using the suggested types causes errors because string | number is too restrictive and doesn’t account for the media queries or the pseudo-selectors (e.g. &:focus, &:hover, &.isLastItem etc.). To fix the errors, I extended on your suggestion so that type Style also supports nested objects. Let me know if you agree. Thank you!

Perfect, that makes sense 👍

src/core_modules/capture-core/components/DataEntry/withCancelButton.tsx

sonarqubecloud · 2025-11-17T13:23:17Z

Quality Gate failed

Failed conditions
17 New issues
1 New Critical Issues (required ≤ 0)
17 New Code Smells (required ≤ 0)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

simonadomnisoru added 13 commits September 10, 2025 09:40

chore: upgrade cli-app-scripts ui app-runtime

9ab76e7

chore: atempt to fix import alias path

1228eec

chore: fix typescript error

85ae606

chore: fix linter error

5d07c97

chore: fix missing import alias

354389e

chore: fix global is undefined

6284360

chore: fix regenerator-runtime is not defined

b390d38

chore: remove environment variables deprecated prefix

6e6fafb

fix: missing QueryClient error

f629895

chore: storageControllers.userMetadata and programCollection is undef…

8443af9

…ined

feat: configure Emotion with typescript and vite

65b0cdb

chore: firx typescript

ff288e1

feat: custom withStyles HOC to pass on the style-objects to the compo…

30415e8

…nent & use it in NoSelectionsInfoBox

simonadomnisoru added the preview label Sep 17, 2025

Merge branch 'master' into DHIS2-18801

cad82b4

simonadomnisoru added preview and removed preview labels Sep 17, 2025

Merge branch 'master' into DHIS2-18801

1dcdd60

simonadomnisoru added preview and removed preview labels Sep 17, 2025

simonadomnisoru added 6 commits September 17, 2025 17:08

chore: use switch-case with static imports to load locale

a195f2a

feat: helper to conditionally compose multiple styles

1275873

feat: add theme object & modify withStyles to handle both object and …

f14dbe7

…function

refactor: replace MaterialUI with Emotion

8a14232

refactor: remove leaflet CDN dependencies and import the css

f688878

refactor: ensure consistent use of absolute imports and add eslint ru…

16580d3

…le to enforce this convention

simonadomnisoru added preview and removed preview labels Oct 15, 2025

Merge branch 'master' into DHIS2-18801

a5e2d1e

refactor: deprecated unsafe component lifecycle methods

ede0bd6

simonadomnisoru added testing and removed testing labels Nov 5, 2025

simonadomnisoru requested a review from henrikmv November 5, 2025 14:07

eirikhaugstulen reviewed Nov 5, 2025

View reviewed changes

simonadomnisoru added 2 commits November 6, 2025 10:07

chore: rename vite.config.mts & add retry to useApiMetadataQuery

6b743dd

chore: revert ff288e1 commit

2bdd33a

simonadomnisoru added testing and removed testing labels Nov 6, 2025

simonadomnisoru requested a review from eirikhaugstulen November 6, 2025 09:57

eirikhaugstulen approved these changes Nov 6, 2025

View reviewed changes

henrikmv approved these changes Nov 7, 2025

View reviewed changes

JoakimSM reviewed Nov 10, 2025

View reviewed changes

simonadomnisoru added 3 commits November 11, 2025 09:32

chore: list the react dependencies in package json

827c447

refactor: add useMemo to withStyles HOC

762a628

Merge branch 'master' into DHIS2-18801

67318b1

simonadomnisoru added testing and removed testing labels Nov 11, 2025

JoakimSM reviewed Nov 11, 2025

View reviewed changes

simonadomnisoru added 6 commits November 12, 2025 09:37

chore: improve withStyle types

dacc07e

chore: update to the latest app-platform release

dbf25de

fix: dedupe react-query and remove QueryClientProvider

80698d3

refactor: replace moment dynamic import with switch

d92109f

Merge branch 'master' into DHIS2-18801

9d48554

fix: add missing isInitialLoading

5887eb1

simonadomnisoru added testing and removed testing labels Nov 17, 2025

simonadomnisoru requested a review from JoakimSM November 17, 2025 15:12

-export type WithStyles<S extends Record<string, any> | ((t: typeof theme) => S)> = {
-    classes: Record<string, any>;
-};
+type Style = Record<string, string | number>
+export type WithStyles<T extends Record<string, Style> | ((t: typeof theme) => Record<string, Style>)> = {
+    classes: { [K in keyof (T extends (args: unknown) => unknown ? ReturnType<T> : T)]: string }
+}

refactor: [DHIS2-18801] upgrade capture app to use vite and react 18 #4375

Are you sure you want to change the base?

refactor: [DHIS2-18801] upgrade capture app to use vite and react 18 #4375

Conversation

simonadomnisoru commented Sep 10, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simonadomnisoru commented Nov 5, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eirikhaugstulen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

eirikhaugstulen left a comment

Choose a reason for hiding this comment

Uh oh!

henrikmv left a comment

Choose a reason for hiding this comment

Uh oh!

JoakimSM left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simonadomnisoru Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JoakimSM Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud bot commented Nov 17, 2025

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

simonadomnisoru commented Sep 10, 2025 •

edited by atlassian bot

Loading

github-actions bot commented Sep 17, 2025 •

edited

Loading

simonadomnisoru commented Nov 5, 2025 •

edited by atlassian bot

Loading

simonadomnisoru Nov 12, 2025 •

edited

Loading

JoakimSM Nov 13, 2025 •

edited

Loading