A quick guide on installing/using nvm
Install nvm via your OS package manager (`apt`, `pacman`, `homebrew`, ...) or via the [nvm](https://github.com/nvm-sh/nvm#install--update-script) install script.
Then, install a version of Node.js that you need:
```shell
nvm install 24
```
Finally, whenever you need to ensure a specific version of Node.js is used, run:
```shell
nvm use 24
```
to set the Node.js version for the current shell session.
You can run
```shell
node -v
```
to check the version of Node.js currently being used in this shell session.
Check NVM repo for more details: https://github.com/nvm-sh/nvm.
})
If you get stuck at any point (or just want to chat), reach out to us on [Discord](https://discord.gg/rzdnErX) and we will help you! You can find the complete code of the app we're about to build [here](https://github.com/wasp-lang/wasp/tree/release/examples/tutorials/TodoApp). ### Creating a Project To setup a new Wasp project, run the following command in your terminal:
})
Wasp has generated for you the full front-end and back-end code of the app! Next, we'll take a closer look at how the project is structured. ### A note on supported languages Wasp supports both JavaScript and TypeScript out of the box, but you are free to choose between or mix JavaScript and TypeScript as you see fit. We'll provide you with both JavaScript and TypeScript code in this tutorial. Code blocks will have a toggle to switch between vanilla JavaScript and TypeScript. Try it out:
Here's {name}!
;
};
```
Now you can visit `/hello/johnny` and see "Here's johnny!"
Hello world!
;
};
```
At this point, the main page should look like this:
})
You can now delete redundant files: `src/Main.css`, `src/assets/logo.svg`, and `src/HelloPage.{jsx,tsx}` (we won't need this page for the rest of the tutorial).
Since `src/HelloPage.{jsx,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"
export default app({
name: "TodoApp",
wasp: {
version: "{latestWaspVersion}",
},
title: "TodoApp",
head: [
"",
],
spec: [
route("RootRoute", "/", page(MainPage)),
],
})
```
})
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.
## 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](../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.{jsx,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
{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) => (
);
};
```
})
We'll create a form to add tasks in the next step đĒ
## 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`:
// highlight-next-line
);
};
// ... TaskView, TasksList, NewTaskForm ...
```
})
:::note Automatic Query Invalidation When you create a new task, the list of tasks is automatically updated to display the new task, even though you haven't written any code that does that! Wasp handles these automatic updates under the hood. When you declared the `getTasks` and `createTask` operations, you specified that they both use the `Task` entity. So when `createTask` is called, Wasp knows that the data `getTasks` fetches may have changed and automatically updates it in the background. This means that **out of the box, Wasp keeps all your queries in sync with any changes made through Actions**. This behavior is convenient as a default but can cause poor performance in large apps. While there is no mechanism for overriding this behavior yet, it is something that we plan to include in Wasp in the future. This feature is tracked [here](https://github.com/wasp-lang/wasp/issues/63). ::: ### A Second Action Our Todo app isn't finished if you can't mark a task as done. We'll create a new Action to update a task's status and call it from React whenever a task's checkbox is toggled. Since we've already created one task together, try to create this one yourself. It should be an Action named `updateTask` that receives the task's `id` and its `isDone` status. You can see our implementation below.
{task.description}
);
};
// ... TasksList, NewTaskForm ...
```
I don't have an account yet (go to signup).
I already have an account (go to login).
})
You'll notice that we now have a `User` entity in the database alongside the `Task` entity.
However, you will notice that if you try logging in as different users and creating some tasks, all users share the same tasks. That's because you haven't yet updated the queries and actions to have per-user tasks. Let's do that next.
You might notice some extra Prisma models like `Auth`, `AuthIdentity` and `Session` that Wasp created for you. You don't need to care about these right now, but if you are curious, you can read more about them [here](../auth/entities).
### Defining a User-Task Relation
First, let's define a one-to-many relation between users and tasks (check the [Prisma docs on relations](https://www.prisma.io/docs/orm/prisma-schema/data-model/relations)):
})
You will see that each user has their tasks, just as we specified in our code!
### Logout Button
Last, but not least, let's add the logout functionality:
{$HOLE$}
// highlight-next-line
);
};
```
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.{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).
Explanation for the example above
The above code says that the Query `getAllTasks` doesn't expect any arguments (its input type is `void`), but it does return a list of tasks (its output type is `Task[]`). On the other hand, the Query `getFilteredTasks` expects an object of type `{ isDone: boolean }`. This type is derived from the `Task` entity type. If you don't care about typing the Query's inputs and outputs, you can omit both type arguments. TypeScript will then infer the most general types (`never` for the input and `unknown` for the output). Specifying `Input` or `Output` is completely optional, but we highly recommended it. Doing so gives you: - Type support for the arguments and the return value inside the implementation. - **Full-stack type safety**. We'll explore what this means when we discuss calling the Query from the client.There 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"}
There 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"}
Explanation for the example above
The above code says that the Action `createTask` expects an object with the new task's description (its input type is `Pick"Loading"
} const { description, isDone } = task return (Description: {description}
Is done: {isDone ? "Yes" : "No"}
{isDone || ( // highlight-next-line )}"Loading"
} const { description, isDone } = task return (Description: {description}
Is done: {isDone ? "Yes" : "No"}
{isDone || ( // highlight-next-line )}"Loading"
} const { description, isDone } = task return (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} ))}
Loading...
if (error) return Error: {error.message}
return (
setTaskDescription(e.target.value)}
/>
-
{tasks.map((task) => (
- {task.description} ))}
Create an account
Create an account
{task.description}
);
};
```
{task.description}
);
};
```
{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" auto-js
export function Main() {
const { data: user } = useAuth()
if (!user) {
return (
Please login or{" "}
sign up.
)
} else {
return (
<>
Click to see the code
```ts title="src/auth/signup.ts" auto-js import { defineUserSignupFields } from "wasp/server/auth" import * as z from "zod" export const userSignupFields = defineUserSignupFields({ address: (data) => { const AddressSchema = z .string({ required_error: "Address is required", invalid_type_error: "Address must be a string", }) .min(10, "Address must be at least 10 characters long") const result = AddressSchema.safeParse(data.address) if (result.success === false) { throw new Error(result.error.issues[0].message) } return result.data }, }) ```
Don't have an account yet? go to signup.
I already have an account (go to login).
{children}
Don't have an account yet? go to signup.
I already have an account (go to login).
{children}
Don't have an account yet? go to signup.
Forgot your password? reset it.
I already have an account (go to login).
If everything is okay, go to login
If everything is okay, go to login
{children}
Don't have an account yet? go to signup.
Forgot your password? reset it.
I already have an account (go to login).
If everything is okay, go to login
If everything is okay, go to login
{children}
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] = useState(null) const navigate = useNavigate() async function handleClick() { setError(null) try { // The token is passed as a query parameter const token = new URLSearchParams(window.location.search).get('token') if (!token) throw new Error('Token not found in URL') await verifyEmail({ token }) navigate('/') } catch (error) { console.error('Error during email verification:', error) setError(error) } } return ( <> {error &&Error: {error.message}
} ) } // This will be shown when the user wants to reset their password export function RequestPasswordResetPage() { const [email, setEmail] = useState('') const [error, setError] = useState(null) const [needsConfirmation, setNeedsConfirmation] = useState(false) async function handleSubmit(event) { event.preventDefault() setError(null) try { await requestPasswordReset({ email }) setNeedsConfirmation(true) } catch (error) { console.error('Error during requesting reset:', error) setError(error) } } if (needsConfirmation) { return (Check 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(null) const [newPassword, setNewPassword] = useState('') const navigate = useNavigate() async function handleSubmit(event) { event.preventDefault() setError(null) try { // The token is passed as a query parameter const token = new URLSearchParams(window.location.search).get('token') if (!token) throw new Error('Token not found in URL') await resetPassword({ token, password: newPassword }) navigate('/') } catch (error) { console.error('Error during password reset:', error) setError(error) } } return ( ) } ```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})
4. Go to the **OAuth & Permissions** tab on the sidebar and click **Add New Redirect URL**.
- Enter the value `https://})
4. Go to the **OAuth2** tab on the sidebar and click **Add Redirect**
- For development, put: `http://localhost:3001/auth/discord/callback`.
- Once you know on which URL your API server will be deployed, you can create a new app with that URL instead e.g. `https://your-server-url.com/auth/discord/callback`.
4. Hit **Save Changes**.
5. Hit **Reset Secret**.
6. Copy your Client ID and Client secret as you'll need them in the next step.
#### 4. Adding Environment Variables
Add these environment variables to the `.env.server` file at the root of your project (take their values from the previous step):
```bash title=".env.server"
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
```
#### 5. Adding the Necessary Routes and Pages
Let's define the necessary authentication Routes and Pages.
Add the following code to your `main.wasp.ts` file:
```ts title="main.wasp.ts"
export default app({
// ...
spec: [
route("LoginRoute", "/login", page(LoginPage)),
],
})
```
We'll define the React components for these pages in the `src/pages/auth.{jsx,tsx}` file below.
#### 6. Creating the Client Pages
{tasks.map((task) => (
)
}
```
{task.title} by {task.user.auth?.identities[0].providerUserId}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {task.user.auth?.identities[0].providerUserId}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {getUsername(task.user)}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {getUsername(task.user)}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {getEmail(task.user)}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {getEmail(task.user)}
))}
{tasks.map((task) => (
)
}
```
{task.title} by {getFirstProviderUserId(task.user)}
))}
{tasks.map((task) => (
)
}
```
{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" export default app({ name: "myApp", wasp: { version: "{latestWaspVersion}" }, title: "My App", auth: { // ... onBeforeSignup, }, spec: [ action(customSignup), ], }) ``` ```ts title="src/auth/hooks.ts" auto-js // 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" auto-js 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](../overview.md#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](../overview.md#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](../overview.md#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 out https://opensaas.sh/ for more details. **Features:** Stripe Payments, OpenAI GPT API, Google Auth, SendGrid, Tailwind, & Cron Jobs Use this template: ``` wasp newMy App
My App
}
```
}
```
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:
http://localhost:3000 in development. },
{ name: "WASP_SERVER_URL", type: "URL", isRequired: true, note: <>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. },
{ name: "JWT_SECRET", type: "String", isRequired: true, note: <>A random string of at least 32 characters. Needed to generate secure tokens. Defaults to DEVJWTSECRET in development.https://api.eu.mailgun.net). }
]}
/>
##### OAuth Providers
If you are using OAuth, you need to provide the following environment variables:
Testing Libraries
[`vitest`](https://www.npmjs.com/package/vitest): Unit test framework with native Vite support.
[`@vitest/ui`](https://www.npmjs.com/package/@vitest/ui): A nice UI for seeing your test results.
[`jsdom`](https://www.npmjs.com/package/jsdom): A web browser test environment for Node.js.
[`@testing-library/react`](https://www.npmjs.com/package/@testing-library/react) / [`@testing-library/jest-dom`](https://www.npmjs.com/package/@testing-library/jest-dom): Testing helpers.
[`msw`](https://www.npmjs.com/package/msw): A server mocking library.
-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
-
{tasks &&
tasks.map((task) => (
- {task.description} ))}
Example e2e test
```ts import { expect, test } from '@playwright/test' import { generateRandomUser, logUserIn } from './utils' const user = generateRandomUser() test.describe('basic user flow test', () => { test('log in and add task', async ({ page }) => { await logUserIn({ page, user }) await expect(page).toHaveURL('/') await expect(page.locator('body')).toContainText('No tasks yet.') // Add a task await page.fill('input[name="description"]', 'First task') await page.click('input:has-text("Create task")') await expect(page.locator('body')).toContainText('First task') }) }) ``````bash WASP_WEB_CLIENT_URL=https://myapp.com WASP_SERVER_URL=https://server.myapp.com ``` Learn more about server env variables in the [env vars section](../project/env-vars.md#server-general-configuration). #### DDoS protection and CDN recommendations When deploying your Wasp app, you might want to consider using a Content Delivery Network (CDN) and DDoS protection service to improve the performance and security of your app: 1. **Content Delivery Network (CDN)** is a network of servers distributed worldwide that caches static assets like images, CSS, and JavaScript files. Using a CDN in front of your **client** can help with caching static assets and serving them faster to users around the world. When a user requests a file, the CDN serves it from the server closest to the user, improving load times. 2. **Distributed Denial of Service (DDoS)** attacks are a common threat to web applications. Attackers send a large amount of traffic to your server, overwhelming it and making it unavailable to legitimate users. You can use a DDoS protection service for both your **client and server** to protect your app from these attacks. We recommend using [Cloudflare](https://www.cloudflare.com/) for both CDN and DDoS protection. It's easy to set up and provides a free tier that should be enough for most small to medium-sized apps. There are other CDN providers like [Fastly](https://www.fastly.com/), [Bunny](https://bunnycdn.com/) and [Amazon Cloudfront](https://aws.amazon.com/cloudfront/) that you can consider as well. #### Are Wasp apps production ready? As we mentioned in the [introduction](./intro.md) section, what we call **Wasp apps** are three separate pieces: the client, the server, and the database. For the server, we are using Node.js and the battle-tested Express.js framework. For the database, we are using PostgreSQL, which is a powerful and reliable database system. For the client, we are using React and Vite, which are both widely used and well-maintained. Each of these pieces is production-ready on its own, and Wasp just makes it easy to connect them together. Keep in mind that Wasp is still considered beta software, so there might be some rough edges here and there. ------ # AI & Coding Agents ## Agent Plugin / Skills Wasp provides an official plugin for coding agents that transforms them into Wasp framework experts. The plugin gives your agent curated access to Wasp docs, workflows, and best practices so it can develop full-stack web apps (React, Node.js, Prisma) more effectively. The plugin / skills work with just about all the popular coding agents, such as [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), [Codex](https://openai.com/codex/), [Gemini CLI](https://geminicli.com/), [GitHub Copilot](https://github.com/features/copilot/cli), [OpenCode](https://opencode.ai/), and more. ### Features - **Wasp Documentation** â Ensures your agent always accesses LLM-friendly Wasp docs in sync with your current project's Wasp version. - **Wasp Knowledge** â Imports Wasp best practices and conventions into your project's memory file (e.g. `CLAUDE.md`, `AGENTS.md`). - **Feature Configuration** â Easily add Wasp features like authentication, database, email, styling (Tailwind, shadcn/ui), and other integrations through your agent. - **Deployment Guidance** â Your agent will guide you through deploying your Wasp app to Railway or Fly.io via the Wasp CLI, or manually to your favorite cloud provider. ### Installation #### Claude Code First, add the Wasp plugin marketplace: ```bash claude plugin marketplace add wasp-lang/wasp-agent-plugins ``` Then install the Wasp plugin: ```bash claude plugin install wasp@wasp-agent-plugins --scope project ``` :::tip We recommend installing with `project` scope so the settings are committed to git (via `settings.json`). Use `local` scope if you prefer settings that aren't committed (via `settings.local.json`). ::: #### Other Agents (Cursor, Codex, Gemini, Copilot, OpenCode, etc.) Run the following command and select all the skills: ```bash npx skills add wasp-lang/wasp-agent-plugins ``` ### Setup After installing, initialize the plugin in an active agent session by explicitly invoking the `/wasp-plugin-init` skill: ``` Run the '/wasp-plugin-init' skill. ``` This adds Wasp knowledge to your project's `CLAUDE.md` or `AGENTS.md` file. Next, start the development server as a background task so your agent has full insight into the running app while developing: ``` Run the 'start-dev-server' skill. ``` To see all available features and skills: ``` /wasp-plugin-help ``` ### Learn More Check out the [Wasp Agent Plugins repository](https://github.com/wasp-lang/wasp-agent-plugins) for more details. ------ # Advanced Features ## Sending Emails ## Sending Emails With Wasp's email-sending feature, you can easily integrate email functionality into your web application. ```ts title="main.wasp.ts" export default app({ name: "myApp", emailSender: { provider: "
Chat {connectionIcon}
- {messageList}
Chat {connectionIcon}
- {messageList}
Wasp automatically sets it during development when you run `wasp start`.
In production, you should set it to your client's URL as the server sees it (i.e., with the DNS and proxies considered). You can access it like this: ```js console.log(config.frontendUrl) ``` ### Client configuration object The client configuration object contains these fields: - `apiUrl: String` - Set it with env var `REACT_APP_API_URL` The URL of your server (the app's backend).
Wasp automatically sets it during development when you run `wasp start`.
In production, it should contain the value of your server's URL as the user's browser sees it (i.e., with the DNS and proxies considered). You can access it like this: ```js console.log(config.apiUrl) ``` ## Custom HTTP API Endpoints In Wasp, the default client-server interaction mechanism is through [Operations](../data-model/operations/overview). However, if you need a specific URL method/path, or a specific response, Operations may not be suitable for you. For these cases, you can use an `api`. Best of all, they should look and feel very familiar. ### How to Create an API APIs are used to tie a JS function to a certain endpoint e.g. `POST /something/special`. They are distinct from Operations and have no client-side helpers (like `useQuery`). To create a Wasp API, you must: 1. Declare the API in Wasp using the `api` constructor 2. Define the API's NodeJS implementation After completing these two steps, you'll be able to call the API from the client code (via our `ky` wrapper), or from the outside world. #### Specifying the API in Wasp First, we need to declare the API in the Wasp file and you can easily do this with the `api` function: ```ts title="main.wasp.ts" export default app({ // ... spec: [ api("GET", "/foo/bar", fooBar), ], }) ```
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"
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/7.12.0/start/declarative/routing#splats)), pass the rest of the path as the `*` param:
```ts title="main.wasp.ts"
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"
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"
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/7.12.0/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"
export default app({
// ...
spec: [
route("PhotoRoute", "/photo/:photoId/edit?", page(PhotoPage)),
],
})
```
```tsx title="src/PhotoPage.tsx" auto-js
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/7.12.0/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"
export default app({
// ...
spec: [
route("FilesRoute", "/files/*", page(FilesPage)),
],
})
```
```tsx title="src/FilesPage.tsx" auto-js
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/7.12.0/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"
// 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 `prerender: true`. This generates static HTML that is served immediately, giving faster load times and better SEO.
```ts title="main.wasp.ts"
export default app({
// ...
spec: [
route("LandingRoute", "/", page(LandingPage), { prerender: true }),
],
})
```
Prerendering works on static paths only and cannot be used with `authRequired` pages. See the [Prerendering](./prerendering.md) page for the full documentation.
## 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
Add `prerender: true` to any route spec:
```ts title="main.wasp.ts"
export default app({
// ...
spec: [
route("LandingRoute", "/", page(LandingPage), { prerender: true }),
],
})
```
That's it. When you run `wasp build`, Wasp renders this route's HTML at build time. 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.
### How it works
By default, `wasp build` generates a single `200.html` file that serves as the entry point for all routes. When a request comes in, the server sends this HTML, and React renders the appropriate page on the client. This is called a Single-Page Application (SPA) architecture.
But for `prerender: true` routes, Wasp will call them at build time, and render your page components as HTML, with special markers to allow for hydration. This HTML is then written to a file placed in the build output alongside the SPA file.
When a request hits a prerendered route's path, the server sends the pre-built HTML directly. Once the browser loads the JavaScript bundle, React hydrates the static HTML into a fully interactive app, no second render needed.
Routes without `prerender: true` continue to work as before: the server sends the SPA file, and the client renders the page from scratch.
### When to use prerendering
Prerendering works best for pages where the content is known at build time:
- Landing pages and marketing pages
- About, pricing, and FAQ pages
- Blog posts or documentation
- Any page with mostly static content that doesn't depend on the logged-in user
:::tip
Prerendering is especially valuable if you want your content to be indexed by search engines or readable by AI assistants like ChatGPT, Perplexity, or Claude.
:::
### Limitations
#### Static paths only
Prerendering only works on routes with static paths. Routes with dynamic segments (`:paramName`), optional segments (`?`), or splats (`*`) cannot be prerendered, because the HTML must be generated at build time for a known URL.
```ts title="main.wasp.ts"
export default app({
// ...
spec: [
// â
Works (static path)
route("AboutRoute", "/about", page(AboutPage), { prerender: true }),
// â Won't compile (dynamic segment)
route("UserRoute", "/user/:id", page(UserPage), { prerender: true }),
],
})
```
#### No auth-required pages
Routes pointing to pages with `authRequired: true` cannot be prerendered, since the page content depends on the logged-in user.
```ts title="main.wasp.ts"
export default app({
// ...
spec: [
// â Won't compile (authRequired is true)
route(
"DashRoute",
"/dashboard",
page(DashPage, { authRequired: true }),
{ prerender: true }
),
],
})
```
:::caution
Wasp reports an error at compile time if you try to prerender a route with a dynamic path or an auth-required page.
:::
### Troubleshooting
#### Hydration mismatches
When React hydrates a prerendered page, it expects the prerendered HTML to match what the client renders. If they differ, React logs a warning and may discard the prerendered HTML, losing the performance benefits.
##### Common causes
- **Checking for `window` or `document`:** code like `typeof window !== 'undefined'` or `import.meta.env.SSR` returns different values on the prerender vs. the client, and might change everything that depends on it.
- **Non-deterministic values during render:** functions like `Date.now()`, or `Math.random()` produces different results on each render.
- **Browser-only APIs:** accessing `window.innerWidth`, `navigator.userAgent`, `localStorage`, or similar APIs during render will fail while prerendering. This also applies to some third-party libraries that access these APIs, or less obvious JS APIs like `Intl.DateTimeFormat`, which can use different timezones and locales on the prerender vs. client.
##### How to fix: the `useIsClient` pattern
The fix is to render the same content on both the prerender and the client during the initial render, then add client-only behavior after hydration using `useEffect`.
Here's an example of the **wrong** approach:
```tsx title="src/LandingPage.tsx" auto-js
// â Causes a hydration mismatch
export function LandingPage() {
const isClient = typeof window !== "undefined"
return {isClient ? "Client content" : "Prerendered content"}
} ``` And the **correct** approach: ```tsx title="src/LandingPage.tsx" auto-js // â No hydration mismatch 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 referenceItem {id}
Item {id}
My App
My App
In case the migration script doesn't work well for you, you can do the same steps manually, as described here:
1. Rename your project's root directory to something like `foo_old`.
2. Create a new project by running `wasp new foo`.
3. Delete all files of `foo/src` except `vite-env.d.ts`.
4. If `foo_old/src/client/public` exists and contains any files, copy those files into
`foo/public`.
5. Copy the contents of `foo_old/src` into `foo/src`.
`foo/src` should now contain `vite-env.d.ts`, `.waspignore`, and three subdirectories (`server`, `client`, and `shared`).
Don't change anything about this structure yet.
6. Delete redundant files and folders from `foo/src`:
- `foo/src/.waspignore` - A new version of this file already exists at the top level.
- `foo/src/client/vite-env.d.ts` - A new version of this file already exists at the top level.
- `foo/src/client/tsconfig.json` - A new version of this file already exists at the top level.
- `foo/src/server/tsconfig.json` - A new version of this file already exists at the top level.
- `foo/src/shared/tsconfig.json` - A new version of this file already exists at the top level.
- `foo/src/client/public` - You've moved all the files from this directory in step 5.
7. Update all the `@wasp` imports in your JS(X)/TS(X) source files in the `src/` dir.
For this, we prepared a special script that will rewrite these imports automatically for you.
Before doing this step, as the script will modify your JS(X)/TS(X) files in place, we advise committing
all changes you have so far, so you can then both easily inspect the import rewrites that our
script did (with `git diff`) and also revert them if something went wrong.
To run the import-rewriting script, make sure you are in the root dir of your wasp project, and then run
```
npx jscodeshift@0.15.1 -t https://raw.githubusercontent.com/wasp-lang/wasp-codemod/main/src/transforms/imports-from-0-11-to-0-12.ts --extensions=js,ts,jsx,tsx src/
```
Then, check the changes it did, in case some kind of manual intervention is needed (in which case you should see TODO comments generated by the script).
Alternatively, you can find all the mappings of old imports to the new ones in [this table](https://docs.google.com/spreadsheets/d/1QW-_16KRGTOaKXx9NYUtjk6m2TQ0nUMOA74hBthTH3g/edit#gid=1725669920) and use it to fix some/all of them manually.
8. Replace the Wasp file in `foo` (i.e., `main.wasp`) with the Wasp file from `foo_old`
9. Change the Wasp version field in your Wasp file (now residing in `foo`) to `"^0.12.0"`.
10. Correct external imports in your Wasp file (now residing in `foo`).
imports. You can do this by running search-and-replace inside the file:
- Change all occurrences of `@server` to `@src/server`
- Change all occurrences of `@client` to `@src/client`
For example, if you previously had something like:
```js
page LoginPage {
// highlight-next-line
// This previously resolved to src/client/LoginPage.js
// highlight-next-line
component: import Login from "@client/LoginPage"
}
// ...
query getTasks {
// highlight-next-line
// This previously resolved to src/server/queries.js
// highlight-next-line
fn: import { getTasks } from "@server/queries.js",
}
```
You should change it to:
```js
page LoginPage {
// highlight-next-line
// This now resolves to src/client/LoginPage.js
// highlight-next-line
component: import Login from "@src/client/LoginPage"
}
// ...
query getTasks {
// highlight-next-line
// This now resolves to src/server/queries.js
// highlight-next-line
fn: import { getTasks } from "@src/server/queries.js",
}
```
Do this for all external imports in your `.wasp` file. After you're done, there shouldn't be any occurrences of strings `"@server"` or `"@client"`
11. Take all the dependencies from `app.dependencies` declaration in
`foo/main.wasp` and move them to `foo/package.json`. Make sure to remove the `app.dependencies` field from `foo/main.wasp`.
For example, if `foo_old/main.wasp` had:
```css
app Foo {
// ...
dependencies: [ ('redux', '^4.0.5'), ('reacjt-redux', '^7.1.3')];
}
```
Your `package.json` in `foo` should now list these dependencies (Wasp already generated most of the file, you just have to list additional dependencies).
```json
{
"name": "foo",
"dependencies": {
"wasp": "file:.wasp/out/sdk/wasp",
"react": "^18.2.0",
// highlight-next-line
"redux": "^4.0.5",
// highlight-next-line
"reactjs-redux": "^7.1.3"
},
"devDependencies": {
"typescript": "^5.1.0",
"vite": "^4.3.9",
"@types/react": "^18.0.37",
"prisma": "4.16.2"
}
}
```
12. Copy all lines you might have added to `foo_old/.gitignore` into
`foo/.gitignore`
13. Copy the rest of the top-level files and folders (all of them except for `.gitignore`, `main.wasp` and `src/`)
in `foo_old/` into `foo/` (overwrite the existing files in `foo`).
14. Run `wasp clean` in `foo`.
15. Delete the `foo_old` directory.
Migration for
First, move the value of `auth.signup.additionalFields` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
`{method}` depends on the auth method you are using. For example, if you are using the email auth method, you should move the `auth.signup.additionalFields` to `auth.methods.email.userSignupFields`.
To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` instead of `defineAdditionalSignupFields` from `@wasp/auth/index.js`.
Migration for
First, move the value of `auth.methods.{method}.getUserFieldsFn` to `auth.methods.{method}.userSignupFields` in the `main.wasp` file.
`{method}` depends on the auth method you are using. For example, if you are using Google auth, you should move the `auth.methods.google.getUserFieldsFn` to `auth.methods.google.userSignupFields`.
To finish, update the JS/TS implementation to use the `defineUserSignupFields` from `wasp/server/auth` and modify the code to return the fields in the format that `defineUserSignupFields` expects.
Username & Password data migration function
```wasp title="main.wasp" api migrateUsernameAndPassword { httpRoute: (GET, "/migrate-username-and-password"), fn: import { migrateUsernameAndPasswordHandler } from "@src/migrateToNewAuth", entities: [] } ``` ```ts title="src/migrateToNewAuth.ts" import { prisma } from "wasp/server"; import { type ProviderName, type UsernameProviderData } from "wasp/server/auth"; import { MigrateUsernameAndPassword } from "wasp/server/api"; export const migrateUsernameAndPasswordHandler: MigrateUsernameAndPassword = async (_req, res) => { const result = await migrateUsernameAuth(); res.status(200).json({ message: "Migrated users to the new auth", result }); }; async function migrateUsernameAuth(): Promise<{ numUsersAlreadyMigrated: number; numUsersNotUsingThisAuthMethod: number; numUsersMigratedSuccessfully: number; }> { const users = await prisma.user.findMany({ include: { auth: true, }, }); const result = { numUsersAlreadyMigrated: 0, numUsersNotUsingThisAuthMethod: 0, numUsersMigratedSuccessfully: 0, }; for (const user of users) { if (user.auth) { result.numUsersAlreadyMigrated++; console.log("Skipping user (already migrated) with id:", user.id); continue; } if (!user.username || !user.password) { result.numUsersNotUsingThisAuthMethod++; console.log("Skipping user (not using username auth) with id:", user.id); continue; } const providerData: UsernameProviderData = { hashedPassword: user.password, }; const providerName: ProviderName = "username"; await prisma.auth.create({ data: { identities: { create: { providerName, providerUserId: user.username.toLowerCase(), providerData: JSON.stringify(providerData), }, }, user: { connect: { id: user.id, }, }, }, }); result.numUsersMigratedSuccessfully++; } return result; } ```Steps to create a custom page for migrating the password
1. You will need to install the `secure-password` and `sodium-native` packages to use the old hashing algorithm: ```bash npm install secure-password@4.0.0 sodium-native@3.3.0 --save-exact ``` Make sure to save the exact versions of the packages. 2. Then you'll need to create a new page in your app where users can migrate their password. You can use the following code as a starting point: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 && 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 &&