This is the upgrade guide for both
v0.39andv1.0.0-rc. If you haven’t already, first read the respective Release Notes:
Automated Codemods
Many upgrade steps can be completed using the @redwoodjs/codemods package (preview feature). Amazing!
There are a few things you should know in order to get the most out of this preview feature:
- Start by saving the current state of your project with git — there should be no uncommitted changes. This way, if you ever need to re-try or rollback a codemod step, you can easily revert using git.
- Always review the file changes after you run a codemod. They’re going to be accurate 90% of the time. The remaining 10% is on you.
1. Update Babel Config
Required for all projects.
Codemod Available
To implement this step via automated codemod, run:
npx @redwoodjs/codemods@latest update-babel-config
The release simplifies Redwood’s internal Babel config, resulting in the following changes:
.babelrcfiles are no longer supported — useweb/babel.config.jsorapi/babel.config.jsinstead- using a root
babel.config.jsfile is no longer supported
See the new Babel Doc.
Click to show Manual steps
To upgrade, follow these steps:
- root
./babel.config.js- if the root file contains config (other than ‘@redwoodjs/core/config/babel-preset’), the config should be moved to a respective
web/babel.config.jsorapi/babel.config.jsfile - then remove
babel.config.jsfrom the root of your project
- if the root file contains config (other than ‘@redwoodjs/core/config/babel-preset’), the config should be moved to a respective
web/.bablerc- if custom config is present, rename this file to
babel.config.jsand remove the “extends” property. - remove
.babelrcfromweb/
- if custom config is present, rename this file to
2. Rename Router paramType Properties
This only applies if you’re using custom paramTypes for your Routes.
To implement this step via automated codemod, run:
npx @redwoodjs/codemods@latest update-router-paramTypes
Click for manual steps
Make the following changes within `web/src/Routes.{js,tsx}
- Search for
constraint. If Route param is found, rename tomatch - Search for
transform. If Route param is found, rename toparse
3. Node.js package.json Engine
Recommended for all projects.
This version increases the minimum Node.js version. (See #3761)
It is recommend to update ./package.json:
"engines": {
- "node": ">=14.x <=16.x",
+ "node": ">=14.17 <=16.x",
4. Update your Cell Mocks
This only applies if you custom implementation exports an object.
Cell standard mocks no longer support object exports.
To implement this step via automated codemod, run:
npx @redwoodjs/codemods@latest update-cell-mocks
Click for manual steps
Follow these steps for each of your .mock.{js,ts} files (if applicable):
- Finds all Cell mock files (used in tests and storybook) by searching for the extension
Cell.mock.{js,ts} - Change the standard export to be a function instead of an object. For example:
- export const standard = {
- todosCount: 42,
-}
+ export const standard = () => {
+ return {
+ todosCount: 42
+ }
+}
5. Accessing API Paths
Only applies to projects using Redwood’s built-in API globals, e.g. library authors.
Redwood’s internal API globals have been changed to reflect new configuration options.
If you are using these in your projectm they are now exposed as:
RWJS_API_GRAPHQL_URLRWJS_API_DBAUTH_URLRWJS_API_URL
See the following Doc
6. Upgrade Tailwindcss to v3
May not apply to all projects
Redwood’s setup command now installs Tailwindcss at v3. If your project uses Tailwindcss, upgrading is recommended.
- Upgrade the dependency by running these commands:
yarn workspace web remove tailwindcss
yarn workspace web add --dev tailwindcss@next
- If
tailwind.config.jsexists inweb/config, rename thepurgeprop tocontent. If that prop is’t there at all, then it has to be added with this value:
content: ['src/**/*.{js,jsx,ts,tsx}']
- Follow the official Tailwindcss Upgrade Guide
7. Use Tailwindcss for Scaffolds
Optional and only applies to projects using Tailwindcss and generated Scaffolds.
If a project is using Tailwindcss, the generated Scaffolds will now automatically use Tailwindcss. (See #3644)
If you already have a scaffold.css and want the Tailwind-enabled one instead, there are two things you can do:
-
Delete your existing
web/src/scaffold.cssfile and then re-generate any one of your scaffolds with the--forceflag (note that this will overwrite any changes you’ve made to the scaffold pages/components) -
Copy the Tailwind-enabled
scaffold.csstemplate from the Redwood repo here and overwriteweb/src/scaffold.css
8. dbAuth: Harden getCurrentUser() Implementation
Required for projects using dbAuth
If you are using dbAuth, the default getCurrentUser() function in api/src/lib/auth.js returns a complete user record in your database.
You may not be aware, but anything returned from getCurrentUser() is sent down to the client, and could be viewed by anyone who inspects requests back and forth to the server. Starting with this release we’re only returning the id field on the user by default, and it’s up to the developer to add more fields. If you want to update your getCurrentUser() to match our newly generated code, replace yours with this:
export const getCurrentUser = async (session) => {
return await db.user.findUnique({
where: { id: session.id },
select: { id: true }
})
}
9. Upgrade Azure Active Directory Auth from msal to @azure/msal-*
Required for projects using Azure Auth.
If you are using Azure auth: Microsoft has deprecated msal in favor of @azure/msal-browser, which introduces OAuth 2.0 Authorization Code Grant with PKCE instead of Implicit Flow.
Long story short, you need to make a few changes:
- Update your Application registration.
- See updated Docs
- Replace dependency
msalwith@azure/msal-browserinweb/package.json. Example hereyarn workspace web remove msalyarn workspace web add @azure/msal-browser
- Replace import reference
UserAgentApplicationfrommsaltoPublicClientApplicationfrom@azure/msal-browserinweb/App.{js,tsx}. Example here.
Lastly, this version now uses redirect instead of popup as some browsers may disable popup on first click.
You’re almost done
Don’t forget to upgrade your packages!
Head back over to the Release Notes if you need specific instructions:
