Skip to content
XenonDocs
Esc
    GitHub
    Docs

    Installation

    Install Xenon and its peer dependencies into an existing Next.js App Router application.

    On this page

    Requirements

    You can install Xenon into any existing Next.js App Router project that meets the following peer dependency versions:

    PackageVersionRequirement
    next>=16.0.0Needed for xenon-cms/next and the admin
    react>=19.0.0Needed for xenon-cms/next and the admin
    react-dom>=19.0.0Needed for xenon-cms/next and the admin
    postgres>=3.4.0Needed for xenon-cms/postgres only
    @electric-sql/pglite>=0.3.0Needed for xenon-cms/pglite only

    Core package

    Build an installable tarball from a Xenon source checkout. From the root of that checkout, run:

    Terminal
    bun install --frozen-lockfile
    bun run build
    cd packages/xenon
    bun pm pack --filename xenon-cms.tgz

    In the directory containing your Next.js app’s package.json, copy the archive into the app. Replace /path/to/xenon with the path to your checkout.

    Terminal
    mkdir -p vendor
    cp /path/to/xenon/packages/xenon/xenon-cms.tgz vendor/
    bun add ./vendor/xenon-cms.tgz

    Keep the tarball with the app so a fresh install in CI can resolve the same dependency. Apps inside the Xenon Bun workspace can use "xenon-cms": "workspace:*" like the playground.

    Database drivers

    Each database has its own import, and you install only the driver it uses.

    ImportAdapterInstall
    xenon-cms/postgrespostgresAdapter({ connectionString })postgres
    xenon-cms/pglitepgliteAdapter({ dataDir })@electric-sql/pglite
    xenon-cms/drizzledrizzleAdapter({ db })Nothing; you bring your own Drizzle database

    Postgres server

    For a Postgres server, install postgres and pass your database URL to postgresAdapter.

    bun add postgres

    Embedded database for local development

    For a local database, install PGlite and pass a data directory to pgliteAdapter.

    bun add @electric-sql/pglite

    PGlite needs two Next.js settings. serverExternalPackages lets Next.js load its WebAssembly files from the installed package:

    next.config.ts
    import type { NextConfig } from "next";
    
    const nextConfig: NextConfig = {
      serverExternalPackages: ["@electric-sql/pglite"],
      experimental: { cpus: 1 },
    };
    
    export default nextConfig;

    cpus: 1 makes next build use a single worker. Only one process can open a PGlite database at a time, so when several static pages read it while they prerender, the default worker count fails with an "already open in another process" error. A site with a single page that reads PGlite builds either way.

    The Postgres and Drizzle adapters need no Next.js configuration.

    Admin stylesheets

    The admin interface requires the Xenon base stylesheet for layout and controls.

    src/app/admin/[[...segments]]/page.tsx
    import "xenon-cms/styles.css";

    Import this CSS file at the top of your admin page route.

    Environment variables

    Add the appropriate environment variables to your .env.local file.

    .env.local
    # Set via XENON_SECRET, BETTER_AUTH_SECRET, or config.auth.secret
    XENON_SECRET="your-secure-random-secret"
    
    # Required for postgresAdapter
    DATABASE_URL="postgres://user:password@localhost:5432/mydb"

    Xenon resolves secrets in order: config.auth.secret, XENON_SECRET, then BETTER_AUTH_SECRET. Outside production, Xenon falls back to a fixed development secret. In production, it throws an error the first time the secret is needed (for authentication or admin routes) if none is configured. The secret signs sessions and admin presence tokens.

    Next steps