@digitalygo/create-diggocms-app 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # Create DiggoCMS App
 
-A CLI tool to scaffold new DiggoCMS projects with Next.js and the DiggoCMS SDK.
+A CLI tool to scaffold new DiggoCMS projects with Next.js Pages Router and the DiggoCMS SDK.
 
 ## Usage
 
@@ -10,7 +10,7 @@ A CLI tool to scaffold new DiggoCMS projects with Next.js and the DiggoCMS SDK.
 npx create-diggocms-app@latest
 ```
 
-### With bun
+### With bun (recommended)
 
 ```bash
 bun x create-diggocms-app
@@ -29,41 +29,53 @@ 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 the current supported component templates (recommended)
-   - `with-mock` - Full setup + mock API server + sample fixtures aligned with the SDK/demo payload model
+   - `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. **Package manager** - Choose your preferred package manager (bun, npm, yarn, pnpm)
+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 the current supported component set (title, image, text, video, gallery, card)
+
+- Extended templates for all supported component types (title, image, text, video, gallery, card)
 - Navigation components with dropdown support
-- Dynamic routing with `[...slug]`
-- Data fetching helpers
+- Dynamic routing with `[...slug]` using Pages Router
+- Data fetching helpers with SSG
 - Error handling and mock indicators
-- Ready-to-use styles
+- 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`)
-- Sample fixtures (pages, menu, collection) aligned with the current JSON/content standards used by the SDK/demo
-- Scripts: `mock:api` and `dev:mock`
+
+- 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
+- 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.
 
@@ -71,13 +83,12 @@ Best for: Developing without a real CMS API, testing, or learning.
 
 After scaffolding, your project will have this structure:
 
-```
+```text
 my-app/
-├── app/                  # Next.js app router
-│   ├── [...slug]/        # Dynamic routes
-│   ├── layout.tsx
-│   ├── page.tsx
-│   └── globals.css
+├── 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
@@ -85,10 +96,14 @@ my-app/
 ├── lib/                  # Utilities
 │   ├── diggo-config.ts
 │   └── data-fetching.ts
-├── fixtures/             # Mock data (with-mock only)
+├── 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
@@ -108,6 +123,19 @@ 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
@@ -115,22 +143,63 @@ MOCK_API_URL=http://localhost:3001
 
 ## Options
 
-You can also pass the project name as an argument:
+### Default path
+
+You can pass the project name as an argument to skip the prompt:
 
 ```bash
 npx create-diggocms-app@latest my-project
 ```
 
-This skips the project name prompt and uses `my-project` directly.
+### 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
+
+```bash
+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
+
+```bash
+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, try:
+If you get a permission error with npx, try:
 
 ```bash
-npx create-diggocms-app@latest --use-npm
+npm install -g create-diggocms-app
+create-diggocms-app
 ```
 
 Or use a Node version manager like nvm/fnm.
@@ -143,6 +212,10 @@ If the mock API server fails to start due to port conflicts, set a different por
 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.

package/bin/cli.js

@@ -1,13 +1,9 @@
 #!/usr/bin/env node
-/**
- * Create DiggoCMS App - CLI tool to scaffold new DiggoCMS projects
- * Inspired by create-next-app and create-vite
- */
 
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { cp, mkdir, readFile, writeFile, access, stat } from 'fs/promises';
+import { cp, mkdir, readFile, writeFile, access, stat, readdir, rm } from 'fs/promises';
 import { execSync } from 'child_process';
 import process from 'process';
 import prompts from 'prompts';
@@ -31,11 +27,6 @@ const PACKAGE_MANAGERS = ['bun', 'npm', 'yarn', 'pnpm'];
 
 const DEFAULT_PROJECT_NAME = 'my-diggocms-app';
 
