Redwood v8.0.0 🚀

Background jobs

Redwood now has a Background Jobs system that allows you to easily create and execute background jobs in your Redwood app! This is a powerful feature that can be useful for things like sending emails, processing images, or any other task that doesn't need to be done immediately.

Core team member Rob has an awesome introduction video covering this new feature.

Easier SSR and RSC setup (Experimental)

It's easier than ever to enable our experimental SSR and RSC features. You can now enable SSR or RSC with a single command without having to first upgrade to a canary version of Redwood.

yarn rw experimental setup-streaming-ssr -f # Setup SSR
yarn rw experimental setup-rsc # Setup RSC

👷🏾 Heads up! Make sure that you're running node v20.17.0 or greater and yarn v4.1.1 or greater. If you need help getting set up or upgrading, you can refer to our documentation on using nvm and yarn.

⚠️ NOTE: If you just want to try our work-in-progress RSC implementation, the recommended way to get started is to head over to our React Server Components page and follow the instructions there.

Storybook using vite

Our Storybook setup now uses Vite instead of Webpack which has now been removed. This means your storybook setup will be faster and more consistent with your underlying Redwood app.

Docker support

We've added support for Docker in Redwood. You can now deploy your Redwood app anywhere that supports docker with ease. We have a guide on how to do this here.

yarn rw setup docker # Setup Docker and Docker Compose

Upgraded versions of React, Prisma, Vite, and more

We've upgraded a number of packages in Redwood to their latest versions. This includes React, Prisma, Vite, and more. This means you'll be able to take advantage of the latest features and improvements they have to offer.

What you need to know before you upgrade

In this release, we've dropped support for Webpack. This means that if you're still using Webpack in your project you shouldn't upgrade yet. Instead, you should stick with v7.7.4 and switch over to using Vite. We have a guide on how to do this here.

There are more changes that might impact you so please be sure to read the full guide here to make the upgrade as easy as possible. If you want to see a full list of every single change in v8 you can look at the release here. It details all the PRs that went into this release.

Let's get started!

There are a couple of steps everyone will need to take to upgrade to v8. Let's walk through them.

Begin with v7.7.4

It's always best to start from the latest previous version. Please make sure you're on v7.7.4 and everything is working as expected before upgrading to v8. You can do this by running:

yarn rw upgrade -t 7.7.4

If you're not on v7.7.4 there might be things you have to do that aren't covered in this guide. It'll be easier to upgrade to v7.7.4 first and then upgrade to v8 than to try and upgrade from an older version directly to v8.

Preparing to upgrade

Storybook CLI package

If you've been using storybook you'll have the @redwoodjs/cli-storybook in your root package.json. You'll need to remove this package before upgrading because we provide a different package for storybook in v8.
Simply delete the package from your package.json and run yarn install to remove it.

"devDependencies": {
-  "@redwoodjs/cli-storybook": "7.7.4",
  "@redwoodjs/core": "7.7.4"
},

Running the upgrade command

Now we're ready to upgrade to v8. Run the following command to switch your redwood packages to v8.

yarn rw upgrade

Upgrading React

You'll now want to upgrade your React version to v18.3.1. This is in your ./web/package.json file.

"dependencies": {
-  "react": "18.2.0",
+  "react": "18.3.1",
-  "react-dom": "18.2.0",
+  "react-dom": "18.3.1"
},

TSConfig changes

We've updated our default TSConfig settings to better match modern runtimes. You should update your existing settings to match the new defaults. There are three files, one on the API side, one on the web side, and one in the scripts directory.

API Side

This is found at ./api/tsconfig.json. You'll want to update the target, module, and moduleResolution settings.

{
  "compilerOptions": {
-    "target": "esnext",
+    "target": "ES2023",
-    "module": "esnext",
+    "module": "Node16",
-    "moduleResolution": "node",
+    "moduleResolution": "Node16",
  }
}

Web Side

This is found at ./web/tsconfig.json. Again you'll want to update the target, module, and moduleResolution settings.

{
  "compilerOptions": {
-    "target": "esnext",
+    "target": "ES2022",
-    "module": "esnext",
+    "module": "ESNext",
-    "moduleResolution": "node",
+    "moduleResolution": "Bundler",
  }
}

