Sveltekit Session

escendit

SvelteKit Session Provider

@escendit/sveltekit-session

[!IMPORTANT] The repository has been moved to: https://github.com/escendit/sveltekit-extensions

Lightweight session middleware for SvelteKit. It issues and persists a secure session ID, stores minimal session data in a pluggable store, and exposes the session on event.locals.

Works out of the box with an in‑memory store for development, and includes a Redis store for production when running on Bun.

Features

Simple SessionMiddleware you add to hooks.server.ts
Pluggable session storage via ISessionStore (in‑memory and Redis implementations included)
Secure cookie with httpOnly, secure, sameSite: 'strict', priority: 'high'
Session ID generation using Node crypto and base58 encoding by default
Sensible defaults with runtime validation
Explicit behavior for first request and mutation safety

Installation

npm i @escendit/sveltekit-session
# or
pnpm add @escendit/sveltekit-session
# or
bun add @escendit/sveltekit-session

Peer dependencies:

svelte@^5
@sveltejs/kit@^2 (app peer, used by you)

Notes:

The default in‑memory store works everywhere (Node/Bun) and is great for local development.
The provided RedisSessionStore uses Bun's built‑in Redis client. If you want Redis, run your app with Bun.

Quick start

Add the middleware to your src/hooks.server.ts:

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import type { Handle } from '@sveltejs/kit';
import { SessionMiddleware } from '@escendit/sveltekit-session';

export const handle: Handle = sequence(
  SessionMiddleware({
    cookie: 'session.id',
    expireIn: 60 * 60 * 24 // 1 day (seconds)
  })
);

Access the session in your endpoints or load functions via event.locals:

// src/routes/+page.server.ts
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals }) => {
  // Available on locals:
  // - locals.store: ISessionStore
  // - locals.hasher: ISessionHasher
  // - locals.generator: ISessionGenerator
  // - locals.sessionId: string (present once a session exists)
  // - locals.session: { identity: unknown | null; created: string | null }
  return {
    sessionId: locals.sessionId,
    session: locals.session
  };
};

Locals interface (for reference):

// src/app.d.ts
import type { ISessionGenerator, ISessionHasher, ISessionStore } from '@escendit/sveltekit-session';

declare global {
  namespace App {
    interface Locals {
      store: ISessionStore;
      hasher: ISessionHasher;
      generator: ISessionGenerator;
      sessionId: string;
      session: any;
    }
  }
}
export {};

How it works

On each request the middleware checks for the configured session cookie.
If a valid session exists in the store, it populates:
- event.locals.sessionId
- event.locals.session = { identity: any | null, created: string | null }
- Always available: event.locals.store, event.locals.hasher, event.locals.generator (from middleware config)
If there is no valid session yet:
- It generates a new random ID, stores minimal fields (identity=null, created=timestamp) and sets an expiry on the store entry.
- It sets a secure cookie and Cache-Control: no-store header.
- For GET requests, it performs a 303 redirect to the same URL so the browser will include the cookie on the next request.
- For non‑GET requests without an existing session, it returns 405 to ensure the client establishes a session via GET first.

Configuration

All options are optional; the following are the defaults applied internally:

cookie: "session.id"
expireIn: 86400 (seconds)
size: 128 (entropy bytes for ID generation)
sessionStore: new InMemorySessionStore()
sessionHasher: new DefaultSessionHasher() (encodes to base58)
sessionGenerator: new DefaultSessionGenerator() (uses crypto.randomBytes)

Example with custom options:

import { SessionMiddleware, InMemorySessionStore } from '@escendit/sveltekit-session';

export const handle = sequence(
  SessionMiddleware({
    cookie: 'sid',
    expireIn: 60 * 10, // 10 minutes
    size: 256,
    sessionStore: new InMemorySessionStore()
  })
);

Setting identity or other session fields

This library keeps the session store minimal by design. If you want to associate an identity (e.g., after login), create and reuse the same store instance you pass into the middleware.

// src/lib/session-store.ts
import { InMemorySessionStore } from '@escendit/sveltekit-session';
export const sessionStore = new InMemorySessionStore();

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { SessionMiddleware } from '@escendit/sveltekit-session';
import { sessionStore } from '$lib/session-store';

export const handle = sequence(
  SessionMiddleware({ sessionStore })
);

// src/routes/login/+page.server.ts (example)
import type { Actions } from './$types';
import { sessionStore } from '$lib/session-store';

export const actions: Actions = {
  default: async ({ locals }) => {
    const sessionKey = `session:${locals.sessionId}`;
    await sessionStore.setMultiple(sessionKey, [
      'identity', JSON.stringify({ userId: '123', roles: ['user'] })
    ]);
    // Optionally refresh TTL
    // await sessionStore.expire(sessionKey, 60 * 60 * 24);
    return { success: true };
  }
};

The middleware will deserialize the identity JSON on subsequent requests and expose it on locals.session.identity.

Using Redis (Bun runtime)

The package includes a Redis store that uses Bun's built‑in Redis client.

// src/lib/session-store.ts
import { RedisSessionStore } from '@escendit/sveltekit-session';
export const sessionStore = new RedisSessionStore();

// src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks';
import { SessionMiddleware } from '@escendit/sveltekit-session';
import { sessionStore } from '$lib/session-store';

export const handle = sequence(
  SessionMiddleware({ sessionStore, cookie: 'sid', expireIn: 60 * 60 })
);

Requirements:

Run your SvelteKit server with Bun (bun run dev / bun run start).
Ensure your Redis instance is reachable per Bun's configuration. See Bun docs for bun:redis.

API

Package exports:

SessionMiddleware(sessionConfig?: SessionConfig): Handle
type SessionConfig — public configuration shape
type ISessionStore — storage interface with exists, expire, getSingle, setSingle, getMultiple, setMultiple
type ISessionHasher — hash(buffer: Uint8Array): string
type ISessionGenerator — generate(size: number): Uint8Array
InMemorySessionStore — default dev store
RedisSessionStore — Bun Redis store
DefaultSessionGenerator — uses Node crypto.randomBytes
DefaultSessionHasher — base58 encoding

Scripts

Common scripts from package.json:

dev — start vite dev server (Bun)
build — build library and package
preview — preview built app
check / check:watch — typecheck with svelte-check
format / lint — Prettier
test — run unit tests (Vitest)

Notes

Cookies are set with secure: true; when testing locally on http://localhost, ensure your browser still handles the cookie as expected or use HTTPS.
First request sets the session; non‑GET requests before a session is established will receive 405.
The library sets Cache-Control: no-store on session‑issuing responses to avoid caching issues.

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for the full text.

Top categories