Start a new project
Create a Next.js App Router app, add Xenon with an embedded local database, and publish your first post.
On this page
Create the app
From the directory where you keep your projects, create a TypeScript app with Bun and Node.js 20.9 or later. This command puts the App Router under src/app and sets the import alias used in the examples.
bunx create-next-app@16 my-site --ts --app --src-dir --import-alias "@/*" --use-bun --no-cache-components --yes
cd my-siteInstall Xenon and a local database
Follow the core package installation to add Xenon to my-site. Then install PGlite, the embedded database, in the same app. It stores posts on disk without a separate database server, and it's the only driver this setup needs.
bun add @electric-sql/pgliteIn next.config.ts, add these settings to the exported configuration object. serverExternalPackages lets Next.js load PGlite's WebAssembly files from the installed package. cpus: 1 builds with a single worker. Only one process can open the local database at a time, so it's needed once several static pages read PGlite while they prerender; a site with a single such page, like this one at first, also builds without it.
// Add these properties inside the existing nextConfig object.
serverExternalPackages: ["@electric-sql/pglite"],
experimental: { cpus: 1 },Add .xenon/ to the app’s .gitignore. This directory holds the local database and uploads. Stop the dev server before running a production build against the same PGlite directory.
Connect the routes
Use the file examples in the Quickstart, in order:
- Create
src/xenon.config.tswith thepostscollection and the file-backed PGlite adapter. - Create
src/app/api/xenon/[...slug]/route.tsfor the REST API. - Create
src/app/admin/[[...segments]]/page.tsxfor the admin and its Server Action. - Replace the starter
src/app/page.tsxwith the Server Component that lists published posts.
Publish your first post
bun run devOpen /admin at the local URL printed by Next.js and create the first administrator. Under Posts, create a document, enter a title and select Publish. Open / to see the title on your site. You can also visit /api/xenon/posts to see the same post in the JSON response’s docs array.
Before deploying, configure a production secret and persistent storage for your hosting environment. Follow the deployment guide.