Auth.js automatically creates simple, unbranded authentication pages for handling Sign in, Sign out, Email Verification and displaying error messages. The options displayed on the sign-up page are automatically generated based on the providers specified in the options passed to Auth.js. It also provides us with the flexibility to customize them as per our requirements. In this article, we will explore the Pages option in Auth.js, its importance, and various use-cases.

Pages

In Auth.js (formerly known as NextAuth.js), pages refer to custom user interface pages that you can create to handle various authentication-related actions. These pages allow you to customize the look and feel of the authentication process to better match your application's design and user experience. The need for custom pages arises when the default pages provided by Auth.js do not meet your specific requirements or branding guidelines.

You can configure custom pages for different actions such as sign-in, sign-out, and error handling. This is done by specifying the URLs of your custom pages in the Auth.js configuration. For example, you can create custom sign-in and sign-out pages to provide a more personalized experience for your users.

Examples of custom pages include:

1. Built-in: The default pages provided by Auth.js.

2. Sign-in: A custom page where users can log in to your application.

3. Sign-out: A custom page that users see when they log out.

4. Error: A custom page to display error messages related to authentication.

How to configure custom pages?

Configuring custom pages is very easy; all we have to do is provide the path of the corresponding +page.svelte file in the SvelteKitAuthConfig object.

import type { Handle } from '@sveltejs/kit';
import { SvelteKitAuth, type SvelteKitAuthConfig } from '@auth/sveltekit';
import { VERCEL_SECRET, CLIENT_ID, CLIENT_SECRET, ISSUER, WELL_KNOWN } from '$env/static/private';

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const config: SvelteKitAuthConfig = {
    ...
    pages: {
      signIn: '/auth/signin', // src/routes/auth/signin/+page.svelte
      signOut: '/auth/signout', // src/routes/auth/signout/+page.svelte
      error: '/auth/error' // src/routes/auth/error/+page.svelte
    }
  };
  return config;
});

export const handle = SvelteKitAuth(getAuthConfig) satisfies Handle;

With this simple configuration, we can display our own brand of pages for sign-in, sign-out, and error.

Reference

1. https://authjs.dev/getting-started/session-management/custom-pages

2. https://authjs.dev/guides/pages/built-in-pages

3. https://authjs.dev/guides/pages/signin

4. https://authjs.dev/guides/pages/signout

5. https://authjs.dev/guides/pages/error

6. https://next-auth.js.org/configuration/pages

In the next section we will learn about the Events available with Auth.js.

Events

In Auth.js, events are hooks that allow you to execute custom code in response to specific actions during the authentication process. These events can be used to extend the functionality of your authentication system, such as logging, analytics, or triggering other side effects. Some of the key events in Auth.js include:

1. signin: Triggered when a user signs in.

2. signout: Triggered when a user signs out.

3. session: Sent at the end of a request for the current session.

How to configure and respond to the custom events?

Configuring custom events is very easy; all we have to do is provide the path of the corresponding +page.svelte file in the SvelteKitAuthConfig object.

import type { Handle } from '@sveltejs/kit';
import { SvelteKitAuth, type SvelteKitAuthConfig } from '@auth/sveltekit';
import { VERCEL_SECRET, CLIENT_ID, CLIENT_SECRET, ISSUER, WELL_KNOWN } from '$env/static/private';

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const config: SvelteKitAuthConfig = {
    ...
    events: {
      signOut(message) {
        // message.token & message.session
      },
      signIn({ account, user, isNewUser, profile }) { ... },
      session({ session, token }) { ... }
    }
  };
  return config;
});

export const handle = SvelteKitAuth(getAuthConfig) satisfies Handle;

With this simple configuration, we can respond to the events in case of sign-in and sign-out.

Reference

1. https://next-auth.js.org/configuration/events

Conclusion

In conclusion, customizing authentication pages and handling events in SvelteKitAuth allows you to create a more personalized and seamless user experience. By configuring custom pages, you can ensure that your application's branding and design are consistent throughout the authentication process. Additionally, leveraging events in Auth.js enables you to execute custom code in response to specific actions, enhancing the functionality and flexibility of your authentication system. Whether you need to log user activities, integrate analytics, or trigger other side effects, these features provide the tools necessary to tailor the authentication flow to your specific needs.

Here is the link to the GitHub repository with the codebase. In the next article, we will learn to how to manage shared session between different applications in SvelteKitAuth.