@yourstruly-de/tuic-amplify-storage

TUIC Mixed Amplify Auth Storage

A specialized AWS Amplify Auth Storage solution that splits Cognito Token storage between cookies and local storage based on the token type.

Why?

This library was developed as an improved alternative to Cognito's default cookie storage approach. With Cognito's standard method, the generated cookies tend to grow substantially in size, often approaching the limits imposed by servers. Such large cookies can impact performance and lead to unexpected issues.

TUIC Mixed Amplify Auth Storage addresses this challenge by partitioning the data storage:

• Cookies: Primarily reserved for the refresh token and the last authenticated user values. Storing these crucial pieces of data in cookies ensures accessibility even when local storage might not be available, such as during server-side rendering or in specific browser scenarios.
• Local Storage: Used for storing all other values. Local storage, being client-side and not transmitted with every HTTP request, is an ideal place for bulkier data, ensuring the website's cookies remain lean.

By adopting this split-storage approach, websites can significantly reduce both the number and the overall size of cookies, leading to optimized server communication and better overall site performance.

Installation

Installing the library directly from npm:

$ npm i -S @yourstruly-de/tuic-amplify-storage

Usage

After installation, make sure to properly configure the library and supply it to amplify's auth storage config.

const cookieHeaders = {};

// Refer to `Configuration Options` for comprehensive configuration details.
const mixedStore = createMixedStore({
  debug: false,

  cookies: {
    // Provide the relevant cookie headers, typically `request.cookies` or `request.headers.cookie`.
    // Without these headers, the store won't be able to read the cookies, affecting its functionality.
    headers: cookieHeaders,
    setOptions: {
      domain: '.example.com',
      maxAge: 30 * 24 * 60 * 60, // 30 days
      path: '/',
    },
  },
});

const authConfig = {
  identityPoolId: '<your-id>',
  region: '<your-region>',
  userPoolId: '<your-user-pool-id>',
  userPoolWebClientId: '<your-user-pool-web-client-id>',
  // ... other configurations

  storage: mixedStore,
};

Amplify.configure({
  Auth: {
    ...authConfig,
  },
  ssr: true,
});

Configuration Options

Delve into the full set of configuration options.

• debug (Optional)

  • Type: boolean
  • Description: Indicates if debugging is enabled. If true, additional logging and diagnostics related to store operations may be emitted.

• cookies (Optional)

  • Type: CreateCookieStoreConfig

  • Description: Configuration options for the cookie store.

  • headers (Optional)

    • Type: CookieHeaders
    • Description: Headers related to the cookie. It can be a string or an object mapping keys to string values.

  • setOptions (Optional)

    • Type: CookieSetOptions

    • Description: Configuration options when setting a cookie.

    • path (Optional)

      • Description: Specifies the path for the cookie.

    • expires (Optional)

      • Description: Sets the expiry date for the cookie.

    • maxAge (Optional)

      • Description: Sets the maximum age in seconds for the cookie.

    • domain (Optional)

      • Description: Specifies the domain for the cookie.

    • secure (Optional)

      • Description: Indicates if the cookie transmission requires a secure protocol.

    • httpOnly (Optional)

      • Description: Specifies if the cookie is HTTP only.

    • sameSite (Optional)

      • Description: Sets the SameSite attribute for the cookie. Can be true, false, 'none', 'lax', or 'strict'.

    • encode (Optional)

      • Description: A function to encode the value of the cookie.

• storeFactories (Optional)

  • Type: Partial<Record<StoreName, () => Store>>
  • Description: An object mapping store names to factory functions that create stores. This allows for custom implementations or configurations for specific types of stores.

Usage in Browser

If you need to use the MixedStore directly in a browser where you don't have access to a bundler, load browser.bundle.min.js in your script tag:

<script src="node_modules/@yourstruly-de/tuic-amplify-storage/dist/browser.bundle.min.js"></script>

<script>
  const mixedStore = window._yourstruly_de_tuic_amplify_storage.createMixedStore({
    debug: false,
    cookies: {
      setOptions: {
        domain: '.example.com',
        maxAge: 30 * 24 * 60 * 60, // 30 days
        path: '/',
      },
    },
  });

  const authConfig = {
    identityPoolId: '<your-id>',
    region: '<your-region>',
    userPoolId: '<your-user-pool-id>',
    userPoolWebClientId: '<your-user-pool-web-client-id>',
    // ... other configurations

    storage: mixedStore,
  };

  Amplify.configure({
    Auth: {
      ...authConfig,
    },
  });
</script>