Skip to content
WollyCMS Docs

Quick Start

Prerequisites

Section titled “Prerequisites”
  • Node.js 22 LTS — WollyCMS uses better-sqlite3 which requires native compilation. Node 22 LTS is tested and recommended. If you hit build errors on newer Node versions (e.g. v25), switch to Node 22 or use PostgreSQL instead (DATABASE_URL=postgresql://... in your .env).

Create a new project

Section titled “Create a new project”
Terminal window
npx create-wolly my-site
cd my-site

This scaffolds a new WollyCMS project with:

  • package.json with @wollycms/server dependency
  • .env with a generated JWT secret
  • .gitignore, .env.example, docker-compose.yml
  • data/ and uploads/ directories

Install and run

Section titled “Install and run”
Terminal window
npm install
npm run migrate
npm run seed
npm run dev

Your CMS is now running:

Default login: admin@wollycms.local / admin123

Create your Astro frontend

Section titled “Create your Astro frontend”

In a separate directory, create an Astro project:

Terminal window
npm create astro@latest my-frontend
cd my-frontend
npm install @wollycms/astro

Connect to WollyCMS

Section titled “Connect to WollyCMS”

Create src/lib/wolly.ts:

import { createClient } from '@wollycms/astro';


export const wolly = createClient({
  apiUrl: 'http://localhost:4321/api/content',
});

Create the block mapping

Section titled “Create the block mapping”

Create src/lib/blocks.ts:

// Map CMS block type slugs to Astro components
export { default as hero } from '../blocks/Hero.astro';
export { default as rich_text } from '../blocks/RichText.astro';
export { default as image } from '../blocks/ImageBlock.astro';
// Add more as you create block components

Create a catch-all route

Section titled “Create a catch-all route”

Create src/pages/[...slug].astro:

---
import Layout from '../layouts/Default.astro';
import BlockRenderer from '@wollycms/astro/components/BlockRenderer.astro';
import { wolly } from '../lib/wolly';
import * as blocks from '../lib/blocks';


const slug = Astro.params.slug || 'home';
const page = await wolly.pages.getBySlug(slug);
---


<Layout title={page.title}>
  <BlockRenderer
    blocks={page.regions.hero ?? []}
    components={blocks}
  />
  <BlockRenderer
    blocks={page.regions.content ?? []}
    components={blocks}
  />
</Layout>

Create your first block component

Section titled “Create your first block component”

Create src/blocks/Hero.astro:

---
const { fields } = Astro.props;
---


<section>
  <h1>{fields.heading}</h1>
  {fields.description && <p>{fields.description}</p>}
</section>

Troubleshooting

Section titled “Troubleshooting”

npm install fails with better-sqlite3 errors

Section titled “npm install fails with better-sqlite3 errors”

WollyCMS uses better-sqlite3, a native Node.js module that requires compilation. If the prebuilt binary isn’t available for your platform, it falls back to compiling from source.

Fix: Use Node.js 22 LTS (the tested and recommended version):

Terminal window
nvm install 22
nvm use 22
npm install    # retry

Fix: Install build tools (if compilation is needed):

Terminal window
# Ubuntu / Debian
sudo apt install build-essential python3


# macOS
xcode-select --install


# Windows
npm install -g windows-build-tools

Fix: Rebuild native modules (if npm install succeeded but commands still fail):

Terminal window
npm rebuild better-sqlite3

Alternative: Use PostgreSQL instead (no native modules required):

Edit .env and change DATABASE_URL:

DATABASE_URL=postgresql://user:password@localhost:5432/wollycms

PostgreSQL support is built in — no additional packages needed.

npm run migrate fails with “Can’t find meta/_journal.json” or “migrations folder not found”

Section titled “npm run migrate fails with “Can’t find meta/_journal.json” or “migrations folder not found””

This means the migration files inside @wollycms/server weren’t extracted correctly during install. This can happen on Windows, especially with spaces in the project path.

Fix: Reinstall from scratch:

Terminal window
rm -rf node_modules package-lock.json
npm install
npm run migrate

Fix: Move your project to a path without spaces (if reinstall doesn’t help):

\projects\my-site
# Instead of C:\Web Dev\Projects\my-site

Verify the file exists:

Terminal window
# The journal file should be at:
node_modules/@wollycms/server/drizzle/meta/_journal.json

Commands fail with MODULE_NOT_FOUND or Cannot find module

Section titled “Commands fail with MODULE_NOT_FOUND or Cannot find module”

Check your Node.js version:

Terminal window
node -v    # Should be v22.x.x

WollyCMS requires Node.js 22 LTS. Other versions may have incompatible native module binaries.

Server starts but admin UI shows a blank page

Section titled “Server starts but admin UI shows a blank page”

Clear your browser cache or try an incognito window. The admin UI is a SvelteKit SPA bundled with the server — it should load at http://localhost:4321/admin.

Next steps

Section titled “Next steps”