Plug and play authentication module for Nuxt
[!IMPORTANT] nuxt-slip-auth development is in the early stages.
Slip (French word for "underwear", pronounced /sleep/
) is an attempt to be the most simple way to bring authentication to your Nuxt app.
Authentication is like an underwear: you can you put it on, put it off and sometimes get stolen !
This module is build on top of nuxt-auth-utils and db0 and adds the following features:
Install the module to your Nuxt application with one command:
npx nuxi module add nuxt-slip-auth
Then create a Github OAuth app (or any provider) you want: create app
For a quick demo run the command:
npx nuxt-slip-auth demo
By default, nuxt-auth-utils will use sqlite, so you'll need to run
npm install better-sqlite3
Example: ~/server/routes/auth/github.get.ts
import { drizzle as drizzleIntegration } from "db0/integrations/drizzle/index";
export default defineOAuthGitHubEventHandler({
config: {
emailRequired: true,
},
async onSuccess(event, { user }) {
const auth = useSlipAuth();
const db = drizzleIntegration(useDatabase());
const [userId, sessionFromDb] = await auth.OAuthLoginUser({
email: user.email,
providerId: "github",
providerUserId: user.id,
ua: getRequestHeader(event, "User-Agent"),
ip: getRequestIP(event),
});
const userDb = await db
.select()
.from(auth.schemas.users)
.get();
await setUserSession(event, {
expires_at: sessionFromDb.expires_at,
id: sessionFromDb.id,
user: {
id: userId,
email_verified: userDb?.email_verified || false,
},
});
return sendRedirect(event, "/profile");
},
// Optional, will return a json error and 401 status code by default
onError(event, error) {
console.error("GitHub OAuth error:", error);
return sendRedirect(event, "/?authError=" + error);
},
});
NUXT_OAUTH_GITHUB_CLIENT_ID=""
NUXT_OAUTH_GITHUB_CLIENT_SECRET=""
NUXT_SLIP_AUTH_IP_INFO_TOKEN=""
Update your .env
with your app tokens.
Example: ~/app.vue
<script setup lang="ts">
const { loggedIn, user, session, clear, fetch: fetchSession } = useUserSession();
const authClient = getSlipAuthClient();
async function seedUser() {
const email = `user-${Math.random()}@email.com`;
const password = "password";
await authClient.register({
email,
password,
});
await fetchSession();
}
</script>
<template>
<div v-if="loggedIn && user">
<h1>Welcome {{ user.id }}!</h1>
<p>Logged in until {{ new Date(session.expires_at).toDateString() }}</p>
<button @click="clear">
Logout
</button>
</div>
<div v-else>
<h1>Not logged in</h1>
<button @click="seedUser">Create email + password user</button>
<a href="/auth/github">Login with GitHub</a>
</div>
</template>
checkDbAndTables(dialect: string)
Checks if the required database and tables are set up. Ensures that the environment is ready for authentication.
register(values: ICreateUserParams): Promise<[ string, SlipAuthPublicSession]>
Registers a new user in the database if they don’t already exist, email + password.
login(values: ILoginUserParams): Promise<[ string, SlipAuthPublicSession]>
askEmailVerificationCode(user: SlipAuthUser): Promise<void>
Ask the email verification code for a user.
verifyEmailVerificationCode(user: SlipAuthUser, code: string): Promise<boolean>
Checks the email verification code. Returns a boolean. Don't forget to re-login after verifying the email verification code.
OAuthLoginUser(params: ICreateOrLoginParams): Promise<[string, SlipAuthPublicSession]>
Registers a new user in the database if they don’t already exist. It handles OAuth authentication by registering the OAuth account, creating a session, and linking the user’s details.
getUser(id: string)
Fetches a user by its user ID.
getSession(id: string)
Fetches a session by its session ID.
deleteSession(id: string)
Deletes a session by its session ID.
deleteExpiredSessions(timestamp: number)
Deletes sessions that have expired before the provided timestamp.
askPasswordReset(userId: string)
creates a reset password token for a specified user
askForgotPasswordReset(email: string)
Same as askPasswordReset
but with email instead of userId.
Resets the password using the reset token.
The hooks property allows you to listen for and respond to events during the authentication process. The available hooks are:
Hook Name | Description | Callback |
---|---|---|
"users:create" | Triggered when a new user is created. | (user: SlipAuthUser) => void |
"emailVerificationCode:create" | Triggered when a new user is created. | (code: EmailVerificationCodeTableInsert) => void |
"oAuthAccount:create" | Triggered when a new OAuth account is created. | (oAuthAccount: SlipAuthOAuthAccount) => void |
"sessions:create" | Triggered when a new session is created. | (session: SlipAuthSession) => void |
"sessions:delete" | Triggered when a session is deleted. | (session: SlipAuthSession) => void |
"emailVerificationCode:delete" | Triggered when a user email is validated. | (code: SlipAuthEmailVerificationCode) => void |
"resetPasswordToken:create" | Triggered when a user passsword reset is asked. | (token: SlipAuthPasswordResetToken) => void |
"resetPasswordToken:delete" | Triggered when a user passsword reset is validated or expired. | (token: SlipAuthPasswordResetToken) => void |
schemas
: Contains the database schemas for users, sessions, and OAuth accounts.hooks
: Provides hooks to extend and configure the authentication behavior.under auth.setters
setCreateRandomUserId(fn: () => string)
Sets a custom method for generating random user IDs.
setCreateRandomSessionId(fn: () => string)
Sets a custom method for generating random session IDs.
setCreateRandomEmailVerificationCode(fn: () => string)
Sets a custom method for generating random email verification codes.
setPasswordHashingMethods(fn: () => IPasswordHashingMethods)
Sets custom methods for hashing and verifying passwords.
setCreateResetPasswordTokenHashMethod(fn: (tokenId: string) => Promise<string>)
Sets custom method for reset password token hashing.
setLoginRateLimiter(fn: () => Storage)
setAskEmailRateLimiter(fn: () => Storage)
setVerifyEmailRateLimiter(fn: () => Storage)
setAskResetPasswordRateLimiter(fn: () => Storage)
setVerifyResetPasswordRateLimiter(fn: () => Storage)
By default, nuxt-slip-auth will create tables in your database for you !
However, if you want to use exising table you can still use drizze-kit
to generate and run migrations
create a server/schema.ts file
import { getNuxtSlipAuthSchemas } from "nuxt-slip-auth/nuxt-drizzle";
// getNuxtSlipAuthSchemas accepts a tableNames argument where you can provide your table names
export const {
users,
emailVerificationCodes,
oauthAccounts,
resetPasswordTokens,
sessions,
} = getNuxtSlipAuthSchemas();
then create a drizzle.config.ts file
import { defineConfig } from "drizzle-kit";
import path from "node:path";
function getDbUrl() {
return path.resolve(__dirname, ".data/db.sqlite3");
}
export default defineConfig({
dialect: "sqlite",
out: "./migrations",
schema: "./server/schemas.ts",
dbCredentials: {
url: getDbUrl(),
},
});
run
npx drizzle-kit generate
You should have your migrations in the migrations folder.
# Install dependencies
npm install
# Generate type stubs
npm run dev:prepare
# Develop with the playground
npm run dev
# Build the playground
npm run dev:build
# Run ESLint
npm run lint
# Run Vitest
npm run test
npm run test:watch
# Release new version
npm run release