Astro Session Driver API

Astro sessions allow you to share data between requests for on-demand rendered pages. They require an Astro Session Driver to store session data.

Built-in drivers

Astro exports built-in session drivers from astro/config:

import { sessionDrivers } from 'astro/config'

Any unstorage driver can be used, for example:

astro.config.mjs

import { defineConfig, sessionDrivers } from 'astro/config'

export default defineConfig({
    session: {
        driver: sessionDrivers.redis({
            url: process.env.REDIS_URL
        }),
    }
})

Note

Some drivers may need extra packages to be installed. Some drivers may also require environment variables or credentials to be set. See the Unstorage documentation for more information.

Building a session driver

A session driver is made of two parts:

• The driver config, which lets Astro know what implementation to use at runtime and what config to forward
• The driver implementation, which handles the storage logic at runtime

The session driver config

A SessionDriverConfig is an object containing a required runtime entrypoint and an optional config. The preferred method for implementing it is to export a function that returns this object and takes the configuration as an optional parameter.

The following example defines a memory driver config:

driver/config.ts

import type { SessionDriverConfig } from 'astro'

export interface Config {
    max?: number;
}

export function memoryDriver(config: Config = {}): SessionDriverConfig {
    return {
        entrypoint: new URL('./runtime.js', import.meta.url),
        config,
    }
}

It is then registered in the Astro config:

astro.config.ts

import { defineConfig } from 'astro/config'
import { memoryDriver } from './driver/config'

export default defineConfig({
    session: {
        driver: memoryDriver({
            max: 500
        })
    }
})

entrypoint

Type: string | URL

Hinzugefügt in: astro@6.0.0

Defines the entrypoint for the driver implementation.

config

Type: Record<string, any> | undefined

Hinzugefügt in: astro@6.0.0

Defines the serializable config passed to driver implementation at runtime.

The session driver implementation

A SessionDriver is an object responsible for storing, retrieving and deleting data when using sessions at runtime (e.g. context.session.set()). You can implement it in your session driver module by exporting a default function that takes the driver config as parameter.

The following example implements a memory driver:

driver/runtime.ts

import type { SessionDriver } from 'astro'
import type { Config } from './config'
import { LRUCache } from 'lru-cache'

export default function(config: Config): SessionDriver {
    const cache = new LRUCache({ max: config.max })
    return {
        setItem: async (key, value) => {
            cache.set(key, value)
        },
        getItem: async (key) => {
            return cache.get(key)
        },
        removeItem: async (key) => {
            cache.delete(key)
        },
    }
}

setItem()

Type: (key: string, value: any) => Promise<void>

Hinzugefügt in: astro@6.0.0

Defines a function that sets session data by key.

getItem()

Type: (key: string) => Promise<any>

Hinzugefügt in: astro@6.0.0

Defines a function that retrieves session data by key.

removeItem()

Type: (key: string) => Promise<void>

Hinzugefügt in: astro@6.0.0

Defines a function that removes session data by key.

Unstorage compatibility

The built-in drivers provide the same drivers as Unstorage. When you need greater customization, you can build your own driver based on any Unstorage driver.

Install the unstorage package and pass the driver specifier as the entrypoint:

driver/config.ts

import type { SessionDriverConfig } from "astro";

export function configuredRedisDriver(): SessionDriverConfig {
  return {
    entrypoint: "unstorage/drivers/redis",
    config: {
      tls: true,
    },
  };
}

You can also import an Unstorage driver and wrap it in your own implementation. This can be useful if you want to add extra logic to the driver or override the configuration at runtime.

The following example implements a Redis driver with a default ttl of 7 days:

driver/runtime.ts

import type { SessionDriver } from "astro";
import redisDriver, { type RedisOptions } from "unstorage/drivers/redis";

export default function (config: RedisOptions): SessionDriver {
  const driver = redisDriver({
    ...config,
    ttl: config.ttl ?? 60 * 60 * 24 * 7, // default to 7 days
  });

  return {
    async getItem(key) {
      return await driver.getItem(key);
    },
    async setItem(key, value) {
      await driver.setItem?.(key, value, {});
    },
    async removeItem(key) {
      await driver.removeItem?.(key, {});
    },
  };
}