Skip to content
next-story
Menu

Get started

Install it in a Next.js app you run

next-story is a library, not a hosted service, so getting started means wiring it into your own app. apps/demo in the repository is the reference install, and the next-story-onboarding skill walks an agent through the same steps.

Quickstart in the docs
  1. Step 1

    Add the package

    pnpm add @next-story/journey-recorder. It needs Next.js 15.1 or later.

  2. Step 2

    Mint the token in middleware

    Use withJourneyToken and forward the token as a request header (JOURNEY_TOKEN_HEADER). Keep middleware.ts free of database and store imports so the Edge bundle builds.

  3. Step 3

    Add the collect route

    createCollectHandler with your token secrets, IP salt, site registry, an EventSink (createDrizzleEventSink works against tables shaped like the reference schema) and a rate-limit Store (UpstashStore in production).

  4. Step 4

    Start the client

    Call initJourney once from a client component and report route changes. Set requireConsent if nothing may be recorded before your visitor agrees.

  5. Step 5

    Schedule the jobs

    Run session-close, daily-rollup and retention from apps/worker on a cron, against a direct Postgres connection.

  6. Step 6

    Mint agent tokens

    Give each agent a token with only the scopes and site ids it needs, then point it at the agent API.

Environment variables

Secrets stay on your servers. None of them is needed in the browser.

NS_TOKEN_SECRET
Signs journey tokens (rotate with NS_TOKEN_SECRET_PREVIOUS)
NS_IP_SALT
Salt for the daily IP hash used for rate limiting
WORKER_DATABASE_URL
Direct Postgres connection for the jobs
DATABASE_URL
Postgres connection for the agent API
AGENT_API_TOKENS
Agent tokens with their scopes and site grants
Reference install (apps/demo)Onboarding skill