Skip to main content

@auth/sveltekit

warning

@auth/sveltekit is currently experimental. The API might change.

SvelteKit Auth is the official SvelteKit integration for Auth.js. It provides a simple way to add authentication to your SvelteKit app in a few lines of code.

Installation​

npm install @auth/sveltekit

Usage​

src/hooks.server.ts
import { SvelteKitAuth } from "@auth/sveltekit"
import GitHub from "@auth/sveltekit/providers/github"
import { GITHUB_ID, GITHUB_SECRET } from "$env/static/private"

export const handle = SvelteKitAuth({
  providers: [GitHub({ clientId: GITHUB_ID, clientSecret: GITHUB_SECRET })],
})

or to use SvelteKit platform environment variables for platforms like Cloudflare

src/hooks.server.ts
import { SvelteKitAuth } from "@auth/sveltekit"
import GitHub from "@auth/sveltekit/providers/github"
import type { Handle } from "@sveltejs/kit";

export const handle = SvelteKitAuth(async (event) => {
  const authOptions = {
    providers: [GitHub({ clientId: event.platform.env.GITHUB_ID, clientSecret: event.platform.env.GITHUB_SECRET })]
    secret: event.platform.env.AUTH_SECRET,
    trustHost: true
  }
  return authOptions
}) satisfies Handle;

Remember to set the AUTH_SECRET environment variable. This should be a minimum of 32 characters, random string. On UNIX systems you can use openssl rand -hex 32 or check out https://generate-secret.vercel.app/32.

When deploying your app outside Vercel, set the AUTH_TRUST_HOST variable to true for other hosting providers like Cloudflare Pages or Netlify.

The callback URL used by the providers must be set to the following, unless you override SvelteKitAuthConfig.basePath:

[origin]/auth/callback/[provider]

Signing in and signing out​

The data for the current session in this example was made available through the $page store which can be set through the root +page.server.ts file. It is not necessary to store the data there, however, this makes it globally accessible throughout your application simplifying state management.

<script>
  import { signIn, signOut } from "@auth/sveltekit/client"
  import { page } from "$app/stores"
</script>

