1. Complex Scenarios Workarounds: If your project demands intricate authentication flows or data handling beyond basic login/logout, you might find yourself working around SvelteKitAuth's core functionality, leading to less maintainable code. A few examples of complex scenarios that are not directly possible to work with SvelteKitAuth are:

   • Communication between client and server and vice-versa: If you want to update data from client to server in real-time, it is not possible to do it with SvelteKitAuth.

   • Sharing sessions like having multiple preview URLs: If your project requires multiple preview URLs (like in the case of Vercel), that won't be possible as we cannot customize callbackUrl, making it impossible to share sessions on applications deployed on different domains.

2. Limited updates for SvelteKitAuth: Authjs is the successor to NextAuth, which was designed only for Next.js. Although Authjs aims to be framework agnostic, its main focus is still on Next.js. In SvelteKitAuth, there are many functionalities and configurations that cannot be done, which are possible and can be easily done in Next.js.

3. Poor Documentation: While working on SvelteKitAuth, I had to frequently switch from the documentation of NextAuth and Authjs as the latter did not have all the necessary information. Recently, they did a major update on the documentation front, but the quality and depth from the SvelteKitAuth perspective are still very poor.

4. Limited community support: The community support for SvelteKitAuth is almost negligible. To add to the pain, the authors (or maintainers) of this project have stressed multiple times over different threads that it is their side project and they have limited time to invest. So if you come across a potential blocker, due to limited community support and limited support from maintainers, you could find yourself stuck. Note: They have recently started a Discord community and also try to stay active on Twitter, but support for SvelteKitAuth still remains sparse!

5. Developer Experience: If I speak from my personal experience, I've been one of the early adopters of SvelteKitAuth. I started when we had version v0.2 and worked until v1.0, which is almost one year of working with SvelteKitAuth. This is the time when I realized that SvelteKitAuth is not suitable for my enterprise web application because of the reasons described above. I then switched over to Lucia and the experience so far has been outstanding.

In conclusion, while SvelteKitAuth offers a range of features and benefits for authentication in SvelteKit applications, it is not without its drawbacks. The need for workarounds in complex scenarios, limited updates and focus on Next.js, poor documentation, and minimal community support can pose significant challenges. These factors can make it less suitable for enterprise-level applications or projects with intricate authentication requirements. My personal experience with SvelteKitAuth highlighted these limitations, leading me to switch to Lucia, which has proven to be a more robust solution for my needs. As with any technology, it's essential to weigh the pros and cons to determine the best fit for your specific project requirements.

Sharing session with applications on the same domain

Let's take an example where my application is hosted on myapp.com and we perform authentication on auth.myapp.com. In this example, the domain myapp.com is shared among two applications, making it easy to share the session between them. The session is stored in the session-token cookie. If the applications share the same domain, we can simply update the domain property in the cookies. This is the example from the SvelteKitAuthConfig:

// hooks.server.ts

import { dev } from '$app/environment';
import type { Handle } from '@sveltejs/kit';
import { SvelteKitAuth, type SvelteKitAuthConfig } from '@auth/sveltekit';

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const useSecureCookies = !dev;
  const config: SvelteKitAuthConfig = {
    ...
    cookies: {
      callbackUrl: {
        name: `${useSecureCookies ? '__Secure-' : ''}authjs.callback-url`,
        options: {
          httpOnly: true,
          sameSite: useSecureCookies ? 'none' : 'lax',
          path: '/',
          secure: useSecureCookies,
          domain: '.myapp.com'
        }
      },
      pkceCodeVerifier: {
        name: `${useSecureCookies ? '__Secure-' : ''}authjs.pkce.code_verifier`,
        options: {
          httpOnly: true,
          sameSite: useSecureCookies ? 'none' : 'lax',
          path: '/',
          secure: useSecureCookies,
          domain: '.myapp.com'
        }
      },
      sessionToken: {
        name: `${useSecureCookies ? '__Secure-' : ''}authjs.session-token`,
        options: {
          httpOnly: true,
          sameSite: useSecureCookies ? 'none' : 'lax',
          path: '/',
          secure: useSecureCookies,
          domain: '.myapp.com'
        }
      },
      state: {
        name: `${useSecureCookies ? '__Secure-' : ''}authjs.state`,
        options: {
          httpOnly: true,
          sameSite: useSecureCookies ? 'none' : 'lax',
          path: '/',
          secure: useSecureCookies,
          domain: '.myapp.com'
        }
      }
    },
  }
});

export const handle = getAuthConfig;

With this simple setup, we can share the session between two applications having a common domain. In the next section, we will learn how to share sessions with multiple applications that do not share a common domain.

Sharing session with applications in different domains

Sharing sessions with applications on different domains is very tricky to implement in Authjs as they don't allow having a dynamic callbackURL. When we configure the SvelteKitAuthConfig object, we don't have any option to manually set the callbackURL. It is automatically set by Authjs and defaults to ${url.origin}/${base_path}/auth/callback/${provider-id} (e.g., http://localhost:4200/base/auth/callback/auth0). Since it always picks up the current origin, we cannot customize the callbackURL, resulting in an authentication error:

error {
  error: 'unauthorized_client',
  error_description: 'The redirect URI is wrong. You sent http://localhost:4201, and we expected http://localhost:4200'
}
ERROR in AUTH:  {
  "name":"CallbackRouteError",
  "type":"CallbackRouteError",
  "kind":"error",
  "message":"Read more at https://errors.authjs.dev#callbackrouteerror"
}

The solution is to use our own proxy identity server and configure it with the redirectProxyURL property. The redirectProxyURL property in Auth.js is used to specify a proxy server that handles the redirection process during authentication. This is particularly useful when dealing with scenarios where applications are hosted on different domains and you need to manage cross-domain authentication. By setting the redirectProxyURL, you can centralize the callback handling to a single domain, which then forwards the authentication response to the appropriate application. This helps in overcoming the limitation of having a dynamic callbackURL in Auth.js.

Let's understand how this works for the application on the same domain:

• It makes a request to the OAuth provider by passing the authorization URL and a whitelisted redirectURL.

• The OAuth provider validates the authentication and passes the authorization code to the application via the redirectURL that was provided earlier.

• In this scenario, since the application was performing and maintaining the session in the same domain, the auto-generated callbackURL by Authjs is the same as the whitelisted redirectURL provided by us, and hence authentication was successful.

For the application on a different domain:

• It makes a request to the OAuth provider by passing the authorization URL and a redirectURL that is not whitelisted.

• Since the auto-generated callbackURL by Authjs is NOT the same as the whitelisted redirectURL provided by us, authentication fails.

• To correct this, we must first create a temporary Identity server that will impersonate our application and interact with the OAuth provider.

• We will first whitelist the redirectURL of this temporary identity server so that it is able to communicate seamlessly with the OAuth provider.

• Our application passes the authorization request to this identity server instead of the actual OAuth. In the authorization request, it passes the source_url, which is the current application URL that triggers the authentication process. Our fake identity server will give back control to this particular URL.

• Apart from passing the authorization request, our application also sets the redirectProxyURL property, which holds the value of the origin of the fake identity server.

• The identity server then interacts with the OAuth provider and requests authentication.

• The OAuth server validates the request and sends back the authorization code via the whitelisted redirectURL property of the fake identity server.

• Once the authorization code is received, the fake identity server transfers back control to our application. It picks up the source_url that was passed earlier.

• Since the redirectProxyURL property was set, our application realizes that the authentication was performed via a proxy source and it lets the session continue on our application.

Creating Identity Server

The identity server must be configured keeping the pattern of authorizeURL and the whitelisted redirectURL in mind. For example, let's consider the following pattern for our OAuth provider where the value of the authorizeURL is https://oauth-provider/authorize and for the whitelisted redirectURL is https://my-app/auth/callback/oauth. The folder structure of our new application will be:

routes/
├── authorize/
│   └── +page.svelte
└── auth/
    └── callback/
        └── oauth/
            └── +page.svelte

Consider the value of the origin of our identity server is https://oauth-identity.com/. Our application will make a call to https://oauth-identity.com/authorize?source_url=https://my-app.com/. Please note that we are passing the source_url where we expect the control back from our identity server once the authentication is done.

The authorization code in the identity server will do the following:

• It will save the source_url in the browser's local storage, where the key could be a random string like "state" and the value will be { redirect_uri: https://my-app.com }.

• It will then invoke the OAuth provider's authorization URL by passing in the whitelisted URL of the fake identity server.

Once the authentication is completed, the control will come back to our identity server's whitelisted URL, i.e., https://oauth-identity.com/auth/callback/oauth/+page.svelte. This file will perform the following operations:

• It will pick the source_url from the browser's local storage that was saved in the previous step.

• It will append /auth/callback/<provider-id> as a suffix to the source_url so that when the control is passed back to our application, Authjs is able to recognize this callback pattern.

• It will append the authorization code that was received from the OAuth and send back control to our application, i.e., https://my-app.com/auth/callback/auth0?code=abcd1234.

Finally, control comes back to our application, and since the redirectProxyURL property was configured, Authjs will realize that the authentication was performed by a proxy server. It will pick up the authorization code and make a token and userinfo call and proceed ahead to create and save the session-token cookie.

Here is the gist of the SvelteKitAuthConfig object:

// hooks.server.ts

import { dev } from '$app/environment';
import type { Handle } from '@sveltejs/kit';
import { SvelteKitAuth, type SvelteKitAuthConfig } from '@auth/sveltekit';

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const useSecureCookies = !dev;
  const config: SvelteKitAuthConfig = {
    providers: [
      id: 'auth0',
      authorization: {
        url: `https://sveltekit-auth-identity-server.vercel.app/authorize?source_url=${event.url.origin}`,
        params: {
          scope: 'openid name email profile',
          redirect_uri: `https://sveltekit-auth-identity-server.vercel.app/auth/callback/auth1`,
        }
      },
      token: `${ISSUER}oauth/token`,
      userinfo: `${ISSUER}userinfo`,
      redirectProxyUrl: 'https://sveltekit-auth-identity-server.vercel.app/auth'
    ]
  }
});

export const handle = getAuthConfig;

While working on the local machine, you can run code in two IDEs: one will execute the code of the main application, say, on port 4201, and one will execute the code of the identity server on port 4200. In that use case, you can configure:

authorization: {
  url: `http://localhost:4200/authorize?source_url=${event.url.origin}`,
  params: {
    scope: 'openid name email profile',
    redirect_uri: `http://localhost:4200/auth/callback/auth0`
  }
},
redirectProxyUrl: 'http://localhost:4200/auth'

With this configuration, we are able to share sessions among multiple applications spread across different domains.

Conclusion

In conclusion, managing shared sessions across multiple applications using SvelteKitAuth can be effectively achieved through careful configuration and understanding of domain-specific challenges. For applications sharing the same domain, a straightforward update to the cookie's domain property ensures seamless session sharing. However, for applications on different domains, implementing a proxy identity server becomes essential. This server handles the redirection process, allowing cross-domain authentication by centralizing callback handling. By following the outlined steps and configurations, developers can ensure secure and efficient session management across diverse application environments.

Here is the link to the GitHub repository with the codebase for the main application and the one with the identity application. Here is the link to view a live demo of this use case. In the next article, we will explore the shortcomings or the limitations of the SvelteKitAuth.

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.

Updating and Syncing data from the Client to the Server

Since the SvelteKitAuthConfig is attached to the hooks, it triggers with every API call that is intercepted by the hooks. The SvelteKitAuthConfig comes with two important callback functions, i.e., jwt and session, that trigger on every network request intercepted by the hooks.

The jwt callback holds the token property, which includes the authenticated user's token and profile data. This information constitutes the session information that will be shared site-wide. This information is stored in an encrypted format in the session-token cookie.

On every network request, this callback decrypts the session-token cookie, reads the information, performs operations, and then encrypts it back and saves it in the session-token cookie. This token is then passed to the session callback, which forms the session object that will be shared site-wide and can be accessed on the server as const session = await locals.auth() and on the client-side as const session = $page.data.session.

Hence, in order to update the user information, we must use the jwt callback so that it is preserved in the session-token cookie and later pass the information to the session callback so that the information is accessible on both the server and the client side.

The First Step: Updating the Config Object

With this knowledge in hand, let's configure the jwt and the session callback in the SvelteKitAuthConfig object.

{
  callbacks: {
    async jwt({ token, account, profile }) {
      ...
      const userQuery = event.request.headers.get('query') || event.url.searchParams.get('query');
      if (userQuery === 'update-user-data') {
        try {
          const clonedRequest = event.request.clone();
          const clonedBody = clonedRequest.body;
          const response = await new Response(clonedBody);
          const body = await response.json();
          if (!isEmpty(body)) {
            token = {
              ...token,
              ...body
            };
          }
        } catch (ex: any) {
          console.log('Unable to update user data for url', ex?.message);
        }
      }
      return token;
    },
    async session({ session, token }) {
      if (session.user) {
        if (token?.access_token) {
          session.user = { ...session.user, ...token } as any;
        }
      }
      return session;
    }
  }
}

Let's take a moment to understand what the above code snippet actually does:

• Since the jwt callback is invoked for every API request intercepted by the hooks, we cherry-pick the ones that have a particular flag passed via the header or the query params, which will instruct us that we must perform data communication operations. For the sake of this example, we use the string update-user-data.

• Once we get hold of this flag, we will fetch the payload from the request and update the token property of the jwt callback. Remember, this is the same property that will be preserved in an encrypted format in the session-cookie. Side Note: cookie size up to 4kb could be saved at any given time due to the browser's storage limitation. However, if we pass too much data into the token property, they will be chunked into multiple cookies, i.e., session-cookie_0, session-cookie_1, and so on.

• Finally, we pass the token property to the session callback so that it is available for use on both the client and the server side.

The Second Step: Creating the Update Endpoint

As we discussed in the last section, we need to intercept specific API requests that have flags which will enable us to kickstart the data operation. So in this section, we will create an API route that will be used by the client to send the payload which must be synced and updated on the server side.

So we create an API route in the file src/routes/api/update-user-data/+server.ts. The aim of this API route is to pass data to the jwt callback. The API route then sends the updated data back, which we can catch by invoking the auth() method. We then return the updated object back to the client.

import type { RequestHandler } from '@sveltejs/kit';
import { isEmpty } from 'lodash-es';

