diff --git a/web/docs/migrate-from-0-13-to-0-14.md b/web/docs/migrate-from-0-13-to-0-14.md index ebf7a43c2..545b9cc79 100644 --- a/web/docs/migrate-from-0-13-to-0-14.md +++ b/web/docs/migrate-from-0-13-to-0-14.md @@ -89,7 +89,68 @@ Wasp introduced a much simpler API for accessing user auth fields like `username ## How to migrate? +To migrate your app to Wasp 0.14.x, you must: + +1. Update your `tsconfig.json`. +2. Migrate your entities into the new `schema.prisma` file. +3. Update code that accesses user fields. + +### Update your `tsconfig.json` + +To ensure your project works correctly with Wasp 0.14.0, you must update your +`tsconfig.json` file. + +If you haven't changed anything in your project's `tsconfig.json` file (this is +the case for most users), just replace its contents with the new version shown +below. + +If you have made changes to your `tsconfig.json` file, we recommend taking the +new version of the file and reapplying them. + +Here's the new version of the `tsconfig.json` file: + +```json title=tsconfig.json +// =============================== IMPORTANT ================================= +// +// This file is only used for Wasp IDE support. You can change it to configure +// your IDE checks, but none of these options will affect the TypeScript +// compiler. Proper TS compiler configuration in Wasp is coming soon :) +{ + "compilerOptions": { + "module": "esnext", + "target": "esnext", + // We're bundling all code in the end so this is the most appropriate option, + // it's also important for autocomplete to work properly. + "moduleResolution": "bundler", + // JSX support + "jsx": "preserve", + "strict": true, + // Allow default imports. + "esModuleInterop": true, + "lib": ["dom", "dom.iterable", "esnext"], + "allowJs": true, + "typeRoots": [ + // This is needed to properly support Vitest testing with jest-dom matchers. + // Types for jest-dom are not recognized automatically and Typescript complains + // about missing types e.g. when using `toBeInTheDocument` and other matchers. + "node_modules/@testing-library", + // Specifying type roots overrides the default behavior of looking at the + // node_modules/@types folder so we had to list it explicitly. + // Source 1: https://www.typescriptlang.org/tsconfig#typeRoots + // Source 2: https://github.com/testing-library/jest-dom/issues/546#issuecomment-1889884843 + "node_modules/@types" + ], + // Since this TS config is used only for IDE support and not for + // compilation, the following directory doesn't exist. We need to specify + // it to prevent this error: + // https://stackoverflow.com/questions/42609768/typescript-error-cannot-write-file-because-it-would-overwrite-input-file + "outDir": ".wasp/phantom" + } +} +``` + ### Migrate to the new `schema.prisma` file + To use the new `schema.prisma` file, you need to move your entities from the `.wasp` file to the `schema.prisma` file. 1\. **Create a new `schema.prisma` file** @@ -106,6 +167,7 @@ Create a new file named `schema.prisma` in the root of your project: ├── tsconfig.json └── vite.config.ts ``` + 2\. **Add the `datasource` block** to the `schema.prisma` file This block specifies the database type and connection URL: @@ -119,20 +181,21 @@ datasource db { url = env("DATABASE_URL") } ``` + - ```prisma title="schema.prisma" datasource db { provider = "postgresql" url = env("DATABASE_URL") } ``` + -- The `provider` should be either `"postgresql"` or `"sqlite"`. +- The `provider` should be either `"postgresql"` or `"sqlite"`. - The `url` must be set to `env("DATABASE_URL")` so that Wasp can inject the database URL from the environment variables. @@ -155,10 +218,10 @@ generator client { } // highlight-end ``` + - ```prisma title="schema.prisma" datasource db { provider = "postgresql" @@ -171,6 +234,7 @@ generator client { } // highlight-end ``` + @@ -209,10 +273,10 @@ model Task { } // highlight-end ``` + - ```prisma title="schema.prisma" datasource db { provider = "postgresql" @@ -239,13 +303,14 @@ model Task { } // highlight-end ``` + - When moving the entities over, you'll need to change `entity` to `model` and remove the `=psl` and `psl=` tags. If you had the following in the `.wasp` file: + ```wasp title="main.wasp" entity Task {=psl // Stays the same @@ -253,6 +318,7 @@ psl=} ``` ... it would look like this in the `schema.prisma` file: + ```prisma title="schema.prisma" model Task { // Stays the same @@ -326,7 +392,6 @@ This command generates the Prisma client based on the `schema.prisma` file. Read more about the [Prisma Schema File](./data-model/prisma-file.md) and how Wasp uses it to generate the database schema and Prisma client. - ### Migrate how you access user auth fields We had to make a couple of breaking changes to reach the new simpler API.