Package Compatibility Tiers

GuideKit uses a tiered release model so core integrations stay stable while optional platform packages evolve independently.

Tier A — Integrated (lockstep semver)

These packages ship together for breaking API changes:

Rule: Bump all Tier A packages together when pipeline options, proxy routes, or provider props change incompatibly.

Tier B — Extensions (peer on core)

Rule: Minor bumps when core types change. Optional — zero bundle cost when not imported.

Tier C — Experimental subpaths

Rule: May change more frequently; tree-shakeable subpath exports.

Multi-instance deployments

For horizontal scaling, use RedisSessionStore from @guidekit/server/redis:

import Redis from 'ioredis';
import { RedisSessionStore } from '@guidekit/server/redis';
import { createGuideKitHandler } from '@guidekit/server';
 
const redis = new Redis(process.env.REDIS_URL!);
const sessionStore = new RedisSessionStore({ redis });
 
const handler = createGuideKitHandler({
  signingSecret: process.env.GUIDEKIT_SECRET!,
  sessionStore,
  createTokenOptions: () => ({
    llmApiKey: process.env.LLM_API_KEY!,
    expiresIn: '15m',
  }),
});
 
// In your HTTP framework:
// await handler(request, 'llm')

Each app instance shares session keys via Redis while the client holds only a short-lived JWT.

Semver governance (1.0)

SessionStore (1.0 breaking change)

SessionStore methods are fully async in 1.0:

const keys = await sessionStore.get(sessionId);
await sessionStore.set(sessionId, providerKeys, expiresAt);
await sessionStore.delete(sessionId);

Production security checklist

1. Use tokenEndpoint + proxy.llm — never ship provider API keys to the browser.
2. Store keys in SessionStore server-side only.
3. Enable rate limiting middleware on proxy routes.
4. Run pnpm audit --audit-level high in CI (enabled by default).