export const POST = (async ({ locals }) => {
  const session = await locals.auth();
  const user = session?.user;

  if (!isEmpty(user) && !isEmpty(session)) {
    try {
      return new Response(JSON.stringify({
        data: user
      }), { status: 200 });
    } catch (error: any) {
      console.log('Error while updating user data: ', error?.message, '. Sending existing data');
      return new Response(JSON.stringify({ data: user }), { status: 200 });
    }
  } else {
    return new Response(JSON.stringify({ data: 'user is not authorized to update data' }), { status: 401 });
  }
}) satisfies RequestHandler;

The Third Step: Client Initiates the Update Request

The client triggers the API route that we created in the previous section and sends the payload object along with it.

<script lang="ts">
  let userData = $page.data.session?.user?.fav_num || '';

  async function updateUserData() {
    const request = await fetch('/api/update-user-data?query=update-user-data', {
      method: 'POST',
      body: JSON.stringify({
        fav_num: `My favourite number is: ${Math.ceil(Math.random() * 100)}`
      })
    });
    const response = await request.json();
    userData = response?.data?.fav_num;
  }
</script>

<button on:click={updateUserData} class="button">Update user data</button>

{#if userData}
  <p>Updated user-data {userData}</p>
{/if}

With these three steps, the data is synced and updated by the client to the server. In the next section, we will learn how to update and sync the data from the server to the client.

Updating and Syncing Data from the Server to the Client

The only way for the server to send the information back to the client is via hydration. The server load functions, i.e., +layout.server.ts and +page.server.ts, can send data to the client by returning an object. Only objects that can be serialized using devalue can be used. Here is an example where the server load function returns the session property to the client.

NOTE: Properties returned by the layout server load function will be available to all the child routes, whereas the properties returned by the page server load will only be available to the current route. If both functions return the same property, the one that returns the last will precede over others.

// server load functions

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

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

The client can access this information using the $page.data property.

<script lang="ts">
  import { page } from '$app/stores';

  let session = $page.data.session;
  let user = $page.data.session.user;
</script>

Conclusion

In this article, we explored the process of exchanging data between the client and server using SvelteKitAuth. We delved into the importance of JWT and session callbacks, and how to effectively synchronize and store sessions. By configuring the jwt and session callbacks, creating an update endpoint, and initiating update requests from the client, we ensured seamless data synchronization from the client to the server. Additionally, we discussed how the server can send information back to the client through hydration using server load functions. By following these steps, you can maintain a consistent and secure data exchange between the client and server in your SvelteKit applications.

Here is the link to the GitHub repository with the codebase. In the next article, we will learn to how to build custom pages and handle events in SvelteKitAuth.

Using jwt and session callbacks in the provider configuration, we can persist OAuth tokens and refresh them when they expire. These callbacks trigger every time a call is made to auth(), i.e., event.locals.auth().

The first step is to create an API route that will refresh the token. In the file src/routes/api/renew-token/+server.ts:

import { isEmpty } from 'lodash-es';
import type { RequestHandler } from '@sveltejs/kit';
import { CLIENT_ID, CLIENT_SECRET, ISSUER, API_IDENTIFIER } from '$env/static/private';

export const POST = (async ({ fetch, locals }) => {
  const session = await locals.auth();
  const user = session?.user;

  if (!isEmpty(user)) {
    try {
      const request = await fetch(`${ISSUER}oauth/token`, {
        method: 'POST',
        headers: {
          'content-type': 'application/x-www-form-urlencoded'
        },
        body: new URLSearchParams({
          grant_type: 'client_credentials',
          client_id: CLIENT_ID,
          client_secret: CLIENT_SECRET,
          audience: API_IDENTIFIER // ${ISSUER}/api/v2/
        })
      });
      await request.json();
      console.log(`Response from API: ${JSON.stringify(response)}`);
      return new Response(JSON.stringify(response), { status: 200 });
    } catch (error: any) {
      console.log(`Error while updating token data: ${error?.message}. Reusing existing tokens!`);
      return new Response(JSON.stringify({
        access_token: user.access_token,
        expires_in: user.expires_in,
        token_type: 'Bearer'
      }), { status: 200 });
    }
  } else {
    return new Response(JSON.stringify({
      message: 'User is not authorized to rotate access-token'
    }), { status: 401 });
  }
}) satisfies RequestHandler;

Now, the second step is to configure the jwt and session callbacks in the provider's configuration to trigger token rotation upon invocation of the target API route:

// hooks.server.ts
export const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const config: SvelteKitAuthConfig = {
    ....,
    callbacks: {
      async jwt({ token, account, profile }) {
        /**
         * This callback triggers multiple times. For the very first time,
         * token -> { name, email, picture, sub }
         * account -> { all_tokens }
         * profile -> { all_user_details_and_custom-attributes }
         * trigger -> { signin, signut, update }
         * For second and successive times,
         * token -> { name, email, picture, sub, iat, exp, jti }
         * account -> undefined
         * profile -> undefined
         * trigger -> undefined
        */
        // store init values that must be passed to session cb, if this line is skipped then
        // { name, email, picture, sub, iat, exp, jti } will always be undefined in session cb
        try {
          if (!isEmpty(account)) {
            token = { ...token, ...account };
          }
          if (!isEmpty(profile)) {
            token = { ...token, ...(profile as any) };
          }

          // update user data on request
          const userQuery = event.request.headers.get('query') || event.url.searchParams.get('query');

          // refresh token post 30 minutes
          if (
            token &&
            (isTokenRefreshRequired(token.token_expires_in as string) || userQuery === 'update-token-data')
          ) {
            const tokenRequest = await event.fetch(
              event.url.origin + '/api/renew-token',
              { method: 'POST' }
            );
            const updatedToken = await tokenRequest.json();
            if (updatedToken.access_token) {
              token = {
                ...token,
                ...updatedToken
              };
            }
          }
        } catch (e: any) {
          console.log('ERROR in AUTH JWT CALLBACK: ', e?.message);
        }
        return token;
      },
      async session({ session, token }) {
        try {
          // This callback triggers multiple times
          if (session.user) {
            if (token?.access_token) {
              session.user = { ...session.user, ...token } as any;
            }
          }
        } catch (e: any) {
          console.log('ERROR in AUTH SESSION CALLBACK: ', e?.message);
        }
        return session;
      }
    },
  }
});

function isTokenRefreshRequired(issued_at: string) {
  return +difference([new Date(+issued_at), new Date(), 'minutes']) > 29;
}

In the jwt callback, we trigger the token rotation request in two scenarios:

1. Automatically, after every 30 minutes (just for the sake of example).

2. Once the user has manually requested token rotation.

It is important to save the updated access_token in the token property, as the contents of this token property are encrypted and saved in the session-token cookie. So when a new request is made, the same token is decrypted, and hence the value must be preserved.

As we know that the jwt and session callbacks trigger every time a call to auth() is made, to trigger the refresh token, we will have to create a dummy API route that will trigger the renew token process:

// FILE -> src/routes/api/trigger-renew-token/+server.ts

import type { RequestHandler } from '@sveltejs/kit';
import { isEmpty } from 'lodash-es';

export const POST = (async ({ locals }) => {
  const session = await locals.auth();
  const returnValue = !isEmpty(session)
    ? { status: 200 }
    : { status: 401 };
  return new Response(JSON.stringify(returnValue), { status: 200 });
}) satisfies RequestHandler;

Finally, we invoke it from the client side:

<!-- some *.svelte file -->
<script lang="ts">
  async function refreshToken() {
    const request = await fetch(
      '/api/trigger-renew-token?query=update-token-data',
      { method: 'POST' }
    });
  }
</script>
<button on:click={refreshToken} class="button">Refresh Token</button>

In conclusion, implementing refresh token rotation in SvelteKitAuth is a crucial practice for maintaining secure and seamless user sessions. By leveraging jwt and session callbacks, we can efficiently manage OAuth tokens, ensuring they are refreshed without user intervention. This approach not only enhances the user experience by avoiding frequent re-authentication but also maintains the integrity and security of the session. By following the outlined steps, including creating an API route for token renewal and configuring the necessary callbacks, developers can ensure that access tokens are consistently updated and preserved, providing a robust authentication mechanism in their SvelteKit applications.

Here is the link to the GitHub repository with the codebase. In the next article, we will learn how to effectively communicate data between client and the server in SvelteKitAuth.

Managing session on the Server side

As soon as the authentication is successful, SvelteKitAuth populates user sessions within locals that are accessible across the server-side code (i.e., hooks.server.ts, +page.server.ts, +layout.server.ts, +server.ts). Here is the programmatic representation of the statement:

src/hooks.server.ts

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const config: SvelteKitAuthConfig = {...}
});
export const handle = SvelteKitAuth(getAuthConfig) satisfies Handle;
// this adds { users, expires } property to locals

In server files, i.e., src/\.server.ts*,

We can access the session using the auth() method. Here, the session object will hold the user property that contains the user information and the expires property that depicts until which session is valid.

// [page | layout].server.ts
export const load = async (event) => {
  const session = await event.locals.auth();
  const isUserLoggedIn = !isEmpty(session?.user);
  if (isUserLoggedIn) {
    // execute business logic
  } else {
    // redirect user to sign-in oage
  }
  return { session };
};

// +server.ts
export const POST = (async ({ locals }) => {
  const session = await locals.auth();
  const isUserLoggedIn = !isEmpty(session?.user);
  if (isUserLoggedIn) {
    // execute business logic
  } else {
    // redirect user to sign-in oage
  }
};

We can verify if the user is authenticated or not based on the user and expires properties.

NOTE: The expires property updates itself every time the call to auth() is made, thus extending the user session.

Lastly, the page and layout server files can return this session object so that it is available on the client side as well.

Managing session on the Client side

The session management on the client starts from the session property that was returned by parent layout or page server files. It 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.

In the src/routes/+page.svelte.ts file, we can access the session variable:

<script>
  import { page } from '$app/stores';
</script>

{#if $page.data?.session?.user}
  <span>Display User specific Information</span>
{/if}

In universal load functions, src/routes/+[layout | page].ts, we can access the session variable:

export const load = (async ({ data }) => {
  const session = data.session;
  const isUserLoggedIn = !isEmpty(session?.user);
  if (isUserLoggedIn) {
    // execute business logic
  } else {
    // redirect user to sign-in oage
  }

  return { session };
});

This mechanism allows us to protect components from unauthorized access, i.e., Handling Authorization Per Component.

Coming to the second use case to protect routes/paths from unauthorized access, i.e., Handling Authorization Per Route. For this scenario, we first create an API route that returns the current session status.

src/routes/api/get-session-status/+server.ts

import type { RequestHandler } from "@sveltejs/kit";
import { isEmpty } from "lodash-es";

export const GET = (async (event) => {
  let returnValue = { status: 200 };
  try {
    const session = await event.locals.auth();
    const user = session?.user;
    const isUserLoggedIn = !isEmpty(session) && !isEmpty(user);
    returnValue = isUserLoggedIn ? { status: 200 } : { status: 401 };
  } catch (ex: any) {
    console.log(`Exception occured while quering user session: ${ex?.message}`);
    returnValue = { status: 401 };
  }

  return new Response(JSON.stringify(returnValue), { status: 200 });
}) satisfies RequestHandler;

Before navigating to each route, we can check if session is defined or not

<script lang="ts">
  import { beforeNavigate, goto } from '$app/navigation';

  beforeNavigate(async ({ to, cancel }) => {
    if (to?.url && to.url.pathname !== '/') {
      // check user session on every navigation
      const request = await fetch(`${window.location.origin}/api/get-session-status`);
      const response = await request.json();
      const publicURLs = ['/ssr-login', '/ssr-logout', '/public', '/'];
      if (response.status !== 200 && !publicURLs.includes(window.location.pathname)) {
        // user is not-logged in, redirect to sign-in screen
        cancel();
        goto(`/`);
      }
    }
    return true;
  });
</script>

Conclusion

In conclusion, managing sessions in SvelteKit with SvelteKitAuth can be effectively handled both on the server side and the client side. On the server side, sessions are managed using the auth() method, which provides a session object containing user information and session expiration details. This session object can be accessed across various server-side files and returned to the client side for further use. On the client side, the session data is available in the $page store, allowing for component-level and route-level authorization checks. By leveraging these mechanisms, developers can ensure secure and efficient session management in their SvelteKit applications.

Here is the link to the GitHub repository with the codebase. In the next article, we will learn how to rotate the refresh token in SvelteKitAuth.

When you trigger a signOut(), SvelteKitAuth logs the user out from your application by clearing the session-token cookie and resetting the Session to null. However, the user is still active in the OAuth provider's session layer. You can read more about this in the official Auth0 documentation, and this holds true for all OAuth providers.

You can verify the above statement in the following way:

• If you log in for the very first time using signIn(), you'll see a pop-up from your OAuth provider for credentials.

• Now log out using signOut(). Verify that the session-token and the Session are nullified.

• Log in again with signIn(). This time, you won't see any pop-up asking for credentials; instead, you will be auto-logged in the moment you press the sign-in button!

This proves that the user session was still active in the Auth0 session layer. If you want to clear the user session on Auth0's session layer as well, you will have to log out the user from Auth0 using the OIDC endpoint.

<!-- src/routes/logout/+page.svelte file -->
<script lang="ts">
  import { onMount } from 'svelte';
  import { page } from '$app/stores';

  onMount(async () => {
    const idToken = $page.data?.session?.user.id_token as string;
    window.location.href =
            import.meta.env.VITE_ISSUER +
            `oidc/logout?post_logout_redirect_uri=${encodeURIComponent(
                window.location.origin
            )}&id_token_hint=${idToken}`;
  });
</script>

The above code snippet showcases one of the many ways to log out users from the Auth0 session layer.

We need to do one more configuration in our Auth0 application. We need to add the URL to the Allowed Logout URLs option. I always redirect users to the home page, so I've given the URL of my root page. If you wish to redirect the user to any other page, that URL must be whitelisted here.

In this article, we explored the differences between signing out a user from the Application layer and the OAuth layer. We demonstrated how SvelteKitAuth handles user sign-out by clearing the session token and resetting the session, while the OAuth provider's session remains active. We also provided a method to log out users from the OAuth provider's session layer using the OIDC endpoint and highlighted the importance of configuring the Allowed Logout URLs in Auth0. Understanding these differences and configurations ensures a more secure and seamless user experience.

Here is the link to the GitHub repository with the codebase. In the next section, we will delve into managing sessions within the application.

Using Form Actions

<SignIn /> and <SignOut /> are components that @auth/sveltekit provides out of the box - they handle the sign-in/sign-out flow, and can be used as-is as a starting point or customized for your own components.

The detailed example is provided in the official documentation, so I'll skip this approach and move to the next one.

Using programatically to auto sign-in and sign-out users

If your organization has outsourced the authentication mechanism to a third-party vendor, you will not have the flexibility to use form actions (as described in the previous section) to perform authentication. You will have to programatically login user and this is how you could do that:

Sign-in Flow

We can programmatically redirect users to the login route via hooks if they are unauthenticated and carry on with silent sign-in.

The procedure is exactly the same as in client-side authentication. The difference is we have to carry out each step manually, which otherwise was done by SvelteKitAuth for us in the client-side flow.

1. Prepare payload for sign-in and pass callbackUrl and other params if required

2. Make a POST call to /auth/signin/<provider-id> by passing Content-Type and X-Auth-Return-Redirect header values

3. Get the URL for sign-in as response (this is the same URL that we pass as authorization URL in the provider) and redirect user for authentication.

// -> `/login/page.server.ts`

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

export const load = (async ({ fetch, locals, url: _url }) => {
  let url = '';
  try {
    const session = await locals.auth();
    if (!session?.user) {
      const params = new URLSearchParams();
      params.append('scope', 'api openid profile email');

      const formData = new URLSearchParams();
      formData.append('redirect', 'true');
      formData.append('callbackUrl', `${_url.origin}/ssr-login`);

      const signInRequest = await fetch('/auth/signin/auth1? ' + params.toString(), {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'X-Auth-Return-Redirect': '1'
        },
        body: formData.toString()
      });
      const signInResponse = await new Response(signInRequest.body).json();

      if (signInResponse?.url) {
        url = signInResponse.url;
      }
    }
  } catch (e: any) {
    console.log('Exception thrown while auto-sign-in: ', e);
  }

  if (url) {
    console.log('Auto login user: ', url);
    throw redirect(302, url);
  }
}) satisfies PageServerLoad;

NOTE: In the above code snippet, if you provide the option of callbackUrl within formData, that will be the output of signInResponse, else it will default to the URL of the page that initiated the sign-in request!

Sign-out Flow

The process is exactly similar to the one that we saw for the sign-in flow in the previous section.

// -> src/routes/logout/+page.server.ts file
import { redirect } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load = (async ({ fetch, locals }) => {
  try {
    const session = await locals.auth();
    if (session && !!session.user?.access_token) {
      const formData = new URLSearchParams();
      formData.append('redirect', 'false');
      formData.append('callbackUrl', `${_url.origin}`);

      const signOutRequest = await fetch('/auth/signout', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'X-Auth-Return-Redirect': '1'
        },
        body: formData.toString()
      });
    }
  } catch (e: any) {
    console.log('Exception thrown while auto-sign-out: ', e);
  }
}) satisfies PageServerLoad;

