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 22
```
Finally, whenever you need to ensure a specific version of Node.js is used, run:
```shell
nvm use 22
```
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` and `page` declarations from the `main.wasp` file.
Your Wasp file should now look like this:
```wasp title="main.wasp"
app TodoApp {
wasp: {
version: "{latestWaspVersion}"
},
title: "TodoApp",
head: [
"",
]
}
route RootRoute { path: "/", to: MainPage }
page MainPage {
component: import { MainPage } from "@src/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 &&
);
// highlight-end
};
// highlight-start
const TaskView = ({ task }: { task: Task }) => {
return (
{task.description}
);
};
const TasksList = ({ tasks }: { tasks: Task[] }) => {
if (!tasks?.length) return No tasks
;
return (
{tasks.map((task, idx) => (
);
};
// highlight-end
```
})
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.
#### Declaring an Action
We must first declare the Action in `main.wasp`:
// highlight-next-line
);
};
// ... TaskList, TaskView, 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}
);
};
// ... TaskList, 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/reference/tools-and-interfaces/prisma-schema/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}
Click the link below to verify your email
Verify email `, }) ```Click the link below to verify your email
Verify email `, }) ```Click the link below to reset your password
Reset password `, }) ```Click the link below to reset your password
Reset password `, }) ```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 EmailVerification() { 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 RequestPasswordReset() { 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 PasswordReset() { 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 EmailVerification() { const [error, setError] = useStateError: {error.message}
} ) } // This will be shown when the user wants to reset their password export function RequestPasswordReset() { 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 PasswordReset() { const [error, setError] = useState{children}
{children}
{children}
})
4. Go to the **OAuth & Permissions** tab on the sidebar and click **Add New Redirect URL**.
- Enter the value `https://{children}
})
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` file:
```wasp title="main.wasp"
// ...
route LoginRoute { path: "/login", to: LoginPage }
page LoginPage {
component: import { Login } from "@src/pages/auth"
}
```
We'll define the React components for these pages in the `src/pages/auth.{jsx,tsx}` file below.
#### 6. Creating the Client Pages
:::info
We are using [Tailwind CSS](https://tailwindcss.com/) to style the pages. Read more about how to add it [here](../../project/css-frameworks).
:::
Let's create a `auth.{jsx,tsx}` file in the `src/pages` folder and add the following to it:
```tsx title="src/pages/auth.tsx" auto-js
export function Login() {
return (
{children}
{children}
{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 ```wasp title="main.wasp" app myApp { // ... auth: { // ... onBeforeSignup: import { onBeforeSignup } from "@src/auth/hooks", }, } // ... action customSignup { fn: import { signup } from "@src/auth/signup", } ``` ```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 signup: 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. [4] ai-generated đ¤ Describe an app in a couple of sentences and have Wasp AI generate initial code for you. (experimental) ⸠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 new