<h1>SvelteKit Auth Example</h1>
<p>
  {#if $page.data.session}
    {#if $page.data.session.user?.image}
      <span
        style="background-image: url('{$page.data.session.user.image}')"
        class="avatar"
      />
    {/if}
    <span class="signedInText">
      <small>Signed in as</small><br />
      <strong>{$page.data.session.user?.name ?? "User"}</strong>
    </span>
    <button on:click={() => signOut()} class="button">Sign out</button>
  {:else}
    <span class="notSignedInText">You are not signed in</span>
    <button on:click={() => signIn("github")}>Sign In with GitHub</button>
  {/if}
</p>

Managing the session​

The above example checks for a session available in $page.data.session, however that needs to be set by us somewhere. If you want this data to be available to all your routes you can add this to src/routes/+layout.server.ts. The following code sets the session data in the $page store to be available to all routes.

import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = async (event) => {
  return {
    session: await event.locals.getSession()
  };
};

What you return in the function LayoutServerLoad will be available inside the $page store, in the data property: $page.data. In this case we return an object with the 'session' property which is what we are accessing in the other code paths.

Handling authorization​

In SvelteKit there are a few ways you could protect routes from unauthenticated users.

Per component​

The simplest case is protecting a single page, in which case you should put the logic in the +page.server.ts file. Notice in this case that you could also await event.parent and grab the session from there, however this implementation works even if you haven't done the above in your root +layout.server.ts

import { redirect } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async (event) => {
  const session = await event.locals.getSession();
  if (!session?.user) throw redirect(303, '/auth');
  return {};
};
danger

Make sure to ALWAYS grab the session information from the parent instead of using the store in the case of a PageLoad. Not doing so can lead to users being able to incorrectly access protected information in the case the +layout.server.ts does not run for that page load. This code sample already implements the correct method by using const { session } = await parent();

You should NOT put authorization logic in a +layout.server.ts as the logic is not guaranteed to propagate to leafs in the tree. Prefer to manually protect each route through the +page.server.ts file to avoid mistakes. It is possible to force the layout file to run the load function on all routes, however that relies certain behaviours that can change and are not easily checked. For more information about these caveats make sure to read this issue in the SvelteKit repository: https://github.com/sveltejs/kit/issues/6315

Per path​

Another method that's possible for handling authorization is by restricting certain URIs from being available. For many projects this is better because:

  • This automatically protects actions and api routes in those URIs
  • No code duplication between components
  • Very easy to modify

The way to handle authorization through the URI is to override your handle hook. The handle hook, available in hooks.server.ts, is a function that receives ALL requests sent to your SvelteKit webapp. You may intercept them inside the handle hook, add and modify things in the request, block requests, etc. Some readers may notice we are already using this handle hook for SvelteKitAuth which returns a handle itself, so we are going to use SvelteKit's sequence to provide middleware-like functions that set the handle hook.

import { SvelteKitAuth } from '@auth/sveltekit';
import GitHub from '@auth/sveltekit/providers/github';
import { GITHUB_ID, GITHUB_SECRET } from '$env/static/private';
import { redirect, type Handle } from '@sveltejs/kit';
import { sequence } from '@sveltejs/kit/hooks';

async function authorization({ event, resolve }) {
	// Protect any routes under /authenticated
	if (event.url.pathname.startsWith('/authenticated')) {
   const session = await event.locals.getSession();
		if (!session) {
			throw redirect(303, '/auth');
		}
	}

	// If the request is still here, just proceed as normally
	return resolve(event);
}

// First handle authentication, then authorization
// Each function acts as a middleware, receiving the request handle
// And returning a handle which gets passed to the next function
export const handle: Handle = sequence(
	SvelteKitAuth({
		providers: [GitHub({ clientId: GITHUB_ID, clientSecret: GITHUB_SECRET })]
	}),
	authorization
);
info

Learn more about SvelteKit's handle hooks and sequence here.

Now any routes under /authenticated will be transparently protected by the handle hook. You may add more middleware-like functions to the sequence and also implement more complex authorization business logic inside this file. This can also be used along with the component-based approach in case you need a specific page to be protected and doing it by URI could be faulty.

Notes​

info

Learn more about @auth/sveltekit here.

info

PRs to improve this documentation are welcome! See this file.

SvelteKitAuth()​

SvelteKitAuth(config): Handle

The main entry point to @auth/sveltekit

Parameters​

▪ config: SvelteKitAuthConfig | (event) => PromiseLike< SvelteKitAuthConfig >

Returns​

Handle

See​

https://sveltekit.authjs.dev

Account​

Usually contains information about the provider being used and also extends TokenSet, which is different tokens returned by OAuth Providers.

Extends​

  • Partial< OpenIDTokenEndpointResponse >

Properties​

provider​

provider: string;

Provider's id for this account. Eg.: "google"

providerAccountId​

providerAccountId: string;

This value depends on the type of the provider being used to create the account.

  • oauth/oidc: The OAuth account's id, returned from the profile() callback.
  • email: The user's email address.
  • credentials: id returned from the authorize() callback

type​

type: ProviderType;

Provider's type for this account

expires_at​

expires_at?: number;

Calculated value based on [OAuth2TokenEndpointResponse.expires_in]([object Object]).

It is the absolute timestamp (in seconds) when the [OAuth2TokenEndpointResponse.access_token]([object Object]) expires.

This value can be used for implementing token rotation together with [OAuth2TokenEndpointResponse.refresh_token]([object Object]).

See​

userId​

userId?: string;

id of the user this account belongs to

See​

https://authjs.dev/reference/core/adapters#user

Profile​

The user info returned from your OAuth provider.

See​

https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Session​

The active session of the logged in user.

Extends​

  • DefaultSession

SvelteKitAuthConfig​

Configure the SvelteKitAuth method.

Extends​

  • Omit< AuthConfig, "raw" >

Properties​

providers​

providers: Provider[];

List of authentication providers for signing in (e.g. Google, Facebook, Twitter, GitHub, Email, etc) in any order. This can be one of the built-in providers or an object with a custom provider.

Default​
[]
Inherited from​

Omit.providers

adapter​

adapter?: Adapter;

You can use the adapter option to pass in your database adapter.

Inherited from​

Omit.adapter

basePath​

basePath?: string;

The base path of the Auth.js API endpoints.

Default​
"/auth"
Inherited from​

Omit.basePath

callbacks​

callbacks?: Partial< CallbacksOptions< Profile, Account > >;

Callbacks are asynchronous functions you can use to control what happens when an action is performed. Callbacks are extremely powerful, especially in scenarios involving JSON Web Tokens as they allow you to implement access controls without a database and to integrate with external databases or APIs.

Inherited from​

Omit.callbacks

cookies​

cookies?: Partial< CookiesOptions >;

You can override the default cookie names and options for any of the cookies used by Auth.js. You can specify one or more cookies with custom properties and missing options will use the default values defined by Auth.js. If you use this feature, you will likely want to create conditional behavior to support setting different cookies policies in development and production builds, as you will be opting out of the built-in dynamic policy.

  • ⚠ This is an advanced option. Advanced options are passed the same way as basic options, but may have complex implications or side effects. You should try to avoid using advanced options unless you are very comfortable using them.
Default​
{}
Inherited from​

Omit.cookies

debug​

debug?: boolean;

Set debug to true to enable debug messages for authentication and database operations.

  • ⚠ If you added a custom [AuthConfig.logger]([object Object]), this setting is ignored.
Default​
false
Inherited from​

Omit.debug

events​

events?: Partial< EventCallbacks >;

Events are asynchronous functions that do not return a response, they are useful for audit logging. You can specify a handler for any of these events below - e.g. for debugging or to create an audit log. The content of the message object varies depending on the flow (e.g. OAuth or Email authentication flow, JWT or database sessions, etc), but typically contains a user object and/or contents of the JSON Web Token and other information relevant to the event.

Default​
{}
Inherited from​

Omit.events

experimental​

experimental?: Record< string, boolean >;

Use this option to enable experimental features. When enabled, it will print a warning message to the console.

Note​

Experimental features are not guaranteed to be stable and may change or be removed without notice. Please use with caution.

Default​
{}
Inherited from​

Omit.experimental

jwt​

jwt?: Partial< JWTOptions >;

JSON Web Tokens are enabled by default if you have not specified an [AuthConfig.adapter]([object Object]). JSON Web Tokens are encrypted (JWE) by default. We recommend you keep this behaviour.

Inherited from​

Omit.jwt

logger​

logger?: Partial< LoggerInstance >;

Override any of the logger levels (undefined levels will use the built-in logger), and intercept logs in NextAuth. You can use this option to send NextAuth logs to a third-party logging service.

Example​
// /pages/api/auth/[...nextauth].js
import log from "logging-service"
export default NextAuth({
  logger: {
    error(code, ...message) {
      log.error(code, message)
    },
    warn(code, ...message) {
      log.warn(code, message)
    },
    debug(code, ...message) {
      log.debug(code, message)
    }
  }
})
  • ⚠ When set, the [AuthConfig.debug]([object Object]) option is ignored
Default​
console
Inherited from​

Omit.logger

pages​

pages?: Partial< PagesOptions >;

Specify URLs to be used if you want to create custom sign in, sign out and error pages. Pages specified will override the corresponding built-in page.

Default​
{}
Example​
  pages: {
    signIn: '/auth/signin',
    signOut: '/auth/signout',
    error: '/auth/error',
    verifyRequest: '/auth/verify-request',
    newUser: '/auth/new-user'
  }
Inherited from​

Omit.pages

redirectProxyUrl​

redirectProxyUrl?: string;

When set, during an OAuth sign-in flow, the redirect_uri of the authorization request will be set based on this value.

This is useful if your OAuth Provider only supports a single redirect_uri or you want to use OAuth on preview URLs (like Vercel), where you don't know the final deployment URL beforehand.

The url needs to include the full path up to where Auth.js is initialized.

Note​

This will auto-enable the state OAuth2Config.checks on the provider.

Example​
"https://authjs.example.com/api/auth"

You can also override this individually for each provider.

Example​
GitHub({
  ...
  redirectProxyUrl: "https://github.example.com/api/auth"
})
Default​

AUTH_REDIRECT_PROXY_URL environment variable

See also: Guide: Securing a Preview Deployment

Inherited from​

Omit.redirectProxyUrl

secret​

secret?: string | string[];

A random string used to hash tokens, sign cookies and generate cryptographic keys.

To generate a random string, you can use the Auth.js CLI: npx auth secret

Note​

You can also pass an array of secrets, in which case the first secret that successfully decrypts the JWT will be used. This is useful for rotating secrets without invalidating existing sessions. The newer secret should be added to the start of the array, which will be used for all new sessions.

Inherited from​

Omit.secret

session​

session?: {
  generateSessionToken: () => string;
  maxAge: number;
  strategy: "jwt" | "database";
  updateAge: number;
};

Configure your session like if you want to use JWT or a database, how long until an idle session expires, or to throttle write operations in case you are using a database.

Type declaration​
generateSessionToken​
generateSessionToken?: () => string;

Generate a custom session token for database-based sessions. By default, a random UUID or string is generated depending on the Node.js version. However, you can specify your own custom string (such as CUID) to be used.

Returns​

string

Default​

randomUUID or randomBytes.toHex depending on the Node.js version

maxAge​
maxAge?: number;

Relative time from now in seconds when to expire the session

Default​
2592000 // 30 days
strategy​
strategy?: "jwt" | "database";

Choose how you want to save the user session. The default is "jwt", an encrypted JWT (JWE) in the session cookie.

If you use an adapter however, we default it to "database" instead. You can still force a JWT session by explicitly defining "jwt".

When using "database", the session cookie will only contain a sessionToken value, which is used to look up the session in the database.

Documentation | Adapter | About JSON Web Tokens

updateAge​
updateAge?: number;

How often the session should be updated in seconds. If set to 0, session is updated every time.

Default​
86400 // 1 day
Inherited from​

Omit.session

theme​

theme?: Theme;

Changes the theme of built-in [AuthConfig.pages]([object Object]).

Inherited from​

Omit.theme

trustHost​

trustHost?: boolean;

Auth.js relies on the incoming request's host header to function correctly. For this reason this property needs to be set to true.

Make sure that your deployment platform sets the host header safely.

note

Official Auth.js-based libraries will attempt to set this value automatically for some deployment platforms (eg.: Vercel) that are known to set the host header safely.

Inherited from​

Omit.trustHost

useSecureCookies​

useSecureCookies?: boolean;

When set to true then all cookies set by NextAuth.js will only be accessible from HTTPS URLs. This option defaults to false on URLs that start with http:// (e.g. http://localhost:3000) for developer convenience. You can manually set this option to false to disable this security feature and allow cookies to be accessible from non-secured URLs (this is not recommended).

  • ⚠ This is an advanced option. Advanced options are passed the same way as basic options, but may have complex implications or side effects. You should try to avoid using advanced options unless you are very comfortable using them.

The default is false HTTP and true for HTTPS sites.

Inherited from​

Omit.useSecureCookies

User​

The shape of the returned object in the OAuth providers' profile callback, available in the jwt and session callbacks, or the second parameter of the session callback, when using a database.