Version: 0.11.8

Username & Password

Wasp supports username & password authentication out of the box with login and signup flows. It provides you with the server-side implementation and the UI components for the client-side.

Setting Up Username & Password Authentication

To set up username authentication we need to:

Enable username authentication in the Wasp file
Add the user entity
Add the routes and pages
Use Auth UI components in our pages

Structure of the main.wasp file we will end up with:

main.wasp

// Configuring e-mail authentication
appmyApp{
auth: { ... }
}
// Defining User entity
entityUser{ ... }
// Defining routes and pages
routeSignupRoute{ ... }
pageSignupPage{ ... }
// ...

1. Enable Username Authentication

Let's start with adding the following to our main.wasp file:

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
// 1. Specify the user entity (we'll define it next)
userEntity: User,
methods: {
// 2. Enable username authentication
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
// 1. Specify the user entity (we'll define it next)
userEntity: User,
methods: {
// 2. Enable username authentication
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}

Read more about the usernameAndPassword auth method options here.

2. Add the User Entity

When username authentication is enabled, Wasp expects certain fields in your userEntity. Let's add these fields to our main.wasp file:

JavaScript
TypeScript

main.wasp

// 3. Define the user entity
entityUser{=psl
 id Int@id@default(autoincrement())
 username String@unique
 password String
// Add your own fields below
// ...
psl=}

main.wasp

// 3. Define the user entity
entityUser{=psl
 id Int@id@default(autoincrement())
 username String@unique
 password String
// Add your own fields below
// ...
psl=}

Read more about the userEntity fields here.

3. Add the Routes and Pages

Next, we need to define the routes and pages for the authentication pages.

Add the following to the main.wasp file:

JavaScript
TypeScript

main.wasp

// ...
// 4. Define the routes
routeLoginRoute{path: "/login",to: LoginPage}
pageLoginPage{
component: import{Login}from"@client/pages/auth.jsx"
}
routeSignupRoute{path: "/signup",to: SignupPage}
pageSignupPage{
component: import{Signup}from"@client/pages/auth.jsx"
}

main.wasp

// ...
// 4. Define the routes
routeLoginRoute{path: "/login",to: LoginPage}
pageLoginPage{
component: import{Login}from"@client/pages/auth.tsx"
}
routeSignupRoute{path: "/signup",to: SignupPage}
pageSignupPage{
component: import{Signup}from"@client/pages/auth.tsx"
}

We'll define the React components for these pages in the client/pages/auth.tsx file below.

4. Create the Client Pages

info

We are using Tailwind CSS to style the pages. Read more about how to add it here.

Let's create a auth.tsx file in the client/pages folder and add the following to it:

JavaScript
TypeScript

client/pages/auth.jsx

import{LoginForm}from"@wasp/auth/forms/Login";
import{SignupForm}from"@wasp/auth/forms/Signup";
import{Link}from"react-router-dom";

exportfunctionLogin(){
return(
<Layout>
<LoginForm/>
<br/>
<spanclassName="text-sm font-medium text-gray-900">
 Don't have an account yet? <Linkto="/signup">go to signup</Link>.
</span>
</Layout>
);
}

exportfunctionSignup(){
return(
<Layout>
<SignupForm/>
<br/>
<spanclassName="text-sm font-medium text-gray-900">
 I already have an account (<Linkto="/login">go to login</Link>).
</span>
</Layout>
);
}

// A layout component to center the content
exportfunctionLayout({ children }){
return(
<divclassName="w-full h-full bg-white">
<divclassName="min-w-full min-h-[75vh] flex items-center justify-center">
<divclassName="w-full h-full max-w-sm p-5 bg-white">
<div>{children}</div>
</div>
</div>
</div>
);
}

client/pages/auth.tsx

import{LoginForm}from"@wasp/auth/forms/Login";
import{SignupForm}from"@wasp/auth/forms/Signup";
import{Link}from"react-router-dom";

exportfunctionLogin(){
return(
<Layout>
<LoginForm/>
<br/>
<spanclassName="text-sm font-medium text-gray-900">
 Don't have an account yet? <Linkto="/signup">go to signup</Link>.
</span>
</Layout>
);
}

exportfunctionSignup(){
return(
<Layout>
<SignupForm/>
<br/>
<spanclassName="text-sm font-medium text-gray-900">
 I already have an account (<Linkto="/login">go to login</Link>).
</span>
</Layout>
);
}

// A layout component to center the content
exportfunctionLayout({ children }:{ children:React.ReactNode}){
return(
<divclassName="w-full h-full bg-white">
<divclassName="min-w-full min-h-[75vh] flex items-center justify-center">
<divclassName="w-full h-full max-w-sm p-5 bg-white">
<div>{children}</div>
</div>
</div>
</div>
);
}

We imported the generated Auth UI components and used them in our pages. Read more about the Auth UI components here.

Conclusion

That's it! We have set up username authentication in our app. 🎉

Running wasp db migrate-dev and then wasp start should give you a working app with username authentication. If you want to put some of the pages behind authentication, read the using auth docs.

Customizing the Auth Flow

The login and signup flows are pretty standard: they allow the user to sign up and then log in with their username and password. The signup flow validates the username and password and then creates a new user entity in the database.

Read more about the default username and password validation rules and how to override them in the using auth docs.

If you require more control in your authentication flow, you can achieve that in the following ways:

Create your UI and use signup and login actions.
Create your custom sign-up and login actions which uses the Prisma client, along with your custom code.

1. Using the `signup` and `login` actions

`login()`

An action for logging in the user.

It takes two arguments:

username: string required

Username of the user logging in.

password: string required

Password of the user logging in.

You can use it like this:

JavaScript
TypeScript

client/pages/auth.jsx

// Importing the login action 👇
importloginfrom'@wasp/auth/login'

import{ useState }from'react'
import{ useHistory }from'react-router-dom'
import{Link}from'react-router-dom'

exportfunctionLoginPage(){
const[username, setUsername]=useState('')
const[password, setPassword]=useState('')
const[error, setError]=useState(null)
const history =useHistory()

asyncfunctionhandleSubmit(event){
 event.preventDefault()
try{
awaitlogin(username, password)
 history.push('/')
}catch(error){
setError(error)
}
}

return(
<formonSubmit={handleSubmit}>
{/* ... */}
</form>
);
}

client/pages/auth.tsx

// Importing the login action 👇
importloginfrom'@wasp/auth/login'

import{ useState }from'react'
import{ useHistory }from'react-router-dom'
import{Link}from'react-router-dom'

exportfunctionLoginPage(){
const[username, setUsername]=useState('')
const[password, setPassword]=useState('')
const[error, setError]=useState<Error |null>(null)
const history =useHistory()

asyncfunctionhandleSubmit(event:React.FormEvent<HTMLFormElement>){
 event.preventDefault()
try{
awaitlogin(username, password)
 history.push('/')
}catch(error:unknown){
setError(error asError)
}
}

return(
<formonSubmit={handleSubmit}>
{/* ... */}
</form>
);
}

note

When using the exposed login() function, make sure to implement your redirect on success login logic (e.g. redirecting to home).

`signup()`

An action for signing up the user. This action does not log in the user, you still need to call login().

It takes one argument:

userFields: object required

It has the following fields:
- username: string required
- password: string required
info
Wasp only stores the auth-related fields of the user entity. Adding extra fields to userFields will not have any effect.
If you need to add extra fields to the user entity, we suggest doing it in a separate step after the user logs in for the first time.

You can use it like this:

JavaScript
TypeScript

client/pages/auth.jsx

// Importing the signup and login actions 👇
importsignupfrom'@wasp/auth/signup'
importloginfrom'@wasp/auth/login'

import{ useState }from'react'
import{ useHistory }from'react-router-dom'
import{Link}from'react-router-dom'

exportfunctionSignup(){
const[username, setUsername]=useState('')
const[password, setPassword]=useState('')
const[error, setError]=useState(null)
const history =useHistory()

asyncfunctionhandleSubmit(event){
 event.preventDefault()
try{
awaitsignup({
 username,
 password,
})
awaitlogin(username, password)
 history.push("/")
}catch(error){
setError(error)
}
}

return(
<formonSubmit={handleSubmit}>
{/* ... */}
</form>
);
}

client/pages/auth.tsx

// Importing the signup and login actions 👇
importsignupfrom'@wasp/auth/signup'
importloginfrom'@wasp/auth/login'

import{ useState }from'react'
import{ useHistory }from'react-router-dom'
import{Link}from'react-router-dom'

exportfunctionSignup(){
const[username, setUsername]=useState('')
const[password, setPassword]=useState('')
const[error, setError]=useState<Error |null>(null)
const history =useHistory()

asyncfunctionhandleSubmit(event:React.FormEvent<HTMLFormElement>){
 event.preventDefault()
try{
awaitsignup({
 username,
 password,
})
awaitlogin(username, password)
 history.push("/")
}catch(error:unknown){
setError(error asError)
}
}

return(
<formonSubmit={handleSubmit}>
{/* ... */}
</form>
);
}

2. Creating your custom actions

The code of your custom sign-up action can look like this:

JavaScript
TypeScript

main.wasp

// ...

actionsignupUser{
fn: import{ signUp }from"@server/auth/signup.js",
entities: [User]
}

src/server/auth/signup.js

exportconstsignUp=async(args, context)=>{
// Your custom code before sign-up.
// ...

const newUser = context.entities.User.create({
data:{
username: args.username,
password: args.password// password hashed automatically by Wasp! 🐝
}
})

// Your custom code after sign-up.
// ...
return newUser
}

main.wasp

// ...

actionsignupUser{
fn: import{ signUp }from"@server/auth/signup.js",
entities: [User]
}

src/server/auth/signup.ts

importtype{ User }from'@wasp/entities'
importtype{ SignupUser }from'@wasp/actions/types'

typeSignupPayload= Pick<User,'username'|'password'>

exportconst signUp: SignupUser<SignupPayload, User>=async(args, context)=>{
// Your custom code before sign-up.
// ...

const newUser = context.entities.User.create({
 data:{
 username: args.username,
 password: args.password // password hashed automatically by Wasp! 🐝
}
})

// Your custom code after sign-up.
// ...
return newUser
}

Using Auth

To read more about how to set up the logout button and how to get access to the logged-in user in our client and server code, read the using auth docs.

API Reference

`userEntity` fields

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}

