Broadleaf Microservices
  • v1.0.0-latest-prod

Upgrading the Starter to AdminWeb 2.0.0

In the 2.0.0 release of AdminWeb, the core Admin components library has been upgraded to React 19 and React Router v6, meaning any projects depending on it must also update their local dependencies and initialization logic to support the new APIs. These require a few changes to AdminStarter.

Update package.json Dependencies

You will need to bump your core React packages, React Router, and TypeScript (to support the new React 19 type definitions) versions.

Update the following dependencies in your package.json:
  "dependencies": {
+   "react": "^19.0.0",
+   "react-dom": "^19.0.0",
+   "react-router-dom": "^6.28.0",
-   "react": "^16.13.1",
-   "react-dom": "^16.13.1",
-   "react-router-dom": "^5.2.0",
    // ...other dependencies
  },
  "devDependencies": {
+   "@types/react": "^19.0.0",
+   "@types/react-dom": "^19.0.0",
+   "typescript": "^5.6.3",
-   "@types/react": "^17.0.15",
-   "@types/react-dom": "^17.0.15",
-   "typescript": "4.9.5",
    // ...other dependencies
  }
Note
 As with any update made to package.json, run yarn install or npm install after making these changes to update your yarn.lock with the new versions. If you notice any issues with the new versions, you can try deleting yarn.lock and node_modules and then running yarn install or npm install again to ensure a clean slate.

Update the Application Mount Point (index.tsx)

React 19 completely removes the legacy ReactDOM.render API. You must switch to using createRoot to render your application.

In index.tsx, replace the existing render logic with the following:
- import ReactDOM from 'react-dom';
+ import { createRoot } from 'react-dom/client';

  import App from './App';
  // ...other imports

- ReactDOM.render(<App />, document.getElementById('root'));
+ const rootElement = document.getElementById('root');
+ if (rootElement) {
+   createRoot(rootElement).render(<App />);
+ }

Update React Router Configuration (App.tsx)

React Router v6 introduces significant changes to how routes are defined and rendered. You will need to update your routing logic to use the new Routes and Route components. Because React Router was upgraded from v5 to v6, the <BrowserRouter> API has changed. Specifically, the forceRefresh prop has been removed and must be deleted from your router configuration.

In App.tsx, replace your existing router configuration with the following:
- const browserSupportsHistory = 'pushState' in window.history;
  const App = () => (
    <Router
      basename={utils.Environment.get('public.url')}
-     forceRefresh={!browserSupportsHistory}
    >
      <AdminProvider messages={combinedMessages}>
        <AdminApp />
      </AdminProvider>
    </Router>
  );

Update Test Files (App.test.tsx)

Finally, if your project relies on legacy rendering APIs in its tests, those must also be updated to use createRoot.

In App.test.tsx and similar test files, replace the existing render logic with the following:
- import ReactDOM from 'react-dom';
+ import { createRoot } from 'react-dom/client';

  test('renders without crashing', () => {
    const div = document.createElement('div');
-   ReactDOM.render(<App />, div);
-   ReactDOM.unmountComponentAtNode(div);
+   const root = createRoot(div);
+   root.render(<App />);
+   root.unmount();
  });

Additional Considerations for Custom Components

If your workspace contains custom React components or custom routing, you may also need to address the following breaking changes introduced by React 19 and React Router v6:

  • React 19: defaultProps are no longer supported in functional components. Use ES6 default parameters instead.

Example ES6 setting of default props
const MyComponent = ({ myProp = 'defaultValue' }) => ...

  • React 19: The forwardRef API is deprecated. Refs can now be passed as standard props (props.ref).

  • React Router v6: <Switch> has been replaced entirely by <Routes>. All <Route> components must be direct children of a <Routes> block. Additonally, useHistory has been replaced by useNavigate.