Create DiggoCMS App

A CLI tool to scaffold new DiggoCMS projects with Next.js Pages Router and the DiggoCMS SDK.

Usage

With npx (no installation required)

npx create-diggocms-app@latest

With bun (recommended)

bun x create-diggocms-app

Global installation

npm install -g create-diggocms-app
create-diggocms-app

Interactive Setup

The CLI will guide you through the setup process:

1. Project name - Name of your new project directory
2. Template - Choose from:
   • full - Complete setup with all components, SSG-ready with Pages Router (recommended)
   • with-mock - Full setup + mock API server + optional fixtures
   • minimal - Basic setup, add components yourself
3. Fixtures (with-mock only) - Include sample fixtures for development
4. Package manager - Choose your preferred package manager (bun, npm, yarn, pnpm)

Templates

Minimal

A bare-bones setup with just the SDK installed. You'll need to:

• Create your own extended components
• Configure the SDK manually
• Set up data fetching

Features:

• Next.js 16 with Pages Router
• Tailwind CSS configured
• SSG structure with getStaticProps/getStaticPaths
• Hot reload via next dev

Best for: Experienced developers who want full control.

Full

Complete setup including:

• Extended templates for all supported component types (title, image, text, video, gallery, card) with SDK variant prop support
• Navigation components with dropdown support
• Dynamic routing with [...slug] using Pages Router
• Data fetching helpers with SSG
• Error handling and mock indicators
• Tailwind CSS with component styles

Best for: Most users starting a new project.

With Mock

Everything from the full template, plus:

• Standalone mock API server (scripts/mock-server.ts) using tsx (works with any package manager)
• Optional sample fixtures (pages, menu, collection) aligned with SDK payload model and seeded with variant examples
• Scripts: mock:api and dev:mock (uses concurrently for cross-platform parallel execution)
• Pre-configured .env.local for mock mode
• Mock mode indicator in UI

Best for: Developing without a real CMS API, testing, or learning.

Project Structure

After scaffolding, your project will have this structure:

my-app/
├── pages/                # Next.js pages (Pages Router)
│   ├── [...slug].tsx     # Dynamic routes
│   ├── _app.tsx          # App wrapper
│   ├── index.tsx         # Home redirect
├── components/           # React components
│   ├── DiggoProvider.tsx
│   ├── server-components.ts
│   └── Extended*.tsx
├── lib/                  # Utilities
│   ├── diggo-config.ts
│   └── data-fetching.ts
├── fixtures/             # Mock data (with-mock only, optional)
├── scripts/              # Mock server (with-mock only)
├── styles/               # Global styles
│   └── globals.css       # Tailwind + custom styles
├── .env.local.example
├── next.config.ts
├── tailwind.config.ts    # Tailwind configuration
├── postcss.config.js     # PostCSS configuration
├── package.json
├── tsconfig.json
└── README.md

Environment Variables

Copy .env.local.example to .env.local and configure:

# Use real CMS API
BASE_URL=https://your-cms-api.com
MOCK=0

# Or use mock mode
MOCK=1
MOCK_API_URL=http://localhost:3001

Note: BASE_URL must be set to a valid URL when not using mock mode. Requests will timeout after 5 seconds if the server is unreachable.

Package Manager Support

The CLI supports multiple package managers:

• bun (default if available) - Fast, all-in-one JavaScript runtime
• npm - Node.js default package manager
• yarn - Fast, reliable, and secure dependency management
• pnpm - Fast, disk space efficient package manager

Scripts in package.json are automatically adjusted for your chosen package manager.

Requirements

• Node.js >= 18.0.0 or Bun >= 1.1.0
• A DiggoCMS API endpoint (or use mock mode)

Options

Default path

You can pass the project name as an argument to skip the prompt:

npx create-diggocms-app@latest my-project

With fixtures toggle (with-mock template)

When selecting the with-mock template, you'll be prompted to include fixtures:

• Yes (default) - Includes sample pages, menu, and collection fixtures
• No - Sets up the mock server infrastructure without sample data

SSG (Static Site Generation)

All templates use Next.js Pages Router with SSG-first approach:

• getStaticProps - Fetches page data at build time
• getStaticPaths - Pre-generates pages (configure for your CMS)
• ISR (Incremental Static Regeneration) - Enabled with 60s revalidation by default

To pre-generate specific pages at build time, update getStaticPaths in pages/[...slug].tsx.

Commands Reference

Commands work with any package manager (bun, npm, yarn, pnpm). Examples use bun:

All Templates

bun run dev       # Start development server with hot reload
bun run build     # Build for production
bun run start     # Start production server
bun run lint      # Run ESLint
bun run typecheck # Run TypeScript check

With-Mock Template Only

bun run mock:api  # Start the mock API server
bun run dev:mock  # Start mock API and dev server together

With yarn, omit run (for example: yarn dev, yarn mock:api).

Troubleshooting

Permission denied

If you get a permission error with npx, try:

npm install -g create-diggocms-app
create-diggocms-app

Or use a Node version manager like nvm/fnm.

Port already in use

If the mock API server fails to start due to port conflicts, set a different port:

PORT=3002 bun run mock:api

Hot reload not working

Ensure you're using next dev (via bun run dev, npm run dev, yarn dev, or pnpm run dev). Hot reload is enabled by default in development mode.

Contributing

This CLI is part of the DiggoCMS SDK monorepo. See the main repository for contribution guidelines.

License

MIT © DigitalyGo Team