NOTE: After signing out, we must reload the page. If we use the inbuilt signOut(), SvelteKitAuth auto reloads the page and redirects to the callbackUrl or to the URL that initiated the sign-in request. Since we programmatically logged users out, it is our responsibility to reload the page afterward.

<!-- src/routes/logout/+page.svelte file -->
<script lang="ts">
  import { onMount } from 'svelte';
  import { page } from '$app/stores';
  import { goto } from '$app/navigation';

  onMount(() => {
    // session-storage ensures that we reload only once!
    const isAppReloaded = sessionStorage.getItem('reloadApp') || 'false';
    if (isAppReloaded === 'false') {
      sessionStorage.setItem('reloadApp', 'true');
      window.location.reload();
    }
  });
</script>

Conclusion

In this article, we have explored the intricacies of optimizing server-side login and logout processes. We began by discussing the use of form actions provided by @auth/sveltekit for handling authentication flows seamlessly. However, recognizing that not all organizations have the flexibility to use these form actions, we delved into the programmatic approach for auto sign-in and sign-out, which is particularly useful when dealing with third-party authentication vendors.

We detailed the steps involved in the sign-in flow, including preparing the payload, making a POST call, and redirecting users for authentication. Similarly, we covered the sign-out flow, emphasizing the importance of reloading the page after logging out to ensure a smooth user experience.

By understanding both client-side and server-side authentication processes, you are now equipped to implement robust and flexible authentication mechanisms in your applications.

Here is the link to the GitHub repository with the codebase. In the next section, we will explore the differences between signing out a user from the application versus signing out from the OAuth provider, providing further insights into managing user sessions effectively.

There are two ways to initiate the authentication flow: client-side and server-side. In this article, we will go through a step-by-step approach for client-side authentication.

We have two methods, signIn() and signOut(), from @auth/sveltekit/client to perform client-side sign-in and sign-out actions, respectively.

Sign-in Flow

signIn() is the client-side method to initiate a sign-in flow or send the user to the sign-in page listing all possible providers. It automatically adds the CSRF token to the request.

Use the signIn() method with the following properties:

• providerId: This is the "id" property that we specified in the previous sections. This is optional; if omitted, it defaults to the first id property specified in the SvelteKit configuration.

• options: This is an optional property where we can specify the callbackURL, i.e., the URL to which the user should be redirected once sign-in is successful. In some cases, you might want to handle the sign-in response on the same page and disable the default redirection. For example, if an error occurs (like wrong credentials given by the user), you might want to handle the error on the same page. For that, you can pass redirect: false in the second parameter object.

• Additional parameters: It is also possible to pass additional parameters to the /authorize endpoint through the third argument of signIn().

Although this is more than enough, if you still want to dive deeper into more options, you can read more configuration details in the official documentation.

<script lang="ts">
  import { signIn } from '@auth/sveltekit/client';
</script>

<button on:click={() => signIn(
  'auth0', {
    redirect: false,
    callbackUrl: 'http://localhost:4000/about'
  },
  {
    scope: 'api openid profile email'
  }
)}>Sign In with Auth0</button>

Sign-out Flow

The signOut() method logs the user out by removing the session cookie. It automatically adds the CSRF token to the request.

Like the signIn() method, you can pass a callbackURL and redirect option. More details are available in the official documentation.

<script lang="ts">
  import { signOut } from '@auth/sveltekit/client';
</script>

<button on:click={() => signOut()} class="button">Sign out</button>
<!-- OR -->
<button on:click={() => signOut({
  redirect: true,
  callbackUrl: 'url-post-logout'
})} class="button">Sign out with optional params</button>

NOTE: If you don't provide the callbackUrl option, it will redirect you to the page that initiated the sign-in request.

In this article, we explored the client-side sign-in and sign-out processes using SvelteKitAuth. By leveraging the signIn() and signOut() methods from @auth/sveltekit/client, we can streamline the authentication flow, providing a seamless user experience. Whether specifying a provider, handling callbacks, or managing errors, these methods offer flexibility and control.

Here is the link to the GitHub repository with the codebase. In the next section, we will go through server-side sign-in and sign-out flow.

Step 1: Create a file named types/auth.d.ts at the same level as src. Here, we will extend the core Session type with our custom type.

import type { DefaultSession } from '@auth/core/types';

declare module '@auth/core/types' {
    interface Session {
        user: DefaultSession['user'] & Partial<IUser>;
    }
}

interface IUser {
    name: string;
    email: string;
    image: string;
    picture: string;
    sub: string;
    access_token: string;
    id_token: string;
    scope: string;
    expires_in: number;
    token_type: string;
    expires_at: number;
    provider: string;
    type: string;
    providerAccountId: string;
    nickname: string;
    updated_at: string;
    email_verified: boolean;
    iss: string;
    aud: string;
    iat: number;
    exp: number;
    sid: string;
    jti: string;
    fav_num: string;
}

Step 2: Update the tsconfig.json file's types and include properties.

{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    ...,
    "types": ["vite/client", "svelte", "@auth/core", "@auth/sveltekit"]
  },
  "include": [
    ...,
    "types/**/*.ts"
  ]
}

Step 3: Restart your IDE.

In conclusion, enhancing SvelteKitAuth with custom type additions is a straightforward process that can significantly improve your development experience. By creating a custom typings file and updating your TypeScript configuration, you can ensure that your IDE recognizes all necessary types, reducing errors and improving code quality. Remember to restart your IDE after making these changes to apply the updates effectively. This small but crucial step can make a big difference in maintaining a smooth and efficient development workflow.

Here is the link to the GitHub repository with the codebase. In the next section, we will delve into initiating client-side sign-in and sign-out flows, further streamlining the user authentication journey.

Let's first discuss the scenarios where such a configuration is beneficial. For instance, offering multiple sign-in options like Google, GitHub, or LinkedIn can enhance user convenience and flexibility.

Here’s how to achieve this:

// hooks.server.ts

import type { Handle } from '@sveltejs/kit';
import Auth0Provider from "@auth/core/providers/auth0";
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 = {
    providers: [{
      Auth0Provider({
        id: 'auth0',
        name: 'built-in-oauth-provider',
        clientId: CLIENT_ID,
        clientSecret: CLIENT_SECRET,
        issuer: ISSUER
      }),
      id: 'auth1',
      name: 'custom-oauth-provider',
      type: 'oidc',
      client: {
        token_endpoint_auth_method: 'client_secret_post'
      },
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      issuer: ISSUER,
      wellKnown: WELL_KNOWN,
      checks: ['pkce'],
      authorization: {
        url: `${ISSUER}authorize`, // 'http://localhost:4200/authorize
        params: {
          scope: 'openid name email profile',
          redirect_uri: `${event.url.origin}/auth/callback/auth1`
        }
      },
      token: `${ISSUER}oauth/token`,
      userinfo: `${ISSUER}userinfo`
    }],
    secret: VERCEL_SECRET,
    debug: true,
    trustHost: true,
    session: {
      strategy: 'jwt',
      maxAge: 1800 // 30 mins
    },
    logger: {
      error: async (error: any) => {
        console.log('Error trace from SvelteKitAuth:', error);
      }
    }
  };
  return config;
});

export const handle = SvelteKitAuth(config) satisfies Handle;

The main differentiating factor is the id property. The id property uniquely identifies which provider should be used for authentication. The name property acts as a label or a detailed description that helps us differentiate the providers from each other.

We can switch the providers based on the id example:

<button on:click={() => signIn('auth0')} >
  <span>Sign In with Built-in Auth0 Provider</span>
</button>

<button on:click={() => signIn('auth1')} >
  <span>Sign In with Custom Auth0 Provider</span>
</button>

In conclusion, integrating multiple OAuth providers in SvelteKitAuth significantly enhances user experience by offering diverse sign-in options. This flexibility not only improves user convenience but also broadens the potential user base by accommodating various preferences. By following the outlined steps, developers can seamlessly configure multiple providers, ensuring a smooth and secure authentication process.

Here is the link to the GitHub repository with the codebase. In the next article, we will learn how to enhance custom typings with SvelteKitAuth.

A custom provider can be particularly useful when (a) you require extensive customization in your authentication mechanism, or (b) the authentication provider you're using is not currently supported by Auth.js.

Here is the code snippet for the custom provider. Let us now deep dive into custom providers and the properties that are used within the provider.

// hooks.server.ts

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

const config: SvelteKitAuthConfig = {
  providers: [{
    id: 'auth0',
    name: 'custom-oauth-provider',
    type: 'oidc',
    client: {
      token_endpoint_auth_method: 'client_secret_post'
    },
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
    issuer: ISSUER,
    wellKnown: WELL_KNOWN,
    checks: ['pkce'],
    authorization: {
      url: `${ISSUER}authorize`, // 'http://localhost:4200/authorize
      params: {
        scope: 'openid name email profile',
        redirect_uri: `${event.url.origin}/auth/callback/auth0`
      }
    },
    token: `${ISSUER}oauth/token`,
    userinfo: `${ISSUER}userinfo`
  }],
  secret: VERCEL_SECRET,
  debug: true,
  session: {
    maxAge: 1800 // 30 mins
  }
};

export const handle = SvelteKitAuth(config) satisfies Handle;

• id, name, clientId, clientSecret, issuer and wellKnown - these configurations remain the same as they were discussed in the last section. The focus here will be on the type property. The type property specifies the type of authentication mechanism, allowed values are: "oidc", "oauth", "credentials", and "email".

• If your provider is OpenID Connect (OIDC) compliant, the recommendation is to use the wellKnown option instead. OIDC usually returns an id_token from the token endpoint. SvelteKitAuth can decode the id_token to get the user information, instead of making an additional request to the userinfo endpoint.

• In case your provider is not OIDC compliant, we have the option to customize the configuration by using a combination of the following properties. You can find more information in the docs.

  • authorization: This is the URL for authentication. There are two ways to use this option:

    1. You can either set authorization to be a full URL, like "https://example.com/oauth/authorization?scope=email".

    2. Use an object with url and params like so

         authorization: {
           url: "https://example.com/oauth/authorization",
           params: { scope: "email" }
         }
       

  • token: This is the URL that will fetch token information. There are three ways to use this option:

    1. You can either set token to be a full URL, like "https://example.com/oauth/token?some=param".

    2. Use an object with url and params like so

         token: {
           url: "https://example.com/oauth/token",
           params: { some: "param" }
         }
       

    3. Completely take control of the request:

         token: {
           url: "https://example.com/oauth/token",
           async conform(response) {
             if (response.ok) {
               const body = await response.clone().json()
               if (body?.response?.access_token) {
                 return new Response(JSON.stringify(body.response), response)
               } else if (body?.access_token) {
                 console.warn("Token response conforms to the standard, workaround not needed.")
               }
             }
             return response
           }
         }
       

  • userinfo: A userinfo endpoint returns information about the logged-in user. It is not part of the OAuth specification but is usually available for most providers. There are three ways to use this option:

    1. You can either set userinfo to be a full URL, like "https://example.com/oauth/userinfo?some=param".

    2. Use an object with url and params like so

         userinfo: {
           url: "https://example.com/oauth/userinfo",
           params: { some: "param" }
         }
       

    3. Completely take control of the request:

         userinfo: {
           url: "https://example.com/oauth/userinfo",
           // The result of this method will be the input to the `profile` callback.
           async conform(response) {
             if (response.ok) {
               const body = await response.clone().json()
               if (body?.response?.access_token) {
                 return new Response(JSON.stringify(body.response), response)
               } else if (body?.access_token) {
                 console.warn("Token response conforms to the standard, workaround not needed.")
               }
             }
             return response
           }
         }
       

