Getting started

New here? Start with the 5-minute tutorial: generate a site, install it, add a plugin, deploy to Cloudflare. This page is the reference for requirements, framework development and upgrades.

Requirements

Create a site in one command

npx -y https://insightme.top/create-nuxtcms.tgz my-site --template corporate
cd my-site && pnpm install && pnpm dev

Templates and options: Templates. The steps below are for working on the framework itself.

Install

git clone https://github.com/guxingbiao0507/nuxtcms.git
cd nuxtcms
pnpm install
cp .env.example .env

Set at least these values in .env:

NUXT_JWT_SECRET=<random string, 32+ chars>      # openssl rand -base64 32
NUXT_SESSION_PASSWORD=<random string, 32+ chars>
DATABASE_URL=file:.data/cms.sqlite

Run

pnpm dev

Open http://localhost:3000; it redirects to the default-language home page /zh. Visit /zh/setup (or /us/setup) on first run:

1. Enter the site name, description and the administrator account.
2. Keep Import demo content checked to seed a bilingual technology-company sample: 3 product categories, 6 products, 2 post categories, 6 posts and an About page.
3. You are signed in automatically and land in the admin at /zh/admin.

Database migrations run automatically when the dev server starts. The demo content can also be seeded into an empty database at any time with pnpm seed:demo.

Project layout

app/                 public pages, layouts, components (sites usually override these)
  pages/admin/       admin pages
server/api/          API routes: public, admin, auth, setup
server/database/     Drizzle schema, dialect adapters, migrations, demo seed
server/utils/        auth, cache, storage, SEO, mail helpers
server/routes/       robots.txt, sitemap.xml, llms.txt
i18n/                locale configuration and message files
deploy/              PM2, nginx, Dockerfile and wrangler examples
docs/                documentation (Chinese and English)

Using InsightSite as a base layer

A site project references this repository as a Nuxt Layer and overrides only what it needs:

// the site's nuxt.config.ts
export default defineNuxtConfig({
  extends: ['nuxtcms'],
})

// the site's package.json
{ "dependencies": { "nuxtcms": "github:guxingbiao0507/nuxtcms#v1.3.2" } }

Pin a tag and bump it deliberately when upgrading the base.

The site's main.css

The base registers ~/assets/css/main.css, which in a site resolves to the site's own app/assets/css/main.css, so that file must carry what the base needs. The base admin pages and the official plugins (shop, blog) live in node_modules, which Tailwind does not scan by default; point @source at them (upgrade.mjs adds missing lines):

@import "tailwindcss";
@import "@nuxt/ui";
@source "../../../node_modules/nuxtcms/app";
@source "../../../node_modules/nuxtcms/plugins";

@custom-variant dark (&:where(.dark, .dark *));

Upgrading

One command (recommended):

node node_modules/nuxtcms/scripts/upgrade.mjs --deploy   # latest version: install, D1 migrations, build, deploy, health check

The admin dashboard shows this command when a newer release is out. By hand:

1. Change the tag in package.json, pnpm install.
2. Read the Upgrade notes in the changelog and apply new SQLite migrations (all idempotent) to D1: wrangler d1 migrations apply <db> --remote; sites with a custom table prefix run the SQL with the prefix replaced.
3. Commit and deploy once pnpm build:cf passes.

Check a site with nuxtcms doctor

npx nuxtcms doctor (or node node_modules/nuxtcms/scripts/doctor.mjs) lists the base files the site overrides and what each copy is missing (plugin slots, revision history, update notice, admin menus...). Most gaps close with one line: <CmsAppEnd /> in app.vue, <AdminUpdateBanner /> on a custom dashboard, <ContentRevisions /> in a custom editor, useAdminNavExtras() in a custom admin layout. Identical copies can simply be deleted.

Common commands

Next: Configuration · Deployment