Scripts

This is found at ./scripts/tsconfig.json. You'll want to update the target, module, and moduleResolution settings.

{
  "compilerOptions": {
-    "target": "esnext",
+    "target": "ES2023",
-    "module": "esnext",
+    "module": "Node16",
-    "moduleResolution": "node",
+    "moduleResolution": "Node16",
  }
}

Yarn version

We've updated the default version of yarn to v4.4.0. You can update this in your root ./package.json file.

{
-  "packageManager": "yarn@4.3.0",
+  "packageManager": "yarn@4.4.0",
}

<NavLink> active classes

Redwood's NavLink component uses the className and activeClassName props to apply classes to the link based on the current route. In v8 we've changed how activeClassName works. In v7 activeClassName would be merged with className if the link was active. In v8 activeClassName will replace className if the link is active.

This means you'll need to update your activeClassName prop to include any of the className classes you wanted to be applied while the link is active since these won't be merged in anymore. For example, take this component:

<NavLink
  to={routes.home()}
  className="border-b-2"
  activeClassName="text-red-200"
>
  Home
</NavLink>

In v7 you'd get both the border and color when the link was active. In v8 you'll only get the color and the border will no longer show. To fix this you'll need to update the activeClassName to include the border.

<NavLink
  to={routes.home()}
  className="border-b-2"
-  activeClassName="text-red-200"
+  activeClassName="text-red-200 border-b-2"
>
  Home
</NavLink>

Database file structure change

This is not technically a breaking change to your code but we have changed how we structure the database file (api/src/lib/db.{ts,js}) by default and strongly recommend you update your database file to match this new expectation. It's a simple change. We instead expect you to create a distinct variable for the Prisma client and export that later as db. This is in preparation for future changes that will introduce some awesome features. Here's what the typical diff would look like:

import { PrismaClient } from '@prisma/client'
import { emitLogLevels, handlePrismaLogging } from '@redwoodjs/api/logger'
import { logger } from './logger'

