|
| 1 | +--- |
| 2 | +title: Migration from v1.1 |
| 3 | +--- |
| 4 | + |
| 5 | +:::warning |
| 6 | +This guide is a work in progress to enable you to migrate your application from Contember v1.1 to v1.2.0 before the final release. |
| 7 | +::: |
| 8 | + |
| 9 | +1.2.0 is a major release of the framework. It contains some pretty exciting features, but also a few breaking changes to make way for the future. This guide will help you upgrade your application to 1.2.0 and take advantage of the new features. |
| 10 | + |
| 11 | +## Bump versions of `@contember/*` packages and run `npm install`. |
| 12 | + |
| 13 | +```diff title="package.json" |
| 14 | + { |
| 15 | + "scripts": { |
| 16 | +- "contember": "docker-compose run contember-cli", |
| 17 | ++ "contember": "docker-compose run --rm contember-cli", |
| 18 | + ... |
| 19 | + }, |
| 20 | + "devDependencies": { |
| 21 | +- "@contember/schema": "1.2.1", |
| 22 | ++ "@contember/schema": "1.3.0-rc.1", |
| 23 | +- "@contember/schema-definition": "1.2.1", |
| 24 | ++ "@contember/schema-definition": "1.3.0-rc.1", |
| 25 | +- "@contember/admin": "^1.0.0", |
| 26 | ++ "@contember/admin": "^1.2.0-rc.14", |
| 27 | + ... |
| 28 | +- "@types/react": "^17", |
| 29 | ++ "@types/react": "^18", |
| 30 | ++ "@types/react-dom": "^18", |
| 31 | +- "react": "^17", |
| 32 | ++ "react": "^18", |
| 33 | +- "react-dom": "^17", |
| 34 | ++ "react-dom": "^18", |
| 35 | +- "typescript": "^4.5", |
| 36 | ++ "typescript": "^5.0", |
| 37 | +- "vite": "^2.7" |
| 38 | ++ "vite": "^4" |
| 39 | + } |
| 40 | + } |
| 41 | +``` |
| 42 | + |
| 43 | +## Add support for React 17 JSX transform |
| 44 | + |
| 45 | +Use React 17+ `react-jsx` transform instead of `react` in `tsconfig.json`: |
| 46 | + |
| 47 | +```diff title="tsconfig.json" |
| 48 | + { |
| 49 | + "compilerOptions": { |
| 50 | + ... |
| 51 | +- "jsx": "react", |
| 52 | ++ "jsx": "react-jsx", |
| 53 | + ... |
| 54 | +``` |
| 55 | + |
| 56 | +Now you can remove all unnecessary `React` namespace imports from your codebase: |
| 57 | + |
| 58 | +```diff |
| 59 | +-import * as React from 'react' |
| 60 | +``` |
| 61 | + |
| 62 | +## Add support for React 18 |
| 63 | + |
| 64 | +```diff title="admin/index.tsx" |
| 65 | +@@ -1,6 +1,6 @@ |
| 66 | +-import * as React from 'react' |
| 67 | +-import { ApplicationEntrypoint, Pages, runReactApp } from '@contember/admin' |
| 68 | ++import { ApplicationEntrypoint, PageModule, Pages, runReactApp } from '@contember/admin' |
| 69 | +-import '@contember/admin/style.css' |
| 70 | ++import '@contember/admin/index.css' |
| 71 | ++import { createRoot } from 'react-dom/client' |
| 72 | + import { Layout } from './components/Layout' |
| 73 | + |
| 74 | + runReactApp( |
| 75 | + <ApplicationEntrypoint |
| 76 | + basePath={import.meta.env.BASE_URL} |
| 77 | + apiBaseUrl={import.meta.env.VITE_CONTEMBER_ADMIN_API_BASE_URL} |
| 78 | + sessionToken={import.meta.env.VITE_CONTEMBER_ADMIN_SESSION_TOKEN} |
| 79 | + project={import.meta.env.VITE_CONTEMBER_ADMIN_PROJECT_NAME} |
| 80 | + stage="live" |
| 81 | ++ envVariables={{ WEB_URL: import.meta.env.VITE_CONTEMBER_ADMIN_WEB_URL }} |
| 82 | +- children={<Pages layout={Layout} children={import.meta.globEager('./pages/**/*.tsx')} />} |
| 83 | ++ children={ |
| 84 | ++ <Pages |
| 85 | ++ layout={Layout} |
| 86 | ++ children={import.meta.glob<PageModule>( |
| 87 | ++ './pages/**/*.tsx', |
| 88 | ++ { eager: true }, |
| 89 | ++ )} |
| 90 | ++ /> |
| 91 | ++ } |
| 92 | + />, |
| 93 | ++ null, |
| 94 | ++ (dom, react, onRecoverableError) => createRoot(dom, { onRecoverableError }).render(react), |
| 95 | + ) |
| 96 | +``` |
| 97 | + |
| 98 | +## Admin Interface |
| 99 | + |
| 100 | +Remove extra nesting of `Menu.Item` components: |
| 101 | + |
| 102 | +```diff title="admin/components/Navigation.tsx" |
| 103 | +-import * as React from 'react' |
| 104 | + import { Menu } from '@contember/admin' |
| 105 | ++import * as React from 'react' |
| 106 | + |
| 107 | + export const Navigation = () => ( |
| 108 | + <Menu> |
| 109 | +- <Menu.Item> |
| 110 | +- <Menu.Item title="Dashboard" to="index" /> |
| 111 | +- </Menu.Item> |
| 112 | ++ <Menu.Item title="Dashboard" to="index" /> |
| 113 | + </Menu> |
| 114 | + ) |
| 115 | +``` |
| 116 | + |
| 117 | +## Add favicon, Apple touch icon and theme color (optional but recommended): |
| 118 | + |
| 119 | +```diff title="admin/index.html" |
| 120 | + <head> |
| 121 | + <meta charset="utf-8"> |
| 122 | + <meta name="viewport" content="width=device-width, viewport-fit=cover, initial-scale=1"> |
| 123 | ++ <link rel="icon" type="image/png" href="./favicon.png"> |
| 124 | ++ <link rel="apple-touch-icon" href="./apple-touch-icon.png"> |
| 125 | + <title>Admin quickstart</title> |
| 126 | ++ <meta name="theme-color" content="#F2F5F1" media="(prefers-color-scheme: light)"> |
| 127 | ++ <meta name="theme-color" content="#000000" media="(prefers-color-scheme: dark)"> |
| 128 | + <script type="module" src="./index.tsx"></script> |
| 129 | + </head> |
| 130 | + </html> |
| 131 | +``` |
0 commit comments