Skip to content

Commit a916032

Browse files
ahaywoodTobbe
ahaywood
and
Tobbe
authored
docs: Added the Upgrade Guide to the Docs (#12083)
Co-authored-by: Tobbe Lundberg <[email protected]>
1 parent 4e45151 commit a916032

File tree

2 files changed

+355
-0
lines changed

2 files changed

+355
-0
lines changed

‎docs/docs/upgrade-guides/v8.md‎

Lines changed: 345 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,345 @@
1+
---
2+
title: Redwood v8.0.0
3+
description: Getting started & Core Concepts
4+
---
5+
6+
# Background Jobs
7+
8+
Redwood now has a [Background Jobs](https://docs.redwoodjs.com/docs/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.
9+
10+
Core team member Rob has an awesome introduction video covering this new feature.
11+
12+
<!-- TODO: Inject YouTube Video -->
13+
14+
## Easier SSR and RSC setup (Experimental)
15+
16+
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.
17+
18+
```bash
19+
yarn rw experimental setup-streaming-ssr -f # Setup SSR
20+
yarn rw experimental setup-rsc # Setup RSC
21+
```
22+
23+
👷🏾 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](https://docs.redwoodjs.com/docs/how-to/using-nvm) and [yarn](https://docs.redwoodjs.com/docs/how-to/using-yarn).
24+
25+
:::note
26+
⚠️ NOTE: If you just want to try our work-in-progress RSC implementation, the recommended way to get started is to run `npx -y create-redwood-rsc-app APP-NAME`.
27+
:::
28+
29+
## Storybook using vite
30+
31+
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.
32+
33+
## Docker support
34+
35+
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](https://docs.redwoodjs.com/docs/docker).
36+
37+
```bash
38+
yarn rw setup docker # Setup Docker and Docker Compose
39+
```
40+
41+
## Upgraded versions of React, Prisma, Vite, and more
42+
43+
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.
44+
45+
# Upgrade Guide
46+
47+
## What you need to know before you upgrade
48+
49+
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](https://community.redwoodjs.com/t/redwood-v6-0-0-upgrade-guide/5044#vite-1).
50+
51+
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](https://github.com/redwoodjs/redwood/releases/v8.0.0). It details all the PRs that went into this release.
52+
53+
## Let's get started!
54+
55+
There are a couple of steps everyone will need to take to upgrade to v8. Let's walk through them.
56+
57+
### Begin with v7.7.4
58+
59+
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:
60+
61+
```bash
62+
yarn rw upgrade -t 7.7.4
63+
```
64+
65+
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.
66+
67+
### Preparing to upgrade
68+
69+
**Storybook CLI package**
70+
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.
71+
Simply delete the package from your `package.json` and run `yarn install` to remove it.
72+
73+
```json
74+
"devDependencies": {
75+
- "@redwoodjs/cli-storybook": "7.7.4",
76+
"@redwoodjs/core": "7.7.4"
77+
},
78+
```
79+
80+
**Update `tsconfig/jsconfig` for Storybook**
81+
In order for TypeScript and your editor's language server to find the new Storybook files we need to include a new path in your web side's `tsconfig.json` (or `jsconfig.json` if you're not using TypeScript). Add `"./.storybook/**/*"`, to the includes in your `web/tsconfig.json` or `web/jsconfig.json` file. Like this:
82+
83+
```json
84+
"include": [
85+
"src",
86+
"config",
87+
+ "./.storybook/**/*",
88+
"../.redwood/types/includes/all-*",
89+
"../.redwood/types/includes/web-*",
90+
"./types"
91+
]
92+
```
93+
94+
### Running the upgrade command
95+
96+
Now we're ready to upgrade to v8. Run the following command to switch your redwood packages to v8.
97+
98+
```bash
99+
yarn rw upgrade
100+
```
101+
102+
### Upgrading React
103+
104+
You'll now want to upgrade your React version to v18.3.1. This is in your `./web/package.json` file.
105+
106+
```json
107+
"dependencies": {
108+
- "react": "18.2.0",
109+
+ "react": "18.3.1",
110+
- "react-dom": "18.2.0",
111+
+ "react-dom": "18.3.1"
112+
},
113+
```
114+
115+
### TSConfig changes
116+
117+
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.
118+
119+
**API Side**
120+
This is found at `./api/tsconfig.json`. You'll want to update the `target`, `module`, and `moduleResolution` settings.
121+
122+
```json
123+
{
124+
"compilerOptions": {
125+
- "target": "esnext",
126+
+ "target": "ES2023",
127+
- "module": "esnext",
128+
+ "module": "Node16",
129+
- "moduleResolution": "node",
130+
+ "moduleResolution": "Node16",
131+
}
132+
}
133+
```
134+
135+
**Web Side**
136+
This is found at `./web/tsconfig.json`. Again you'll want to update the `target`, `module`, and `moduleResolution` settings.
137+
138+
```json
139+
{
140+
"compilerOptions": {
141+
- "target": "esnext",
142+
+ "target": "ES2022",
143+
- "module": "esnext",
144+
+ "module": "ESNext",
145+
- "moduleResolution": "node",
146+
+ "moduleResolution": "Bundler",
147+
}
148+
}
149+
```
150+
151+
**Scripts**
152+
This is found at `./scripts/tsconfig.json`. You'll want to update the `target`, `module`, and `moduleResolution` settings.
153+
154+
```json
155+
{
156+
"compilerOptions": {
157+
- "target": "esnext",
158+
+ "target": "ES2023",
159+
- "module": "esnext",
160+
+ "module": "Node16",
161+
- "moduleResolution": "node",
162+
+ "moduleResolution": "Node16",
163+
}
164+
}
165+
```
166+
167+
**Yarn Version**
168+
We've updated the default version of yarn to v4.4.0. You can update this in your root `./package.json` file.
169+
170+
```json
171+
{
172+
- "packageManager": "[email protected]",
173+
+ "packageManager": "[email protected]",
174+
}
175+
```
176+
177+
## `<NavLink>` active classes
178+
179+
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.
180+
181+
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:
182+
183+
```tsx
184+
<NavLink
185+
to={routes.home()}
186+
className="border-b-2"
187+
activeClassName="text-red-200"
188+
>
189+
Home
190+
</NavLink>
191+
```
192+
193+
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.
194+
195+
```tsx
196+
<NavLink
197+
to={routes.home()}
198+
className="border-b-2"
199+
- activeClassName="text-red-200"
200+
+ activeClassName="text-red-200 border-b-2"
201+
>
202+
Home
203+
</NavLink>
204+
```
205+
206+
### Database file structure change
207+
208+
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:
209+
210+
```tsx
211+
import { PrismaClient } from '@prisma/client'
212+
import { emitLogLevels, handlePrismaLogging } from '@redwoodjs/api/logger'
213+
import { logger } from './logger'
214+
215+
- export const db = new PrismaClient({
216+
+ const prismaClient = new PrismaClient({
217+
log: emitLogLevels(['info', 'warn', 'error']),
218+
})
219+
220+
handlePrismaLogging({
221+
- db
222+
+ db: prismaClient,
223+
logger,
224+
logLevels: ['info', 'warn', 'error'],
225+
})
226+
227+
+ export const db = prismaClient
228+
```
229+
230+
## Other Changes
231+
232+
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.
233+
234+
### Prettier v3
235+
236+
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.
237+
238+
To do so you can make a few changes:
239+
240+
- Change `prettier.config.js` to `prettier.config.mjs` (notice `.js` → `.mjs`)
241+
- Change `module.exports` to `export default`
242+
- Change `require('...')` to `await import('...')` for any plugins
243+
244+
Here's an example of an updated `prettier.config.mjs` to work with `prettier-plugin-tailwindcss@^0.5.12`:
245+
246+
```mjs
247+
// prettier.config.mjs
248+
export default {
249+
trailingComma: 'es5',
250+
bracketSpacing: true,
251+
tabWidth: 2,
252+
semi: false,
253+
singleQuote: true,
254+
arrowParens: 'always',
255+
overrides: [
256+
{
257+
files: 'Routes.*',
258+
options: {
259+
printWidth: 999,
260+
},
261+
},
262+
],
263+
tailwindConfig: './web/config/tailwind.config.js',
264+
plugins: [await import('prettier-plugin-tailwindcss')],
265+
}
266+
```
267+
268+
### Vite v5
269+
270+
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](https://vitejs.dev/guide/migration.html#migration-from-v4).
271+
272+
### Redwood package imports and exports
273+
274+
We have added [conditional exports](https://nodejs.org/api/packages.html#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.
275+
276+
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`.
277+
278+
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](https://github.com/redwoodjs/redwood/tree/main/packages) and look at the `package.jso`n 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.
279+
280+
### `server.config.js` no longer supported
281+
282+
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](https://docs.redwoodjs.com/docs/canary/docker/#using-the-server-file).
283+
284+
### Apollo `GraphQLFormattedError` and `GraphQLError`
285+
286+
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](https://github.com/apollographql/apollo-client/issues/11787) and [here](https://github.com/apollographql/apollo-client/pull/11789).
287+
288+
### `yarn rw build` no longer accepts a `performance` flag
289+
290+
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.
291+
292+
### `firebase-admin` upgraded to v12
293+
294+
Our [firebase auth provider](https://docs.redwoodjs.com/docs/auth/firebase/) uses the [firebase-admin](https://www.npmjs.com/package/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](https://github.com/firebase/firebase-admin-node/releases/tag/v12.0.0) if you use this auth provider.
295+
296+
### Resend upgraded to v3
297+
298+
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.
299+
300+
Please see [here](https://github.com/resend/resend-node/releases/tag/v2.0.0) and [here](https://github.com/resend/resend-node/releases/tag/v3.0.0) for the Resend release notes.
301+
302+
### Edgio deploy provider removed
303+
304+
The [Edgio](https://edg.io/) deploy provider was deprecated in previous versions. In this release, it has been removed and is no longer available from the Redwood CLI.
305+
306+
If you are affected by this change we'd be happy to hear more about your deployment needs on our [community forums](https://community.redwoodjs.com/).
307+
308+
`mockHttpEvent` updated for `null` bodies
309+
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'`.
310+
311+
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.
312+
313+
### Change to `isDataEmpty` function in `@redwoodjs/web`
314+
315+
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”).
316+
317+
### Colors update in `@redwoodjs/cli-helpers`
318+
319+
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:
320+
321+
- The `warning` color has changed slightly.
322+
- The `green` color has been renamed and is now available from `success` instead.
323+
- Additional colors are available; `note`, `tip`, `important`, `caution`, and `link`.
324+
325+
### Linting upgrades and changes
326+
327+
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](https://typescript-eslint.io/blog/announcing-typescript-eslint-v6/), [v7](https://typescript-eslint.io/blog/announcing-typescript-eslint-v7/) and [v8](https://typescript-eslint.io/blog/announcing-typescript-eslint-v8).
328+
329+
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](https://community.redwoodjs.com/).
330+
331+
### v1 codemods
332+
333+
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/codemod`s package.
334+
335+
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`.
336+
337+
## Things to watch out for
338+
339+
### Prisma Client
340+
341+
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`.
342+
343+
### Node v18 to v20 upgrade
344+
345+
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](https://community.redwoodjs.com/).

‎docs/sidebars.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -251,5 +251,15 @@ module.exports = {
251251
},
252252
],
253253
},
254+
{
255+
type: 'category',
256+
label: 'Upgrade Guide',
257+
items: [
258+
{
259+
type: 'autogenerated',
260+
dirName: 'upgrade-guides',
261+
},
262+
],
263+
},
254264
],
255265
}

0 commit comments

Comments
 (0)