- export const db = new PrismaClient({
+ const prismaClient = new PrismaClient({
  log: emitLogLevels(['info', 'warn', 'error']),
})

handlePrismaLogging({
- db
+ db: prismaClient,
  logger,
  logLevels: ['info', 'warn', 'error'],
})

+ export const db = prismaClient

Other changes

Those changes discussed above are likely to affect everyone. There are other changes that might impact you depending on how you're using Redwood. Let's walk through those.

Prettier v3

We have internally updated to Prettier v3. We believe this won't have any downstream effect on users. However, if you have Tailwind CSS configured you can upgrade prettier-plugin-tailwindcss to a version later than v0.4.1, like for example 0.5.12.

To do so you can make a few changes:

• Change prettier.config.js to prettier.config.mjs (notice .js → .mjs)
• Change module.exports to export default
• Change require('...') to await import('...') for any plugins

Here's an example of an updated prettier.config.mjs to work with prettier-plugin-tailwindcss@^0.5.12:

// prettier.config.mjs
export default {
  trailingComma: 'es5',
  bracketSpacing: true,
  tabWidth: 2,
  semi: false,
  singleQuote: true,
  arrowParens: 'always',
  overrides: [
    {
      files: 'Routes.*',
      options: {
        printWidth: 999,
      },
    },
  ],
  tailwindConfig: './web/config/tailwind.config.js',
  plugins: [await import('prettier-plugin-tailwindcss')],
}

Vite v5

We have upgraded from Vite v4 to v5. There are no breaking changes for users with the default Redwood config. If however, you have added additional Vite config or plugins and encounter problems you should consult their migration guide here.

Redwood package imports and exports

We have added conditional exports to our web, router, forms, prerender, api and internal packages. This could mean that if you were importing from deep within the package like @redwoodjs/web/dist/xyz this will no longer work.

For example, you could have been using components such as Toast by importing from the dist directory inside of @redwoodjs/web. We often no longer support importing directly from dist and you should instead import from the root like so @redwoodjs/web/toast.

In order to make this upgrade as smooth as possible, we have not removed all possible deep imports. There are cases like: '@redwoodjs/web/dist/components/DevFatalErrorPage' where this import will still work. If you encounter a problem with an import you should check the Redwood repository and look at the package.json file of the package you're having difficulty with. If there is an exports field then you'll be able to see all our supported import paths, if there is no exports field then you can simply continue importing from dist as before.

server.config.js no longer supported

You can no longer use the server.config.js file to configure your fastify server. Instead, you'll have to migrate to the new server file setup. This is documented here.

Apollo GraphQLFormattedError and GraphQLError

Apollo recently fixed a type error with GraphQLError and GraphQLFormatterError which can impact you if you're using these types in your code. You can see more about those changes here and here.

yarn rw build no longer accepts a performance flag

When using the Webpack bundler a --performance flag was available for the yarn rw build command. This flag, and the underlying functionality, are no longer available since we've removed Webpack. In v8 attempting to use this flag will throw an error.

firebase-admin upgraded to v12

Our firebase auth provider uses the firebase-admin package. This has been upgraded from v11 to v12. We have seen no breaking changes that would affect a Redwood user with regards to authentication but please do consult their changelog if you use this auth provider.

Resend upgraded to v3

The Resend node SDK used within the Resend mail handler has been upgraded to v3. None of the mail handlers' own functionality has changed in a breaking way but there are still underlying changes to the SDK's types and to the contacts API that you should be aware of.

Please see here and here for the Resend release notes.

Edgio deploy provider removed

The Edgio deploy provider was deprecated in previous versions. In this release, it has been removed and is no longer available from the Redwood CLI.

If you are affected by this change we'd be happy to hear more about your deployment needs on our community forums.

mockHttpEvent updated for null bodies

We provide mockHttpEvent for testing purposes. Previously, when you used this function with an empty or null payload (which is the default) then the body returned would be 'null'. In v8 this has been corrected and an empty body will no longer return a string value of 'null'.

If you have used this function in your API side tests and have snapshots or other logic which expects the payload property to be 'null' then they will have to be updated to accept null instead.

Change to isDataEmpty function in @redwoodjs/web

The isDataEmpty function from the @redwoodjs/web package is not typically used within Redwood projects but if you have chosen to import and use it you must now be aware that it will no longer throw an error when the data parameter is null or undefined. Instead, it'll return true (as in, “yes, the data is empty”).

Colors update in @redwoodjs/cli-helpers

We have made changes to the colors available from the colors utility in the @redwoodjs/cli-helpers package. If you happen to be using this then you'll need to be aware that:

• The warning color has changed slightly.
• The green color has been renamed and is now available from success instead.
• Additional colors are available; note, tip, important, caution, and link.

Linting upgrades and changes

We have upgraded our @typescript-eslint packages. We do not anticipate any breaking changes for users that do not have additional config related to linting. If you do, or you experience linting related errors, please consult the typescript-eslint upgrade guides for v6, v7 and v8.

We expect in this release a small change in the linting rules applied to your project. If you discover a change you find unpalatable then please raise that on our community forums.

v1 codemods

During upgrades, we try when possible to provide codemods for non-trivial changes that need to be made to your project. There were a number of such codemods designed to make changes when upgrading from versions between v0.0.0 and v1.0.0. These codemods are published in the @redwoodjs/codemods package.

From v8 this package will no longer contain codemods designed for versions prior to v1.0.0. If you still need those codemods then you can still use them by using the v7.7.4 of @redwoodjs/codemods.

Things to watch out for

Prisma Client

You'll want to ensure you have generated a new Prisma client once you've upgraded. We have seen occasions where even though our upgrade script will regenerate the client you will have to do so again to avoid errors. An example of an error we've seen where this has been the fix is when your API side is throwing because of reading length on undefined with regards to currentUser.

Node v18 to v20 upgrade

If you happen to be migrating from node version v18 to v20 as part of this upgrade you should take care to deal with any changes that itself required. For example, deploying baremental and using pm2. In that case, there are additional pm2 specific actions you must take when upgrading your system from v18 to v20. It won't be possible for us to document all things like that here. We can of course try to offer help in debugging issues that arise on our community forums.