Getting Started

Headcode CMS is distributed through the shadcn registry, so you can install it directly into your Next.js project using the Shadcn CLI you’re probably familiar with.

Each part of Headcode CMS (themes, section UIs, fields, etc.) is published as its own registry component and can be added using this format:

1. Install the Starter

The easiest way to begin is with the Headcode CMS Starter:

The starter installs:

• Next.js 16

• shadcn/ui

• Headcode CMS admin

• The Headcode CMS Starter theme (including a demo site)

By default, it uses:

• SQLite (file-based) for the database

• Better Auth for authentication

• Local file storage

This configuration works great for local development or testing.

If you’re setting up for production, you’ll want to use real services.

Update your .env.local file to configure:

• A database (e.g. Turso Cloud)

• A storage provider (e.g. Vercel Blob Storage)

2. Initialize the Database

After installing, set up your database schema using Drizzle Kit.

To push the schema directly:

Or, if you prefer using migrations:

3. Project Structure

The starter sets up two main routes:

• Admin: app/(headcode)

• Demo Site: app/(site)

To avoid conflicts, remove the default Next.js layout and page files from the app root (these are no longer needed):

• app/layout.tsx

• app/page.tsx

Note: Keep globals.css — it’s required for shadcn/ui.

4. Run the Development Server

You’re ready to start developing your website with Headcode CMS.

Then open your browser:

• Website: http://localhost:3000

• Admin: http://localhost:3000/headcode

When you open the admin for the first time, you’ll be prompted to create an administrator user. After that, you can start editing content and customizing your site.

Next Steps

• Explore the /app/(site) directory to build your pages and layouts.

• Browse available Headcode CMS registry components (themes, fields, UI blocks).

• Try replacing the starter theme with your own.