// Wasp requires the `userEntity` to have at least the following fields
entityUser{=psl
 id Int@id@default(autoincrement())
 username String@unique
 password String
psl=}

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}

// Wasp requires the `userEntity` to have at least the following fields
entityUser{=psl
 id Int@id@default(autoincrement())
 username String@unique
 password String
psl=}

Username & password auth requires that userEntity specified in auth contains:

username field of type String
password field of type String

Fields in the `usernameAndPassword` dict

JavaScript
TypeScript

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}
// ...

main.wasp

appmyApp{
wasp: {
version: "^0.11.0"
},
title: "My App",
auth: {
userEntity: User,
methods: {
usernameAndPassword: {},
},
onAuthFailedRedirectTo: "/login"
}
}
// ...

info

usernameAndPassword dict doesn't have any options at the moment.

You can read about the rest of the auth options in the using auth section of the docs.

Setting Up Username & Password Authentication​

1. Enable Username Authentication​

2. Add the User Entity​

3. Add the Routes and Pages​

4. Create the Client Pages​

Conclusion​

Customizing the Auth Flow​

1. Using the signup and login actions​

login()​

signup()​

2. Creating your custom actions​

Using Auth​

API Reference​

userEntity fields​

Fields in the usernameAndPassword dict​

Setting Up Username & Password Authentication

1. Enable Username Authentication

2. Add the User Entity

3. Add the Routes and Pages

4. Create the Client Pages

Conclusion

Customizing the Auth Flow

1. Using the `signup` and `login` actions

`login()`

`signup()`

2. Creating your custom actions

Using Auth

API Reference

`userEntity` fields

Fields in the `usernameAndPassword` dict