-/**
- * Validates project name (no spaces, special chars, etc.)
- * @param {string} name
- * @returns {string | true} Error message or true if valid
- */
 function validateProjectName(name) {
   if (!name || name.trim().length === 0) {
     return 'Project name is required';
@@ -52,11 +43,6 @@ function validateProjectName(name) {
   return true;
 }
 
-/**
- * Checks if directory exists and is not empty
- * @param {string} dir
- * @returns {Promise<boolean>}
- */
 async function isDirectoryEmpty(dir) {
   try {
     const stats = await stat(dir);
@@ -70,11 +56,6 @@ async function isDirectoryEmpty(dir) {
   }
 }
 
-/**
- * Checks if a command exists
- * @param {string} cmd
- * @returns {boolean}
- */
 function commandExists(cmd) {
   try {
     execSync(`${cmd} --version`, { stdio: 'ignore' });
@@ -84,11 +65,6 @@ function commandExists(cmd) {
   }
 }
 
-/**
- * Gets the version of Node.js or Bun
- * @param {string} runtime
- * @returns {string | null}
- */
 function getRuntimeVersion(runtime) {
   try {
     const version = execSync(`${runtime} --version`, { encoding: 'utf-8' }).trim();
@@ -98,10 +74,6 @@ function getRuntimeVersion(runtime) {
   }
 }
 
-/**
- * Checks version requirements
- * @returns {{ node: string | null, bun: string | null }}
- */
 function checkRuntimeVersions() {
   return {
     node: getRuntimeVersion('node'),
@@ -109,12 +81,7 @@ function checkRuntimeVersions() {
   };
 }
 
-/**
- * Copies template files to target directory
- * @param {string} template
- * @param {string} targetDir
- */
-async function copyTemplate(template, targetDir) {
+async function copyTemplate(template, targetDir, includeFixtures = true) {
   const templateDir = join(__dirname, '..', 'templates', template);
 
   async function copyRecursive(src, dest) {
@@ -124,6 +91,11 @@ async function copyTemplate(template, targetDir) {
       const srcPath = join(src, entry.name);
       const destPath = join(dest, entry.name);
 
+      // Skip fixtures if not included (for with-mock template)
+      if (entry.name === 'fixtures' && !includeFixtures) {
+        continue;
+      }
+
       if (entry.isDirectory()) {
         await mkdir(destPath, { recursive: true });
         await copyRecursive(srcPath, destPath);
@@ -136,26 +108,36 @@ async function copyTemplate(template, targetDir) {
   await copyRecursive(templateDir, targetDir);
 }
 
-/**
- * Updates package.json with project name
- * @param {string} targetDir
- * @param {string} projectName
- */
-async function updatePackageJson(targetDir, projectName) {
+async function updatePackageJson(targetDir, projectName, packageManager) {
   const packageJsonPath = join(targetDir, 'package.json');
   const content = await readFile(packageJsonPath, 'utf-8');
   const packageJson = JSON.parse(content);
 
   packageJson.name = projectName;
 
+  const scripts = packageJson.scripts;
+
+  if (scripts['dev:mock']) {
+    const mockCmd = {
+      bun: 'bun run mock:api',
+      npm: 'npm run mock:api',
+      yarn: 'yarn mock:api',
+      pnpm: 'pnpm run mock:api',
+    }[packageManager];
+
+    const devCmd = {
+      bun: 'bun run dev',
+      npm: 'npm run dev',
+      yarn: 'yarn dev',
+      pnpm: 'pnpm run dev',
+    }[packageManager];
+
+    scripts['dev:mock'] = `concurrently "${mockCmd}" "${devCmd}"`;
+  }
+
   await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
 }
 
-/**
- * Installs dependencies using specified package manager
- * @param {string} packageManager
- * @param {string} cwd
- */
 function installDependencies(packageManager, cwd) {
   const installCmd = {
     bun: 'bun install',
@@ -168,10 +150,6 @@ function installDependencies(packageManager, cwd) {
   execSync(installCmd, { cwd, stdio: 'inherit' });
 }
 
-/**
- * Initializes git repository
- * @param {string} cwd
- */
 function initGit(cwd) {
   try {
     execSync('git init', { cwd, stdio: 'ignore' });
@@ -186,14 +164,7 @@ function initGit(cwd) {
   }
 }
 
-/**
- * Shows the final success message with next steps
- * @param {string} projectName
- * @param {string} targetDir
- * @param {string} packageManager
- * @param {string} template
- */
-function showSuccessMessage(projectName, targetDir, packageManager, template) {
+function showSuccessMessage(projectName, targetDir, packageManager, template, includeFixtures) {
   const runCmd = {
     bun: 'bun run',
     npm: 'npm run',
@@ -202,6 +173,13 @@ function showSuccessMessage(projectName, targetDir, packageManager, template) {
   }[packageManager];
 
   console.log(`\n${green('✔')} Successfully created ${cyan(projectName)}`);
+  console.log(`\n${lightGray('Configuration:')}`);
+  console.log(`  Template: ${cyan(template)}`);
+  console.log(`  Package manager: ${cyan(packageManager)}`);
+  if (template === 'with-mock') {
+    console.log(`  Fixtures: ${includeFixtures ? cyan('included') : dim('excluded')}`);
+  }
+  
   console.log(`\n${lightGray('Next steps:')}`);
   console.log(`  ${cyan('cd')} ${projectName}`);
 
@@ -227,13 +205,9 @@ function showSuccessMessage(projectName, targetDir, packageManager, template) {
   console.log(`\n${blue('Happy coding with DiggoCMS!')} ${magenta('🚀')}\n`);
 }
 
-/**
- * Main CLI function
- */
 async function main() {
   console.log(`\n${cyan('◆')} ${bold('DiggoCMS')} ${lightGray('– Create a new CMS-powered app')}\n`);
 
-  // Check runtime versions
   const versions = checkRuntimeVersions();
 
   if (!versions.node && !versions.bun) {
@@ -241,7 +215,6 @@ async function main() {
     process.exit(1);
   }
 
-  // Get project name from command line or prompt
   let projectName = process.argv[2];
 
   if (!projectName) {
@@ -267,7 +240,6 @@ async function main() {
     process.exit(1);
   }
 
-  // Check if directory exists
   const targetDir = join(process.cwd(), projectName);
 
   try {
@@ -297,18 +269,16 @@ async function main() {
       }
     }
   } catch {
-    // Directory doesn't exist, create it
     await mkdir(targetDir, { recursive: true });
   }
 
-  // Choose template
   const { template } = await prompts({
     type: 'select',
     name: 'template',
     message: 'Choose a template:',
     choices: [
-      { title: green('full'), value: 'full', description: 'Complete setup with all components' },
-      { title: blue('with-mock'), value: 'with-mock', description: 'Full setup + mock API server' },
+      { title: green('full'), value: 'full', description: 'Complete setup with all components (SSG, Pages Router)' },
+      { title: blue('with-mock'), value: 'with-mock', description: 'Full setup + mock API server + optional fixtures' },
       { title: yellow('minimal'), value: 'minimal', description: 'Basic setup, add components yourself' },
     ],
     initial: 0,
@@ -319,7 +289,17 @@ async function main() {
     process.exit(1);
   }
 
-  // Choose package manager
+  let includeFixtures = true;
+  if (template === 'with-mock') {
+    const { fixtures } = await prompts({
+      type: 'confirm',
+      name: 'fixtures',
+      message: 'Include sample fixtures (pages, menu, collection)?',
+      initial: true,
+    });
+    includeFixtures = fixtures;
+  }
+
   const availableManagers = PACKAGE_MANAGERS.filter(commandExists);
   const defaultManager = availableManagers.includes('bun') ? 'bun' : 'npm';
 
@@ -340,24 +320,14 @@ async function main() {
     process.exit(1);
   }
 
-  // Scaffold project
   console.log(dim(`\nScaffolding project in ${targetDir}...`));
 
   try {
-    // Copy template
-    await copyTemplate(template, targetDir);
-
-    // Update package.json
-    await updatePackageJson(targetDir, projectName);
-
-    // Initialize git
+    await copyTemplate(template, targetDir, includeFixtures);
+    await updatePackageJson(targetDir, projectName, packageManager);
     const gitInitialized = initGit(targetDir);
-
-    // Install dependencies
     installDependencies(packageManager, targetDir);
-
-    // Show success message
-    showSuccessMessage(projectName, targetDir, packageManager, template);
+    showSuccessMessage(projectName, targetDir, packageManager, template, includeFixtures);
 
     if (gitInitialized) {
       console.log(`${green('✔')} Git repository initialized\n`);
@@ -369,22 +339,10 @@ async function main() {
   }
 }
 
-// Helper functions
 function bold(str) {
   return `\x1b[1m${str}\x1b[0m`;
 }
 
-async function readdir(path, options) {
-  const fs = await import('fs/promises');
-  return fs.readdir(path, options);
-}
-
-async function rm(path, options) {
-  const fs = await import('fs/promises');
-  return fs.rm(path, options);
-}
-
-// Run main function
 main().catch((error) => {
   console.error(red('\nUnexpected error:'));
   console.error(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalygo/create-diggocms-app",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI tool to scaffold a new DiggoCMS project",
   "type": "module",
   "bin": {

package/templates/full/.env.local.example

@@ -2,8 +2,9 @@
 # Copy this file to .env.local and update the values
 
 # CMS API Configuration
-# Set your DiggoCMS API base URL
-BASE_URL=https://your-cms-api.com
+# Set your DiggoCMS API base URL (required when not using mock mode)
+# Example: BASE_URL=https://cms.example.com
+BASE_URL=
 
 # Mock Mode
 # Set to 1 to use local mock data instead of a real API

package/templates/full/README.md

@@ -1,34 +1,40 @@
 # My DiggoCMS App
 
-A complete DiggoCMS application built with Next.js and the DiggoCMS SDK.
+A complete DiggoCMS application built with Next.js Pages Router and the DiggoCMS SDK.
 
 ## Features
 
-- Dynamic routing with `[...slug]` pattern
-- Extended components for the current supported standalone types: title, image, text, video, gallery, and card
-- Navigation with dropdown support
-- Mock mode for development
-- Error handling and loading states
+- Next.js 16 with Pages Router
+- Static Site Generation (SSG) with `getStaticProps`/`getStaticPaths`
+- Tailwind CSS for styling
+- Hot reload via `next dev`
+- Extended components for all supported types: title, image, text, video, gallery, and card
+- Navigation components with dropdown support
+- Header renders the main menu from CMS or mock API data
+- Error handling and mock indicators
 
 ## Getting Started
 
 1. Copy `.env.local.example` to `.env.local` and configure:
+
    ```bash
    cp .env.local.example .env.local
    ```
 
 2. Install dependencies:
+
    ```bash
-   npm install
-   # or
    bun install
+   # or
+   npm install
    ```
 
 3. Run the development server:
+
    ```bash
-   npm run dev
-   # or
    bun run dev
+   # or
+   npm run dev
    ```
 
 4. Open [http://localhost:3000](http://localhost:3000) in your browser.
@@ -37,29 +43,29 @@ A complete DiggoCMS application built with Next.js and the DiggoCMS SDK.
 
 ### Using a Real CMS API
 
-Set your CMS API base URL:
+Set your CMS API base URL in `.env.local`:
+
 ```env
 BASE_URL=https://your-cms-api.com
 MOCK=0
 ```
 
+Note: The template defaults to an empty `BASE_URL`. You must configure it before running in non-mock mode. Requests timeout after 5 seconds to prevent hanging.
+
 ### Using Mock Mode
 
 Enable mock mode for development without a real API:
+
 ```env
 MOCK=1
 MOCK_API_URL=http://localhost:3001
 ```
 
-## Project Structure
+When `MOCK=1`, the `BASE_URL` setting is ignored.
 
-```
-app/                  # Next.js app router
-├── [...slug]/        # Dynamic catch-all route
-├── layout.tsx        # Root layout with DiggoProvider
-├── page.tsx          # Home redirect
-└── globals.css       # Global styles
+## Project Structure
 
+```text
 components/           # React components
 ├── DiggoProvider.tsx    # SDK provider wrapper
 ├── server-components.ts # Server-safe component exports
@@ -75,11 +81,30 @@ components/           # React components
 lib/                  # Utility functions
 ├── diggo-config.ts   # SDK configuration
 └── data-fetching.ts  # Data fetching helpers
+
+pages/                # Next.js pages (Pages Router)
+├── _app.tsx          # App wrapper with DiggoProvider
+├── index.tsx         # Home redirect
+└── [...slug].tsx     # Dynamic catch-all route
+
+public/               # Static assets
+styles/               # Global styles
+└── globals.css       # Tailwind + component styles
 ```
 
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `bun run dev` | Start development server with hot reload |
+| `bun run build` | Build for static export |
+| `bun run start` | Start production server |
+| `bun run lint` | Run ESLint |
+| `bun run typecheck` | Run TypeScript check |
+
 ## Extended Components
 
-This template includes extended versions of the current SDK component set used by the starter:
+This template includes extended versions of all SDK-supported component types:
 
 - **ExtendedTitle** - Styled H1 heading
 - **ExtendedImage** - Responsive image with shadow
@@ -90,11 +115,27 @@ This template includes extended versions of the current SDK component set used b
 - **ExtendedMenuItem** - Navigation item with active state
 - **ExtendedMenuContainer** - Navigation wrapper
 
-Standalone page payloads in this template are expected to use only the supported types above. Card payloads can still include internal card fields such as `richtext` when provided by the CMS.
+Page payloads should use only the supported types above. Card payloads can include card-specific fields such as `richtext` when provided by the CMS.
+
+## SSG Configuration
+
+By default, pages are generated on-demand. To pre-generate pages at build time, modify `getStaticPaths` in `pages/[...slug].tsx`:
+
+```typescript
+export const getStaticPaths: GetStaticPaths = async () => {
+  // Fetch all page slugs from your CMS
+  const pages = await fetchAllPages();
+  
+  return {
+    paths: pages.map(page => ({ params: { slug: page.slug.split('/') } })),
+    fallback: 'blocking',
+  };
+};
+```
 
 ## Customization
 
-1. Edit styles in `app/globals.css`
+1. Edit styles in `styles/globals.css`
 2. Modify components in `components/`
 3. Update configuration in `lib/diggo-config.ts`
 4. Add more data fetching functions in `lib/data-fetching.ts`
@@ -102,4 +143,5 @@ Standalone page payloads in this template are expected to use only the supported
 ## Documentation
 
 - [DiggoCMS SDK Documentation](https://github.com/digitalygo/diggocms-sdk)
-- [Next.js Documentation](https://nextjs.org/docs)
+- [Next.js Pages Router Documentation](https://nextjs.org/docs/pages)
+- [Tailwind CSS Documentation](https://tailwindcss.com/docs)