And that's it! We are ready with our custom OAuth Auth0 provider. Here is the final snippet that we will be using in the hooks.server.ts file:

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 = {
    providers: [{
      id: 'auth0',
      name: 'custom-oauth-provider',
      type: 'oidc',
      client: {
        token_endpoint_auth_method: 'client_secret_post'
      },
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      issuer: ISSUER,
      wellKnown: WELL_KNOWN,
      checks: ['pkce'],
      authorization: {
        url: `${ISSUER}authorize`, // 'http://localhost:4200/authorize
        params: {
          scope: 'openid name email profile',
          redirect_uri: `${event.url.origin}/auth/callback/auth0`
        }
      },
      token: `${ISSUER}oauth/token`,
      userinfo: `${ISSUER}userinfo`
    }],
    secret: VERCEL_SECRET,
    debug: true,
    trustHost: true,
    session: {
      strategy: 'jwt',
      maxAge: 1800 // 30 mins
    },
    logger: {
      error: async (error: any) => {
        console.log('Error trace from SvelteKitAuth:', error);
      }
    }
  };
  return config;
});

export const handle = SvelteKitAuth(getAuthConfig) satisfies Handle;

In conclusion, integrating a custom OAuth provider with SvelteKitAuth offers flexibility and extensive customization options for your authentication mechanism. By understanding and configuring properties such as authorization, token, and userinfo, you can tailor the authentication process to meet your specific needs. Additionally, the ability to include multiple providers in the same configuration enhances the versatility of your application. With these steps, you are well-equipped to implement a robust and customized authentication system using SvelteKitAuth.

Here is the link to the GitHub repository with the codebase. In the next article, we will go through the steps on configuring multiple providers with SvelteKitAuth.

Basic Configuration

Below is the code snippet for using the built-in Auth0 OAuth provider:

// hooks.server.ts

import Auth0Provider from "@auth/core/providers/auth0";
import type { SvelteKitAuthConfig } from '@auth/sveltekit';

const config: SvelteKitAuthConfig = {
  providers: [
    Auth0Provider({
      id: 'auth0',
      name: 'Auth0',
      clientId: '-client-id-',
      clientSecret: '-client-secret-',
      issuer: 'https://dev-****.auth0.com/',  // <- remember to add trailing `/` 
      wellKnown: 'https://dev-****.auth0.com/.well-known/openid-configuration'
    }) as Provider
  ],
  secret: 'random-32-bit-hexadecimal-string',
  session: {
    strategy: 'jwt',
    maxAge: 3600 
  },
  trustHost: true
  ...
}

Let discuss about these properties in detail:

• id: It is a string value that you can assign to uniquely identify the provider. As we can see from the syntax providers[{...}] is an array, and hence this id property helps in referencing a particular provider in the case where we have multiple providers. Also, this particular id is used in the callback URL pattern. Our callback URL is localhost:4000/auth/callback/auth0; here "auth0" comes from this "id" parameter. It is an optional parameter; if we skip this, it defaults to the in-built provider that we are using, in this case, "Auth0".

• name: This is an optional property wherein you can provide any string value, preferred one is the name of the OAuth provider you're using i.e., "Auth0"

• clientId: is a unique identifier that is assigned to an application when it registers with an OAuth 2.0 service provider. The clientId is used by the application to authenticate itself to the service provider and to obtain access tokens. Client Id value can be obtained from the OAuth application. In your Auth0 application, go to -> Settings tab -> Basic Information Section -> Get Client ID string.

• clientSecret: is a secret key that is used to protect the client ID. The clientSecret is not shared with the service provider and must be kept confidential by the application. Client Secret value, similar to Client ID, can be retrieved from the Basic Information Section of your Auth0 application.

• issuer: The issuer is the domain of your Auth0 application, which can be fetched from the Basic Information Section of your Auth0 application.

  

• wellKnown: The wellKnown URL is a preassigned stable endpoint that a server uses every time it runs. It contains information about where to fetch tokens and user information post-authentication.

• secret: This is a random string used as a salt for encryption. It should be a 32-character Hexadecimal string. You can generate one from this site.

• trustHost: 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.

• session: This sets the strategy used for authentication. Available options are "database" and "jwt". It defaults to "jwt". For this tutorial series, we will be using "jwt". You can read more about session strategy here.

These were the core properties that should suffice the basic requirement for authentication. However, we will discuss a few more properties that enhance the developer experience to manage authentication.

• debug: This will use the console methods to log out many details about the authentication process, including requests, responses, errors, and database requests and responses.

• basePath: If your application has a base path configured, then you must set the same base path here as well.

• cookies: SvelteKitAuth sets a minimum of 3 and a maximum of 5 cookies based on the configuration of the provider.

    import { dev } from '$app/environment';
  
    const useSecureCookies = !dev;
  
    cookies: {
      callbackUrl: {
        name: `${useSecureCookies ? '__Secure-' : ''}authjs.callback-url`,
        options: {
          httpOnly: true,
          sameSite: useSecureCookies ? 'none' : 'lax',
          path: '/',
          secure: useSecureCookies
        }
      },
      ...
    }
  

  1. callbackUrl: This property saves callbackUrl

  2. csrfToken: This property saves the CSRF token that is generated by SvelteKit (by default, if on else by SvelteKitAuth)

  3. pkceCodeVerifier: This sets pkce cookie only once check for PKCE is enabled

  4. sessionToken: This is a very important cookie and sets the actual session of the user.

  5. state: This sets pkce cookie only once check for STATE is enabled

You can change these default configurations, however, 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. More Reading...

• callbacks: 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.

  There are 4 types of callbacks: (1) jwt, (2) session, (3) redirect and (4) signIn.

    optional callbacks: {
      jwt: (params) => Awaitable<null | JWT>;
      redirect: (params) => Awaitable<string>;
      session: (params) => Awaitable<Session | DefaultSession>;
      signIn: (params) => Awaitable<string | boolean>;
    };
  

  We will discuss some of these in detail in our next tutorial on creating a custom OAuth provider. However, if you want to utilize these options within in-built providers, you can read the details from official documentation

• logger: You can customize the logging output by providing your own logger. This is useful if you want to send logs to a logging service or if you want to customize the format of the logs.

    logger: {
      error(code, ...message) {
        console.error(code, message)
      },
      warn(code, ...message) {
        console.warn(code, message)
      },
      debug(code, ...message) {
        console.debug(code, message)
      },
    },
  

• events: 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.

    events: {
      createUser: (message) => Awaitable<void>;
      linkAccount: (message) => Awaitable<void>;
      session: (message) => Awaitable<void>;
      signIn: (message) => Awaitable<void>;
      signOut: (message) => Awaitable<void>;
      updateUser: (message) => Awaitable<void>;
    };
  

• pages: 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. We have 4 types of pages:

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

  Here are a few examples from the official documentation:

  1. Built-in pages

  2. Custom sign-in page

  3. Custom sign-out page

  4. Custom Error page

We will go through a few examples in depth later in this tutorial series.

Environment Variables

We must set a couple of mandatory environment variables:

1. AUTH_URL: This environment variable is mostly unnecessary with v5 as the host is inferred from the request headers. However, if you are using a different base path, you can set this environment variable as well. For example, AUTH_URL=http://localhost:3000/web/auth or AUTH_URL=https://company.com/app1/auth

2. CLIENT_ID and CLIENT_SECRET: It is recommended to save CLIENT_ID and CLIENT_SECRET in the .env file and access via $env/static/private.

3. ISSUER and WELL_KNOWN: Same strategy as above for these two variables as well.

Here are few other environment variables that you may find useful.

Final Setup

With these additional properties, out updated configuration will be:

import { AUTH_SECRET, CLIENT_ID, CLIENT_SECRET, ISSUER, WELL_KNOWN } from '$env/static/private';

const config: SvelteKitAuthConfig = {
  providers: [
    Auth0Provider({
      id: 'auth0',
      name: 'Auth0',
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      issuer: ISSUER,
      wellKnown: WELL_KNOWN
    }) as Provider
  ],
  secret: AUTH_SECRET,
  session: {
    strategy: 'jwt',
    maxAge: 3600 
  },
  trustHost: true,
  debug: true,
  logger: {
    error: async (error: any) => {
      console.log('Error trace from SvelteKitAuth:', error);
    }
  }
}

We must use this piece of code in the hooks.server.ts file. Why? Because we want authentication to happen on every network request we make. We want to ensure that protected resources are not accessed if the user is not authenticated. In the SvelteKit ecosystem, hooks act as a middleware that taps request and response. Hence, this is the ideal place where we want our Authentication code to be integrated.

// hooks.server.ts

import type { Handle } from '@sveltejs/kit';
import Auth0Provider from "@auth/core/providers/auth0";
import { SvelteKitAuth, type SvelteKitAuthConfig } from '@auth/sveltekit';

const { handle: getAuthConfig } = SvelteKitAuth(async (event) => {
  const config: SvelteKitAuthConfig = {...};
  return config;
});

export const handle = getAuthConfig;

SvelteKitAuth(() => {}) is the callback expose by SvelteKitAuth that return three functions:

• handle: This must be used within handle function in hooks

• signIn: User for server side sign-in.

• signOut: Used for server side sign-out.

For the sake of this tutorial, we only need the handle callback that will be consumed by our hooks file. We will discuss the other two callbacks in detail in the later part of the tutorial.

Integrating the built-in Auth0 OAuth provider with SvelteKit can significantly streamline the authentication process in your application. By understanding and configuring the essential properties such as id, clientId, clientSecret, and issuer, you can ensure a secure and efficient authentication flow. Additionally, leveraging advanced options like callbacks, logger, and events can enhance the developer experience and provide greater control over the authentication process. Setting up the necessary environment variables and placing the authentication code in the hooks.server.ts file ensures that protected resources are accessed only by authenticated users. With this setup, you are well-equipped to manage authentication in your SvelteKit application, paving the way for more advanced configurations and custom providers in the next tutorial. Here is the link to the GitHub repository with the codebase.

Creating a Auth0 application

Before we start coding, we need to have an Auth0 application. Let's create one.

• Assuming you have a registered account with Auth0, go to the dashboard and on left-hand side navigation, click on "Applications" -> "Create Application".

  

• Enter the Application name and choose the application type as "Regular Web Applications".

  

• You should now reach the dashboard page. Click on the "Settings" tab.

  

• Scroll down to the section "Application URIs" -> "Allowed Callback URLs". A callback URL is a URL that is invoked after OAuth authorization for the consumer. SvelteKitAuth has a specific pattern for callback URLs which is <origin>/auth/callback/providerId We must follow this pattern. We will enter two values here, one for local development http://localhost:4000/auth/callback/auth0 and the other for where we host our site https://my-app.vercel.app/auth/callback/auth0 We can also use a wildcard pattern to whitelist the entire domain: https://*.vercel.app.

  

• The next section will be "Allowed web origins" within "Application URIs" http://localhost:4000, https://*.vercel.app

• Click on "Save Changes".

With these changes, our OAuth application is now ready, and we can configure it with SvelteKitAuth.

Integrating Auth0 application with SvelteKit using SvelteKitAuth

In SvelteKit, authentication is typically handled using community-supported libraries and services. In this series of articles, we will be focusing on OAuth provider - Auth0

Before we begin, let's install two dependencies:

"dependencies": {
  ...,
  "@auth/core": "^0.34.1",
  "@auth/sveltekit": "^1.4.1"
}

There are two ways to integrate OAuth providers with our application:

1. Using built-in OAuth providers

   • A built-in OAuth provider typically refers to a service or platform that offers OAuth authentication as part of its core functionality.

   • These services are designed to handle the complexities of OAuth authentication, including token management, user sessions, and integration with various identity providers (like Auth0, Google, GitHub, etc.).

   • Integration with these built-in providers often involves using SDKs or libraries provided by the service, which abstracts much of the OAuth protocol details and makes integration straightforward.

2. Using custom OAuth providers

   • A custom OAuth provider refers to implementing OAuth authentication yourself or using a custom implementation not provided by a dedicated authentication service.

   • This approach requires you to set up your own OAuth server, which manages the OAuth flow, token generation, and user authentication.

   • Advantages of a custom OAuth provider include greater control over the authentication process, customization to fit specific application needs, and potentially lower cost (as you manage the infrastructure yourself).

   • However, implementing a custom OAuth provider requires a good understanding of OAuth protocols (like OAuth 2.0), security considerations (such as token management and secure communication), and may involve more development effort compared to using a built-in provider.

Key Differences:

• Complexity and Maintenance: Built-in OAuth providers typically abstract away much of the complexity of OAuth authentication, making integration easier and reducing maintenance overhead. Custom OAuth providers require more setup and ongoing maintenance.

• Control and Customization: Custom OAuth providers offer more control and customization options but require deeper technical expertise and effort to implement securely.

• Integration Effort: Built-in OAuth providers often provide SDKs and libraries that simplify integration with various platforms, whereas custom OAuth implementations require you to handle integration details manually.

In summary, the choice between a built-in OAuth provider and a custom OAuth provider depends on factors like your project's specific requirements, desired level of control, and your team's expertise in handling authentication protocols and security. For most applications, leveraging a well-established built-in OAuth provider like Auth0, Firebase Authentication, or others can often provide a good balance of ease of use, security, and functionality.

Stay tuned for the next article, where we will delve deeper into integrating SvelteKitAuth with the Auth0 OAuth provider.

If I were to explain OAuth to a 5 years old:

Imagine you have a box full of toys and you want to share them with your friend. But you don't want to just give them the whole box, because there might be some toys you don't want them to play with yet.

This is kind of like how websites work sometimes. They have information that they want to share with other websites, but they don't want to give them full access to everything.

OAuth is like a special way of sharing. Here's how it works:

1. You ask your friend's parent: You tell your friend's parent (like a website's login) that you want to play with some of their child's toys (like the website's information).

2. The parent asks your friend: The parent asks their child (the website asks the user) if it's okay for you to play with some of their toys (access some information).

3. Your friend gives a special key: If your friend says yes, they give you a special key (like an authorization code) that lets you open a small box of toys (access a specific part of the information).

4. You show the key to get the toys: You take that key back to the parent (the website sends the code back to a special server) and show it to them.

5. The parent gives you the small box: The parent sees the key and knows it's okay, so they give you a small box of toys to play with (the website gives the special key to access the specific information you requested).

This way, your friend (the website) gets to control what you can play with (what information you can access), and their parent (the login system) makes sure it's okay.

A little more technical explanation of previous version:

OAuth works behind the scenes when you use a website or app to sign in with another account, like signing into Facebook with your Google account. Here's a simplified breakdown:

The Players:

• You (the Resource Owner): The person using the website or app.

• Your Main Account (the Client): The account you want to use to sign in (like Google).

• The Website/App (the Resource Server): The website or app you're trying to access.

• Login Service (the Authorization Server): The service handling the login process (like Google in this case).

The Flow:

1. Website asks to Sign In: The website or app asks you to sign in with your main account.

2. Choose Account & Permissions: You choose your main account (like Google) and see what information the website wants to access (like your name and email).

3. Login to Main Account: You log in to your main account if needed.

4. Permission Decision: You decide to allow or deny the website access to your information.

5. Code Sent Back (if allowed): If you allow, your main account sends a special code back to the website.

6. Website Exchanges Code for Token: The website sends the code back to the login service to get a special token.

7. Website Access Granted: The login service verifies the code and sends a token back to the website. This token acts like a key that lets the website access your information securely.

8. Website Gets Your Information: The website uses the token to get your information from your main account, without needing your password.

Benefits:

• Security: You don't share your main account password with the website.

• Convenience: You can sign in easily without creating a new account for every website.

• Control: You control what information the website can access.

This is a basic explanation, and OAuth can be more complex depending on the situation. But hopefully, this gives you a general idea of how it works!

OAuth with PKCE

OAuth 2.0 with PKCE (Proof Key for Code Exchange) is an extra secure version of the regular OAuth flow we talked about earlier. It's kind of like adding a special lock to the code exchange process. Here's how it works:

1. App Makes Secret Key: Imagine the app you're using makes up a super secret message (the code verifier) like a fun codeword only they know.

2. Secret Key Gets Disguised: The app scrambles this codeword into something unrecognizable (the code challenge). This disguised code is like the secret key hidden inside a puzzle box.

3. Login Request with Puzzle: The app sends the disguised code (code challenge) to the login service along with your request to sign in.

4. Login and Permission: You log in to your main account and decide if the app can access your information.

5. Authorization Code Sent: If you say yes, the login service sends a special code (authorization code) back to the app.

6. App Reveals Secret Key: The app now reveals the original secret message (code verifier) it created earlier.

7. Checking the Puzzle: The login service checks if the unscrambled code (code verifier) matches the disguised code (code challenge) it received before.

8. Token Granted (if match): If the codes match, it proves the app is who it says it is. Then, the login service gives the app a special token to access your information.

Why PKCE?

Regular OAuth flow might send the authorization code openly, which could be risky if someone peeked at it. PKCE adds a layer of security because only the real app that created the secret message can solve the puzzle and get the token.

Think of it like this:

• The secret message (code verifier) is like a special key you keep hidden.

• The disguised code (code challenge) is like a secret message someone else can see, but they can't figure out the real key from it.

• Matching the codes proves the app has the real key and is who it claims to be.

Understanding OAuth and its enhanced version with PKCE is crucial for implementing secure authentication in modern web applications. OAuth provides a robust framework for delegating access without sharing passwords, ensuring both security and convenience for users. By incorporating PKCE, the security of the OAuth flow is further strengthened, making it resilient against interception attacks. In the next article, we will delve into the practical aspects of configuring the SvelteKitAuth authentication library with SvelteKit, enabling you to implement these concepts effectively in your applications. Stay tuned for a step-by-step guide to secure your SvelteKit apps with SvelteKitAuth.

References

https://authjs.dev/concepts/oauth

What is SvelteKitAuth?

• SvelteKitAuth is part of the Auth.js project - Authentication for Web which is an open-source library that is easy to use.

• SvelteKitAuth is an extension of NextAuth - a popular authentication framework from the Next / React world. NextAuth is now getting a major overhaul and is now becoming Auth.js

• It can be used with any OAuth2 or OpenID Connect provider and has built-in support for 68+ popular services like Google, Facebook, Auth0, Apple etc.

• Apart from OAuth authentication, it has built-in support for authentication using email/passwordless/magic link/username/password.

• We can configure SvelteKitAuth to use database sessions (MySQL, Postgres, MSSQL, MongoDB etc.) or JWT.

• It comes with a built-in security mechanism having features like Signed, prefixed, server-only cookies, has built-in CSRF protection & doesn't rely on client-side JavaScript.

How does SvelteKitAuth work under the hood?

To understand how SvelteKitAuth works under the hood, let's explore its internal architecture and the steps involved in the authentication flow.

1. Configuration: When setting up SvelteKitAuth, you define a configuration file that specifies authentication providers, such as Google, GitHub, or a custom provider. The configuration also includes settings like secret keys, session storage options, and callback URLs.

2. Authentication Providers: SvelteKitAuth supports multiple authentication providers, and you can choose the ones you want to enable. Each provider has its configuration options, such as client ID, client secret, scopes, and authorization URLs.

3. Client-Side Flow: When a user initiates the authentication process, SvelteKitAuth handles the flow by redirecting them to the respective authentication providers login page. This typically involves generating a state and storing it in a server-side session to prevent CSRF attacks.

4. Callback URL: After successful authentication with the provider, the user is redirected back to a callback URL specified in the SvelteKitAuth configuration. This URL is typically an API route that SvelteKitAuth exposes.

5. Server-Side Flow: SvelteKitAuth receives the callback request on the specified API route. It validates the received data, including the state parameter, to ensure it matches the stored session state. This step prevents CSRF attacks.

6. Token Exchange: SvelteKitAuth then exchanges the authorization code received from the authentication provider with an access token. This token allows SvelteKitAuth to make authenticated API requests on behalf of the user.

7. User Information: With the access token, SvelteKitAuth retrieves the user's profile information from the authentication provider's API. It can fetch details like name, email, profile picture, or any other data that the provider makes available.

8. Session Management: SvelteKitAuth creates a session for the authenticated user, typically using a secure HTTP-only cookie or a JWT (JSON Web Token). This session contains the user's data and is used for subsequent authenticated requests.

9. Persistent Sessions: SvelteKitAuth can optionally store session information in a database or other storage mechanisms. This allows users to remain logged in even if the server restarts or the user refreshes the page.

10. Hooks and Events: SvelteKitAuth provides various hooks and events that you can use to customize the authentication flow, add additional functionality, or integrate with external systems. Examples include the $page.data.session for accessing the session data in components and event hooks like signIn or signOut for performing actions on authentication events.

Why choose SvelteKitAuth?

SvelteKitAuth supports OAuth 1.0, 1.0A, 2.0 and OpenID Connect and has built-in support for the most popular sign-in services like Google, GitHub, Auth0, Salesforce etc. It also supports multiple popular database adapters like MySQL, Postgres, MSSQL, MongoDB etc. Apart from that it provides a mechanism to create a custom OAuth provider and custom database adapter as well.

Overall, SvelteKitAuth abstracts away the complexities of authentication and provides a unified API for integrating with multiple authentication providers. It handles the authentication flow, token exchange, and session management, allowing developers to focus on building their applications without getting caught up in the intricacies of authentication protocols.

svelte-i18n

Features

• It is a simple and minimalistic library that uses formatjs for localizing messages and supports the ICU message syntax.

• It offers to load translations in a synchronous as well as asynchronous manner as per requirement.

• Provides a decent number of options for formatting and pluralization.

Ease of Use

• Since this library uses native Svelte stores for implementing localization, it feels like part of the ecosystem and hence very easy to get started with!

• If you have a simple requirement of changing translations based on a given locale with limited formatting, this should be your go-to library.

Size

• As of v3.7.0, the size of the svelte-i18n package is 48.3 kB in the minified form and 14.2 kB in minified + gzipped form. (source)

Community Support

• It has 29,978 downloads/week as of the time of writing this article.

• The only downside is, this library is not actively managed. Several issues are on the rise and resolution is almost zero.

Limitations

• There are very less options available for formatting and pluralization.

• As mentioned before, the library is not actively managed.

sveltekit-i18n

Features

• It is built for SvelteKit and has good SSR support.

• We can load translations from API, database and local file system.

• The translations are loaded for visited pages only. (and only once!)

• Component-scoped translations: you can create multiple instances with custom definitions.

• It provides good TS support and has no external dependencies.

• Supports ICU syntax + provides a native parsing engine as well.

Ease of Use

• It is very easy to use. I found it even easier while working with the ICU parser (instead of the default parser).

Size

• As of v2.4.2, the size of the sveltekit-i18n package is 14 kB in the minified form and 4.6 kB in minified + gzipped form. (source)

Community Support

• It has 3,052 downloads/week as of the time of writing this article.

• Even though the number of downloads is less than the svelte-i18n but good news is that this library is actively maintained.

Limitations

• While working with pluralization, understanding the syntax of the default parser could be a bit challenging at the start.

typesafe-i18n

Features

• It is a lightweight, easy-to-use syntax and has no external dependencies.

• Because of its strong typings, it prevents you from making mistakes (also in plain JavaScript projects).

• Unlike the other two libraries, typesafe-i18n can be used with any framework and supports both TypeScript and JavaScript.

• Creates boilerplate code for you which ensures the well-structured flow of i18n in your codebase.

• Supports plural rules and allows formatting of values e.g. locale-dependent date or number formats.

• It also supports switch-case statements e.g. for gender-specific output.

• Provides an option for asynchronous loading of locales.

• It supports SSR (Server-Side Rendering) and can be used for frontend, backend and API projects.

• Import and Export translations from/to files or services.

Ease of Use

• It has some initial learning curve but as soon as we become familiar with the typesafe-i18n ecosystem, this library is not only easy to use but super convenient as well!

• Personally, this is my go-to library for i18n.

Size

• As of v5.26.0, the size of the typesafe-i18n package is 2.8 kB in the minified form and 1.3 kB in minified + gzipped form. (source)

Community Support

• It has 13,588 downloads/week as of the time of writing this article.

• This library is actively maintained.

Limitations

• It has a huge eco-system (generators, detectors, importers, exporters etc.) and hence learning curve is a bit steep.

The typesafe-i18n is a fully type-safe and lightweight internationalization library for all your TypeScript and JavaScript projects. One thing that makes typesafe-i18n stand out is that it is a generic library and not limited to Svelte, you can use it with any of your JavaScript or TypeScript projects.

This library introduces a full-fledged flow for maintaining localization in your application. The moment you install this library, it generates a specific folder structure encompassing all the i18n-specific files.

Understanding typesafe-i18n ecosystem and nomenclature

There are six main packages that I want to explain before we start with actual implementation.

1. Generators:

   • Generators, as the name says generate boilerplate code specific to i18n and look for changes that you make to locale files.

   • Once we have installed typesafe-i18n and run the command typesafe-i18n, the generator kicks in and will generate the following project structure within the src/i18n directory. By default locales for de and en will be auto-generated.

       src/
         i18n/
           en/
             index.ts
           de/
             index.ts
           custom-types.ts
           formatters.ts
           i18n-types.ts
           i18n-util.async.ts
           i18n-util.sync.ts
           i18n-util.ts
     

   • Let's go through these generated files as they will be very useful when we localize our application:

     • en/index.ts: If 'en' is your base locale, the file src/i18n/en/index.ts will contain your translations. Whenever you make changes to this file, the generator will create updated type definitions.

     • custom-types.ts
       To define types that are unknown to typesafe-i18n.

     • formatters.ts
       In this file, you can configure the formatters to use inside your translations. The Formatters type gets generated automatically by reading all your translations from the base locale file.

     • i18n-types.ts
       Type definitions are generated in this file. You don't have to understand them. They are just here to help TypeScript understand, how you need to call the translation functions.

     • i18n-util.async.ts
       This file contains the logic to load individual locales asynchronously. This is the preferred approach and we will be using this approach while localizing our application.

     • i18n-util.sync.ts
       This file contains the logic to load your locales synchronously.

     • i18n-util.ts
       This file contains wrappers with type information around the base i18n functions.

   • These files will be auto-updated (except formatters.ts and custom-types.ts) every time you make changes to your locale, if you manually make any changes to these files, they will be over-written!

   • We can configure generators as per our requirements. Here is the list of available options that can be utilized to customize generators. In this article, I'll be keeping things simple and won't be customizing them.

2. Detectors:

   • Locale detection is a key part of any i18n solution. Therefore typesafe-i18n provides a solution to detect a user's locale.

   • Dectotors exports multiple utility methods that enable us to detect locale on the client and server side. We will see a few of them in sections Detect the locale on the server side and Detect the locale on the client side.

3. Runtime:

   • The runtime package provides the means of writing and using translations in typesafe-i18n. It exposes wrappers that enable us to pluralize, format and translate our messages.

   • From amongst many utilities exported by this package, three important ones that I want to highlight are:

     • i18nString: It is represented as LLL. It is used for simple string interpolation.

     • i18nObject: It is represented as LL. It is useful in scenarios when we want to provide translations for a particular locale asynchronously i.e. load one locale at a time. We will be using this method in our application.

     • i18n: It is represented as L. It is useful in scenarios when we want to load all the locales synchronously.

   • As mentioned before, I'll be using the LL approach in this article. Here is the link to official documentation that explains how to use the other two approaches.

4. Formatters

   • This package exports multiple utility methods useful for formatting. We will see a few of them in the section on Formatting.

5. Importers:

   • This package is used for importing language files that come from an API, spreadsheet or JSON files. I won't be covering details about this package in this article.

6. Exporters:

   • This package is used for exporting language files to a service or an API. I won't be covering details about this package in this article.

That's it with the fundamentals, let's start with localizing our application.

Application Structure

Before we begin, I want to give you a detailed walkthrough of the application that we will be working on. You can find the code in the GitHub repository.

As we can see from the image, this will be a simple single-page application demonstrating i18n features like locale switching, pluralization and formatting.

In the next section, we will work on integrating the typesafe-i18n library with SvelteKit.

Integration with SvelteKit

1. Install and Configure the typesafe-i18n library

   • This first step is to install this library as a dependency in our SvelteKit project. We will also need to install npm-run-all package as the dev-dependency. NOTE: Use npm, I tried with pnpm but was not able to execute this command.

       npm i --save-dev npm-run-all
       npx typesafe-i18n --setup-auto
     

   • This command will run the setup process and automatically detect the config needed. If you want to manually setup the configuration, the command for that is: npx typesafe-i18n --setup

   • This will generate a config file .typesafe-i18n.json. In this file, we will add a new property outputPath to generate folder structure within the src/lib/i18n (default is src/i18n) so that we can access those files with SvelteKit $lib feature.

       {
         ...,
         "outputPath": "./src/lib/i18n/"
       }
     

   • The next step is to update the package.json file to include the script for running the typesafe-i18n CLI along with the Vite development server.

       "scripts" : {
         "dev": "npm-run-all --parallel vite typesafe-i18n",
         "vite": "vite dev",
         "typesafe-i18n": "typesafe-i18n",
         ...
       }
     

   • If we run the script npm run dev, it will generate a folder structure for your locales inside the src/lib/i18n folder. By default locales for de and en will be auto-generated, we will customize this in the next section.

2. Define Locale Dictionary

   • Now that we have installed this library, it's time to identify the areas in our demo application that need localization. We then define the locale dictionaries within the src/lib/i18n folder generated by typesafe-i18n. A locale dictionary is a regular JSON object which contains message definitions for a certain language.

   • The best thing about typesafe-i18n is all the dictionaries will be typed. We can use BaseTranslation type for the same.

   • In our example application, I want five fields to be localized: The main heading, Lable for locale switching, Body text (the paragraph) and Text for pluralization.

   • For the sake of this application, I will define dictionaries in three languages - English (en.json), Hindi (hi.json) and French (fr.json) within the src/lib/i18n folder.

   • By default en/index.ts and de/index.ts will be pre-configured. We will rename de to hi and create a new entry for the fr/index.ts language.

       // file -> src/lib/i18n/en/index.ts
       import type { BaseTranslation } from '../i18n-types';
     
       const en = {
         heading: 'Internationalization in SvelteKit',
         toggle_label: 'Select Locale',
         body_text:
               'This is a small example to demonstrate i18n functionality in SvelteKit using typesafe-i18n library. typesafe-i18n is a fully type-safe and lightweight internationalization library for all your TypeScript and JavaScript projects. typesafe-i18n comes with an API that allows other services to read and update translations. Total number of npm downloads per week as of {date:Date|simpleDate} are {download:number|simpleNumber}.',
         awards: 'You have {{ not won any awards | won exactly ?? award | won ?? awards }}!',
         time: '{value:Date|simpleTime}',
         date: '{value:Date|simpleDate}',
         currency: '{value:number|simpleCurrency}'
       } satisfies BaseTranslation;
     
       export default en;
     
       // file -> src/lib/i18n/hi/index.ts
       import type { BaseTranslation } from '../i18n-types';
     
       const hi = {
         heading: 'SvelteKit में अंतर्राष्ट्रीयकरण',
         toggle_label: 'भाषा चुने',
         body_text:
               'यह typesafe-i18n लाइब्रेरी का उपयोग करके SvelteKit में i18n कार्यक्षमता प्रदर्शित करने के लिए एक छोटा सा उदाहरण है। typesafe-i18n आपके सभी टाइपस्क्रिप्ट और जावास्क्रिप्ट प्रोजेक्ट्स के लिए पूरी तरह से टाइप-सुरक्षित और हल्के अंतर्राष्ट्रीयकरण लाइब्रेरी है। typesafe-i18n एक एपीआई के साथ आता है जो अन्य सेवाओं को अनुवाद पढ़ने और अपडेट करने की अनुमति देता है।। {date:Date|simpleDate} तक प्रति सप्ताह npm डाउनलोड की कुल संख्या {download:number|simpleNumber} है|',
         awards: 'आपने {{ कोई पुरस्कार नहीं जीता | बिल्कुल ?? पुरस्कार जीता | ?? पुरस्कार जीते }} है|',
         time: '{value:Date|simpleTime}',
         date: '{value:Date|simpleDate}',
         currency: '{value:number|simpleCurrency}'
       } satisfies BaseTranslation;
     
       export default hi;
     
       // etc... all other languages that you wish to support
     

   • Pay attention to the syntax {value: <type>|<formatter} Let's break this syntax down into three parts:

     • {value} is a placeholder that will be populated with a value of a particular locale during runtime. As the locale changes, this field will be recomputed.

     • {value: <type>} is used to specify the data type of value e.g. number, Date etc.

     • {value: <type>|<formatter>} is used to specify a value with a particular data type along with a formatter to format value based on a particular locale.

   • As soon you update these locale dictionary (translation) files, typesafe-i18n will recompute all the files within the src/lib/i18n directory.

3. Detect the locale on the server side

   • Now that our library is installed and the locale dictionary is ready, it is time to create an entry point that will load the assets based on the user locale and initialize the library with a specific locale.

   • We can make use of detectors to detect the locale. Now this package exports multiple utilities to detect locale and I cannot cover every of those in this article, I'll advise readers to go through every method and pick the best one as per requirement.

   • In the below code snippet within the hooks.server.ts file, I am querying request headers using initAcceptLanguageHeaderDetector() to determine if the locale is present. If yes, then I call detectLocale(...) that returns the final locale to be used. If no locale is returned from headers, I query cookies for the same using initRequestCookiesDetector() If cookies don't return anything, I use the default locale i.e. en

       import type { Handle } from '@sveltejs/kit';
       import { loadLocaleAsync } from '$lib/i18n/i18n-util.async';
       import { setLocale } from '$lib/i18n/i18n-svelte';
       import { detectLocale } from '$lib/i18n/i18n-util';
       import {
         initAcceptLanguageHeaderDetector,
         initRequestCookiesDetector
       } from 'typesafe-i18n/detectors';
     
       export const handle: Handle = async ({ event, resolve }) => {
         let deafultLocale = 'en';
     
         const acceptLanguageHeaderDetector = initAcceptLanguageHeaderDetector(event.request);
         const localeFromHeaders = detectLocale(acceptLanguageHeaderDetector);
     
         if (!localeFromHeaders) {
           // if locale is not present in headers, try fetching it from cookies
           const requestCookiesDetector = initRequestCookiesDetector({
             cookies: event.cookies.get('lang') || ''
           });
           const localeFromCookies = detectLocale(requestCookiesDetector);
           if (localeFromCookies) {
             deafultLocale = localeFromCookies;
           } else {
             // add in cookes
             event.cookies.set('lang', deafultLocale, { path: '/' });
           }
         } else {
           deafultLocale = localeFromHeaders;
         }
         const locale = detectLocale(() => [deafultLocale]);
         // Load it
         await loadLocaleAsync(locale);
         // Set it
         setLocale(locale);
         // [OPTIONAL] set locale within locals property
         event.locals.locale = deafultLocale;
         return resolve(event);
       };
     

   • [OPTIONAL] If you see any typescript error in the line event.locals.locale = deafultLocale; then update the file src/app.d.ts to include locale property.

       // See https://kit.svelte.dev/docs/types#app
       // for information about these interfaces
       declare global {
         namespace App {
           // interface Error {}
           interface Locals {
             locale: string;
           }
           // interface PageData {}
           // interface Platform {}
         }
       }
     
       export {};
     

   • Once the locale is detected, we asynchronously load the corresponding translation messages for that particular locale using loadLocaleAsync(locale). Finally, we set the store setLocale(locale) to save the current locale across the server.

4. Detect the locale on the client side

   • Once we have the locale set up on the server side, it's time to load the locale on the client side as well. In the file +layout.ts, once the client-side is initialized, we detect the locale from session storage using sessionStorageDetector(), if the locale is not found we pick the locale from the user's browser configuration using navigatorDetector()

       import { browser } from '$app/environment';
       import type { LayoutLoad } from './$types';
       import { setLocale } from '$lib/i18n/i18n-svelte';
       import { detectLocale } from '$lib/i18n/i18n-util';
       import { loadLocaleAsync } from '$lib/i18n/i18n-util.async';
       import { sessionStorageDetector, navigatorDetector } from 'typesafe-i18n/detectors';
     
       export const load: LayoutLoad = async (event) => {
         if (browser) {
           const deafultLocale = 'en';
           const locale =
             detectLocale(sessionStorageDetector) || detectLocale(navigatorDetector) || deafultLocale;
     
           await loadLocaleAsync(locale);
           setLocale(locale);
         }
         return event.data;
       };
     

   • Similar to the server side, once the locale is detected, we asynchronously load the corresponding translation messages for that particular locale using loadLocaleAsync(locale). Finally, we set the store setLocale(locale) to save the current locale across the application.

Localizing Application

Now that we have configured the library and have the initial locale set, we're ready to start localizing our app. To do that we simply import $LL and pass message id in any component that needs to be translated.

Let's take a look at our locale file:

const en = {
  heading: 'Internationalization in SvelteKit',
  toggle_label: 'Select Locale',
  body_text: '... {date:Date|simpleDate} are {download:number|simpleNumber}.',
  ...
} satisfies BaseTranslation;

To set the main heading, the label for locale switching, we simply invoke $LL.<message-id>():

<h1>{$LL.heading()}</h1>
<span>{$LL.toggle_label()}: </span>

We can also pass additional parameters to $LL to populate values at runtime based on the current locale. For example, body_text message-id has two variables date of type Date and download of type number. We can pass the same variables as an object in $LL

<p>{$LL.body_text({
  download: 16711,
  date: new Date(2023, 6, 14, 0, 0, 0, 0)
})}</p>

Locale Switching

To switch between locales, we must first load the translations asynchronously for the new locale using loadLocaleAsync() and then update the store using setLocale()

<script lang="ts">
  import { browser } from '$app/environment';
  import { onDestroy, onMount } from 'svelte';
  import { LL, setLocale } from '$lib/i18n/i18n-svelte';
  import { loadLocaleAsync } from '$lib/i18n/i18n-util.async';

  let value: Locales = 'en';

  async function handleLocaleChange(event: Event) {
    event.preventDefault();
    value = event?.target?.value;
    await loadLocaleAsync(value);
    setLocale(value);
    sessionStorage.setItem('lang', value);
  }

  onMount(() => {
    const valueFromSession = sessionStorage.getItem('lang') || 'en';
    value = valueFromSession as Locales;
    sessionStorage.setItem('lang', valueFromSession);
  })

  onDestroy(() => {
    if (browser) {
      sessionStorage.removeItem('lang');
    }
  })
</script>

<div class="container__toggle">
  <span>{$LL.toggle_label()}: </span>
  <select {value} on:change={handleLocaleChange}>
    <option value="en">English</option>
    <option value="hi">Hindi</option>
    <option value="fr">French</option>
  </select>
</div>

One more point, in the last section, we detected locale in the +layout.ts file using sessionStorageDetector() and hence we must update the session storage to reflect the latest locale value. Also, the key used in session storage must be "lang" only, this is a requirement from typesafe-i18n.

Pluralization

The typesafe-i18n provides multiple ways in which we can pluralize a string. I would encourage readers to go through examples in their documentation as it would be not possible for me to cover them all.

For this example application, the syntax for pluralization used will be:

{{ zero | one | other }}

Consider the following message-id from our translation file:

awards: 'You have {{ not won any awards | won exactly ?? award | won ?? awards }}!',

This is how we are going to localize:

<span>{$LL.awards(randomNumber)}</span>

Now if we compare the message-id with the plural syntax that we have used, this is how things will break up:

• if randomNumber = 0, the output will be "not won any awards"

• if randomNumber = 1, the output will be "won exactly 1 award". Here ?? is the value of the argument that was passed to $LL()

• if randomNumber > 1, the output will be "won 5 awards" (assuming randomNumber = 5)

Formatting

Coming to the last section of the article where I will discuss formatting Date, Time, Number and Currency using inbuild Formatters.

The typesafe-i18n has one entire package dedicated to formatters. It enables us to use inbuild formatters as well as provides utilities to create custom formatters.

We will write all formatter utilities within the file src/lib/i8n/formatters.ts. We will use time(), date() and number() formatters from typesafe-i18n/formatters. These methods are wrappers around the Intl namespace.

The idea here is to create an object with the custom keys and export it and later while localizing, chain them with respective message-id.

As a first step, we export an object with our custom format options.

import type { FormattersInitializer } from 'typesafe-i18n';
import type { Locales, Formatters } from './i18n-types';
import { date, time, number } from 'typesafe-i18n/formatters';

export const initFormatters: FormattersInitializer<Locales, Formatters> = (locale: Locales) => {
  const formatters: Formatters = {
    simpleDate: date(locale, { year: 'numeric', month: 'long', day: 'numeric' }),
    simpleTime: time(locale, { hour: 'numeric', minute: 'numeric' }),
    simpleNumber: number(locale),
    simpleCurrency: number(locale, { style: 'currency', currency: getCurrencyCode(locale) })
  };

  return formatters;
};

function getCurrencyCode(value: Locales): string {
  switch (value) {
    case 'en':
      return 'USD';
    case 'hi':
      return 'INR';
    case 'fr':
      return 'EUR';
    default:
      return 'USD';
  }
}

Now we can use those keys to the chain with our message-id in our translation files.

const en = {
  ...
  time: '{value:Date|simpleTime}',
  date: '{value:Date|simpleDate}',
  currency: '{value:number|simpleCurrency}'
} satisfies BaseTranslation;

The last step is to just invoke $LL() and pass relevant arguments.

<span>Time: { $LL.time({ value: new Date() }) }</span>
<span>Date: { $LL.date({ value: new Date() }) }</span>
<span>Currency: { $LL.currency({ value: 16711 }) }</span>

Conclusion

Finally, we were able to localize our application using typesafe-i18n. You can find the code in the GitHub repo and link to the live demo.

This was the final article of three-part series to demonstrate i18n in SvelteKit. In the next article, I'll be comparing three libraries: svelte-i18n, sveltekit-i18n and typesafe-i18n.

References

• Official Documentation

• Util Functions

The sveltekit-i18n is a tiny library with no external dependencies, built for Svelte and SvelteKit. Key features include:

• SvelteKit ready.

• SSR support.

• Custom data sources: no matter if you are using local files or remote API to get your translations.

• Module-based: your translations are loaded for visited pages only (and only once!)

• Component-scoped translations: you can create multiple instances with custom definitions.

• Custom modifiers: you can modify the input data the way you need.

• TS support.

• No external dependencies.

Application Structure

Before we begin, I want to give you a detailed walkthrough of the application that we will be working on. You can find the code in the GitHub repository.

As we can see from the image, this will be a simple single-page application demonstrating i18n features like locale switching, pluralization and formatting.

In the next section, we will work on integrating the sveltekit-i18n library with SvelteKit.

Integration with SvelteKit

1. Install the sveltekit-i18n library

   • This first step is to install this library as a dependency in our SvelteKit project:

       pnpm i sveltekit-i18n
     

2. Define Locale Dictionary

   • Now that we have installed this library, it's time to identify the areas in our application that need localization. We then define the locale dictionaries within the src/lib/lang folder. A locale dictionary is a regular JSON object which contains message definitions for a certain language.

   • In our example application, I want five fields to be localized: The main heading, Lable for locale switching, Button label text, Body text (the paragraph) and Text for pluralization.

   • For the sake of this application, I will define dictionaries in three languages - English (en.json), Hindi (hi.json) and French (fr.json) within the src/lib/lang folder.

       // en.json
       {
         "heading": "Internationalization in SvelteKit",
         "toggle_label": "Select Locale",
         "button_label_0": "{{value:number}}",
         "button_label_1": "{{value:number}}",
         "button_label_2": "{{value:number}}",
         "body_text": "This is a small example to demonstrate i18n functionality in SvelteKit using sveltekit-i18n library. sveltekit-i18n is a tiny library with no external dependencies, built for Svelte and SvelteKit. It glues @sveltekit-i18n/base and @sveltekit-i18n/parser-default together to provide you the most straightforward sveltekit-i18n solution. Total number of npm downloads per week as of {{dateValue:date}} are {{download:number}}.",
         "awards":"You have {{award:gt; 0: {{award; 1:won exactly {{award}} award; default:won {{award}} awards}}; default:not won any awards}}!",
         "date": "{{val:date}}",
         "time": "Only 'time' formatter is not available, it must be DateTime formatter",
         "number": "{{value:currency}}"
       }
     
       // hi.json
       {
         "heading": "SvelteKit में अंतर्राष्ट्रीयकरण",
         "toggle_label": "भाषा चुने",
         "button_label_0": "{{value:number}}",
         "button_label_1": "{{value:number}}",
         "button_label_2": "{{value:number}}",
         "body_text": "यह sveltekit-i18n लाइब्रेरी का उपयोग करके SvelteKit में i18n कार्यक्षमता प्रदर्शित करने के लिए एक छोटा सा उदाहरण है। sveltekit-i18n एक छोटी लाइब्रेरी है जिसमें कोई बाहरी निर्भरता नहीं है, जो Svelte और SvelteKit के लिए बनाई गई है। यह आपको सबसे सीधा sveltekit-i18n समाधान प्रदान करने के लिए @sveltekit-i18n/base और @sveltekit-i18n/parser-default को एक साथ जोड़ता है। {{dateValue:date}} तक प्रति सप्ताह npm डाउनलोड की कुल संख्या {{download:number}} है|",
         "awards": "आपने {{award:gt; 0: {{award; 1:बिल्कुल {{award}} पुरस्कार जीता; default:{{award}} पुरस्कार जीते }}; default:कोई पुरस्कार नहीं जीता }} है|",
         "date": "{{val:date}}",
         "time": "केवल 'समय' फ़ॉर्मेटर उपलब्ध नहीं है, यह डेटटाइम फ़ॉर्मेटर होना चाहिए",
         "number": "{{value:currency}}"
       }
     
       // etc... all other languages that you wish to support
     

   • Pay attention to the syntax {{value: <type>}} Let's break this syntax down into two parts:

     • {value} is a placeholder that will be populated with a value of a particular locale during runtime. As the locale changes, this field will be recomputed.

     • {value: <type>} is used to specify the data type of value e.g. number, Date etc.

3. Defining entry point and mode for initializing the sveltekit-i18n library

   • Now that our library is installed and the locale dictionary is ready, it is time to create an entry point that will load the assets based on the user locale and initialize the library with a specific locale.

   • This entry point will be invoked as soon as the application bootstraps - once on the client side and once on the server side.

   • We will create the helper methods in the src/lib/translations.ts file.

       import i18n, { type Config } from 'sveltekit-i18n';
     
       const config: Config<> = {
         initLocale: 'en',
         loaders: [
           {
             locale: 'en',
             key: '',
             loader: async () => (await import('./lang/en.json')).default
           },
           {
             locale: 'hi',
             key: '',
             loader: async () => (await import('./lang/hi.json')).default
           },
           {
             locale: 'fr',
             key: '',
             loader: async () => (await import('./lang/fr.json')).default
           }
         ]
       };
     
       export const { t, loading, locales, locale, initialized, translations, loadTranslations } =
           new i18n(config);
     

   • The above code snippet loads the locale files (en.json, hi.json and fr.json) and registers them with the library. Now when the user switches the locale, the corresponding translation file will be used.

   • We also provide initLocale and the translations will be initialized immediately using this locale.

   • The other property is loaders. You can use loaders to define your asynchronous translation load. Each loader can include:

     • locale : locale (e.g. en, de).

     • key: represents the translation namespace. This key is used as a translation prefix so it should be module-unique. You can access your translation later using $t('key.yourTranslation'). It shouldn't include . (dot) character.

     • loader: is a function returning a Promise with translation data. You can use it to load files locally or fetch them from your API.

   • There are other options as well, but for the sake of simplicity, I won't be using them all. You can refer to them in the official documentation.

   • Finally, we export out few helper properties and methods that will be used throughout our application for localization.

     • $t: This is a readable store using which you can obtain your translations for a given translation key and interpolation variables. Example: $t('heading') or $t('body_text', { variable: 'value' })

     • $loading: A readable store that indicates whether translations are loading or not.

     • $locales: A readable store, containing all instance locales.

     • $initialized: This readable store returns true after the first translation is successfully initialized.

     • $translations: A readable store, containing all preprocessed translations.

     • loadTranslations(locale: string, route: string): This functions loads the translation based on provided locale and route.

   • There are other options as well, but for the sake of simplicity, I won't be using them all. You can refer to them in the official documentation.

4. Load the translations

   • We load the translations in the +layout.ts file.

       import type { LayoutLoad } from './$types';
       import { browser } from '$app/environment';
       import { loadTranslations } from '$lib/translations';
     
       export const load: LayoutLoad = async ({ url }) => {
         const { pathname } = url;
         const initLocale = getInitialLocale();
     
         await loadTranslations(initLocale, pathname);
     
         return { locale: initLocale, route: pathname };
       };
     
       function getInitialLocale(): string {
         if (browser) {
           try {
             return window.navigator.language.split('-')[0];
           }
           catch(e) {
             return 'en';
           }
         }
     
         return 'en';
       }
     

     For the sake of explanation, I am keeping things simple and limiting them to use the default language configured in the user's browser but you can extend this logic to set locale returned by parent layout or by any other means and set it accordingly!

   • One last step is to update the locale for the requests that are hitting our servers. We need to tell the server what language is being used. The easiest way to set the locale is in the hooks.server.ts file.

       import type { Handle } from '@sveltejs/kit';
       import { locale } from '$lib/translations';
     
       export const handle: Handle = async ({ event, resolve }) => {
         const lang = event.request.headers.get('accept-language')?.split(',')[0];
         if (lang) {
           locale.set(lang);
         }
         return resolve(event);
       };
     

   • In the above example, we intercept every request and look for a header with the key "accept-language" and set it as the current locale.

     For the sake of explanation, I am keeping things simple and limiting them to query headers only but you can extend this logic to query cookies and URL parameters to compute the locale and set it accordingly!

Localizing Application

Before we start with localization, it is important to ensure the default locale is set up and that we do have an initial set of key-value message pairs for translations. To do so we can make use of $initialized store.

import { t, initialized } from '$lib/translations';

<div class="content">
  {#if $initialized}
    <h1>{$t('heading')}</h1>
  {:else}
    <div>Locale initializing...</div>
  {/if}
</div>

Now that we have configured the library and have the initial locale set, we're ready to start localizing our app. To do that we simply import $t and pass the message-id in any component that needs to be translated.

<script>
  import { t } from '$lib/translations';
</script>

<h1>{$t('page_title')}</h1>

From the context of our application, let us revisit our translation file:

{
  "heading": "Internationalization in SvelteKit",
  "toggle_label": "Select Locale",
  "button_label_0": "{{value:number}}",
  "button_label_1": "{{value:number}}",
  "button_label_2": "{{value:number}}",
  "body_text": "This is a small example to demonstrate i18n functionality in SvelteKit using sveltekit-i18n library. sveltekit-i18n is a tiny library with no external dependencies, built for Svelte and SvelteKit. It glues @sveltekit-i18n/base and @sveltekit-i18n/parser-default together to provide you the most straightforward sveltekit-i18n solution. Total number of npm downloads per week as of {{dateValue:date}} are {{download:number}}.",
  "awards":"You have {{award:gt; 0: {{award; 1:won exactly {{award}} award; default:won {{award}} awards}}; default:not won any awards}}!",
  "date": "{{val:date}}",
  "time": "Only 'time' formatter is not available, it must be DateTime formatter",
  "number": "{{value:currency}}"
}

To set the main heading, the label for locale switching and the button label text, we simply invoke $t() and pass in the message-id as explained above:

<h1>{$t('heading')}</h1>
<span>{$t('toggle_label')}: </span>
<button>{$t('button_label_0')}</button>
<button>{$t('button_label_1')}</button>
<button>{$t('button_label_2')}</button>

We can also pass additional parameters to $t() and the syntax is:

$t(messageId: string, vars?: Record<any, any>): string

In the message-id, we had something like:

"body_text": "...  {{dateValue:date}} are {{download:number}}."

We can use the new syntax that we just saw and fill in the values of the dateValue and the download placeholders ({{ ... }}) dynamically:

<p>{$t('body_text',
  { dateValue: Date.UTC(2023, 6, 14, 0, 0, 0, 0), download: 3722 }
)}</p>

We can extend this snippet to format the Date as well

<p>{$t('body_text',
  { dateValue: Date.UTC(2023, 6, 14, 0, 0, 0, 0), download: 3722 },
  { date: { year: "numeric", month: "long", day: "numeric" }}
)}</p>

Note that ;, :, { and } characters are used as placeholder identifiers and separators, so you shouldn't use them within your definition keys and values. You should use their escaped form instead (\\;, \\:, \\{ or \\}).

Type Safety in Translations using Modifiers

Let's revisit the last example from our translation file and observe the syntax:

"body_text": "...  {{dateValue:date}} are {{download:number}}."

The sveltekit-i18n allows us to define the type of value we are expecting at runtime using modifiers.

The Modifiers don't represent the payload value directly, but they can use it for further calculations. The syntax for modifiers is:

{{ placeholder: modifier }} 
Example: {{dateValue:date}}, {{download:number}}

The sveltekit-i18n provides multiple inbuild modifiers as well as the flexibility to create custom modifiers. I won't be able to cover all modifiers in this article, so I'll recommend going through official documentation for more examples and use cases.

Locale Switching

To switch between locales, we make use of the $locale store variable. The locale store defines what is the current locale.

<script lang="ts">
  import { locale } from '$lib/translations';

  let value: string = 'en';

  function handleLocaleChange(event: Event) {
    event.preventDefault();
    value = event?.target?.value;
    $locale = value;
  }
</script>

<select {value} on:change={handleLocaleChange}>
  <option value="en" selected>English</option>
  <option value="hi">Hindi</option>
  <option value="fr">French</option>
</select>

We can get the list of locales available in our application using the $locales

<script>
  import { locales } from '$lib/translations';
</script>

{#each $locales as locale, i}
  <option value={locale}>{locale.toUpperCase()}</option>
{/each}
<!-- $locales = ['en', 'hi', 'fr'] -->

Pluralization

Let's start with Pluralization. Consider the following message-id:

"awards":"You have {{award:gt; 0: {{award; 1:won exactly {{award}} award; default:won {{award}} awards}}; default:not won any awards}}!"

The syntax for pluralizing a string in the sveltekit-i18n is as follows:

{{ variable:modifier; 0:{{ variable }} {{ variable; 1: some-message; default: some-message }}; default:some-default-message; }}

While pluralizing a string we make use of modifiers. We compare the input value against the modifier and execute conditions and display the message. If none of the conditions satisfies, we display a default value!

Concerning our application example, consider the following invocation:

<span>{$t('awards', { award: randomNumber })}</span>

In the given example, we make use of gt modifier (input value is greater than the value in your definition). Statement {{ award:gt; ... }} means the input variable award value should be compared and if that is greater than 0, display a specific message else display a default message.

• if award = 1, the modifier will execute the condition within 1: some-message and output will be "You have won exactly 1 award". Here {{award}} specifies the value of the variable.

• if award > 1, the modifier will execute the condition within default: some-message and output will be "You have won 5 awards" (assuming award = 5)

• if award = 0, since we have used gt modifier, it will always execute certain conditions if the value > 0 else will execute default: some-default-message and output will be "You have not won any awards". Since we are using gt modifier, we can omit the condition post 0: i.e. 0:{{ ... }} can be 0: as it will always be ignored!

Parsers

The Parsers are responsible for interpreting and translating messages. The sveltekit-i18n comes with two parsers: The default parser and the ICU parser.

Until this point in the article, we have been using the default parser. However, we can adapt the ICU parser as well. To do this, we have to first install the dependency of the ICU parser

pnpm i @sveltekit-i18n/parser-icu

We need to make a few changes in the src/lib/translations.ts file

import i18n from 'sveltekit-i18n';
import parser from '@sveltekit-i18n/parser-icu';
import type { Config } from '@sveltekit-i18n/parser-icu';

const config: Config<Partial<Params>> = {
  initLocale: 'en',
  parser: parser(),
  loaders: [ ... ]
}

Let's walk through these changes:

• Update import of type Config from sveltekit-i18n to @sveltekit-i18n/parser-icu

• Import parser from @sveltekit-i18n/parser-icu

• Add an instance of the parser within the existing configuration.

That's it now we are ready to use ICU syntax for formatting and pluralization.

NOTE: We can either use the ICU parser or the default parser and cannot mix them!

Formatting

In this section, I will discuss formatting Date and Currency using inbuild modifiers.

The sveltekit-i18n provides inbuild modifiers as well as provisions to create a custom modifier. For the sake of simplicity, I will only be explaining how to use inbuild modifiers. You can refer to this guide on how to create custom modifiers.

The sveltekit-i18n provides the date and currency modifiers that we can use to format data accordingly. The syntax for formatting is:

<p>{ $t('message-id', { variable: value }, { date: { date-format-option } }) }</p>
<p>{ $t('message-id', { variable: value }, { currency: { currency-format-option } }) }</p>

Coming back to our example application, we can now format the date and currency:

// our translation file
{
  ...,
  "date": "{{val:date}}",
  "number": "{{value:currency}}"
}

<div class="container__content__formatter">
  <span><strong>Date: </strong>{$t('date', { val: new Date() }, { date: { year: "numeric", month: "long", day: "numeric" } })}</span>
  <span><strong>Currency: </strong>{$t('number', { value: 3722 }, { currency: { style: "currency", currency: "INR" } })}</span>
</div>

Miscellaneous

The one last thing I want to cover before concluding this article is type binding the translation configuration. If you're following this article you will see typescript errors within $t() in +page.svelte i.e. the file that we have used for localization.

To correct this, we must define all the variables used for translations within the src/lib/translations.ts file. Refer to the en.json translation file, we make use of 5 variables. We can create an interface out of them and pass it to our configuration object:

interface Params {
  dateValue: number;
  value: number;
  download: number;
  award: number;
  val: Date;
}

const config: Config<Partial<Params>> = {
  initLocale: 'en',
  ...
}

Conclusion

Finally, we were able to localize our application using sveltekit-i18n. You can find the code in the GitHub repo and link to the live demo.

This was the second article of three-part series to demonstrate i18n in SvelteKit. In the next article, I'll be explaining i18n in SvelteKit with typesafe-i18n.

References

• Core properties and methods

• Base properties and methods

• Default Parser

• ICU Parser

• Multiple working project examples

svelte-i18n helps you localize your app using the reactive tools Svelte provides. By using stores to keep track of the current locale, dictionary of messages and format messages, it keeps everything neat, in sync and easy to use on svelte files.

Under the hood, svelte-i18n uses formatjs for localizing messages. It allows svelte-i18n to support the ICU message syntax.

Application Structure

Before we begin, I want to give you a detailed walkthrough of the application that we will be working on. You can find the code in the GitHub repository.

As we can see from the image, this will be a simple single-page application demonstrating i18n features like locale switching, pluralization and formatting.

In the next section, we will work on integrating the svelte-i18n library with SvelteKit.

Integration with SvelteKit

1. Install svelte-i18n library

   • This first step is to install this library as a dependency in our SvelteKit project:

       pnpm i svelte-i18n
     

   • [OPTIONAL] If you're using VSCode and want to have your messages previewed alongside your components, check out the i18n-ally and their FAQ to see how to set it up.

2. Define Locale Dictionary

   • Now that we have installed this library, it's time to identify the areas in our application that need localization. We then define the locale dictionaries within the src/lib/lang folder. A locale dictionary is a regular JSON object which contains message definitions for a certain language.

   • In our example application, I want five fields to be localized: The main heading, Lable for locale switching, Button label text, Body text (the paragraph) and Text for pluralization.

   • We also have the requirement for formatting date, time and currency but for that, we don't need a special entry in the locale dictionary. We will implement the same using inbuild methods provided by the svelte-i18n for formatting.

   • For the sake of this application, I will define dictionaries in three languages - English (en.json), Hindi (hi.json) and French (fr.json) within the src/lib/lang folder.

       // en.json
       {
         "heading": "Internationalization in SvelteKit",
         "toggle_label": "Select Locale",
         "button_label": "Generate Awards",
         "body_text": "This is a small example to demonstrate i18n functionality in SvelteKit using svelte-i18n library. svelte-i18n helps you localize your app using the reactive tools Svelte provides. By using stores to keep track of the current locale, dictionary of messages and to format messages, we keep everything neat, in sync and easy to use on your svelte files. Total number of npm downloads per week as of {date} are {download}.",
         "awards": "You have {n, plural, =0 { not won any awards } one { won exactly # award } other { won # awards }}!"
       }
     
       // hi.json
       {
         "heading": "SvelteKit में अंतर्राष्ट्रीयकरण",
         "toggle_label": "भाषा चुने",
         "button_label": "पुरस्कार उत्पन्न करें",
         "body_text": "svelte-i18n लाइब्रेरी का उपयोग करके SvelteKit में i18n कार्यक्षमता प्रदर्शित करने के लिए यह एक छोटा सा उदाहरण है। svelte-i18n, Svelte द्वारा प्रदान किए गए प्रतिक्रियाशील टूल का उपयोग करके आपके ऐप को स्थानीयकृत करने में आपकी सहायता करता है। वर्तमान स्थान, संदेशों के शब्दकोश पर नज़र रखने और संदेशों को प्रारूपित करने के लिए स्टोर का उपयोग करके, हम सब कुछ साफ-सुथरा, सिंक में रखते हैं और आपकी विस्तृत फ़ाइलों पर उपयोग में आसान रखते हैं। {date} तक प्रति सप्ताह NPM डाउनलोड की कुल संख्या {download} है|",
         "awards": "आपने {n, plural, =0 { कोई पुरस्कार नहीं जीता } one { बिल्कुल # पुरस्कार जीता } other { # पुरस्कार जीते }} है|"
       }
     
       // etc... all other languages that you wish to support
     

   • Pay attention to the syntax {value} Here {value} is a placeholder that will be populated with a value of a particular locale during runtime. As the locale changes, this field will be recomputed.

3. Defining entry point and mode for initializing svelte-i18n library

   • Now that our library is installed and the locale dictionary is ready, it is time to create an entry point that will load the assets based on the user locale and initialize the library with a specific locale.

   • This entry point will be invoked as soon as the application bootstraps - once on the client side and once on the server side.

   • We will create the helper methods in the src/lib/i18n.ts file.

       import { browser } from '$app/environment';
       import { init, register } from 'svelte-i18n';
     
       const defaultLocale = 'en';
     
       register('en', () => import('./lang/en.json'));
       register('hi', () => import('./lang/hi.json'));
       register('fr', () => import('./lang/fr.json'));
     
       init({
         fallbackLocale: defaultLocale,
         initialLocale: browser ? window.navigator.language : defaultLocale
       });
     

   • The above code snippet loads the locale files (en.json, hi.json and fr.json) and registers them with the library. Now when the user switches the locale, the corresponding translation file will be used. We also provide initialLocale and a fallbackLocale. Please note that the fallbackLocale is always loaded, independent of the current locale, since only some messages can be missing. Let's go through each method in detail.

   • init() is responsible for configuring some of the library behaviors such as the global fallback and initial locales. Must be called before setting a locale and displaying your view.

   • register() adds a new dictionary of messages to a certain locale i.e. it will register your local dictionaries (en.json etc.) and get all translation keys ready for you.

   • Now there are two ways to register/add dictionaries to your locale:

     • the synchronous way using addMessages() that imports your locale JSON files

     • the asynchronous way using register() The asynchronous way is a more performant way to load your dictionaries. This way, only the files registered to the current locale will be loaded. As the locale value changes, it will automatically load the registered loaders for the new locale.

4. Initialize the library on the server side

   • The rule is to initialize the svelte-i18n library with a locale as soon as the application boots up. For SSR we need to tell the server what language is being used. This could use cookies or the accept-language header for example. The easiest way to set the locale is in the server hook.

       import type { Handle } from '@sveltejs/kit';
       import { locale } from 'svelte-i18n';
     
       export const handle: Handle = async ({ event, resolve }) => {
         const lang = event.request.headers.get('accept-language')?.split(',')[0];
         if (lang) {
           locale.set(lang);
         }
         return resolve(event);
       };
     

   • In the above example, we intercept every request and look for a header with the key "accept-language" and set it as the current locale.

     For the sake of explanation, I am keeping things simple and limiting them to query headers only but you can extend this logic to query cookies and URL parameters to compute the locale and set it accordingly!

5. Initialize the library on the client side

   • Once the backend is all wired up, we will now proceed with client-side initialization in the +layout.ts

       import { browser } from '$app/environment';
       import '$lib/i18n'; // Import to initialize. Very Important!
       import { locale, waitLocale } from 'svelte-i18n';
       import type { LayoutLoad } from './$types';
     
       export const load: LayoutLoad = async () => {
         if (browser) {
           locale.set(window.navigator.language);
         }
         await waitLocale();
       };
     

   • In the above code example, as soon as the browser is initialized, we set locale to the default language configured in the user's browser.

   • After that we invoke waitLocale() This method executes the queue of the locale. If the queue isn't resolved yet, the same promise is returned.

     For the sake of explanation, I am keeping things simple and limiting them to use the default language configured in the user's browser but you can extend this logic to set locale returned by parent layout or by any other means and set it accordingly!

Localizing Application

Before we start with localization, it is important to ensure the default locale is set up and that we do have an initial set of key-value message pairs for translations. To do so we can implement a derived store variable in the src/lib/i18n.ts file and react to it accordingly:

import { derived } from 'svelte/store';
import { locale } from 'svelte-i18n';

export const isLocaleLoaded = derived(locale, ($locale) => typeof $locale === 'string');

<div class="content">
  {#if $isLocaleLoaded}
    <h1>{$_('heading')}</h1>
  {:else}
    <div>Locale initializing...</div>
  {/if}
</div>

Now that we have configured the library and have the initial locale set, we're ready to start localizing our app. To do that we simply import $_ and pass message id in any component that needs to be translated.

The $_ is the implementation of format() from formnatjs. To format a message is as simple as executing the $_ method and passing the message-id:

<script>
  import { _ } from 'svelte-i18n';
</script>

<h1>{$_('page_title')}</h1>

It has two aliases $t and $format. So we can do any of the following:

<h1>{$_('page_title')}</h1>
<h1>{$t('page_title')}</h1>
<h1>{$format('page_title')}</h1>

From the context of our application, let us revisit our translation file:

{
  "heading": "Internationalization in SvelteKit",
  "toggle_label": "Select Locale",
  "button_label": "Generate Awards",
  "body_text": "This is a small example to demonstrate i18n functionality in SvelteKit using svelte-i18n library. svelte-i18n helps you localize your app using the reactive tools Svelte provides. By using stores to keep track of the current locale, dictionary of messages and to format messages, we keep everything neat, in sync and easy to use on your svelte files. Total number of npm downloads per week as of {date} are {download}.",
  "awards": "..."
}

To set the main heading, the label for locale switching and the button label text, we simply invoke $_() and pass in the message-id as explained above:

<h1>{$_('heading')}</h1>
<span>{$_('toggle_label')}: </span>
<button>{$_('button_label')}</button>

We can also pass additional parameters to $_() and the syntax is:

$_(messageId: string, options?: MessageObject): string
$_(options: MessageObject): string

interface MessageObject {
  id?: string;
  locale?: string;
  format?: string;
  default?: string;
  values?: Record<string, string | number | Date>;
}

In the message-id, we had something like:

"body_text": "...  {date} are {download}."

We can use the new syntax that we just saw and fill in the values of the date and the download placeholders ({ ... }) dynamically:

<p>{$_('body_text', {
  values: {
    download: $number(30242),
    date: $date(Date.UTC(2023, 6, 14, 0, 0, 0, 0), { year: "numeric", month: "long", day: "numeric" })
  }
})}</p>

For now, ignore $number() and $date() I'll discuss them in detail, in the following section about the Formatters. For now, switching to the next section where we will learn how to switch between locales!

Locale Switching

To switch between locales, we make use of the $locale store variable.

The locale store defines what is the current locale. When its value is changed, before updating the actual stored value, svelte-i18n sees if there are any message loaders registered for the new locale:

• If yes, changing the locale is an async operation.

• If no, the locale's dictionary is fully loaded and changing the locale is a sync operation.

<script lang="ts">
  import { locale } from 'svelte-i18n';

  let value: string = 'en';

  function handleLocaleChange(event: Event) {
    event.preventDefault();
    value = event?.target?.value;
    $locale = value;
  }
</script>

<select {value} on:change={handleLocaleChange}>
  <option value="en" selected>English</option>
  <option value="hi">Hindi</option>
  <option value="fr">French</option>
</select>

We can get the list of locales available in our application using the $locales

{#each $locales as locale, i}
  <option value={locale}>{locale.toUpperCase()}</option>
{/each}
<!-- $locales = ['en', 'hi', 'fr'] -->

While changing the locales, we can also make use of the $loading store that can detect if the app is currently fetching any enqueued message definitions.

<script>
  import { isLoading } from 'svelte-i18n'
</script>

{#if $isLoading}
  Please wait...
{:else}
  <Nav />
  <Main />
{/if}

We can also check the list of all messages with a particular locale using $dictionary The $dictionary store is responsible for holding all loaded message definitions for each locale.

<script>
  import { dictionary } from 'svelte-i18n'

  console.log($dictionary); // { en: {...}, hi: {...}, fr: {...} }
</script>

Pluralization

As I have mentioned before that svelte-i18n uses ICU syntax, and we can leverage that to implement Pluralization.

Consider the following message-id:

"awards": "You have {n, plural, =0 { not won any awards } one { won exactly # award } other { won # awards }}!"

If we break that into a simple format and compare it with ICU syntax { key, plural, matches }

{ n, plural, =0 { some-message } one { some-message # } other { some-message # } }

Here n is the key that will be passed via $_() followed by a plural keyword. matches resemble the rest of the conditions where if:

• n=0 we can output custom messages within {...} Example: =0 { not won any awards }

• n=1 for plural category one we can output custom messages within {...} Here # represents the value of n which will be 1 in this case. Example: one { won exactly # award }

• n=any-number for plural category other we can output custom messages within {...} Example: other { won # awards }

Coming back to our example:

<span>{$_('awards', { values: { n: randomNumber } })}</span>

• if n = 0, output = You have not won any awards!

• if n = 1, output = You have won exactly 1 award!

• if n = 10, output = You have won 10 awards!

Formatting

Coming to the last section of the article where I will discuss formatting Date, Time, Number and Currency using inbuild Formatters.

svelte-i18n provides inbuild formatters as well as provisions to create a custom formatter. For the sake of simplicity, I will only be explaining how to use inbuild formatters. You can refer to this guide on how to create custom formatters.

svelte-i18n provides $time(), $date() and $number() formatters that we can use to format data accordingly.

The following are the available Formats:

Number:

• currency: { style: 'currency' }

• percent: { style: 'percent' }

• scientific: { notation: 'scientific' }

• engineering: { notation: 'engineering' }

• compactLong: { notation: 'compact', compactDisplay: 'long' }

• compactShort: { notation: 'compact', compactDisplay: 'short' }

Date:

• short: { month: 'numeric', day: 'numeric', year: '2-digit' }

• medium: { month: 'short', day: 'numeric', year: 'numeric' }

• long: { month: 'long', day: 'numeric', year: 'numeric' }

• full: { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }

Time:

• short: { hour: 'numeric', minute: 'numeric' }

• medium: { hour: 'numeric', minute: 'numeric', second: 'numeric' }

• long: { hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' }

• full: { hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' }

Coming back to our example application, we can now format date, time and currency:

<script lang="ts">
  import { time, date, number } from 'svelte-i18n';
</script>

<span>Time: { $time(new Date(), { hour: "numeric", minute: "numeric", second: "numeric" }) }</span>
<span>Date: { $date(new Date(), { year: "numeric", month: "long", day: "numeric" }) }</span>
<span>Currency: { $number(2, { style: "currency", currency: "INR" }) }</span>
<span>Number: { $number(2) }</span>

Conclusion

Finally, we were able to localize our application using svelte-i18n. You can find the code in the GitHub repo and link to the live demo.

This was the first article of three-part series to demonstrate i18n in SvelteKit. In the next article, I'll be explaining i18n in SvelteKit with sveltekit-i18n library.

References

• List of Methods in svelte-i18n

• CLI commands reference

• Formatters