+
+:::
+
+Next, let's copy the `fly.toml` file up to our Wasp project dir for safekeeping.
+```shell
+cp fly.toml ../../
+```
+
+Next, let's add a few more environment variables:
+
+```bash
+flyctl secrets set PORT=8080
+flyctl secrets set JWT_SECRET=+ What does it look like when your DB is deployed correctly? +
+
+ 
+
+When your DB is deployed correctly, you'll see it in the Fly.io dashboard:
+
+
+ Dockerfile
+ echo "$dockerignore_contents" > .dockerignore
+
+ railway up
+ ```
+
+ Make it executable with:
+
+ ```shell
+ chmod +x deploy_client.sh
+ ```
+
+ You can run it with:
+
+ ```shell
+ REACT_APP_API_URL= ./deploy_client.sh
+ ```
+
+
+ :::
+
+5. Set the `PORT` environment variable to `8043` under the `Variables` tab.
+
+6. Deploy the client and select `client` when prompted with `Select Service`:
+
+```shell
+railway up
+```
+
+#### Conclusion
+
+And now your Wasp should be deployed! π π π
+
+Back in your [Railway dashboard](https://railway.app/dashboard), click on your project and you should see your newly deployed services: PostgreSQL, Server, and Client.
+
+### Updates & Redeploying
+
+When you make updates and need to redeploy:
+
+- run `wasp build` to rebuild your app
+- run `railway up` in the `.wasp/build` directory (server)
+- repeat all the steps in the `.wasp/build/web-app` directory (client)
+
+## Heroku (server and database)
+
+We will show how to deploy the server and provision a database for it on Heroku.
+
+:::note
+Heroku used to offer free apps under certain limits. However, as of November 28, 2022, they ended support for their free tier. https://blog.heroku.com/next-chapter
+
+As such, we recommend using an alternative provider like [Fly.io](#flyio) for your first apps.
+:::
+
+You will need Heroku account, `heroku` [CLI](https://devcenter.heroku.com/articles/heroku-cli) and `docker` CLI installed to follow these instructions.
+
+Make sure you are logged in with `heroku` CLI. You can check if you are logged in with `heroku whoami`, and if you are not, you can log in with `heroku login`.
+
+### Set Up a Heroku App
+
+:::info
+You need to do this only once per Wasp app.
+:::
+
+Unless you want to deploy to an existing Heroku app, let's create a new Heroku app:
+
+```
+heroku create + Here's a useful shell script to do the process +
+ + If you want to automate the process, save the following as `deploy_client.sh` in the root of your project: + + ```bash title="deploy_client.sh" + #!/usr/bin/env bash + + if [ -z "$REACT_APP_API_URL" ] + then + echo "REACT_APP_API_URL is not set" + exit 1 + fi + + wasp build + cd .wasp/build/web-app + + npm install && REACT_APP_API_URL=$REACT_APP_API_URL npm run build + + cp -r build dist + + dockerfile_contents=$(cat <
+ ","ssl":{"rejectUnauthorized":false}}`. This is because pg-boss uses the `pg` extension, which does not seem to connect to Heroku over SSL by default, which Heroku requires. Additionally, Heroku uses a self-signed cert, so we must handle that as well.
+ - https://devcenter.heroku.com/articles/connecting-heroku-postgres#connecting-in-node-js
+
+
+
+ :::
+
+- `perform: dict` pg-boss details
+ + pg-boss provides many useful features, which can be found [here](https://github.com/timgit/pg-boss/blob/8.4.2/README.md). + + When you add pg-boss to a Wasp project, it will automatically add a new schema to your database called `pgboss` with some internal tracking tables, including `job` and `schedule`. pg-boss tables have a `name` column in most tables that will correspond to your Job identifier. Additionally, these tables maintain arguments, states, return values, retry information, start and expiration times, and other metadata required by pg-boss. + + If you need to customize the creation of the pg-boss instance, you can set an environment variable called `PG_BOSS_NEW_OPTIONS` to a stringified JSON object containing [these initialization parameters](https://github.com/timgit/pg-boss/blob/8.4.2/docs/readme.md#newoptions). **NOTE**: Setting this overwrites all Wasp defaults, so you must include database connection information as well. + + ### pg-boss considerations + - Wasp starts pg-boss alongside your web server's application, where both are simultaneously operational. This means that jobs running via pg-boss and the rest of the server logic (like Operations) share the CPU, therefore you should avoid running CPU-intensive tasks via jobs. + - Wasp does not (yet) support independent, horizontal scaling of pg-boss-only applications, nor starting them as separate workers/processes/threads. + - The job name/identifier in your `.wasp` file is the same name that will be used in the `name` column of pg-boss tables. If you change a name that had a `schedule` associated with it, pg-boss will continue scheduling those jobs but they will have no handlers associated, and will thus become stale and expire. To resolve this, you can remove the applicable row from the `schedule` table in the `pgboss` schema of your database. + - If you remove a `schedule` from a job, you will need to do the above as well. + - If you wish to deploy to Heroku, you need to set an additional environment variable called `PG_BOSS_NEW_OPTIONS` to `{"connectionString":"
+ {tasks.map((task) => (
+
+ {/* π All the params must be correctly passed in */}
+ {task.description}
+
+ ))}
+
+ )
+}
+```
+
+### Using Search Query & Hash
+
+You can also pass `search` and `hash` props to the `Link` component:
+
+```tsx title="TaskList.tsx"
+
+ {task.description}
+
+```
+
+This will result in a link like this: `/task/1?sortBy=date#comments`. Check out the [API Reference](#link-component) for more details.
+
+## The `routes` Object
+
+You can also get all the pages in your app with the `routes` object:
+
+```jsx title="TaskList.tsx"
+import { routes } from 'wasp/client/router'
+
+const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })
+```
+
+This will result in a link like this: `/task/1`.
+
+You can also pass `search` and `hash` props to the `build` function. Check out the [API Reference](#routes-object) for more details.
+
+
+## API Reference
+
+### `Link` Component
+
+The `Link` component accepts the following props:
+- `to` Chat {connectionIcon}
+
+
+
+
+ )
+}
+```
+- {messageList}
Chat {connectionIcon}
+
+
+
+
+ )
+}
+```
+- {messageList}
+ + Don't have an account yet? go to signup. + +
+ + Forgot your password? reset it + . + +
+ + I already have an account (go to login). + +
+ + If everything is okay, go to login + +
+ + If everything is okay, go to login + +
+
+ );
+}
+```
+
+
+
+
+ {children}
+ + + Don't have an account yet? go to signup. + +
+ + Forgot your password? reset it + . + +
+ + I already have an account (go to login). + +
+ + If everything is okay, go to login + +
+ + If everything is okay, go to login + +
+
+ );
+}
+```
+
+
+
+
+ {children}
+ Click the link below to verify your email
+ Verify email + `, + } + ); + } catch (e: unknown) { + console.error("Failed to send email verification email:", e); + throw new HttpError(500, "Failed to send email verification email."); + } + } + } catch (e) { + return { + success: false, + message: e.message, + } + } + + // Your custom code after sign-up. + // ... + + return { + success: true, + message: 'User created successfully', + } +} +``` +Click the link below to verify your email
+ Verify email + `, + } + ); + } catch (e: unknown) { + console.error("Failed to send email verification email:", e); + throw new HttpError(500, "Failed to send email verification email."); + } + } + } catch (e) { + return { + success: false, + message: e.message, + } + } + + // Your custom code after sign-up. + // ... + + return { + success: true, + message: 'User created successfully', + } +} +``` +Click the link below to verify your email
+ Verify email + `, + }) + ``` +Click the link below to verify your email
+ Verify email + `, + }) + ``` +Click the link below to reset your password
+ Reset password + `, + }) + ``` +Click the link below to reset your password
+ Reset password + `, + }) + ``` +
+
+
+
+Enabling auth for your app is optional and can be done by configuring the `auth` field of your `app` declaration:
+
+
+
+ {JSON.stringify(user, null, 2)}
+
+ )
+}
+
+export default AccountPage
+```
+
+
+
+ {JSON.stringify(user, null, 2)}
+
+ )
+}
+
+export default AccountPage
+```
+
+
+
+
+
+```js title="src/auth/signup.js"
+import { defineUserSignupFields } from 'wasp/server/auth'
+import * as z from 'zod'
+
+export const userSignupFields = defineUserSignupFields({
+ address: (data) => {
+ const AddressSchema = z
+ .string({
+ required_error: 'Address is required',
+ invalid_type_error: 'Address must be a string',
+ })
+ .min(10, 'Address must be at least 10 characters long')
+ const result = AddressSchema.safeParse(data.address)
+ if (result.success === false) {
+ throw new Error(result.error.issues[0].message)
+ }
+ return result.data
+ },
+})
+```
+
+
+
+
+```ts title="src/auth/signup.ts"
+import { defineUserSignupFields } from 'wasp/server/auth'
+import * as z from 'zod'
+
+export const userSignupFields = defineUserSignupFields({
+ address: (data) => {
+ const AddressSchema = z
+ .string({
+ required_error: 'Address is required',
+ invalid_type_error: 'Address must be a string',
+ })
+ .min(10, 'Address must be at least 10 characters long')
+ const result = AddressSchema.safeParse(data.address)
+ if (result.success === false) {
+ throw new Error(result.error.issues[0].message)
+ }
+ return result.data
+ },
+})
+```
+
+
+
+
+
+:::
+
+Now that we defined the fields, Wasp knows how to:
+
+1. Validate the data sent from the client
+2. Save the data to the database
+
+Next, let's see how to customize [Auth UI](../auth/ui) to include those fields.
+
+### 2. Customizing the Signup Component
+
+:::tip Using Custom Signup Component
+
+If you are not using Wasp's Auth UI, you can skip this section. Just make sure to include the extra fields in your custom signup form.
+
+Read more about using the signup actions for:
+
+- email auth [here](../auth/email#fields-in-the-email-dict)
+- username & password auth [here](../auth/username-and-pass#customizing-the-auth-flow)
+:::
+
+If you are using Wasp's Auth UI, you can customize the `SignupForm` component by passing the `additionalFields` prop to it. It can be either a list of extra fields or a render function.
+
+#### Using a List of Extra Fields
+
+When you pass in a list of extra fields to the `SignupForm`, they are added to the form one by one, in the order you pass them in.
+
+Inside the list, there can be either **objects** or **render functions** (you can combine them):
+
+1. Objects are a simple way to describe new fields you need, but a bit less flexible than render functions.
+2. Render functions can be used to render any UI you want, but they require a bit more code. The render functions receive the `react-hook-form` object and the form state object as arguments.
+
+Click to see the code
+ +
+ {authMethods.map((authMethod) => (
+
+ + Click on each provider for more details. +
+ + ) +} + +function AuthMethodBox({ + linkToDocs, + title, + description, +}: { + linkToDocs: string + title: string + description: string +}) { + return ( + +{title} Β»
+{description}
+ + ) +} diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_api-reference-intro.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_api-reference-intro.md new file mode 100644 index 0000000000..f9b90f022b --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_api-reference-intro.md @@ -0,0 +1,10 @@ +Provider-specific behavior comes down to implementing two functions. + +- `configFn` +- `userSignupFields` + +The reference shows how to define both. + +For behavior common to all providers, check the general [API Reference](../../auth/overview.md#api-reference). + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_default-behaviour.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_default-behaviour.md new file mode 100644 index 0000000000..a5e2462374 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_default-behaviour.md @@ -0,0 +1,3 @@ +When a user **signs in for the first time**, Wasp creates a new user account and links it to the chosen auth provider account for future logins. + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_getuserfields-type.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_getuserfields-type.md new file mode 100644 index 0000000000..091473d851 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_getuserfields-type.md @@ -0,0 +1,3 @@ +Wasp automatically generates the `defineUserSignupFields` function to help you correctly type your `userSignupFields` object. + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_override-example-intro.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_override-example-intro.md new file mode 100644 index 0000000000..5b89b83a92 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_override-example-intro.md @@ -0,0 +1,10 @@ +When a user logs in using a social login provider, the backend receives some data about the user. +Wasp lets you access this data inside the `userSignupFields` getters. + +For example, the User entity can include a `displayName` field which you can set based on the details received from the provider. + +Wasp also lets you customize the configuration of the providers' settings using the `configFn` function. + +Let's use this example to show both fields in action: + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_override-intro.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_override-intro.md new file mode 100644 index 0000000000..ea438c6fc2 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_override-intro.md @@ -0,0 +1,10 @@ +By default, Wasp doesn't store any information it receives from the social login provider. It only stores the user's ID specific to the provider. + +There are two mechanisms used for overriding the default behavior: + +- `userSignupFields` +- `configFn` + +Let's explore them in more detail. + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_using-auth-note.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_using-auth-note.md new file mode 100644 index 0000000000..7fe740be18 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_using-auth-note.md @@ -0,0 +1,3 @@ +To read more about how to set up the logout button and get access to the logged-in user in both client and server code, read the docs on [using auth](../../auth/overview). + + diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/_wasp-file-structure-note.md b/web/versioned_docs/version-0.13.11/auth/social-auth/_wasp-file-structure-note.md new file mode 100644 index 0000000000..b30c2c2daa --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/_wasp-file-structure-note.md @@ -0,0 +1,15 @@ +Here's a skeleton of how our `main.wasp` should look like after we're done: + +```wasp title="main.wasp" +// Configuring the social authentication +app myApp { + auth: { ... } +} + +// Defining entities +entity User { ... } + +// Defining routes and pages +route LoginRoute { ... } +page LoginPage { ... } +``` diff --git a/web/versioned_docs/version-0.13.11/auth/social-auth/github.md b/web/versioned_docs/version-0.13.11/auth/social-auth/github.md new file mode 100644 index 0000000000..f1359d0890 --- /dev/null +++ b/web/versioned_docs/version-0.13.11/auth/social-auth/github.md @@ -0,0 +1,562 @@ +--- +title: GitHub +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import DefaultBehaviour from './\_default-behaviour.md'; +import OverrideIntro from './\_override-intro.md'; +import OverrideExampleIntro from './\_override-example-intro.md'; +import UsingAuthNote from './\_using-auth-note.md'; +import WaspFileStructureNote from './\_wasp-file-structure-note.md'; +import GetUserFieldsType from './\_getuserfields-type.md'; +import ApiReferenceIntro from './\_api-reference-intro.md'; +import UserSignupFieldsExplainer from '../\_user-signup-fields-explainer.md'; + +Wasp supports Github Authentication out of the box. +GitHub is a great external auth choice when you're building apps for developers, as most of them already have a GitHub account. + +Letting your users log in using their GitHub accounts turns the signup process into a breeze. + +Let's walk through enabling Github Authentication, explain some of the default settings, and show how to override them. + +## Setting up Github Auth + +Enabling GitHub Authentication comes down to a series of steps: + +1. Enabling GitHub authentication in the Wasp file. +1. Adding the `User` entity. +1. Creating a GitHub OAuth app. +1. Adding the necessary Routes and Pages +1. Using Auth UI components in our Pages. + +
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+
+
+
+
+ {children}
+
+ 
+
diff --git a/web/versioned_docs/version-0.13.11/auth/username-and-pass.md b/web/versioned_docs/version-0.13.11/auth/username-and-pass.md
new file mode 100644
index 0000000000..1f6c5aff26
--- /dev/null
+++ b/web/versioned_docs/version-0.13.11/auth/username-and-pass.md
@@ -0,0 +1,723 @@
+---
+title: Username & Password
+---
+
+import { Required } from '@site/src/components/Tag';
+import MultipleIdentitiesWarning from './\_multiple-identities-warning.md';
+import ReadMoreAboutAuthEntities from './\_read-more-about-auth-entities.md';
+import GetUsername from './entities/\_get-username.md';
+import UserSignupFieldsExplainer from './\_user-signup-fields-explainer.md';
+import UserFieldsExplainer from './\_user-fields.md';
+
+Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.
+
+## Setting Up Username & Password Authentication
+
+To set up username authentication we need to:
+1. Enable username authentication in the Wasp file
+1. Add the `User` entity
+1. Add the auth routes and pages
+1. Use Auth UI components in our pages
+
+Structure of the `main.wasp` file we will end up with:
+
+```wasp title="main.wasp"
+// Configuring e-mail authentication
+app myApp {
+ auth: { ... }
+}
+// Defining User entity
+entity User { ... }
+// Defining routes and pages
+route SignupRoute { ... }
+page SignupPage { ... }
+// ...
+```
+
+### 1. Enable Username Authentication
+
+Let's start with adding the following to our `main.wasp` file:
+
+
++ + Don't have an account yet? go to signup. + +
+ + I already have an account (go to login). + +
+
+ );
+}
+```
+
+
+
+
+ {children}
+ + + Don't have an account yet? go to signup. + +
+ + I already have an account (go to login). + +
+
+ );
+}
+```
+
+
+
+
+ {children}
+ Loading...
+ if (error) return Error: {error.message}
+ return (
+
+
+ )
+}
+```
+
+
+ setTaskDescription(e.target.value)}
+ />
+
+
+ -
+ {tasks.map((task) => (
+
- {task.description} + ))} +
Loading...
+ if (error) return Error: {error.message}
+ return (
+
+
+ )
+}
+```
+
+
+ setTaskDescription(e.target.value)}
+ />
+
+
+ -
+ {tasks.map((task) => (
+
- {task.description} + ))} +
+
+ )
+}
+```
+
+
+ Create an account
+
+
+
+ )
+}
+```
+
+
+ Create an account
+
+
+
+ )
+}
+```
+
+
+
+ )
+}
+```
+
+"Loading"
+ } + + const { description, isDone } = task + return ( +
+
+ )
+}
+```
+
++ Description: + {description} +
++ Is done: + {isDone ? 'Yes' : 'No'} +
+ {isDone || ( + // highlight-next-line + + )} +"Loading"
+ } + + const { description, isDone } = task + return ( +
+
+ )
+}
+```
+
++ Description: + {description} +
++ Is done: + {isDone ? 'Yes' : 'No'} +
+ {isDone || ( + // highlight-next-line + + )} +"Loading"
+ } + + const { description, isDone } = task + return ( +
+
+ )
+}
+
+export default TaskPage
+```
+
++ Description: + {description} +
++ Is done: + {isDone ? 'Yes' : 'No'} +
+ {isDone || ( + + )} +"Loading"
; + } + + const { description, isDone } = task; + return ( +
+
+ );
+};
+
+export default TaskPage;
+```
+
++ Description: + {description} +
++ Is done: + {isDone ? "Yes" : "No"} +
+ {isDone || ( + + )} +There was an error
+ }
+
+ return (
+
+
+ )
+}
+
+const Task = ({ description, isDone }: Task) => {
+ return (
+ All Tasks
+ {allTasks && allTasks.length > 0 + ? allTasks.map((task) =>Finished Tasks
+ {doneTasks && doneTasks.length > 0 + ? doneTasks.map((task) =>
+
+ )
+}
+
+export default MainPage
+```
+
++ Description: + {description} +
++ Is done: + {isDone ? 'Yes' : 'No'} +
+There was an error
+ }
+
+ return (
+
+
+ )
+}
+
+const Task = ({ description, isDone }: Task) => {
+ return (
+ All Tasks
+ {allTasks && allTasks.length > 0 + ? allTasks.map((task) =>Finished Tasks
+ {doneTasks && doneTasks.length > 0 + ? doneTasks.map((task) =>
+
+ )
+}
+
+export default MainPage
+```
+
+Notice how you don't need to annotate the Query's return value type. Wasp automatically infers the from the Query's backend implementation. This is **full-stack type safety**: the types on the client always match the types on the server.
+
++ Description: + {description} +
++ Is done: + {isDone ? 'Yes' : 'No'} +
+Loading...
;
+ }
+
+ return (
+
+
+ );
+}
+```
+
+And voila! We are listing all the recipes in our app π
+
+This was just a quick example to give you a taste of what Wasp is. For step by step tour through the most important Wasp features, check out the [Todo app tutorial](../tutorial/01-create.md).
+
+:::note
+Above we skipped defining `/login` and `/signup` pages to keep the example a bit shorter, but those are very simple to do by using Wasp's Auth UI feature.
+:::
+
+## When to use Wasp
+Wasp is addressing the same core problems that typical web app frameworks are addressing, and it in big part [looks, swims and quacks](https://en.wikipedia.org/wiki/Duck_test) like a web app framework.
+
+### Best used for
+- building full-stack web apps (like e.g. Airbnb or Asana)
+- quickly starting a web app with industry best practices
+- to be used alongside modern web dev stack (currently supported React and Node)
+
+### Avoid using Wasp for
+- building static/presentational websites
+- to be used as a no-code solution
+- to be a solve-it-all tool in a single language
+
+## Wasp is a DSL
+
+:::note
+You don't need to know what a DSL is to use Wasp, but if you are curious, you can read more about it below.
+:::
+
+Wasp does not match typical expectations of a web app framework: it is not a set of libraries, it is instead a simple programming language that understands your code and can do a lot of things for you.
+
+Wasp is a programming language, but a specific kind: it is specialized for a single purpose: **building modern web applications**. We call such languages *DSL*s (Domain Specific Language).
+
+Other examples of *DSL*s that are often used today are e.g. *SQL* for databases and *HTML* for web page layouts.
+The main advantage and reason why *DSL*s exist is that they need to do only one task (e.g. database queries)
+so they can do it well and provide the best possible experience for the developer.
+
+The same idea stands behind Wasp - a language that will allow developers to **build modern web applications with 10x less code and less stack-specific knowledge**.
diff --git a/web/versioned_docs/version-0.13.11/introduction/quick-start.md b/web/versioned_docs/version-0.13.11/introduction/quick-start.md
new file mode 100644
index 0000000000..e33552e164
--- /dev/null
+++ b/web/versioned_docs/version-0.13.11/introduction/quick-start.md
@@ -0,0 +1,150 @@
+---
+title: Quick Start
+slug: /quick-start
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+## Installation
+
+Welcome, new Waspeteer π!
+
+Let's create and run our first Wasp app in 3 short steps:
+
+1. **To install Wasp on Linux / OSX / WSL (Windows), open your terminal and run:**
+
+ ```shell
+ curl -sSL https://get.wasp-lang.dev/installer.sh | sh
+ ```
+
+ βΉοΈ Wasp requires Node.js and will warn you if it is missing: check below for [more details](#requirements).
+
+2. **Then, create a new app by running:**
+
+ ```shell
+ wasp new
+ ```
+
+3. **Finally, run the app:**
+
+ ```shell
+ cd Recipes
+-
+ {recipes ? recipes.map((recipe) => (
+
-
+ {recipe.title}+{recipe.description}+
+ )) : 'No recipes defined yet!'}
+
+
+
+
+### Installation
+
++ A quick guide on installing/using nvm +
+
+
+ Install nvm via your OS package manager (`apt`, `pacman`, `homebrew`, ...) or via the [nvm](https://github.com/nvm-sh/nvm#install--update-script) install script.
+
+ Then, install a version of Node.js that you need:
+ ```shell
+ nvm install 20
+ ```
+
+ Finally, whenever you need to ensure a specific version of Node.js is used, run:
+ ```shell
+ nvm use 20
+ ```
+ to set the Node.js version for the current shell session.
+
+ You can run
+ ```shell
+ node -v
+ ```
+ to check the version of Node.js currently being used in this shell session.
+
+ Check NVM repo for more details: https://github.com/nvm-sh/nvm.
+
+
+
+
+
+That's it! You now have a properly structured Wasp 0.12.0 project in the `foo` directory.
+Your app probably doesn't quite work yet due to some other changes in Wasp 0.12.0, but we'll get to that in the next sections.
+
+### Migrating declaration names
+Wasp 0.12.0 adds a casing constraints when naming Queries, Actions, Jobs, and Entities in the `main.wasp` file.
+
+The following casing conventions have now become mandatory:
+- Operation (i.e., Query and Action) names must begin with a lowercase letter: `query getTasks {...}`, `action createTask {...}`.
+- Job names must begin with a lowercase letter: `job sendReport {...}`.
+- Entity names must start with an uppercase letter: `entity Task {...}`.
+
+### Migrating the Tailwind Setup
+
+:::note
+If you don't use Tailwind in your project, you can skip this section.
+:::
+
+There is a small change in how the `tailwind.config.cjs` needs to be defined in Wasp 0.12.0.
+
+You'll need to wrap all your paths in the `content` field with the `resolveProjectPath` function. This makes sure that the paths are resolved correctly when generating your CSS.
+
+Here's how you can do it:
+
++ In case the migration script doesn't work well for you, you can do the same steps manually, as described here: +
+
+
+1. Rename your project's root directory to something like `foo_old`.
+2. Create a new project by running `wasp new foo`.
+3. Delete all files of `foo/src` except `vite-env.d.ts`.
+4. If `foo_old/src/client/public` exists and contains any files, copy those files into
+ `foo/public`.
+5. Copy the contents of `foo_old/src` into `foo/src`.
+ `foo/src` should now contain `vite-env.d.ts`, `.waspignore`, and three subdirectories (`server`, `client`, and `shared`).
+ Don't change anything about this structure yet.
+6. Delete redundant files and folders from `foo/src`:
+ - `foo/src/.waspignore` - A new version of this file already exists at the top level.
+ - `foo/src/client/vite-env.d.ts` - A new version of this file already exists at the top level.
+ - `foo/src/client/tsconfig.json` - A new version of this file already exists at the top level.
+ - `foo/src/server/tsconfig.json` - A new version of this file already exists at the top level.
+ - `foo/src/shared/tsconfig.json` - A new version of this file already exists at the top level.
+ - `foo/src/client/public` - You've moved all the files from this directory in step 5.
+7. Update all the `@wasp` imports in your JS(X)/TS(X) source files in the `src/` dir.
+
+ For this, we prepared a special script that will rewrite these imports automatically for you.
+
+ Before doing this step, as the script will modify your JS(X)/TS(X) files in place, we advise committing
+ all changes you have so far, so you can then both easily inspect the import rewrites that our
+ script did (with `git diff`) and also revert them if something went wrong.
+
+ To run the import-rewriting script, make sure you are in the root dir of your wasp project, and then run
+ ```
+ npx jscodeshift@0.15.1 -t https://raw.githubusercontent.com/wasp-lang/wasp-codemod/main/src/transforms/imports-from-0-11-to-0-12.ts --extensions=js,ts,jsx,tsx src/
+ ```
+
+ Then, check the changes it did, in case some kind of manual intervention is needed (in which case you should see TODO comments generated by the script).
+
+ Alternatively, you can find all the mappings of old imports to the new ones in [this table](https://docs.google.com/spreadsheets/d/1QW-_16KRGTOaKXx9NYUtjk6m2TQ0nUMOA74hBthTH3g/edit#gid=1725669920) and use it to fix some/all of them manually.
+8. Replace the Wasp file in `foo` (i.e., `main.wasp`) with the Wasp file from `foo_old`
+9. Change the Wasp version field in your Wasp file (now residing in `foo`) to `"^0.12.0"`.
+10. Correct external imports in your Wasp file (now residing in `foo`).
+ imports. You can do this by running search-and-replace inside the file:
+
+ - Change all occurrences of `@server` to `@src/server`
+ - Change all occurrences of `@client` to `@src/client`
+
+ For example, if you previously had something like:
+
+ ```js
+ page LoginPage {
+ // highlight-next-line
+ // This previously resolved to src/client/LoginPage.js
+ // highlight-next-line
+ component: import Login from "@client/LoginPage"
+ }
+
+ // ...
+
+ query getTasks {
+ // highlight-next-line
+ // This previously resolved to src/server/queries.js
+ // highlight-next-line
+ fn: import { getTasks } from "@server/queries.js",
+ }
+ ```
+
+ You should change it to:
+
+ ```js
+ page LoginPage {
+ // highlight-next-line
+ // This now resolves to src/client/LoginPage.js
+ // highlight-next-line
+ component: import Login from "@src/client/LoginPage"
+ }
+
+ // ...
+
+ query getTasks {
+ // highlight-next-line
+ // This now resolves to src/server/queries.js
+ // highlight-next-line
+ fn: import { getTasks } from "@src/server/queries.js",
+ }
+ ```
+
+ Do this for all external imports in your `.wasp` file. After you're done, there shouldn't be any occurrences of strings `"@server"` or `"@client"`
+
+11. Take all the dependencies from `app.dependencies` declaration in
+ `foo/main.wasp` and move them to `foo/package.json`. Make sure to remove the `app.dependencies` field from `foo/main.wasp`.
+
+ For example, if `foo_old/main.wasp` had:
+
+ ```css
+ app Foo {
+ // ...
+ dependencies: [ ('redux', '^4.0.5'), ('reacjt-redux', '^7.1.3')];
+ }
+ ```
+
+ Your `package.json` in `foo` should now list these dependencies (Wasp already generated most of the file, you just have to list additional dependencies).
+
+ ```json
+ {
+ "name": "foo",
+ "dependencies": {
+ "wasp": "file:.wasp/out/sdk/wasp",
+ "react": "^18.2.0",
+ // highlight-next-line
+ "redux": "^4.0.5",
+ // highlight-next-line
+ "reactjs-redux": "^7.1.3"
+ },
+ "devDependencies": {
+ "typescript": "^5.1.0",
+ "vite": "^4.3.9",
+ "@types/react": "^18.0.37",
+ "prisma": "4.16.2"
+ }
+ }
+ ```
+
+12. Copy all lines you might have added to `foo_old/.gitignore` into
+ `foo/.gitignore`
+13. Copy the rest of the top-level files and folders (all of them except for `.gitignore`, `main.wasp` and `src/`)
+ in `foo_old/` into `foo/` (overwrite the existing files in `foo`).
+14. Run `wasp clean` in `foo`.
+15. Delete the `foo_old` directory.
+
+
+
+ Migration for
+
+ First, move the value of `auth.signup.additionalFields` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
+
+ `{method}` depends on the auth method you are using. For example, if you are using the email auth method, you should move the `auth.signup.additionalFields` to `auth.methods.email.userSignupFields`.
+
+ To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` instead of `defineAdditionalSignupFields` from `@wasp/auth/index.js`.
+
+
+
+
+ ```wasp title="main.wasp"
+ app crudTesting {
+ // ...
+ auth: {
+ userEntity: User,
+ methods: {
+ email: {},
+ },
+ onAuthFailedRedirectTo: "/login",
+ // highlight-start
+ signup: {
+ additionalFields: import { fields } from "@server/auth/signup.js",
+ },
+ // highlight-end
+ },
+ }
+ ```
+
+ ```ts title="src/server/auth/signup.ts"
+ // highlight-next-line
+ import { defineAdditionalSignupFields } from '@wasp/auth/index.js'
+
+ // highlight-next-line
+ export const fields = defineAdditionalSignupFields({
+ address: async (data) => {
+ const address = data.address
+ if (typeof address !== 'string') {
+ throw new Error('Address is required')
+ }
+ if (address.length < 5) {
+ throw new Error('Address must be at least 5 characters long')
+ }
+ return address
+ },
+ })
+ ```
+
+
+
+
+
+ ```wasp title="main.wasp"
+ app crudTesting {
+ // ...
+ auth: {
+ userEntity: User,
+ methods: {
+ email: {
+ // highlight-next-line
+ userSignupFields: import { fields } from "@src/server/auth/signup.js",
+ },
+ },
+ onAuthFailedRedirectTo: "/login",
+ },
+ }
+ ```
+
+ ```ts title="src/server/auth/signup.ts"
+ // highlight-next-line
+ import { defineUserSignupFields } from 'wasp/server/auth'
+
+ // highlight-next-line
+ export const fields = defineUserSignupFields({
+ address: async (data) => {
+ const address = data.address;
+ if (typeof address !== 'string') {
+ throw new Error('Address is required');
+ }
+ if (address.length < 5) {
+ throw new Error('Address must be at least 5 characters long');
+ }
+ return address;
+ },
+ })
+ ```
+
+ Read more about the `userSignupFields` function [here](/auth/overview.md#1-defining-extra-fields).
+
+
+
+
+
+
+ Migration for
+
+ First, move the value of `auth.signup.additionalFields` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
+
+ `{method}` depends on the auth method you are using. For example, if you are using the email auth method, you should move the `auth.signup.additionalFields` to `auth.methods.email.userSignupFields`.
+
+ To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` instead of `defineAdditionalSignupFields` from `@wasp/auth/index.js`.
+
+
+ Migration for
+
+ First, move the value of `auth.methods.{method}.getUserFieldsFn` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
+
+ `{method}` depends on the auth method you are using. For example, if you are using Google auth, you should move the `auth.methods.google.getUserFieldsFn` to `auth.methods.google.userSignupFields`.
+
+ To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` and modify the code to return the fields in the format that `defineUserSignupFields` expects.
+
+
+
+
+ ```wasp title="main.wasp"
+ app crudTesting {
+ // ...
+ auth: {
+ userEntity: User,
+ methods: {
+ google: {
+ // highlight-next-line
+ getUserFieldsFn: import { getUserFields } from "@server/auth/google.js"
+ },
+ },
+ onAuthFailedRedirectTo: "/login",
+ },
+ }
+ ```
+
+ ```ts title="src/server/auth/google.ts"
+ // highlight-next-line
+ import type { GetUserFieldsFn } from '@wasp/types'
+
+ // highlight-start
+ export const getUserFields: GetUserFieldsFn = async (_context, args) => {
+ const displayName = args.profile.displayName
+ return { displayName }
+ }
+ // highlight-end
+ ```
+
+
+
+
+
+ ```wasp title="main.wasp"
+ app crudTesting {
+ // ...
+ auth: {
+ userEntity: User,
+ methods: {
+ google: {
+ // highlight-next-line
+ userSignupFields: import { fields } from "@src/server/auth/google.js",
+ },
+ },
+ onAuthFailedRedirectTo: "/login",
+ },
+ }
+ ```
+
+ ```ts title="src/server/auth/signup.ts"
+ // highlight-next-line
+ import { defineUserSignupFields } from 'wasp/server/auth'
+
+ // highlight-start
+ export const fields = defineUserSignupFields({
+ displayName: async (data) => {
+ const profile: any = data.profile;
+ if (!profile?.displayName) { throw new Error('Display name is not available'); }
+ return profile.displayName;
+ },
+ })
+ // highlight-end
+ ```
+
+ If you want to properly type the `profile` object, we recommend you use a validation library like Zod to define the shape of the `profile` object.
+
+ Read more about this and the `defineUserSignupFields` function in the [Auth Overview - Defining Extra Fields](./auth/overview.md#1-defining-extra-fields) section.
+
+
+
+
+
+
+1. **Remove the `auth.methods.email.allowUnverifiedLogin` field** from your `main.wasp` file.
+
+ In Wasp 0.12.X we removed the `auth.methods.email.allowUnverifiedLogin` field to make our Email auth implementation easier to reason about. If you were using it, you should remove it from your `main.wasp` file.
+
+1. Ensure your **local development database is running**.
+1. **Do the schema migration** (create the new auth tables in the database) by running:
+ ```bash
+ wasp db migrate-dev
+ ```
+You should see the new `Auth`, `AuthIdentity` and `Session` tables in your database. You can use the `wasp db studio` command to open the database in a GUI and verify the tables are there. At the moment, they will be empty.
+1. **Do the data migration** (move existing users from the old auth system to the new one by filling the new auth tables in the database with their data):
+
+ 1. **Implement your data migration function(s)** in e.g. `src/migrateToNewAuth.ts`.
+
+ Below we prepared [examples of migration functions](#example-data-migration-functions) for each of the auth methods, for you to use as a starting point.
+ They should be fine to use as-is, meaning you can just copy them and they are likely to work out of the box for typical use cases, but you can also modify them for your needs.
+
+ We recommend you create one function per each auth method that you use in your app.
+
+ 1. **Define custom API endpoints for each migration function** you implemented.
+
+ With each data migration function below, we provided a relevant `api` declaration that you should add to your `main.wasp` file.
+
+ 1. **Run the data migration function(s)** on the local development database by calling the API endpoints you defined in the previous step.
+
+ You can call the endpoint by visiting the URL in your browser, or by using a tool like `curl` or Postman.
+
+ For example, if you defined the API endpoint at `/migrate-username-and-password`, you can call it by visiting `http://localhost:3001/migrate-username-and-password` in your browser.
+
+ This should be it, you can now run `wasp db studio` again and verify that there is now relevant data in the new auth tables (`Auth` and `AuthIdentity`; `Session` should still be empty for now).
+
+1. **Verify that the basic auth functionality works** by running `wasp start` and successfully signing up / logging in with each of the auth methods.
+1. **Update your JS/TS code** to work correctly with the new auth.
+
+ You might want to use the new auth helper functions to get the `email` or `username` from a user object. For example, `user.username` might not work anymore for you, since the `username` obtained by the Username & Password auth method isn't stored on the `User` entity anymore (unless you are explicitly storing something into `user.username`, e.g. via `userSignupFields` for a social auth method like Github). Same goes for `email` from Email auth method.
+
+ Instead, you can now use `getUsername(user)` to get the username obtained from Username & Password auth method, or `getEmail(user)` to get the email obtained from Email auth method.
+
+ Read more about the helpers in the [Auth Entities - Accessing the Auth Fields](auth/entities#accessing-the-auth-fields) section.
+1. Finally, **check that your app now fully works as it worked before**. If all the above steps were done correctly, everything should be working now.
+
+ :::info Migrating a deployed app
+
+ After successfully performing migration locally so far, and verifying that your app works as expected, it is time to also migrate our deployed app.
+
+ Before migrating your production (deployed) app, we advise you to back up your production database in case something goes wrong. Also, besides testing it in development, it's good to test the migration in a staging environment if you have one.
+
+ We will perform the production migration in 2 steps:
+ - Deploying the new code to production (client and server).
+ - Migrating the production database data.
+
+ ---
+
+ Between these two steps, so after successfully deploying the new code to production and before migrating the production database data, your app will not be working completely: new users will be able to sign up, but existing users won't be able to log in, and already logged in users will be logged out. Once you do the second step, migrating the production database data, it will all be back to normal. You will likely want to keep the time between the two steps as short as you can.
+
+ ---
+
+ - **First step: deploy the new code** (client and server), either via `wasp deploy` (i.e. `wasp deploy fly deploy`) or manually.
+
+ Check our [Deployment docs](advanced/deployment/overview.md) for more details.
+
+ - **Second step: run the data migration functions** on the production database.
+
+ You can do this by calling the API endpoints you defined in the previous step, just like you did locally. You can call the endpoint by visiting the URL in your browser, or by using a tool like `curl` or Postman.
+
+ For example, if you defined the API endpoint at `/migrate-username-and-password`, you can call it by visiting `https://your-server-url.com/migrate-username-and-password` in your browser.
+
+ Your deployed app should be working normally now, with the new auth system.
+ :::
+
+
+#### 2. Cleanup the Old Auth System
+
+Your app should be working correctly and using new auth, but to finish the migration, we need to clean up the old auth system:
+
+1. In `main.wasp` file, **delete auth-related fields from the `User` entity**, since with 0.12 they got moved to the internal Wasp entity `AuthIdentity`.
+
+ - This means any fields that were required by Wasp for authentication, like `email`, `password`, `isEmailVerified`, `emailVerificationSentAt`, `passwordResetSentAt`, `username`, etc.
+ - There are situations in which you might want to keep some of them, e.g. `email` and/or `username`, if they are still relevant for you due to your custom logic (e.g. you are populating them with `userSignupFields` upon social signup in order to have this info easily available on the `User` entity). Note that they won't be used by Wasp Auth anymore, they are here just for your business logic.
+
+1. In `main.wasp` file, **remove the `externalAuthEntity` field from the `app.auth`** and also **remove the whole `SocialLogin` entity** if you used Google or GitHub auth.
+1. **Delete the data migration function(s)** you implemented earlier (e.g. in `src/migrateToNewAuth.ts`) and also the corresponding API endpoints from the `main.wasp` file.
+1. **Run `wasp db migrate-dev`** again to apply these changes and remove the redundant fields from the database.
+
+:::info Migrating a deployed app
+
+ After doing the steps above successfully locally and making sure everything is working, it is time to push these changes to the deployed app again.
+
+ _Deploy the app again_, either via `wasp deploy` or manually. Check our [Deployment docs](advanced/deployment/overview.md) for more details.
+
+ The database migrations will automatically run on successful deployment of the server and delete the now redundant auth-related `User` columns from the database.
+
+ Your app is now fully migrated to the new auth system.
+
+:::
+
+### Next Steps
+
+If you made it this far, you've completed all the necessary steps to get your
+Wasp app working with Wasp 0.12.x. Nice work!
+
+Finally, since Wasp no longer requires you to separate your client source files
+(previously in `src/client`) from server source files (previously in
+`src/server`), you are now free to reorganize your project however you think is best,
+as long as you keep all the source files in the `src/` directory.
+
+This section is optional, but if you didn't like the server/client
+separation, now's the perfect time to change it.
+
+For example, if your `src` dir looked like this:
+
+```
+src
+β
+βββ client
+βΒ Β βββ Dashboard.tsx
+βΒ Β βββ Login.tsx
+βΒ Β βββ MainPage.tsx
+βΒ Β βββ Register.tsx
+βΒ Β βββ Task.css
+βΒ Β βββ TaskLisk.tsx
+βΒ Β βββ Task.tsx
+βΒ Β βββ User.tsx
+βββ server
+βΒ Β βββ taskActions.ts
+βΒ Β βββ taskQueries.ts
+βΒ Β βββ userActions.ts
+βΒ Β βββ userQueries.ts
+βββ shared
+ βββ utils.ts
+```
+
+you can now change it to a feature-based structure (which we recommend for any project that is not very small):
+
+```
+src
+β
+βββ task
+βΒ Β βββ actions.ts -- former taskActions.ts
+βΒ Β βββ queries.ts -- former taskQueries.ts
+βΒ Β βββ Task.css
+βΒ Β βββ TaskLisk.tsx
+βΒ Β βββ Task.tsx
+βββ user
+βΒ Β βββ actions.ts -- former userActions.ts
+βΒ Β βββ Dashboard.tsx
+βΒ Β βββ Login.tsx
+βΒ Β βββ queries.ts -- former userQueries.ts
+βΒ Β βββ Register.tsx
+βΒ Β βββ User.tsx
+βββ MainPage.tsx
+βββ utils.ts
+```
+
+
+## Appendix
+
+### Example Data Migration Functions
+
+The migration functions provided below are written with the typical use cases in mind and you can use them as-is. If your setup requires additional logic, you can use them as a good starting point and modify them to your needs.
+
+Note that all of the functions below are written to be idempotent, meaning that running a function multiple times can't hurt. This allows executing a function again in case only a part of the previous execution succeeded and also means that accidentally running it one time too much won't have any negative effects. **We recommend you keep your data migration functions idempotent**.
+
+#### Username & Password
+
+To successfully migrate the users using the Username & Password auth method, you will need to do two things:
+1. Migrate the user data
+
+ Migration for
+
+ First, move the value of `auth.methods.{method}.getUserFieldsFn` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
+
+ `{method}` depends on the auth method you are using. For example, if you are using Google auth, you should move the `auth.methods.google.getUserFieldsFn` to `auth.methods.google.userSignupFields`.
+
+ To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` and modify the code to return the fields in the format that `defineUserSignupFields` expects.
+
+
+
+
+2. Provide a way for users to migrate their password
+
+ There is a **breaking change between the old and the new auth in the way the password is hashed**. This means that users will need to migrate their password after the migration, as the old password will no longer work.
+
+ Since the only way users using username and password as a login method can verify their identity is by providing both their username and password (there is no email or any other info, unless you asked for it and stored it explicitly), we need to provide them a way to **exchange their old password for a new password**. One way to handle this is to inform them about the need to migrate their password (on the login page) and provide a custom page to migrate the password.
+
+Username & Password data migration function
+ + ```wasp title="main.wasp" + api migrateUsernameAndPassword { + httpRoute: (GET, "/migrate-username-and-password"), + fn: import { migrateUsernameAndPasswordHandler } from "@src/migrateToNewAuth", + entities: [] + } + ``` + + ```ts title="src/migrateToNewAuth.ts" + import { prisma } from "wasp/server"; + import { type ProviderName, type UsernameProviderData } from "wasp/server/auth"; + import { MigrateUsernameAndPassword } from "wasp/server/api"; + + export const migrateUsernameAndPasswordHandler: MigrateUsernameAndPassword = + async (_req, res) => { + const result = await migrateUsernameAuth(); + + res.status(200).json({ message: "Migrated users to the new auth", result }); + }; + + async function migrateUsernameAuth(): Promise<{ + numUsersAlreadyMigrated: number; + numUsersNotUsingThisAuthMethod: number; + numUsersMigratedSuccessfully: number; + }> { + const users = await prisma.user.findMany({ + include: { + auth: true, + }, + }); + + const result = { + numUsersAlreadyMigrated: 0, + numUsersNotUsingThisAuthMethod: 0, + numUsersMigratedSuccessfully: 0, + }; + + for (const user of users) { + if (user.auth) { + result.numUsersAlreadyMigrated++; + console.log("Skipping user (already migrated) with id:", user.id); + continue; + } + + if (!user.username || !user.password) { + result.numUsersNotUsingThisAuthMethod++; + console.log("Skipping user (not using username auth) with id:", user.id); + continue; + } + + const providerData: UsernameProviderData = { + hashedPassword: user.password, + }; + const providerName: ProviderName = "username"; + + await prisma.auth.create({ + data: { + identities: { + create: { + providerName, + providerUserId: user.username.toLowerCase(), + providerData: JSON.stringify(providerData), + }, + }, + user: { + connect: { + id: user.id, + }, + }, + }, + }); + result.numUsersMigratedSuccessfully++; + } + + return result; + } + ``` + +
+
+
+
+```wasp title="main.wasp"
+route MigratePasswordRoute { path: "/migrate-password", to: MigratePassword }
+page MigratePassword {
+ component: import { MigratePasswordPage } from "@src/pages/MigratePassword"
+}
+```
+
+```jsx title="src/pages/MigratePassword.jsx"
+import {
+ FormItemGroup,
+ FormLabel,
+ FormInput,
+ FormError,
+} from "wasp/client/auth";
+import { useForm } from "react-hook-form";
+import { migratePassword } from "wasp/client/operations";
+import { useState } from "react";
+
+export function MigratePasswordPage() {
+ const [successMessage, setSuccessMessage] = useState(null);
+ const [errorMessage, setErrorMessage] = useState(null);
+ const form = useForm();
+
+ const onSubmit = form.handleSubmit(async (data) => {
+ try {
+ const result = await migratePassword(data);
+ setSuccessMessage(result.message);
+ } catch (e) {
+ console.error(e);
+ if (e instanceof Error) {
+ setErrorMessage(e.message);
+ }
+ }
+ });
+
+ return (
+
+
+
+```wasp title="main.wasp"
+route MigratePasswordRoute { path: "/migrate-password", to: MigratePassword }
+page MigratePassword {
+ component: import { MigratePasswordPage } from "@src/pages/MigratePassword"
+}
+```
+
+```tsx title="src/pages/MigratePassword.tsx"
+import {
+ FormItemGroup,
+ FormLabel,
+ FormInput,
+ FormError,
+} from "wasp/client/auth";
+import { useForm } from "react-hook-form";
+import { migratePassword } from "wasp/client/operations";
+import { useState } from "react";
+
+export function MigratePasswordPage() {
+ const [successMessage, setSuccessMessage] = useState(null);
+ const [errorMessage, setErrorMessage] = useState(null);
+ const form = useForm<{
+ username: string;
+ password: string;
+ }>();
+
+ const onSubmit = form.handleSubmit(async (data) => {
+ try {
+ const result = await migratePassword(data);
+ setSuccessMessage(result.message);
+ } catch (e: unknown) {
+ console.error(e);
+ if (e instanceof Error) {
+ setErrorMessage(e.message);
+ }
+ }
+ });
+
+ return (
+
+
+
+ 3. Finally, you will need to create a new operation in your app to handle the password migration. You can use the following code as a starting point:
+
+
+
+
+
+```wasp title="main.wasp"
+action migratePassword {
+ fn: import { migratePassword } from "@src/auth",
+ entities: []
+}
+```
+
+```js title="src/auth.js"
+import SecurePassword from "secure-password";
+import { HttpError } from "wasp/server";
+import {
+ createProviderId,
+ deserializeAndSanitizeProviderData,
+ findAuthIdentity,
+ updateAuthIdentityProviderData,
+} from "wasp/server/auth";
+
+export const migratePassword = async ({ password, username }, _context) => {
+ const providerId = createProviderId("username", username);
+ const authIdentity = await findAuthIdentity(providerId);
+
+ if (!authIdentity) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ const providerData = deserializeAndSanitizeProviderData(
+ authIdentity.providerData
+ );
+
+ try {
+ const SP = new SecurePassword();
+
+ // This will verify the password using the old algorithm
+ const result = await SP.verify(
+ Buffer.from(password),
+ Buffer.from(providerData.hashedPassword, "base64")
+ );
+
+ if (result !== SecurePassword.VALID) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ // This will hash the password using the new algorithm and update the
+ // provider data in the database.
+ await updateAuthIdentityProviderData(providerId, providerData, {
+ hashedPassword: password,
+ });
+ } catch (e) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ return {
+ message: "Password migrated successfully.",
+ };
+};
+```
+
+
+
+
+```wasp title="main.wasp"
+action migratePassword {
+ fn: import { migratePassword } from "@src/auth",
+ entities: []
+}
+```
+
+```ts title="src/auth.ts"
+import SecurePassword from "secure-password";
+import { HttpError } from "wasp/server";
+import {
+ createProviderId,
+ deserializeAndSanitizeProviderData,
+ findAuthIdentity,
+ updateAuthIdentityProviderData,
+} from "wasp/server/auth";
+import { MigratePassword } from "wasp/server/operations";
+
+type MigratePasswordInput = {
+ username: string;
+ password: string;
+};
+type MigratePasswordOutput = {
+ message: string;
+};
+
+export const migratePassword: MigratePassword<
+ MigratePasswordInput,
+ MigratePasswordOutput
+> = async ({ password, username }, _context) => {
+ const providerId = createProviderId("username", username);
+ const authIdentity = await findAuthIdentity(providerId);
+
+ if (!authIdentity) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ const providerData = deserializeAndSanitizeProviderData<"username">(
+ authIdentity.providerData
+ );
+
+ try {
+ const SP = new SecurePassword();
+
+ // This will verify the password using the old algorithm
+ const result = await SP.verify(
+ Buffer.from(password),
+ Buffer.from(providerData.hashedPassword, "base64")
+ );
+
+ if (result !== SecurePassword.VALID) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ // This will hash the password using the new algorithm and update the
+ // provider data in the database.
+ await updateAuthIdentityProviderData<"username">(providerId, providerData, {
+ hashedPassword: password,
+ });
+ } catch (e) {
+ throw new HttpError(400, "Something went wrong");
+ }
+
+ return {
+ message: "Password migrated successfully.",
+ };
+};
+```
+
+
+
+
+
+
+
+#### Email
+
+To successfully migrate the users using the Email auth method, you will need to do two things:
+1. Migrate the user data
+
+ + Steps to create a custom page for migrating the password +
+ + 1. You will need to install the `secure-password` and `sodium-native` packages to use the old hashing algorithm: + + ```bash + npm install secure-password@4.0.0 sodium-native@3.3.0 --save-exact + ``` + + Make sure to save the exact versions of the packages. + + 2. Then you'll need to create a new page in your app where users can migrate their password. You can use the following code as a starting point: + +
+ {errorMessage} }
+
+
+ );
+}
+```
+
+Migrate your password
++ If you have an account on the old version of the website, you can + migrate your password to the new version. +
+ {successMessage &&{successMessage}
}
+ {errorMessage &&
+ {errorMessage} }
+
+
+ );
+}
+```
+
+Migrate your password
++ If you have an account on the old version of the website, you can + migrate your password to the new version. +
+ {successMessage &&{successMessage}
}
+ {errorMessage &&
+
+
+2. Ask the users to reset their password
+
+ There is a **breaking change between the old and the new auth in the way the password is hashed**. This means that users will need to reset their password after the migration, as the old password will no longer work.
+
+ It would be best to notify your users about this change and put a notice on your login page to **request a password reset**.
+
+#### Google & GitHub
+
+Email data migration function
+ + ```wasp title="main.wasp" + api migrateEmail { + httpRoute: (GET, "/migrate-email"), + fn: import { migrateEmailHandler } from "@src/migrateToNewAuth", + entities: [] + } + ``` + + ```ts title="src/migrateToNewAuth.ts" + import { prisma } from "wasp/server"; + import { type ProviderName, type EmailProviderData } from "wasp/server/auth"; + import { MigrateEmail } from "wasp/server/api"; + + export const migrateEmailHandler: MigrateEmail = + async (_req, res) => { + const result = await migrateEmailAuth(); + + res.status(200).json({ message: "Migrated users to the new auth", result }); + }; + + async function migrateEmailAuth(): Promise<{ + numUsersAlreadyMigrated: number; + numUsersNotUsingThisAuthMethod: number; + numUsersMigratedSuccessfully: number; + }> { + const users = await prisma.user.findMany({ + include: { + auth: true, + }, + }); + + const result = { + numUsersAlreadyMigrated: 0, + numUsersNotUsingThisAuthMethod: 0, + numUsersMigratedSuccessfully: 0, + }; + + for (const user of users) { + if (user.auth) { + result.numUsersAlreadyMigrated++; + console.log("Skipping user (already migrated) with id:", user.id); + continue; + } + + if (!user.email || !user.password) { + result.numUsersNotUsingThisAuthMethod++; + console.log("Skipping user (not using email auth) with id:", user.id); + continue; + } + + const providerData: EmailProviderData = { + isEmailVerified: user.isEmailVerified, + emailVerificationSentAt: + user.emailVerificationSentAt?.toISOString() ?? null, + passwordResetSentAt: user.passwordResetSentAt?.toISOString() ?? null, + hashedPassword: user.password, + }; + const providerName: ProviderName = "email"; + + await prisma.auth.create({ + data: { + identities: { + create: { + providerName, + providerUserId: user.email, + providerData: JSON.stringify(providerData), + }, + }, + user: { + connect: { + id: user.id, + }, + }, + }, + }); + result.numUsersMigratedSuccessfully++; + } + + return result; + } + ``` + +
+
diff --git a/web/versioned_docs/version-0.13.11/migrate-from-0-12-to-0-13.md b/web/versioned_docs/version-0.13.11/migrate-from-0-12-to-0-13.md
new file mode 100644
index 0000000000..fb7e5d8270
--- /dev/null
+++ b/web/versioned_docs/version-0.13.11/migrate-from-0-12-to-0-13.md
@@ -0,0 +1,134 @@
+---
+title: Migration from 0.12.X to 0.13.X
+---
+
+:::note Are you on 0.11.X or earlier?
+
+This guide only covers the migration from **0.12.X to 0.13.X**. If you are migrating from 0.11.X or earlier, please read the [migration guide from 0.11.X to 0.12.X](./migrate-from-0-11-to-0-12.md) first.
+
+:::
+
+## What's new in 0.13.0?
+
+### OAuth providers got an overhaul
+
+Wasp 0.13.0 switches away from using Passport for our OAuth providers in favor of [Arctic](https://arctic.js.org/) from the [Lucia](https://lucia-auth.com/) ecosystem. This change simplifies the codebase and makes it easier to add new OAuth providers in the future.
+
+### We added Keycloak as an OAuth provider
+
+Wasp now supports using [Keycloak](https://www.keycloak.org/) as an OAuth provider.
+
+## How to migrate?
+
+### Migrate your OAuth setup
+
+We had to make some breaking changes to upgrade the OAuth setup to the new Arctic lib.
+
+Follow the steps below to migrate:
+
+1. **Define the `WASP_SERVER_URL` server env variable**
+
+ In 0.13.0 Wasp introduces a new server env variable `WASP_SERVER_URL` that you need to define. This is the URL of your Wasp server and it's used to generate the redirect URL for the OAuth providers.
+
+ ```bash title="Server env variables"
+ WASP_SERVER_URL=https://your-wasp-server-url.com
+ ```
+
+ In development, Wasp sets the `WASP_SERVER_URL` to `http://localhost:3001` by default.
+
+ :::info Migrating a deployed app
+
+ If you are migrating a deployed app, you will need to define the `WASP_SERVER_URL` server env variable in your deployment environment.
+
+ Read more about setting env variables in production [here](./project/env-vars#defining-env-vars-in-production).
+ :::
+
+2. **Update the redirect URLs** for the OAuth providers
+
+ The redirect URL for the OAuth providers has changed. You will need to update the redirect URL for the OAuth providers in the provider's dashboard.
+
+ Google & GitHub data migration functions
+ +```wasp title="main.wasp" +api migrateGoogle { + httpRoute: (GET, "/migrate-google"), + fn: import { migrateGoogleHandler } from "@src/migrateToNewAuth", + entities: [] +} + +api migrateGithub { + httpRoute: (GET, "/migrate-github"), + fn: import { migrateGithubHandler } from "@src/migrateToNewAuth", + entities: [] +} +``` + +```ts title="src/migrateToNewAuth.ts" +import { prisma } from "wasp/server"; +import { MigrateGoogle, MigrateGithub } from "wasp/server/api"; + +export const migrateGoogleHandler: MigrateGoogle = + async (_req, res) => { + const result = await createSocialLoginMigration("google"); + + res.status(200).json({ message: "Migrated users to the new auth", result }); + }; + +export const migrateGithubHandler: MigrateGithub = + async (_req, res) => { + const result = await createSocialLoginMigration("github"); + + res.status(200).json({ message: "Migrated users to the new auth", result }); + }; + +async function createSocialLoginMigration( + providerName: "google" | "github" +): Promise<{ + numUsersAlreadyMigrated: number; + numUsersNotUsingThisAuthMethod: number; + numUsersMigratedSuccessfully: number; +}> { + const users = await prisma.user.findMany({ + include: { + auth: true, + externalAuthAssociations: true, + }, + }); + + const result = { + numUsersAlreadyMigrated: 0, + numUsersNotUsingThisAuthMethod: 0, + numUsersMigratedSuccessfully: 0, + }; + + for (const user of users) { + if (user.auth) { + result.numUsersAlreadyMigrated++; + console.log("Skipping user (already migrated) with id:", user.id); + continue; + } + + const provider = user.externalAuthAssociations.find( + (provider) => provider.provider === providerName + ); + + if (!provider) { + result.numUsersNotUsingThisAuthMethod++; + console.log(`Skipping user (not using ${providerName} auth) with id:`, user.id); + continue; + } + + await prisma.auth.create({ + data: { + identities: { + create: { + providerName, + providerUserId: provider.providerId, + providerData: JSON.stringify({}), + }, + }, + user: { + connect: { + id: user.id, + }, + }, + }, + }); + result.numUsersMigratedSuccessfully++; + } + + return result; +} +``` + +
+
+
+ {children}
+
+
+ )
+}
+```
+
+My App
+
+
+
+ {children}
+
+
+ )
+}
+```
+
+My App
+
+
+
+ {children}
+
+
+ )
+ }
+ ```
+
+ My App
+
+
+
+ {children}
+
+
+ )
+ }
+ ```
+
+