Here's {name}!
;
};
```
Now you can visit `/hello/johnny` and see "Here's johnny!"
:::tip[Type-safe links]
Since you are using Typescript, you can benefit from using Wasp's type-safe `Link` component and the `routes` object. Check out the [type-safe links docs](https://wasp.sh/docs/advanced/links) for more details.
:::
### Cleaning Up
Now that you've seen how Wasp deals with Routes and Pages, it's finally time to build the Todo app.
Start by cleaning up the starter project and removing unnecessary code and files.
First, remove most of the code from the `MainPage` component:
```tsx title="src/MainPage.tsx"
export const MainPage = () => {
return Hello world!
;
};
```
At this point, the main page should look like this:
You can now delete redundant files: `src/Main.css`, `src/assets/wasp-logo-rounded.svg`, and `src/HelloPage.tsx` (we won't need this page for the rest of the tutorial).
Since `src/HelloPage.tsx` no longer exists, remove its route from the `main.wasp.ts` file.
Your Wasp file should now look like this:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { MainPage } from "./src/MainPage" with { type: "ref" }
export default app({
name: "TodoApp",
wasp: { version: "^0.25" },
title: "TodoApp",
head: [""],
spec: [
route("RootRoute", "/", page(MainPage)),
],
})
```
Excellent work!
You now have a basic understanding of Wasp and are ready to start building your TodoApp. We'll implement the app's core features in the following sections.
## Tutorial / 4. Database Entities
Entities are one of the most important concepts in Wasp and are how you define what gets stored in the database.
Wasp uses Prisma to talk to the database, and you define Entities by defining Prisma models in the `schema.prisma` file.
Since our Todo app is all about tasks, we'll define a Task entity by adding a Task model in the `schema.prisma` file:
```prisma title="schema.prisma"
// ...
model Task {
id Int @id @default(autoincrement())
description String
isDone Boolean @default(false)
}
```
:::note
Read more about how Wasp Entities work in the [Entities](https://wasp.sh/docs/data-model/entities) section or how Wasp uses the `schema.prisma` file in the [Prisma Schema File](https://wasp.sh/docs/data-model/prisma-file) section.
:::
To update the database schema to include this entity, stop the `wasp start` process, if it's running, and run:
```sh
wasp db migrate-dev
```
You'll need to do this any time you change an entity's definition. It instructs Prisma to create a new database migration and apply it to the database.
To take a look at the database and the new `Task` entity, run:
```sh
wasp db studio
```
This will open a new page in your browser to view and edit the data in your database.
Click on the `Task` entity and check out its fields! We don't have any data in our database yet, but we are about to change that.
## Tutorial / 5. Querying the Database
We want to know which tasks we need to do, so let's list them!
The primary way of working with Entities in Wasp is with [Queries and Actions](https://wasp.sh/docs/data-model/operations/overview), collectively known as ***Operations***.
Queries are used to read an entity, while Actions are used to create, modify, and delete entities. Since we want to list the tasks, we'll want to use a Query.
To list the tasks, you must:
1. Create a Query that fetches the tasks from the database.
2. Update the `MainPage.tsx` to use that Query and display the results.
### Defining the Query
We'll create a new Query called `getTasks`. We'll need to declare the Query in the Wasp file and write its implementation in TS.
#### Specifying a Query
We need to add a **query** specification to `main.wasp.ts` so that Wasp knows it exists:
```ts title="main.wasp.ts"
import { app, page, query, route } from "@wasp.sh/spec"
import { MainPage } from "./src/MainPage" with { type: "ref" }
import { getTasks } from "./src/queries" with { type: "ref" }
export default app({
// ...
spec: [
route("RootRoute", "/", page(MainPage)),
// Tell Wasp that this query reads from the `Task` entity. Wasp will
// automatically update the results of this query when tasks are modified.
query(getTasks, { entities: ["Task"] }),
],
})
```
:::note
To generate the types used in the next section, make sure that `wasp start` is still running.
:::
#### Implementing a Query
Next, create a new file called `src/queries.ts` and define the TypeScript function we've just imported in our `query` spec:
```ts title="src/queries.ts"
import type { Task } from "wasp/entities";
import type { GetTasks } from "wasp/server/operations";
export const getTasks: GetTasks
{tasks &&
);
};
const TaskView = ({ task }: { task: Task }) => {
return (
{task.description}
);
};
const TasksList = ({ tasks }: { tasks: Task[] }) => {
if (!tasks?.length) return No tasks
;
return (
{tasks.map((task, idx) => (
);
};
```
Most of this code is regular React, the only exception being the three special `wasp` imports:
- `getTasks` - The client-side Query function Wasp generated based on the `getTasks` spec in `main.wasp.ts`.
- `useQuery` - Wasp's [useQuery](https://wasp.sh/docs/data-model/operations/queries#the-usequery-hook-1) React hook, which is based on [react-query](https://github.com/tannerlinsley/react-query)'s hook with the same name.
- `Task` - The type for the Task entity defined in `schema.prisma`.
Notice how you don't need to annotate the type of the Query's return value: Wasp uses the types you defined while implementing the Query for the generated client-side function. This is **full-stack type safety**: the types on the client always match the types on the server.
We could have called the Query directly using `getTasks()`, but the `useQuery` hook makes it reactive: React will re-render the component every time the Query changes. Remember that Wasp automatically refreshes Queries whenever the data is modified.
With these changes, you should be seeing the text "No tasks" on the screen:
We'll create a form to add tasks in the next step ๐ช
## Tutorial / 6. Modifying Data
In the previous section, you learned about using Queries to fetch data. Let's now learn about Actions so you can add and update tasks in the database.
In this section, you will create:
1. A Wasp Action that creates a new task.
2. A React form that calls that Action when the user creates a task.
### Creating a New Action
Creating an Action is very similar to creating a Query.
#### Specifying an Action
We must first declare the Action in `main.wasp.ts`:
```ts title="main.wasp.ts"
import { action, app, page, query, route } from "@wasp.sh/spec"
import { MainPage } from "./src/MainPage" with { type: "ref" }
import { getTasks } from "./src/queries" with { type: "ref" }
import { createTask } from "./src/actions" with { type: "ref" }
export default app({
// ...
spec: [
route("RootRoute", "/", page(MainPage)),
query(getTasks, { entities: ["Task"] }),
action(createTask, { entities: ["Task"] }),
],
})
```
#### Implementing an Action
Let's now define a TypeScript function for our `createTask` Action:
```ts title="src/actions.ts"
import type { Task } from "wasp/entities";
import type { CreateTask } from "wasp/server/operations";
type CreateTaskPayload = Pick
{task.description}
);
};
// ... TasksList, NewTaskForm ...
```
Awesome! You can now mark this task as done.
It's time to make one final addition to your app: supporting multiple users.
## Tutorial / 7. Adding Authentication
Most modern apps need a way to create and authenticate users. Wasp makes this as easy as possible with its first-class auth support.
To add users to your app, you must:
- [ ] Create a `User` Entity.
- [ ] Tell Wasp to use the *Username and Password* authentication.
- [ ] Add login and signup pages.
- [ ] Update the main page to require authentication.
- [ ] Add a relation between `User` and `Task` entities.
- [ ] Modify your Queries and Actions so users can only see and modify their tasks.
- [ ] Add a logout button.
### Creating a User Entity
Since Wasp manages authentication, it will create [the auth related entities](https://wasp.sh/docs/auth/entities) for you in the background. Nothing to do here!
You must only add the `User` Entity to keep track of who owns which tasks:
```prisma title="schema.prisma"
// ...
model User {
id Int @id @default(autoincrement())
}
```
### Adding Auth to the Project
Next, tell Wasp to use full-stack [authentication](https://wasp.sh/docs/auth/overview):
```ts title="main.wasp.ts"
import { action, app, page, query, route } from "@wasp.sh/spec"
import { MainPage } from "./src/MainPage" with { type: "ref" }
import { getTasks } from "./src/queries" with { type: "ref" }
import { createTask, updateTask } from "./src/actions" with { type: "ref" }
export default app({
// ...
auth: {
// Tells Wasp which entity to use for storing users.
userEntity: "User",
methods: {
// Enable username and password auth.
usernameAndPassword: {},
},
// We'll see how this is used in a bit.
onAuthFailedRedirectTo: "/login",
},
spec: [
route("RootRoute", "/", page(MainPage)),
query(getTasks, { entities: ["Task"] }),
action(createTask, { entities: ["Task"] }),
action(updateTask, { entities: ["Task"] }),
],
})
```
Don't forget to update the database schema by running:
```sh
wasp db migrate-dev
```
By doing this, Wasp will create:
- [Auth UI](https://wasp.sh/docs/auth/ui) with login and signup forms.
- A `logout()` action.
- A React hook `useAuth()`.
- `context.user` for use in Queries and Actions.
:::info
Wasp also supports authentication using [Google](https://wasp.sh/docs/auth/social-auth/google), [GitHub](https://wasp.sh/docs/auth/social-auth/github), and [email](https://wasp.sh/docs/auth/email), with more on the way!
:::
### Adding Login and Signup Pages
Wasp creates the login and signup forms for us, but we still need to define the pages to display those forms on. We'll start by declaring the pages in the Wasp file:
```ts title="main.wasp.ts"
import { action, app, page, query, route } from "@wasp.sh/spec"
import { MainPage } from "./src/MainPage" with { type: "ref" }
import { SignupPage } from "./src/SignupPage" with { type: "ref" }
import { LoginPage } from "./src/LoginPage" with { type: "ref" }
import { getTasks } from "./src/queries" with { type: "ref" }
import { createTask, updateTask } from "./src/actions" with { type: "ref" }
export default app({
// ...
spec: [
route("RootRoute", "/", page(MainPage)),
route("SignupRoute", "/signup", page(SignupPage)),
route("LoginRoute", "/login", page(LoginPage)),
// ... existing queries and actions
],
})
```
Great, Wasp now knows these pages exist!
Here's the React code for the pages you've just imported:
```tsx title="src/LoginPage.tsx"
import { Link } from "react-router";
import { LoginForm } from "wasp/client/auth";
export const LoginPage = () => {
return (
I don't have an account yet (go to signup).
I already have an account (go to login).
{/* ... */}
);
};
```
This is it, we have a working authentication system, and our Todo app is multi-user!
### What's Next?
We did it ๐ You've followed along with this tutorial to create a basic Todo app with Wasp.
You can find the complete code for the TS version of the tutorial [here](https://github.com/wasp-lang/wasp/tree/release/examples/tutorials/TodoAppTs).
You should be ready to learn about more complicated features and go more in-depth with the features already covered. Scroll through the sidebar on the left side of the page to see every feature Wasp has to offer. Or, let your imagination run wild and start building your app! โจ
Looking for inspiration?
- Get a jump start on your next project with [Starter Templates](https://wasp.sh/docs/project/starter-templates).
- Check out our [official examples](https://github.com/wasp-lang/wasp/tree/release/examples).
- Make a real-time app with [Web Sockets](https://wasp.sh/docs/advanced/web-sockets).
:::note
If you notice that some of the features you'd like to have are missing, or have any other kind of feedback, please write to us on [Discord](https://discord.gg/rzdnErX) or create an issue on [Github](https://github.com/wasp-lang/wasp), so we can learn which features to add/improve next ๐
If you would like to contribute or help to build a feature, let us know! You can find more details on contributing [here](https://wasp.sh/docs/contributing).
:::
Oh, and do [**subscribe to our newsletter**](https://wasp.sh/#signup)! We usually send one per month, and Matija does his best to unleash his creativity to make them engaging and fun to read \:D!
## Data Model / Entities
Entities are the foundation of your app's data model. In short, an Entity defines a model in your database.
Wasp uses the excellent [Prisma ORM](https://www.prisma.io/) to implement all database functionality and occasionally enhances it with a thin abstraction layer. This means that you use the `schema.prisma` file to define your database models and relationships. Wasp understands the Prisma schema file and picks up all the models you define there. You can read more about this in the [Prisma Schema File](https://wasp.sh/docs/data-model/prisma-file) section of the docs.
In your project, you'll find a `schema.prisma` file in the root directory:
```
.
โโโ main.wasp.ts
...
โโโ package.json
โโโ public
โโโ schema.prisma
โโโ src
โโโ tsconfig.json
โโโ tsconfig.src.json
โโโ tsconfig.wasp.json
โโโ vite.config.ts
```
Prisma uses the *Prisma Schema Language*, a simple definition language explicitly created for defining models. The language is declarative and very intuitive. We'll also go through an example later in the text, so there's no need to go and thoroughly learn it right away. Still, if you're curious, look no further than Prisma's official documentation:
- [Basic intro and examples](https://www.prisma.io/docs/orm/prisma-schema/overview)
- [A more exhaustive language specification](https://www.prisma.io/docs/orm/reference/prisma-schema-reference)
### Defining an Entity
A Prisma `model` declaration in the `schema.prisma` file represents a Wasp Entity.
Entity vs Model
You might wonder why we distinguish between a **Wasp Entity** and a **Prisma model** if they're essentially the same thing right now.
While defining a Prisma model is currently the only way to create an Entity in Wasp, the Entity concept is a higher-level abstraction. We plan to expand on Entities in the future, both in terms of how you can define them and what you can do with them.
So, think of an Entity as a Wasp concept and a model as a Prisma concept. For now, all Prisma models are Entities and vice versa, but this relationship might evolve as Wasp grows.
Here's how you could define an Entity that represents a Task:
```prisma title="schema.prisma"
model Task {
id String @id @default(uuid())
description String
isDone Boolean @default(false)
}
```
The above Prisma `model` definition tells Wasp to create a table for storing Tasks where each task has three fields (i.e., the `tasks` table has three columns):
- `id` - A string value serving as a primary key. The database automatically generates it by generating a random unique ID.
- `description` - A string value for storing the task's description.
- `isDone` - A boolean value indicating the task's completion status. If you don't set it when creating a new task, the database sets it to `false` by default.
Wasp also exposes a type for working with the created Entity. You can import and use it like this:
```ts
import { Task } from "wasp/entities"
const task: Task = { ... }
// You can also define functions for working with entities
function getInfoMessage(task: Task): string {
const isDoneText = task.isDone ? "is done" : "is not done"
return `Task '${task.description}' is ${isDoneText}.`
}
```
Using the `Task` type in `getInfoMessage`'s definition connects the argument's type with the `Task` entity.
This coupling removes duplication and ensures the function keeps the correct signature even if you change the entity. Of course, the function might throw type errors depending on how you change it, but that's precisely what you want!
Entity types are available everywhere, including the client code:
```ts
import { Task } from "wasp/entities"
export function ExamplePage() {
const task: Task = {
id: "some-uuid-1234",
description: "Some random task",
isDone: false,
}
return {task.description}
}
```
The mentioned type safety mechanisms also apply here: changing the task entity in our `schema.prisma` file changes the imported type, which might throw a type error and warn us that our task definition is outdated.
You'll learn even more about Entity types when you start using [them with operations](#using-entities-in-operations).
#### Working with Entities
Let's see how you can define and work with Wasp Entities:
1. Create/update some Entities in the `schema.prisma` file.
2. Run `wasp db migrate-dev`. This command syncs the database model with the Entity definitions the `schema.prisma` file. It does this by creating migration scripts.
3. Migration scripts are automatically placed in the `migrations/` folder. Make sure to commit this folder into version control.
4. Use Wasp's JavaScript API to work with the database when implementing Operations (we'll cover this in detail when we talk about [operations](https://wasp.sh/docs/data-model/operations/overview)).
##### Using Entities in Operations
Most of the time, you will be working with Entities within the context of [Operations (Queries & Actions)](https://wasp.sh/docs/data-model/operations/overview). We'll see how that's done on the next page.
##### Using Entities directly
If you need more control, you can directly interact with Entities by importing and using the [Prisma Client](https://www.prisma.io/docs/concepts/components/prisma-client/crud). We recommend sticking with conventional Wasp-provided mechanisms, only resorting to directly using the Prisma client only if you need a feature Wasp doesn't provide.
You can only use the Prisma Client in your Wasp server code. You can import it like this:
```ts
import { prisma } from "wasp/server"
prisma.task.create({
description: "Read the Entities doc",
isDone: true // almost :)
})
```
:::note[Available Prisma features in the client]
While the Prisma Client is not available in your client code, you can still import Prisma there, for accessing type definitions (notably, `enum`s).
You can see more information in the overview of [supported Prisma Schema features](https://wasp.sh/docs/data-model/prisma-file#the-enum-blocks).
:::
#### Next steps
Now that we've seen how to define Entities that represent Wasp's core data model, we'll see how to make the most of them in other parts of Wasp. Keep reading to learn all about Wasp Operations!
## Data Model / Operations / Overview
While Entities enable you to define your app's data model and relationships, Operations are all about working with this data.
There are two kinds of Operations: [Queries](https://wasp.sh/docs/data-model/operations/queries) and [Actions](https://wasp.sh/docs/data-model/operations/actions). As their names suggest, Queries are meant for reading data, and Actions are meant for changing it (either by updating existing entries or creating new ones).
Keep reading to find out all there is to know about Operations in Wasp.
## Data Model / Operations / Queries
We'll explain what Queries are and how to use them. If you're looking for a detailed API specification, skip ahead to the [API Reference](#api-reference).
You can use Queries to fetch data from the server. They shouldn't modify the server's state. Fetching all comments on a blog post, a list of users that liked a video, information about a single product based on its ID... All of these are perfect use cases for a Query.
:::tip
Queries are fairly similar to Actions in terms of their API. Therefore, if you're already familiar with Actions, you might find reading the entire guide repetitive.
We instead recommend skipping ahead and only reading [the differences between Queries and Actions](https://wasp.sh/docs/data-model/operations/actions#differences-between-queries-and-actions), and consulting the [API Reference](#api-reference) as needed.
:::
### Working with Queries
You declare queries in the Wasp file and implement them using NodeJS. Wasp not only runs these queries within the server's context but also creates code that enables you to call them from any part of your codebase, whether it's on the client or server side.
This means you don't have to build an HTTP API for your query, manage server-side request handling, or even deal with client-side response handling and caching. Instead, just concentrate on implementing the business logic inside your query, and let Wasp handle the rest!
To create a Query, you must:
1. Declare the Query in Wasp using the `query` spec.
2. Define the Query's NodeJS implementation.
After completing these two steps, you'll be able to use the Query from any point in your code.
#### Specifying Queries
To create a Query in Wasp, we begin with a `query` spec.
Let's declare two Queries - one to fetch all tasks, and another to fetch tasks based on a filter, such as whether a task is done:
```ts title="main.wasp.ts"
import { app, query } from "@wasp.sh/spec"
import { getAllTasks, getFilteredTasks } from "./src/queries" with { type: "ref" }
export default app({
// ...
spec: [
query(getAllTasks),
query(getFilteredTasks),
],
})
```
If you want to know about all supported options for the `query` spec, take a look at the [API Reference](#api-reference).
:::note
When `main.wasp.ts` needs to point to your code, it uses imports like this:
```ts
import { MainPage } from "./src/MainPage" with { type: "ref" }
```
Notice the `with { type: "ref" }` part at the end of the import statement. This tells Wasp to treat the import as a reference to your app's code, without running the imported code. For more details and examples, see [reference imports](https://wasp.sh/docs/general/spec#reference-imports).
:::
:::info
You might have noticed that we told Wasp to import Query implementations that don't yet exist. Don't worry about that for now. We'll write the implementations imported from `queries.ts` in the next section.
It's a good idea to start with the high-level concept (the Query spec in the Wasp file) and only then deal with the implementation details (the Query's implementation in JavaScript).
:::
After declaring a Wasp Query, Wasp derives the Query's name from the function you pass to `query`. For example, `query(getFilteredTasks)` creates a Query named `getFilteredTasks`.
Two important things then happen:
- Wasp **generates a server-side NodeJS function** with the Query's name.
- Wasp **generates a client-side JavaScript function** with the Query's name (e.g., `getFilteredTasks`). This function takes a single optional argument - an object containing any serializable data you wish to use inside the Query. Wasp will send this object over the network and pass it into the Query's implementation as its first positional argument (more on this when we look at the implementations). Such an abstraction works thanks to an HTTP API route handler Wasp generates on the server, which calls the Query's NodeJS implementation under the hood.
Generating these two functions ensures a similar calling interface across the entire app (both client and server).
#### Implementing Queries in Node
Now that we've declared the Query, what remains is to implement it. We've instructed Wasp to look for the Queries' implementations in the file `src/queries.ts`, so that's where we should export them from.
Here's how you might implement the previously declared Queries `getAllTasks` and `getFilteredTasks`:
```ts title="src/queries.ts"
import { type GetAllTasks, type GetFilteredTasks } from "wasp/server/operations"
type Task = {
id: number
description: string
isDone: boolean
}
// our "database"
const tasks: Task[] = [
{ id: 1, description: "Buy some eggs", isDone: true },
{ id: 2, description: "Make an omelette", isDone: false },
{ id: 3, description: "Eat breakfast", isDone: false },
]
// You don't need to use the arguments if you don't need them
export const getAllTasks: GetAllTasksThere was an error
}
return (
All Tasks
{allTasks && allTasks.length > 0 ? allTasks.map((task) =>Finished Tasks
{doneTasks && doneTasks.length > 0 ? doneTasks.map((task) =>Description: {description}
Is done: {isDone ? "Yes" : "No"}
"Loading"
} const { description, isDone } = task return (Description: {description}
Is done: {isDone ? "Yes" : "No"}
{isDone || ( )}"Loading"
; } const { description, isDone } = task; return (Description: {description}
Is done: {isDone ? "Yes" : "No"}
{isDone || ( )}Loading...
if (error) return Error: {error.message}
return (
setTaskDescription(e.target.value)}
/>
-
{tasks.map((task) => (
- {task.description} ))}
Create an account
{task.description}
);
};
```
:::note[Triple slash comments]
Wasp only supports `///` in the *leading* position:
```prisma title="schema.prisma"
model User {
/// The unique identifier for the user.
id Int @id @default(autoincrement())
}
```
However, Wasp does not support `///` comments in the *trailing* position:
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement()) /// This is not supported
}
```
We are aware of this issue and are tracking it at [#3041](https://github.com/wasp-lang/wasp/issues/3041), let us know if this is something you need.
:::
### Prisma preview features
Prisma is still in active development and some of its features are not yet stable. To enable various preview features in Prisma, you need to add the `previewFeatures` field to the `generator` block in the `schema.prisma` file.
For example, one useful Prisma preview feature is PostgreSQL extensions support, which allows you to use PostgreSQL extensions like `pg_vector` or `pg_trgm` in your database schema:
```prisma title="schema.prisma"
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
extensions = [pgvector(map: "vector")]
}
generator client {
provider = "prisma-client-js"
previewFeatures = ["postgresqlExtensions"]
}
// ...
```
Read more about preview features in the Prisma docs [here](https://www.prisma.io/docs/orm/reference/preview-features/client-preview-features) or about using PostgreSQL extensions [here](https://www.prisma.io/docs/orm/prisma-schema/postgresql-extensions).
## Authentication / Overview
Auth is an essential piece of any serious application. That's why Wasp provides authentication and authorization support out of the box.
Enabling auth for your app is optional and can be done by configuring the `auth` field of your `app` spec:
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
export default app({
name: "MyApp",
wasp: { version: "^0.25" },
title: "My app",
head: [""],
auth: {
userEntity: "User",
methods: {
usernameAndPassword: {}, // use this or email, not both
email: {}, // use this or usernameAndPassword, not both
google: {},
gitHub: {},
},
onAuthFailedRedirectTo: "/someRoute",
},
// ...
})
```
Read more about the `auth` field options in the [API Reference](#api-reference) section.
We will provide a quick overview of auth in Wasp and link to more detailed documentation for each auth method.
### Available auth methods
Wasp supports the following auth methods:
#### [Email ยป](https://wasp.sh/docs/auth/email)
[Email verification, password reset, etc.](https://wasp.sh/docs/auth/email)
#### [Username & Password ยป](https://wasp.sh/docs/auth/username-and-pass)
[The simplest way to get started](https://wasp.sh/docs/auth/username-and-pass)
#### [Google ยป](https://wasp.sh/docs/auth/social-auth/google)
[Users sign in with their Google account](https://wasp.sh/docs/auth/social-auth/google)
#### [Github ยป](https://wasp.sh/docs/auth/social-auth/github)
[Users sign in with their Github account](https://wasp.sh/docs/auth/social-auth/github)
#### [Keycloak ยป](https://wasp.sh/docs/auth/social-auth/keycloak)
[Users sign in with their Keycloak account](https://wasp.sh/docs/auth/social-auth/keycloak)
#### [Slack ยป](https://wasp.sh/docs/auth/social-auth/slack)
[Users sign in with their Slack account](https://wasp.sh/docs/auth/social-auth/slack)
#### [Discord ยป](https://wasp.sh/docs/auth/social-auth/discord)
[Users sign in with their Discord account](https://wasp.sh/docs/auth/social-auth/discord)
Click on each auth method for more details.
Let's say we enabled the [Username & password](https://wasp.sh/docs/auth/username-and-pass) authentication.
We get an auth backend with signup and login endpoints. We also get the `user` object in our [Operations](https://wasp.sh/docs/data-model/operations/overview) and we can decide what to do based on whether the user is logged in or not.
We would also get the [Auth UI](https://wasp.sh/docs/auth/ui) generated for us. We can set up our login and signup pages where our users can **create their account** and **login**. We can then protect certain pages by setting `authRequired: true` for them. This will make sure that only logged-in users can access them.
We will also have access to the `user` object in our frontend code, so we can show different UI to logged-in and logged-out users. For example, we can show the user's name in the header alongside a **logout button** or a login button if the user is not logged in.
### Different ways to use auth
When you have decided which auth methods you want to support, you can also choose how you want to present the authorization flows to your users.
##### Generated components
This is the fastest way to ship, with Wasp generating ready-made components for your app. They allow for some customization to make them consistent with your app. You don't need to implement any UI or logic, and they just work.
#### [Email ยป](https://wasp.sh/docs/auth/email)
#### [Username and password ยป](https://wasp.sh/docs/auth/username-and-pass)
#### [Social Auth ยป](https://wasp.sh/docs/auth/social-auth/overview)
##### Make your own UI {#custom-auth-ui}
Wasp is flexible enough to let you completely customize your login and signup interface. We give you the auth related functions, and you decide how and when to call them. This allows for total customization of the look-and-feel, and the interaction, but it needs a bit more work.
#### [Email ยป](https://wasp.sh/docs/auth/email/create-your-own-ui)
#### [Username and password ยป](https://wasp.sh/docs/auth/username-and-pass/create-your-own-ui)
#### [Social Auth ยป](https://wasp.sh/docs/auth/social-auth/create-your-own-ui)
:::tip
You don't have to choose one *or* the other! Mix-and-match, and use what you need in each moment. For example, you can create a custom signup screen, but use Wasp's generated components for login.
:::
##### Custom login and signup actions
The previously discussed options should cover the vast majority of cases. But, for the few instances where it is not enough, you can [create your own signup flows](https://wasp.sh/docs/auth/advanced/custom-auth-actions), with completely custom logic. This is not recommended, and reserved for advanced use cases. Please check first if other Wasp features (mainly [auth hooks](https://wasp.sh/docs/auth/auth-hooks)) can handle your requirements.
### Protecting a page with `authRequired`
When declaring a page, you can set the `authRequired` property.
If you set it to `true`, only authenticated users can access the page. Unauthenticated users are redirected to a route defined by the `auth.onAuthFailedRedirectTo` field.
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import Main from "./src/pages/Main" with { type: "ref" }
export default app({
// ...
spec: [
route("MainRoute", "/", page(Main, { authRequired: true })),
],
})
```
:::caution[Requires auth method]
You can only use `authRequired` if your app uses one of the [available auth methods](#available-auth-methods).
:::
If `authRequired` is set to `true`, the page's React component (passed as the first argument to `page(...)`) receives the `user` object as a prop. Read more about the `user` object in the [Accessing the logged-in user section](#accessing-the-logged-in-user).
### Logout action
We provide an action for logging out the user. Here's how you can use it:
```tsx title="src/components/LogoutButton.tsx"
import { logout } from "wasp/client/auth"
const LogoutButton = () => {
return
}
```
### Accessing the logged-in user
You can get access to the `user` object both on the server and on the client. The `user` object contains the logged-in user's data.
The `user` object has all the fields that you defined in your `User` entity. In addition to that, it will also contain all the auth-related fields that Wasp stores. This includes things like the `username` or the email verification status. For example, if you have a user that signed up using an email and password, the `user` object might look like this:
```ts
const user = {
// User data
id: "cluqsex9500017cn7i2hwsg17",
address: "Some address",
// Auth methods specific data
identities: {
email: {
id: "user@app.com",
isEmailVerified: true,
emailVerificationSentAt: "2024-04-08T10:06:02.204Z",
passwordResetSentAt: null,
},
},
}
```
You can read more about how the `User` is connected to the rest of the auth system and how you can access the user data in the [Accessing User Data](https://wasp.sh/docs/auth/entities) section of the docs.
#### On the client
There are two ways to access the `user` object on the client:
- the `user` prop
- the `useAuth` hook
##### Getting the `user` in authenticated routes
If the page's spec sets `authRequired` to `true`, the page's React component receives the `user` object as a prop. This is the simplest way to access the user inside an authenticated page:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import Account from "./src/pages/Account" with { type: "ref" }
export default app({
// ...
spec: [
route("AccountRoute", "/account", page(Account, {
authRequired: true
})),
],
})
```
```tsx title="src/pages/Account.tsx"
import type { AuthUser } from "wasp/auth";
import Button from "./Button";
import { logout } from "wasp/client/auth";
const AccountPage = ({ user }: { user: AuthUser }) => {
return (
{JSON.stringify(user, null, 2)}
);
};
export default AccountPage;
```
##### Getting the `user` in non-authenticated routes
Wasp provides a React hook you can use in the client components - `useAuth`.
This hook is a thin wrapper over Wasp's `useQuery` hook and returns data in the same format.
```tsx title="src/pages/MainPage.tsx"
import { useAuth, logout } from "wasp/client/auth";
import { Link } from "react-router";
import Todo from "../Todo";
export function Main() {
const { data: user } = useAuth();
if (!user) {
return (
Please login or{" "}
sign up.
);
} else {
return (
<>
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.
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}
Check your email for the confirmation link. If you don't see it, check spam/junk folder.
) } return ( ) } // This will be shown has clicked on the link in their // email to verify their email address export function EmailVerificationPage() { const [error, setError] = useStateError: {error.message}
} ) } // This will be shown when the user wants to reset their password export function RequestPasswordResetPage() { const [email, setEmail] = useState('') const [error, setError] = useStateCheck your email for the confirmation link. If you don't see it, check spam/junk folder.
) } return ( ) } // This will be shown when the user clicks on the link in their // email to reset their password export function PasswordResetPage() { const [error, setError] = useState{children}
{children}
{children}
{children}
{children}
{children}
{tasks.map((task) => (
)
}
```
Wasp offers a few helper methods to access the user's auth data when you retrieve the `user` like this. They are `getUsername`, `getEmail` and `getFirstProviderUserId`. They can be used both on the client and the server.
##### `getUsername`
It accepts the `user` object and if the user signed up with the [Username & password](https://wasp.sh/docs/auth/username-and-pass) auth method, it returns the username or `null` otherwise. The `user` object needs to have the `auth` and the `identities` relations included.
```tsx title="src/MainPage.tsx"
import { getUsername } from "wasp/auth"
function MainPage() {
// ...
return (
{task.title} by {task.user.auth?.identities[0].providerUserId}
))}
{tasks.map((task) => (
)
}
```
##### `getEmail`
It accepts the `user` object and if the user signed up with the [Email](https://wasp.sh/docs/auth/email) auth method, it returns the email or `null` otherwise. The `user` object needs to have the `auth` and the `identities` relations included.
```tsx title="src/MainPage.tsx"
import { getEmail } from "wasp/auth"
function MainPage() {
// ...
return (
{task.title} by {getUsername(task.user)}
))}
{tasks.map((task) => (
)
}
```
##### `getFirstProviderUserId`
It returns the first user ID that it finds for the user. For example if the user has signed up with email, it will return the email. If the user has signed up with Google, it will return the Google ID. The `user` object needs to have the `auth` and the `identities` relations included.
```tsx title="src/MainPage.tsx"
import { getFirstProviderUserId } from "wasp/auth"
function MainPage() {
// ...
return (
{task.title} by {getEmail(task.user)}
))}
{tasks.map((task) => (
)
}
```
### Entities Explained
To store user's auth information, Wasp does a few things behind the scenes. Wasp takes your `schema.prisma` file and combines it with additional entities to create the final `schema.prisma` file that is used in your app.
In this section, we will explain which entities are created and how they are connected.
#### User Entity
When you want to add authentication to your app, you need to specify the `userEntity` field.
For example, you might set it to `User`:
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
export default app({
name: "myApp",
wasp: { version: "^0.25" },
title: "My App",
head: [""],
auth: {
userEntity: "User",
// ...
},
// ...
})
```
And define the `User` in the `schema.prisma` file:
```prisma title="schema.prisma"
model User {
id Int @id @default(autoincrement())
// Any other fields you want to store about the user
}
```
The `User` entity is a "business logic user" which represents a user of your app.
You can use this entity to store any information about the user that you want to store. For example, you might want to store the user's name or address.
You can also use the user entity to define the relations between users and other entities in your app. For example, you might want to define a relation between a user and the tasks that they have created.
You **own** the user entity and you can modify it as you wish. You can add new fields to it, remove fields from it, or change the type of the fields. You can also add new relations to it or remove existing relations from it.
Auth Entities in a Wasp App
On the other hand, the `Auth`, `AuthIdentity` and `Session` entities are created behind the scenes and are used to store the user's login credentials. You as the developer don't need to care about this entity most of the time. Wasp **owns** these entities.
In the case you want to create a custom signup action, you will need to use the `Auth` and `AuthIdentity` entities directly.
#### Example App Model
Let's imagine we created a simple tasks management app:
- The app has email and Google-based auth.
- Users can create tasks and see the tasks that they have created.
Let's look at how would that look in the database:
Example of Auth Entities
If we take a look at an example user in the database, we can see:
- The business logic user, `User` is connected to multiple `Task` entities.
- In this example, "Example User" has two tasks.
- The `User` is connected to exactly one `Auth` entity.
- Each `Auth` entity can have multiple `AuthIdentity` entities.
- In this example, the `Auth` entity has two `AuthIdentity` entities: one for the email-based auth and one for the Google-based auth.
- Each `Auth` entity can have multiple `Session` entities.
- In this example, the `Auth` entity has one `Session` entity.
:::caution[Using multiple auth identities for a single user]
Wasp currently doesn't support multiple auth identities for a single user. This means, for example, that a user can't have both an email-based auth identity and a Google-based auth identity. This is something we will add in the future with the introduction of the [account merging feature](https://github.com/wasp-lang/wasp/issues/954).
Account merging means that multiple auth identities can be merged into a single user account. For example, a user's email and Google identity can be merged into a single user account. Then the user can log in with either their email or Google account and they will be logged into the same account.
:::
#### `Auth` Entity internal {#auth-entity-}
Wasp's internal `Auth` entity is used to connect the business logic user, `User` with the user's login credentials.
```prisma
model Auth {
id String @id @default(uuid())
userId Int? @unique
// Wasp injects this relation on the User entity as well
user User? @relation(fields: [userId], references: [id], onDelete: Cascade)
identities AuthIdentity[]
sessions Session[]
}
```
The `Auth` fields:
- `id` is a unique identifier of the `Auth` entity.
- `userId` is a foreign key to the `User` entity.
- It is used to connect the `Auth` entity with the business logic user.
- `user` is a relation to the `User` entity.
- This relation is injected on the `User` entity as well.
- `identities` is a relation to the `AuthIdentity` entity.
- `sessions` is a relation to the `Session` entity.
#### `AuthIdentity` Entity internal {#authidentity-entity-}
The `AuthIdentity` entity is used to store the user's login credentials for various authentication methods.
```prisma
model AuthIdentity {
providerName String
providerUserId String
providerData String @default("{}")
authId String
auth Auth @relation(fields: [authId], references: [id], onDelete: Cascade)
@@id([providerName, providerUserId])
}
```
The `AuthIdentity` fields:
- `providerName` is the name of the authentication provider.
- For example, `email` or `google`.
- `providerUserId` is the user's ID in the authentication provider.
- For example, the user's email or Google ID.
- `providerData` is a JSON string that contains additional data about the user from the authentication provider.
- For example, for password based auth, this field contains the user's hashed password.
- This field is a `String` and not a `Json` type because [Prisma doesn't support the `Json` type for SQLite](https://github.com/prisma/prisma/issues/3786).
- `authId` is a foreign key to the `Auth` entity.
- It is used to connect the `AuthIdentity` entity with the `Auth` entity.
- `auth` is a relation to the `Auth` entity.
#### `Session` Entity internal {#session-entity-}
The `Session` entity is used to store the user's session information. It is used to keep the user logged in between page refreshes.
```prisma
model Session {
id String @id @unique
expiresAt DateTime
userId String
auth Auth @relation(references: [id], fields: [userId], onDelete: Cascade)
@@index([userId])
}
```
The `Session` fields:
- `id` is a unique identifier of the `Session` entity.
- `expiresAt` is the date when the session expires.
- `userId` is a foreign key to the `Auth` entity.
- It is used to connect the `Session` entity with the `Auth` entity.
- `auth` is a relation to the `Auth` entity.
### Custom Signup Action
Let's take a look at how you can use the `Auth` and `AuthIdentity` entities to create custom login and signup actions. For example, you might want to create a custom signup action that creates a user in your app and also creates a user in a third-party service.
:::info[Custom Signup Examples]
In the Advanced section you can see an example for [Email](https://wasp.sh/docs/auth/advanced/custom-auth-actions#email) or [Username and password](https://wasp.sh/docs/auth/advanced/custom-auth-actions#username-and-password) authentication.
:::
Below is a simplified version of a custom signup action which you probably wouldn't use in your app but it shows you how you can use the `Auth` and `AuthIdentity` entities to create a custom signup action.
```ts title="main.wasp.ts"
import { action, app } from "@wasp.sh/spec"
import { customSignup } from "./src/auth/signup" with { type: "ref" }
export default app({
// ...
spec: [
action(customSignup, { entities: ["User"] }),
],
})
```
```ts title="src/auth/signup.ts"
import {
createProviderId,
sanitizeAndSerializeProviderData,
createUser,
} from "wasp/server/auth"
import type { CustomSignup } from "wasp/server/operations"
type CustomSignupInput = {
username: string
password: string
}
type CustomSignupOutput = {
success: boolean
message: string
}
export const customSignup: CustomSignup<
CustomSignupInput,
CustomSignupOutput
> = async (args, { entities: { User } }) => {
try {
// Provider ID is a combination of the provider name and the provider user ID
// And it is used to uniquely identify the user in your app
const providerId = createProviderId("username", args.username)
// sanitizeAndSerializeProviderData hashes the password and returns a JSON string
const providerData = await sanitizeAndSerializeProviderData<"username">({
hashedPassword: args.password,
})
await createUser(
providerId,
providerData,
// Any additional data you want to store on the User entity
{}
)
// This is equivalent to:
// await User.create({
// data: {
// auth: {
// create: {
// identities: {
// create: {
// providerName: "username",
// providerUserId: args.username
// providerData,
// },
// },
// }
// },
// }
// })
} catch (e) {
return {
success: false,
message: e.message,
}
}
// Your custom code after sign-up.
// ...
return {
success: true,
message: "User created successfully",
}
}
```
You can use whichever method suits your needs better: either the `createUser` function or Prisma's `User.create` method. The `createUser` function is a bit more convenient to use because it hides some of the complexity. On the other hand, the `User.create` method gives you more control over the data that is stored in the `Auth` and `AuthIdentity` entities.
## Authentication / Auth Hooks
Auth hooks allow you to "hook into" the auth process at various stages and run your custom code. For example, if you want to forbid certain emails from signing up, or if you wish to send a welcome email to the user after they sign up, auth hooks are the way to go.
### Supported hooks
The following auth hooks are available in Wasp:
- [`onBeforeSignup`](#executing-code-before-the-user-signs-up)
- [`onAfterSignup`](#executing-code-after-the-user-signs-up)
- [`onAfterEmailVerified`](#executing-code-after-a-user-verifies-their-email)
- [`onBeforeOAuthRedirect`](#executing-code-before-the-oauth-redirect)
- [`onBeforeLogin`](#executing-code-before-the-user-logs-in)
- [`onAfterLogin`](#executing-code-after-the-user-logs-in)
We'll go through each of these hooks in detail. But first, let's see how the hooks fit into the auth flows:
Signup Flow with Hooks
Login Flow with Hooks \*
\* When using the OAuth auth providers, the login hooks are both called before the session is created but the session is created quickly afterward, so it shouldn't make any difference in practice.
Users registering with [email](https://wasp.sh/docs/auth/email) must verify it before they can log in. This verification triggers the Email verification flow:
Email Verification Flow with Hooks
Users signing in with [OAuth](https://wasp.sh/docs/auth/social-auth/overview) must authorize access before completing login. This authorization triggers the OAuth consent flow:
OAuth Flow with Hooks
### Using hooks
To use auth hooks, you must first declare them in the Wasp file:
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import {
onBeforeSignup,
onAfterSignup,
onAfterEmailVerified,
onBeforeOAuthRedirect,
onBeforeLogin,
onAfterLogin,
} from "./src/auth/hooks" with { type: "ref" }
export default app({
name: "myApp",
wasp: { version: "^0.25" },
title: "My App",
head: [""],
auth: {
userEntity: "User",
methods: {
// ...
},
onBeforeSignup,
onAfterSignup,
onAfterEmailVerified,
onBeforeOAuthRedirect,
onBeforeLogin,
onAfterLogin,
},
// ...
})
```
If the hooks are defined as async functions, Wasp *awaits* them. This means the auth process waits for the hooks to finish before continuing.
Wasp ignores the hooks' return values. The only exception is the `onBeforeOAuthRedirect` hook, whose return value affects the OAuth redirect URL.
We'll now go through each of the available hooks.
#### Executing code before the user signs up
Wasp calls the `onBeforeSignup` hook before the user is created.
The `onBeforeSignup` hook can be useful if you want to reject a user based on some criteria before they sign up.
Works with [Email](https://wasp.sh/docs/auth/email) [Username & Password](https://wasp.sh/docs/auth/username-and-pass) [Slack](https://wasp.sh/docs/auth/social-auth/slack) [Discord](https://wasp.sh/docs/auth/social-auth/discord) [Github](https://wasp.sh/docs/auth/social-auth/github) [Google](https://wasp.sh/docs/auth/social-auth/google) [Keycloak](https://wasp.sh/docs/auth/social-auth/keycloak)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onBeforeSignup } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onBeforeSignup,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import { HttpError } from "wasp/server"
import type { OnBeforeSignupHook } from "wasp/server/auth"
export const onBeforeSignup: OnBeforeSignupHook = async ({
providerId,
prisma,
req,
}) => {
const count = await prisma.user.count()
console.log("number of users before", count)
console.log("provider name", providerId.providerName)
console.log("provider user ID", providerId.providerUserId)
if (count > 100) {
throw new HttpError(403, "Too many users")
}
if (
providerId.providerName === "email" &&
providerId.providerUserId === "some@email.com"
) {
throw new HttpError(403, "This email is not allowed")
}
}
```
Read more about the data the `onBeforeSignup` hook receives in the [API Reference](#the-onbeforesignup-hook).
#### Executing code after the user signs up
Wasp calls the `onAfterSignup` hook after the user is created.
The `onAfterSignup` hook can be useful if you want to send the user a welcome email or perform some other action after the user signs up like syncing the user with a third-party service.
Since the `onAfterSignup` hook receives the OAuth tokens, you can use this hook to store the OAuth access token and/or [refresh token](#refreshing-the-oauth-access-token) in your database.
Works with [Email](https://wasp.sh/docs/auth/email) [Username & Password](https://wasp.sh/docs/auth/username-and-pass) [Slack](https://wasp.sh/docs/auth/social-auth/slack) [Discord](https://wasp.sh/docs/auth/social-auth/discord) [Github](https://wasp.sh/docs/auth/social-auth/github) [Google](https://wasp.sh/docs/auth/social-auth/google) [Keycloak](https://wasp.sh/docs/auth/social-auth/keycloak)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onAfterSignup } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onAfterSignup,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import type { OnAfterSignupHook } from "wasp/server/auth"
export const onAfterSignup: OnAfterSignupHook = async ({
providerId,
user,
oauth,
prisma,
req,
}) => {
const count = await prisma.user.count()
console.log("number of users after", count)
console.log("user object", user)
// If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
if (oauth) {
console.log("accessToken", oauth.tokens.accessToken)
console.log("uniqueRequestId", oauth.uniqueRequestId)
const id = oauth.uniqueRequestId
const data = someKindOfStore.get(id)
if (data) {
console.log("saved data for the ID", data)
}
someKindOfStore.delete(id)
}
}
```
Read more about the data the `onAfterSignup` hook receives in the [API Reference](#the-onaftersignup-hook).
#### Executing code after a user verifies their email
Wasp calls the `onAfterEmailVerified` hook exactly once, after the user verifies their email.
The `onAfterEmailVerified` hook is useful for triggering actions in response to the verification event โ such as sending a welcome email or syncing user data with a third-party service.
The `onAfterEmailVerified` hook receives an `email` string and `user` object, this makes it easy to perform personalized actions upon email verification.
Works with [Email](https://wasp.sh/docs/auth/email)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onAfterEmailVerified } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onAfterEmailVerified,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import type { OnAfterEmailVerifiedHook } from "wasp/server/auth"
import { emailSender } from "wasp/server/email"
export const onAfterEmailVerified: OnAfterEmailVerifiedHook = async ({
email,
}) => {
const info = await emailSender.send({
from: {
name: "John Doe",
email: "john@doe.com",
},
to: email,
subject: "Thank you for verifying your email!",
text: `Your email ${email} has been successfully verified!`,
})
// ...
}
```
Read more about the data the `onAfterEmailVerified` hook receives in the [API Reference](#the-onafteremailverified-hook).
#### Executing code before the OAuth redirect
Wasp calls the `onBeforeOAuthRedirect` hook after the OAuth redirect URL is generated but before redirecting the user. This hook can access the request object sent from the client at the start of the OAuth process.
The `onBeforeOAuthRedirect` hook can be useful if you want to save some data (e.g. request query parameters) that you can use later in the OAuth flow. You can use the `uniqueRequestId` parameter to reference this data later in the `onAfterSignup` or `onAfterLogin` hooks.
Works with [Discord](https://wasp.sh/docs/auth/social-auth/discord) [Github](https://wasp.sh/docs/auth/social-auth/github) [Google](https://wasp.sh/docs/auth/social-auth/google) [Keycloak](https://wasp.sh/docs/auth/social-auth/keycloak)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onBeforeOAuthRedirect } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onBeforeOAuthRedirect,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import type { OnBeforeOAuthRedirectHook } from "wasp/server/auth"
export const onBeforeOAuthRedirect: OnBeforeOAuthRedirectHook = async ({
url,
oauth,
prisma,
req,
}) => {
console.log("query params before oAuth redirect", req.query)
// Saving query params for later use in onAfterSignup or onAfterLogin hooks
const id = oauth.uniqueRequestId
someKindOfStore.set(id, req.query)
return { url }
}
```
This hook's return value must be an object that looks like this: `{ url: URL }`. Wasp uses the URL to redirect the user to the OAuth provider.
Read more about the data the `onBeforeOAuthRedirect` hook receives in the [API Reference](#the-onbeforeoauthredirect-hook).
#### Executing code before the user logs in
Wasp calls the `onBeforeLogin` hook before the user is logged in.
The `onBeforeLogin` hook can be useful if you want to reject a user based on some criteria before they log in.
Works with [Email](https://wasp.sh/docs/auth/email) [Username & Password](https://wasp.sh/docs/auth/username-and-pass) [Slack](https://wasp.sh/docs/auth/social-auth/slack) [Discord](https://wasp.sh/docs/auth/social-auth/discord) [Github](https://wasp.sh/docs/auth/social-auth/github) [Google](https://wasp.sh/docs/auth/social-auth/google) [Keycloak](https://wasp.sh/docs/auth/social-auth/keycloak)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onBeforeLogin } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onBeforeLogin,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import { HttpError } from "wasp/server"
import type { OnBeforeLoginHook } from "wasp/server/auth"
export const onBeforeLogin: OnBeforeLoginHook = async ({
providerId,
user,
prisma,
req,
}) => {
if (
providerId.providerName === "email" &&
providerId.providerUserId === "some@email.com"
) {
throw new HttpError(403, "You cannot log in with this email")
}
}
```
Read more about the data the `onBeforeLogin` hook receives in the [API Reference](#the-onbeforelogin-hook).
#### Executing code after the user logs in
Wasp calls the `onAfterLogin` hook after the user logs in.
The `onAfterLogin` hook can be useful if you want to perform some action after the user logs in, like syncing the user with a third-party service.
Since the `onAfterLogin` hook receives the OAuth tokens, you can use it to update the OAuth access token for the user in your database. You can also use it to [refresh the OAuth access token](#refreshing-the-oauth-access-token) if the provider supports it.
Works with [Email](https://wasp.sh/docs/auth/email) [Username & Password](https://wasp.sh/docs/auth/username-and-pass) [Discord](https://wasp.sh/docs/auth/social-auth/discord) [Github](https://wasp.sh/docs/auth/social-auth/github) [Google](https://wasp.sh/docs/auth/social-auth/google) [Keycloak](https://wasp.sh/docs/auth/social-auth/keycloak)
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import { onAfterLogin } from "./src/auth/hooks" with { type: "ref" }
export default app({
// ...
auth: {
// ...
onAfterLogin,
},
// ...
})
```
```ts title="src/auth/hooks.ts"
import type { OnAfterLoginHook } from "wasp/server/auth"
export const onAfterLogin: OnAfterLoginHook = async ({
providerId,
user,
oauth,
prisma,
req,
}) => {
console.log("user object", user)
// If this is an OAuth signup, you have access to the OAuth tokens and the uniqueRequestId
if (oauth) {
console.log("accessToken", oauth.tokens.accessToken)
console.log("uniqueRequestId", oauth.uniqueRequestId)
const id = oauth.uniqueRequestId
const data = someKindOfStore.get(id)
if (data) {
console.log("saved data for the ID", data)
}
someKindOfStore.delete(id)
}
}
```
Read more about the data the `onAfterLogin` hook receives in the [API Reference](#the-onafterlogin-hook).
#### Refreshing the OAuth access token
Some OAuth providers support refreshing the access token when it expires. To refresh the access token, you need the OAuth **refresh token**.
Wasp exposes the OAuth refresh token in the `onAfterSignup` and `onAfterLogin` hooks. You can store the refresh token in your database and use it to refresh the access token when it expires.
Import the provider object with the OAuth client from the `wasp/server/auth` module. For example, to refresh the Google OAuth access token, import the `google` object from the `wasp/server/auth` module. You use the `refreshAccessToken` method of the OAuth client to refresh the access token.
Here's an example of how you can refresh the access token for Google OAuth:
```ts title="src/auth/hooks.ts"
import type { OnAfterLoginHook } from "wasp/server/auth"
import { google } from "wasp/server/auth"
export const onAfterLogin: OnAfterLoginHook = async ({ oauth }) => {
if (oauth.provider === "google" && oauth.tokens.refreshToken !== null) {
const newTokens = await google.oAuthClient.refreshAccessToken(
oauth.tokens.refreshToken
)
log("new tokens", newTokens)
}
}
```
Google exposes the `accessTokenExpiresAt` field in the `oauth.tokens` object. You can use this field to determine when the access token expires.
If you want to refresh the token periodically, use a [Wasp Job](https://wasp.sh/docs/advanced/jobs).
### API Reference
```ts title="main.wasp.ts"
import { app } from "@wasp.sh/spec"
import {
onBeforeSignup,
onAfterSignup,
onAfterEmailVerified,
onBeforeOAuthRedirect,
onBeforeLogin,
onAfterLogin,
} from "./src/auth/hooks" with { type: "ref" }
export default app({
name: "myApp",
wasp: { version: "^0.25" },
title: "My App",
head: [""],
auth: {
userEntity: "User",
methods: {
// ...
},
onBeforeSignup,
onAfterSignup,
onAfterEmailVerified,
onBeforeOAuthRedirect,
onBeforeLogin,
onAfterLogin,
},
// ...
})
```
#### Common hook input
The following properties are available in all auth hooks:
- `prisma: PrismaClient`
The Prisma client instance which you can use to query your database.
- `req: Request`
The [Express request object](https://expressjs.com/en/api.html#req) from which you can access the request headers, cookies, etc.
#### The `onBeforeSignup` hook
```ts title="src/auth/hooks.ts"
import type { OnBeforeSignupHook } from "wasp/server/auth"
export const onBeforeSignup: OnBeforeSignupHook = async ({
providerId,
prisma,
req,
}) => {
// Hook code goes here
}
```
The hook receives an object as **input** with the following properties:
- [`providerId: ProviderId`](#providerid-fields)
- Plus the [common hook input](#common-hook-input)
Wasp ignores this hook's **return value**.
#### The `onAfterSignup` hook
```ts title="src/auth/hooks.ts"
import type { OnAfterSignupHook } from "wasp/server/auth"
export const onAfterSignup: OnAfterSignupHook = async ({
providerId,
user,
oauth,
prisma,
req,
}) => {
// Hook code goes here
}
```
The hook receives an object as **input** with the following properties:
- [`providerId: ProviderId`](#providerid-fields)
- `user: User`
The user object that was created.
- [`oauth?: OAuthFields`](#oauth-fields)
- Plus the [common hook input](#common-hook-input)
Wasp ignores this hook's **return value**.
#### The `onAfterEmailVerified` hook
```ts title="src/auth/hooks.ts"
import type { OnAfterEmailVerifiedHook } from "wasp/server/auth"
export const onAfterEmailVerified: OnAfterEmailVerifiedHook = async ({
email,
user,
prisma,
req,
}) => {
// Hook code goes here
}
```
The hook receives an object as **input** with the following properties:
- `email: string`
The user's veriried email address.
- `user: User`
The user who completed email verification.
- Plus the [common hook input](#common-hook-input)
Wasp ignores this hook's **return value**.
#### The `onBeforeOAuthRedirect` hook
```ts title="src/auth/hooks.ts"
import type { OnBeforeOAuthRedirectHook } from "wasp/server/auth"
export const onBeforeOAuthRedirect: OnBeforeOAuthRedirectHook = async ({
url,
oauth,
prisma,
req,
}) => {
// Hook code goes here
return { url }
}
```
The hook receives an object as **input** with the following properties:
- `url: URL`
Wasp uses the URL for the OAuth redirect.
- `oauth: { uniqueRequestId: string }`
The `oauth` object has the following fields:
- `uniqueRequestId: string`
The unique request ID for the OAuth flow (you might know it as the `state` parameter in OAuth.)
You can use the unique request ID to save data (e.g. request query params) that you can later use in the `onAfterSignup` or `onAfterLogin` hooks.
- Plus the [common hook input](#common-hook-input)
This hook's return value must be an object that looks like this: `{ url: URL }`. Wasp uses the URL to redirect the user to the OAuth provider.
#### The `onBeforeLogin` hook
```ts title="src/auth/hooks.ts"
import type { OnBeforeLoginHook } from "wasp/server/auth"
export const onBeforeLogin: OnBeforeLoginHook = async ({
providerId,
prisma,
req,
}) => {
// Hook code goes here
}
```
The hook receives an object as **input** with the following properties:
- [`providerId: ProviderId`](#providerid-fields)
- `user: User`
The user that is trying to log in.
- Plus the [common hook input](#common-hook-input)
Wasp ignores this hook's **return value**.
#### The `onAfterLogin` hook
```ts title="src/auth/hooks.ts"
import type { OnAfterLoginHook } from "wasp/server/auth"
export const onAfterLogin: OnAfterLoginHook = async ({
providerId,
user,
oauth,
prisma,
req,
}) => {
// Hook code goes here
}
```
The hook receives an object as **input** with the following properties:
- [`providerId: ProviderId`](#providerid-fields)
- `user: User`
The logged-in user's object.
- [`oauth?: OAuthFields`](#oauth-fields)
- Plus the [common hook input](#common-hook-input)
Wasp ignores this hook's **return value**.
#### ProviderId fields
The `providerId` object represents the user for the current authentication method. Wasp passes it to the `onBeforeSignup`, `onAfterSignup`, `onBeforeLogin`, and `onAfterLogin` hooks.
It has the following fields:
- `providerName: string`
The provider's name (e.g. `"email"`, `"google"`, `"github"`)
- `providerUserId: string`
The user's unique ID in the provider's system (e.g. email, Google ID, GitHub ID)
#### OAuth fields
Wasp passes the `oauth` object to the `onAfterSignup` and `onAfterLogin` hooks only when the user is authenticated with [Social Auth](https://wasp.sh/docs/auth/social-auth/overview).
It has the following fields:
- `providerName: string`
The name of the OAuth provider the user authenticated with (e.g. `"google"`, `"github"`).
- `tokens: Tokens`
You can use the OAuth tokens to make requests to the provider's API on the user's behalf.
Depending on the OAuth provider, the `tokens` object might have different fields. For example, Google has the fields `accessToken`, `refreshToken`, `idToken`, and `accessTokenExpiresAt`.
To access the provider-specific fields, you must first narrow down the `oauth.tokens` object type to the specific OAuth provider type.
```ts
if (oauth && oauth.providerName === "google") {
console.log(oauth.tokens.accessToken)
// ^ Google specific tokens are available here
console.log(oauth.tokens.refreshToken)
console.log(oauth.tokens.idToken)
console.log(oauth.tokens.accessTokenExpiresAt)
}
```
- `uniqueRequestId: string`
The unique request ID for the OAuth flow (you might know it as the `state` parameter in OAuth.)
You can use the unique request ID to get the data that was saved in the `onBeforeOAuthRedirect` hook.
## Authentication / Advanced / Custom sign-up actions
If you need to deeply hook into the sign-up process, you can create your own sign-up action and customize the code to, for example, add extra validation, store more data, or otherwise call custom code at registration time.
:::danger
Custom sign-up actions are complex, and we don't recommend creating a custom sign-up action unless you have a good reason to do so. They also require you to be careful, as any small mistake will compromise the security of your app.
Before using custom actions, check if our support for [custom auth UI](https://wasp.sh/docs/auth/overview#custom-auth-ui) and for [auth hooks](https://wasp.sh/docs/auth/auth-hooks) could fit well with you requirements.
:::
You are not able to use Wasp UI with custom sign-up actions, so you're expected to implemented your own UI and call the custom actions you create from it.
### Example code
Below you will find a starting point for creating your own actions. The given implementation is similar to what Wasp does under the hood, and it is up to you to customize it.
#### Email
```ts title="main.wasp.ts"
import { action, app } from "@wasp.sh/spec"
import { onBeforeSignup } from "./src/auth/hooks" with { type: "ref" }
import { customSignup } from "./src/auth/signup" with { type: "ref" }
export default app({
name: "myApp",
wasp: { version: "^0.25" },
title: "My App",
head: [""],
auth: {
// ...
onBeforeSignup,
},
spec: [
action(customSignup),
],
})
```
```ts title="src/auth/hooks.ts"
import { HttpError } from "wasp/server";
// This disables Wasp's default sign-up action
export const onBeforeSignup = async () => {
throw new HttpError(403, "This sign-up method is disabled");
};
```
```ts title="src/auth/signup.ts"
import type { CustomSignup } from "wasp/server/operations";
import { HttpError } from "wasp/server";
import {
createEmailVerificationLink,
createProviderId,
createUser,
ensurePasswordIsPresent,
ensureValidEmail,
ensureValidPassword,
findAuthIdentity,
getProviderData,
sanitizeAndSerializeProviderData,
sendEmailVerificationEmail,
} from "wasp/server/auth";
type CustomSignupInput = {
email: string;
password: string;
};
type CustomSignupOutput = {
success: boolean;
message: string;
};
export const customSignup: CustomSignup<
CustomSignupInput,
CustomSignupOutput
> = async (args, _context) => {
ensureValidEmail(args);
ensurePasswordIsPresent(args);
ensureValidPassword(args);
try {
const providerId = createProviderId("email", args.email);
const existingAuthIdentity = await findAuthIdentity(providerId);
let providerData;
if (existingAuthIdentity) {
// User already exists, handle accordingly
// For example, throw an error or return a message
throw new HttpError(400, "Email already exists.");
// Or, another example, you can check if the user is already
// verified and re-send the verification email if not
providerData = getProviderData<"email">(
existingAuthIdentity.providerData,
);
if (providerData.isEmailVerified)
throw new HttpError(400, "Email already verified.");
}
if (!providerData) {
providerData = await sanitizeAndSerializeProviderData<"email">({
// The provider will hash the password for us, so we don't need to do it here.
hashedPassword: args.password,
isEmailVerified: false,
emailVerificationSentAt: null,
passwordResetSentAt: null,
});
await createUser(
providerId,
providerData,
// Any additional data you want to store on the User entity
{},
);
}
// Verification link links to a client route e.g. /email-verification
const verificationLink = await createEmailVerificationLink(
args.email,
"/email-verification",
);
try {
await sendEmailVerificationEmail(args.email, {
from: {
name: "My App Postman",
email: "hello@itsme.com",
},
to: args.email,
subject: "Verify your email",
text: `Click the link below to verify your email: ${verificationLink}`,
html: `
{task.title} by {getFirstProviderUserId(task.user)}
))}
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: any) { return { success: false, message: e.message, }; } // Your custom code after sign-up. // ... return { success: true, message: "User created successfully", }; }; ``` #### Username and password ```ts title="main.wasp.ts" import { action, app } from "@wasp.sh/spec" import { onBeforeSignup } from "./src/auth/hooks" with { type: "ref" } import { customSignup } from "./src/auth/signup" with { type: "ref" } export default app({ name: "myApp", wasp: { version: "^0.25" }, title: "My App", auth: { // ... onBeforeSignup, }, spec: [ action(customSignup), ], }) ``` ```ts title="src/auth/hooks.ts" import { HttpError } from "wasp/server"; // This disables Wasp's default sign-up action export const onBeforeSignup = async () => { throw new HttpError(403, "This sign-up method is disabled"); }; ``` ```ts title="src/auth/signup.ts" import type { CustomSignup } from "wasp/server/operations"; import { createProviderId, createUser, ensurePasswordIsPresent, ensureValidPassword, ensureValidUsername, sanitizeAndSerializeProviderData, } from "wasp/server/auth"; type CustomSignupInput = { username: string; password: string; }; type CustomSignupOutput = { success: boolean; message: string; }; export const customSignup: CustomSignup< CustomSignupInput, CustomSignupOutput > = async (args, _context) => { ensureValidUsername(args); ensurePasswordIsPresent(args); ensureValidPassword(args); try { const providerId = createProviderId("username", args.username); const providerData = await sanitizeAndSerializeProviderData<"username">({ // The provider will hash the password for us, so we don't need to do it here. hashedPassword: args.password, }); await createUser(providerId, providerData, {}); } catch (e: any) { console.error("Error creating user:", e); return { success: false, message: e.message, }; } return { success: true, message: "User created successfully", }; }; ``` ### Validators API Reference We suggest using the built-in field validators for your authentication flow. You can import them from `wasp/server/auth`. These are the same validators that Wasp uses internally for the default authentication flow. ##### Username - `ensureValidUsername(args)` Checks if the username is valid and throws an error if it's not. Read more about the validation rules [here](https://wasp.sh/docs/auth/overview#default-validations). ##### Email - `ensureValidEmail(args)` Checks if the email is valid and throws an error if it's not. Read more about the validation rules [here](https://wasp.sh/docs/auth/overview#default-validations). ##### Password - `ensurePasswordIsPresent(args)` Checks if the password is present and throws an error if it's not. - `ensureValidPassword(args)` Checks if the password is valid and throws an error if it's not. Read more about the validation rules [here](https://wasp.sh/docs/auth/overview#default-validations). ## Project Setup / Starter Templates We created a few starter templates to help you get started with Wasp. Check out the list [below](#available-templates). ### Using a Template Run `wasp new` to run the interactive mode for creating a new Wasp project. It will ask you for the project name, and then for the template to use: ``` $ wasp new Enter the project name (e.g. my-project) โธ MyFirstProject Choose a starter template [1] basic (default) A basic starter template designed to help you get up and running quickly. It features examples covering the most common use cases. [2] minimal A minimal starter template that features just a single page. [3] saas Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check out https://opensaas.sh/ for more details. โธ 1 ๐ --- Creating your project from the "basic" template... ------------------------- Created new Wasp app in ./MyFirstProject directory! To run your new app, do: cd MyFirstProject wasp db migrate-dev wasp start ``` ### Available Templates When you have a good idea for a new product, you don't want to waste your time on setting up common things like authentication, database, etc. That's why we created a few starter templates to help you get started with Wasp. #### OpenSaaS.sh template  Everything a SaaS needs! Comes with Auth, ChatGPT API, Tailwind, Stripe payments and more. Check outMy App
}
```
For example, `imgUrl` will be `/img.png` during development, and become `/assets/img.2d8efhg.png` in the production build.
This is what you want to use most of the time, as it ensures that the asset file exists and is included in the bundle.
We are using Vite under the hood, read more about importing static assets in Vite's [docs](https://vitejs.dev/guide/assets.html#importing-asset-as-url).
### The `public` Directory
If you have assets that are:
- Never referenced in source code (e.g. robots.txt)
- Must retain the exact same file name (without hashing)
- ...or you simply don't want to have to import an asset first just to get its URL
Then you can place the asset in the `public` directory at the root of your project:
```
.
โโโ public
โโโ favicon.ico
โโโ robots.txt
```
Assets in this directory will be served at root path `/` during development and copied to the root of the dist directory as-is.
For example, if you have a file `favicon.ico` in the `public` directory, and your app is hosted at `https://myapp.com`, it will be made available at `https://myapp.com/favicon.ico`.
:::info[Usage in client code]
Note that:
- You should always reference public assets using root absolute path
- for example, `public/icon.png` should be referenced in source code as `/icon.png`.
- Assets in the `public` directory **cannot be imported** from TypeScript.
:::
## Project Setup / Env Variables
**Environment variables** are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production.
For instance, *during development*, you may want your project to connect to a local development database running on your machine, but *in production*, you want it to connect to the production database. Similarly, in development, you may want to use a test Stripe account, while in production, your app should use a real Stripe account.
While some env vars are required by Wasp, such as the database connection or secrets for social auth, you can also define your env vars for any other useful purposes, and then access them in the code.
Let's go over the available env vars in Wasp, how to define them, and how to use them in your project.
### Client Env Vars
Client environment variables are injected into the client Javascript code during the build process, making them public and readable by anyone. Therefore, you should **never store secrets in them** (such as secret API keys, you should store secrets in the server env variables).
:::caution[Client Env Var Prefix]
Client env vars must be prefixed with `REACT_APP_`, for example: `REACT_APP_SOME_VAR_NAME=...` for security reasons. Wasp will only inject env vars that start with this prefix into the client code to prevent accidental exposure of sensitive information.
:::
You can read them from the client code like this:
```ts title="src/App.ts"
import { env } from "wasp/client"
console.log(env.REACT_APP_SOME_VAR_NAME)
```
Read more about the `env` object in the [API reference](#client-env-vars-api).
#### Wasp Client Env Vars
Here are the client env vars that Wasp defines:
##### General Configuration {#client-general-configuration}
These are some general env variables used for various Wasp features:
| Name | Type | Notes |
| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `REACT_APP_API_URL` | URLrequired | The client uses this as the server URL. This app is required in production but defaults to `http://localhost:3001` in development. |
### Server Env Vars
You can store secret values (e.g. secret API keys) in the server env variables since they are not publicly readable. You can define them without any special prefix, such as `SOME_VAR_NAME=...`.
You can read the env vars from server code like this:
```ts
import { env } from "wasp/server"
console.log(env.SOME_VAR_NAME)
```
Read more about the `env` object in the [API reference](#server-env-vars-1).
#### Wasp Server Env Vars
##### General Configuration {#server-general-configuration}
These are some general env variables used for various Wasp features:
| Name | Type | Notes |
| --------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | Stringrequired | The URL of the PostgreSQL database you want your app to use. |
| `WASP_WEB_CLIENT_URL` | URLrequired | Server uses this value as your client URL in various features e.g. linking to your app in e-mails. Defaults to `http://localhost:3000` in development. |
| `WASP_SERVER_URL` | URLrequired | Server uses this value as your server URL in various features e.g. to redirect users when logging in with OAuth providers like Google or GitHub. Defaults to `http://localhost:3001` in development. |
| `JWT_SECRET` | Stringrequired | A random string of at least 32 characters. Needed to generate secure tokens. Defaults to `DEVJWTSECRET` in development. Generate secret |
| `PORT` | IntegeroptionalDefault: `3001` | This is where the server listens for requests. |
##### SMTP Email Sender
If you are using `SMTP` as your email sender, you need to provide the following environment variables:
| Name | Type | Notes |
| --------------- | --------------- | ------------------------- |
| `SMTP_HOST` | Stringrequired | The SMTP server host. |
| `SMTP_PORT` | Integerrequired | The SMTP server port. |
| `SMTP_USERNAME` | Stringrequired | The SMTP server username. |
| `SMTP_PASSWORD` | Stringrequired | The SMTP server password. |
##### SendGrid Email Sender
If you are using `SendGrid` as your email sender, you need to provide the following environment variables:
| Name | Type | Notes |
| ------------------ | -------------- | --------------------- |
| `SENDGRID_API_KEY` | Stringrequired | The SendGrid API key. |
##### Mailgun Email Sender
If you are using `Mailgun` as your email sender, you need to provide the following environment variables:
| Name | Type | Notes |
| ----------------- | -------------- | ----------------------------------------------------------------------------- |
| `MAILGUN_API_KEY` | Stringrequired | The Mailgun API key. |
| `MAILGUN_DOMAIN` | Stringrequired | The Mailgun domain. |
| `MAILGUN_API_URL` | URLoptional | Useful if you want to use the EU API endpoint (`https://api.eu.mailgun.net`). |
##### Resend Email Sender
If you are using `Resend` as your email sender, you need to provide the following environment variables:
| Name | Type | Notes |
| ---------------- | -------------- | ------------------- |
| `RESEND_API_KEY` | Stringrequired | The Resend API key. |
##### OAuth Providers
If you are using OAuth, you need to provide the following environment variables:
| Name | Type | Notes |
| ------------------------------- | -------------- | ------------------------------------------------- |
| `-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
Chat {connectionIcon}
- {messageList}
Streaming Example
{response}
{tasks.map((task) => (
{/* ๐ Required and typechecked against the path */}
{task.description}
))}
)
}
```
The `to` prop is autocompleted from the routes you defined in `main.wasp.ts`, and `params` is typechecked against the path you picked. Rename a route or change a param, and any broken `Link` is pointed out by Typescript.
#### Reacting to navigation state with `NavLink`
Use `NavLink` when the current page should be highlighted, or when you want to show a spinner during a pending transition. It takes the same props as `Link`, but `className`, `style`, and `children` can be render-prop functions that receive `{ isActive, isPending, isTransitioning }`.
```tsx title="Navigation.tsx"
import { NavLink } from "wasp/client/router"
export const Navigation = () => {
return (
)
}
```
Everything below applies to both `Link` and `NavLink`.
#### Catch-all routes
If a route path ends with a `/*` pattern (also known as [splat](https://reactrouter.com/8.0.1/start/declarative/routing#splats)), pass the rest of the path as the `*` param:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { CatchAllPage } from "./src/CatchAllPage" with { type: "ref" }
export default app({
// ...
spec: [
route("CatchAllRoute", "/pages/*", page(CatchAllPage)),
],
})
```
```jsx title="TaskList.tsx"
About
```
This renders as `/pages/about`.
#### Optional static segments
If a route has an optional static segment, you can choose at the call site whether to include it or not:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { OptionalPage } from "./src/OptionalPage" with { type: "ref" }
export default app({
// ...
spec: [
route("OptionalRoute", "/task/:id/details?", page(OptionalPage)),
],
})
```
```jsx title="TaskList.tsx"
/* You can include the optional segment ... */
Task 1
/* ... or leave it out */
Task 1
```
#### Search params and hash
You can also pass `search` and `hash` to attach a query string and fragment:
```tsx title="TaskList.tsx"
{task.description}
```
This renders as `/task/1?sortBy=date#comments`. Check out the [API Reference](#link-component) for the full list of accepted props.
### Typesafe navigation outside of components
When you need a URL string instead of a component, for example for `useNavigate`, redirects, `window.location`, or anywhere you are not rendering JSX, use the `routes` object from `wasp/client/router`:
```jsx title="TaskList.tsx"
import { routes } from "wasp/client/router"
const linkToTask = routes.TaskRoute.build({ params: { id: 1 } })
```
`linkToTask` is the string `/task/1`. Each route from `main.wasp.ts` shows up on `routes` with a `build` function whose options are typed against the route's path, so the same compile-time safety you get from `Link` is also available outside of JSX.
`build` follows the same rules as the [components above](#typesafe-navigation-with-components): catch-all routes take a `*` param, optional static segments pick a concrete `path`, and you can attach a query string and fragment via `search` and `hash`.
```tsx
const linkToTaskComments = routes.OptionalRoute.build({
path: "/task/:id/details",
params: { id: 1 },
search: { sortBy: "date" },
hash: "comments",
})
```
This renders as `/task/1/details?sortBy=date#comments`. Check out the [API Reference](#routes-object) for the full shape.
### API Reference
#### `Link` Component
The `Link` component accepts the following props:
- `to` required
- A valid Wasp Route path from your `main.wasp.ts` file.
In the case of optional static segments, you must provide one of the possible paths which include or exclude the optional segment. For example, if the path is `/task/:id/details?`, you must provide either `/task/:id/details` or `/task/:id`.
- `params: { [name: string]: string | number }` required (if the path contains params)
- An object with keys and values for each param in the path.
- For example, if the path is `/task/:id`, then the `params` prop must be `{ id: 1 }`. Wasp supports required and optional params.
- `search: string[][] | RecordViewing photo {photoId}
;
}
```
Read more in the [React Router docs on dynamic segments](https://reactrouter.com/8.0.1/start/data/routing#dynamic-segments).
#### Optional Segments
Append `?` to a path segment to make it optional. The route will match whether or not the segment is present.
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { PhotoPage } from "./src/PhotoPage" with { type: "ref" }
export default app({
// ...
spec: [
route("PhotoRoute", "/photo/:photoId/edit?", page(PhotoPage)),
],
})
```
```tsx title="src/PhotoPage.tsx"
import { useParams, useLocation } from "react-router";
export function PhotoPage() {
const { photoId } = useParams<"photoId">();
const { pathname } = useLocation();
const isEditing = pathname.endsWith("/edit");
return (
{isEditing ? "Editing" : "Viewing"} photo {photoId}
);
}
```
Read more in the [React Router docs on optional segments](https://reactrouter.com/8.0.1/start/data/routing#optional-segments).
#### Splats
Use `/*` at the end of a route path to match any remaining path segments. Access the matched portion with the `'*'` param.
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { FilesPage } from "./src/FilesPage" with { type: "ref" }
export default app({
// ...
spec: [
route("FilesRoute", "/files/*", page(FilesPage)),
],
})
```
```tsx title="src/FilesPage.tsx"
import { useParams } from "react-router";
export function FilesPage() {
const { "*": filePath } = useParams();
// Visiting /files/docs/report.txt โ filePath = "docs/report.txt"
return File: {filePath}
;
}
```
Read more in the [React Router docs on splats](https://reactrouter.com/8.0.1/start/data/routing#splats).
### Lazy-Loaded Routes
By default, Wasp lazy-loads all page routes using React Router's [`lazy`](https://reactrouter.com/how-to/code-splitting) property. This means each page's code is only downloaded when the user navigates to it, resulting in smaller initial bundle sizes. This is especially useful for apps with many routes.
If you need a specific route to be eagerly loaded (included in the main bundle), you can set `lazy: false` on the route spec:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { DashboardPage } from "./src/DashboardPage" with { type: "ref" }
// This route's page will be included in the initial bundle
export default app({
// ...
spec: [
route("DashboardRoute", "/dashboard", page(DashboardPage), { lazy: false }),
],
})
```
:::note
Most apps won't need to change this. Disabling lazy loading is useful when you want to avoid the brief loading delay for a page that users navigate to very frequently, at the cost of a larger initial download.
:::
### Prerendered routes
You can prerender specific routes at build time by setting the `prerender` property. This generates static HTML that is served immediately, giving faster load times and better SEO.
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { LandingPage } from "./src/LandingPage" with { type: "ref" }
export default app({
// ...
spec: [
route("LandingRoute", "/", page(LandingPage), { prerender: true }),
],
})
```
See the [Prerendering](https://wasp.sh/docs/advanced/prerendering) page for the full documentation.
## Advanced Features / Prerendering
By default, Wasp apps are single-page applications: the browser downloads JavaScript, and React renders the page on the client. This means search engines, AI crawlers, and users on slow connections see a blank page until JavaScript loads and executes.
Wasp can **prerender** specific routes at build time, producing static HTML files that are served immediately. The page then hydrates on the client for full interactivity.
This gives you:
- **Better SEO:** search engines index real HTML content instead of an empty shell.
- **LLM and AI readability:** AI crawlers (ChatGPT, Perplexity, Claude, etc.) can read your content directly.
- **Faster performance on user experience:** users see content immediately (better [Largest Contentful Paint](https://developer.chrome.com/docs/lighthouse/performance/lighthouse-largest-contentful-paint)), with no layout shift from content loading in (better [Cumulative Layout Shift](https://web.dev/articles/cls)).
- **Works without JavaScript:** content is visible even before the browser loads your JS bundle.
### Enabling prerendering
You can add the `prerender` option to a Route spec to enable prerendering. The only [limitation](#limitations) is that the route must **not** have the `authRequired` property turned on.
Once `prerender` is enabled, Wasp will know to render this route's HTML on `wasp build`. The generated HTML is served directly to browsers and crawlers, then we [hydrate](https://react.dev/reference/react-dom/client/hydrateRoot) the page for full interactivity.
#### Static routes
For routes with no [dynamic segments](https://wasp.sh/docs/advanced/routing#dynamic-segments), you can just set `prerender: true`:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { AboutPage } from "./src/AboutPage" with { type: "ref" }
import { LandingPage } from "./src/LandingPage" with { type: "ref" }
export default app({
// ...
spec: [
route("LandingRoute", "/", page(LandingPage), {
prerender: true,
}),
route("AboutRoute", "/about", page(AboutPage), {
prerender: true,
}),
],
})
```
#### Dynamic routes
If your route has [dynamic segments](https://wasp.sh/docs/advanced/routing#dynamic-segments), you'll need to declare with which data you want to prerender them, by passing an array of concrete paths:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { CountryPage } from "./src/CountryPage" with { type: "ref" }
export default app({
// ...
spec: [
route("CountryRoute", "/supported-countries/:country", page(CountryPage), {
prerender: ["/supported-countries/us", "/supported-countries/es"],
}),
],
})
```
The prerendered paths must match the route's pattern, with all dynamic segments replaced by concrete values. All paths not declared in the `prerender` array will still work, but they will be rendered on the client as normal, instead of being prerendered.
#### Generating prerendered paths from data
If you have a lot of dynamic paths to prerender, you can generate the list of paths from your data or other sources. For example, if you want to prerender the routes for your Top 10 countries, you can fetch them from your analytics and generate the paths:
```ts title="main.wasp.ts"
import { app, page, route } from "@wasp.sh/spec"
import { CountryPage } from "./src/CountryPage" with { type: "ref" }
async function getTopCountries(): Promise{isClient ? "Client content" : "Prerendered content"}
; } ``` And the **correct** approach: ```tsx title="src/LandingPage.tsx" // โ No hydration mismatch import { useState, useEffect } from "react"; function useIsClient() { const [isClient, setIsClient] = useState(false); useEffect(() => { setIsClient(true); }, []); return isClient; } export function LandingPage() { const isClient = useIsClient(); return{isClient ? "Client content" : "Prerendered content"}
; } ``` ##### Further reading React has some documentation on [hydration](https://react.dev/reference/react-dom/client/hydrateRoot), which is relevant to Wasp prerendering. In particular, you may find useful the section on [suppressing unavoidable errors](https://react.dev/reference/react-dom/client/hydrateRoot#suppressing-unavoidable-hydration-mismatch-errors), or the one on [handling legitimately differences between client and server content](https://react.dev/reference/react-dom/client/hydrateRoot#handling-different-client-and-server-content). ### API reference [API reference](https://wasp.sh/docs/api/@wasp.sh/spec/interfaces/Route#prerender) #### [Route.prerender ยป](https://wasp.sh/docs/api/@wasp.sh/spec/interfaces/Route#prerender) [The full description of the prerender option of the route spec.](https://wasp.sh/docs/api/@wasp.sh/spec/interfaces/Route#prerender) ## Advanced Features / SEO & GEO Search engine optimization (SEO) and generative engine optimization (GEO) are about making your app visible and attractive to search engines, social media platforms, and AI assistants. This page is a quick overview of what Wasp already handles for you, and the features you'll use to optimize your app. ### What Wasp does for you When you run `wasp build`, your app is automatically optimized for production. You don't need to configure anything for: - **Bundling and minification.** Wasp uses Vite to minify your JavaScript and CSS, and split it by page, so browsers only download the code each page needs. Page speed is a ranking factor for search engines. - **Asset hashing.** [Assets imported from your source code](https://wasp.sh/docs/project/static-assets#importing-an-asset-as-url) get hashed filenames, so browsers can cache them aggressively. - **Serving standard files.** Crawlers look for standard files at the root of your site, like `robots.txt`, `sitemap.xml`, or `llms.txt`. Put them in [the `public` directory](https://wasp.sh/docs/project/static-assets#the-public-directory) and Wasp serves them as-is from the root path. ### What Wasp gives you tools for - **Titles and meta tags.** Search engines and social platforms read `` tags to build search results and link previews. Set app-wide tags with the [`title` and `head` fields](https://wasp.sh/docs/project/customizing-app#adding-additional-lines-to-the-head) of your `app` declaration, and per-page tags by rendering `` elements [directly in your page components](https://react.dev/reference/react-dom/components/meta). - **Prerendering.** Wasp apps are single-page applications, and many crawlers and AI assistants don't run JavaScript, so they'd see an empty page. Mark a route with `prerender: true` and [Wasp generates its HTML at build time](https://wasp.sh/docs/advanced/prerendering), making your content readable without JavaScript. - **Crawlable navigation.** Crawlers discover your pages by following `` tags. [Wasp's `Link` component](https://wasp.sh/docs/advanced/links) renders real, type-checked `` tags, unlike programmatic navigation, which crawlers can't see. - **Lazy loading.** Split heavy or below-the-fold components out of the initial bundle with [`React.lazy`](https://react.dev/reference/react/lazy), so your pages stay small and fast. ### Learn more For the full picture, including how to measure your app, where to apply each technique, and recommended tools, read our dedicated guide: [Guide](https://wasp.sh/docs/guides/optimization/seo) #### [SEO & GEO ยป](https://wasp.sh/docs/guides/optimization/seo) [Measure and optimize your app for search engines and AI assistants.](https://wasp.sh/docs/guides/optimization/seo) ## General / Wasp Spec (main.wasp.ts) You define and configure the high level of your app (pages, routes, queries, actions, auth, ...) in a `main.wasp.ts` file in the root of your project. We call this file the **Wasp Spec**. You write the Wasp Spec in TypeScript, so you get out-of-the-box support in all editors, full type checking, and the flexibility of a real programming language while configuring your app. :::info[Coming from an older version of Wasp?] The Wasp Spec replaces two older ways of configuring a Wasp app: - The **Wasp DSL** (`main.wasp`). - The **TS Config** (`main.wasp.ts`, with the class-based `new App(...)` API). If you're upgrading from Wasp `0.23.X` to `0.24.X`, start with the [migration guide](https://wasp.sh/docs/0.24/migration-guide). Then pick the conversion guide matching your old config: - **Wasp DSL** โ [Migrating from the Wasp DSL](https://wasp.sh/docs/guides/legacy/wasp-dsl) - **TS Config** โ [Migrating from the TS Config](https://wasp.sh/docs/guides/legacy/wasp-ts-config) ::: ### A quick example ```ts title="main.wasp.ts" import { app, page, query, route } from "@wasp.sh/spec"; import { MainPage } from "./src/MainPage" with { type: "ref" }; import { getTasks } from "./src/queries" with { type: "ref" }; export default app({ name: "todoApp", wasp: { version: "^0.25" }, title: "ToDo App", head: [""], spec: [ route("MainRoute", "/", page(MainPage, { authRequired: true })), query(getTasks, { entities: ["Task"] }), ], }); ``` You build your app by: 1. Importing the building blocks (`app`, `page`, `route`, `query`, ...) from `@wasp.sh/spec`. 2. Importing your own components and functions adding the import attribute `with { type: "ref" }`. 3. Calling `app({ ... })` with your app's configuration, listing all the pages, routes, queries, actions, etc. in the `spec` property. 4. Exporting the result as the **default export** of the file. `spec` is short for specification: the pages, routes, queries, actions, APIs, jobs and CRUDs that make up your app. ### `wasp install` The `@wasp.sh/spec` package doesn't exist on npm, but it is generated by Wasp per project, so we can customize it to fit the needs of your app. We do this through the `wasp install` command, which installs your app's dependencies and sets up the generated Wasp Spec package. You'll have to run it at least once after creating a new Wasp project, but you might also need to run it again later on when the generated spec needs to be updated. If the Spec needs to be regenerated, Wasp will tell you to run `wasp install` before being able to start the app. Usually, this might happen when upgrading Wasp versions, running `wasp clean`, or removing the `node_modules` folder. ### Referencing your app's code Anywhere the Wasp Spec expects your app's function or component (like a page's `component` or a query's `fn`), you can provide it in one of two ways: #### Reference imports **Recommended** Import the value with the regular syntax, adding `with { type: "ref" }`. Use it when importing components or functions from `src/` so Wasp can connect them to pages, actions, queries, and other specifications. ```ts title="main.wasp.ts" import { MainPage } from "./src/MainPage" with { type: "ref" }; import { getTasks } from "./src/queries" with { type: "ref" }; export default app({ spec: [page(MainPage), query(getTasks)], }); ``` The import paths are relative to the `*.wasp.ts` file they're written in (see [multiple spec files](#splitting-your-spec-into-multiple-files)): ```ts title="src/auth/auth.wasp.ts" import { LoginPage } from "./LoginPage" with { type: "ref" }; export const auth = [page(LoginPage)]; ``` :::note[Limitations] Reference imports have some limitations: - They only work from `*.wasp.ts` files. - The referenced files must be inside the `src` directory. - You can't re-export something as a reference import (`export { X } from "./X" with { type: "ref" }`). Import it first, then re-export it if needed. - Namespace imports (`import * as something from './src/something' with { type: "ref" }`) aren't supported. Use named or default imports instead. The vast majority of Wasp apps won't run into these limitations, so we recommend using reference imports by default. ::: #### `ref` helper {#reference-objects} Use `ref(...)` when a direct reference import is not practical. Import `ref` from `@wasp.sh/spec`, then pass it an import object with `import` (or `importDefault`) and `from`: ```ts title="main.wasp.ts" import { ref } from "@wasp.sh/spec"; export default app({ // ... spec: [ page(ref({ importDefault: "MainPage", from: "./src/MainPage" })), query(ref({ import: "getTasks", from: "./src/queries" })), // You can rename a named import with `alias`: query(ref({ import: "getTasks", alias: "getAllTasks", from: "./src/queries" })), ], }); ``` The `from` path is relative to the `*.wasp.ts` file where you call `ref(...)` and must resolve inside your project's `src` directory. :::note[Limitation] You can't re-export `ref` from `@wasp.sh/spec` (`export { ref } from "@wasp.sh/spec"`). Import it first, then re-export it if needed. ::: ### Useful patterns #### Splitting your spec into multiple files For larger apps you don't have to keep everything in `main.wasp.ts`. You can move related specifications into their own `*.wasp.ts` files and combine them in `main.wasp.ts`. This works well for vertical slices, like keeping a feature's page, route, query, and action specifications in that feature's folder. Each feature file exports it's own `Spec`: ```ts title="src/auth/auth.wasp.ts" import { page, route, type Spec } from "@wasp.sh/spec"; import { LoginPage } from "./LoginPage" with { type: "ref" }; import { SignupPage } from "./SignupPage" with { type: "ref" }; export const authSpec: Spec = [ route("SignupRoute", "/signup", page(SignupPage)), route("LoginRoute", "/login", page(LoginPage)), ]; ``` The `Spec` annotation gives TypeScript enough information to validate the specification in its own file before it's added to the `main.wasp.ts`. Then `main.wasp.ts` imports it and joins in into the `spec`: ```ts title="main.wasp.ts" import { app, page, route } from "@wasp.sh/spec"; import { MainPage } from "./src/MainPage" with { type: "ref" }; import { authSpec } from "./src/auth/auth.wasp"; export default app({ name: "todoApp", wasp: { version: "^0.25" }, title: "ToDo App", head: [""], spec: [ route("MainRoute", "/", page(MainPage, { authRequired: true })), authSpec, ], }); ``` All spec files should have the `.wasp.ts` extension, so they are included in the `tsconfig.wasp.json` and type-checked. #### Detecting production mode Wasp sets the `NODE_ENV` environment variable based on which command you use to run Wasp: - `"development"` during `wasp start` (and some other commands that compile the project, like `wasp db migrate-dev`). - `"production"` during `wasp build`. Because the Wasp Spec is just TypeScript, you can read this variable to switch config values per environment: ```ts title="main.wasp.ts" const isProd = process.env.NODE_ENV === "production"; export default app({ //... emailSender: { provider: isProd ? "SMTP" : "Dummy", defaultFrom: { email: "hi@example.com" }, }, }); ``` ### Reference [API reference](https://wasp.sh/docs/api/@wasp.sh/spec) #### [@wasp.sh/spec ยป](https://wasp.sh/docs/api/@wasp.sh/spec) [A complete overview of all the available configuration options in the Wasp Spec.](https://wasp.sh/docs/api/@wasp.sh/spec) ## General / CLI Reference This guide provides an overview of the Wasp CLI commands, arguments, and options. ### Overview Once [installed](https://wasp.sh/docs/quick-start), you can use the wasp command from your command line. If you run the `wasp` command without any arguments, it will show you a list of available commands and their descriptions: ``` USAGE waspItem {id}
Item {id}
My App
My App
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 &&