@black-magic/create-craft-site

Interactive CLI to scaffold a CraftCMS project with DDEV.

Requirements

• DDEV v1.23+
• Node.js 18+

Usage

npm create craft-site@latest
# or
npx @black-magic/create-craft-site

With a config file (zero-prompt)

npx @black-magic/create-craft-site --config=./craft-site.config.json

What it does

New project flow:

1. Creates the project directory
2. Runs ddev config (PHP 8.4, MySQL 8.0, docroot public_html)
3. Patches .ddev/config.yaml — adds Vite port exposure and upload_dirs
4. Installs the tyler36/ddev-vscode-devcontainer DDEV add-on
5. ddev restart
6. Downloads CraftCMS via Composer (non-interactive mode)
7. Moves web/ → public_html/ and removes web/
8. Runs ddev craft install non-interactively
9. Vite setup (optional, default yes):
   • Downloads wearealloy/craft-site-scaffolding and copies files
   • Merges .env.example vars and .gitignore entries
   • ddev composer require nystudio107/craft-vite
   • ddev craft plugin/install vite
   • npm install --save-dev vite typescript tailwindcss @tailwindcss/vite prettier + plugins

Existing project flow:

1. git clone into the target directory
2. Reads PHP/DB versions from .ddev/config.yaml
3. Patches config + installs add-on + ddev restart
4. ddev composer install
5. Optional DB restore
6. Optional Vite setup (same as above)

Config file

Provide a craft-site.config.json (or .yaml / .yml) to skip all prompts:

{
  "docroot": "public_html",
  "phpVersion": "8.4",
  "dbVersion": "mysql:8.0",
  "siteName": "My Site",
  "adminEmail": "[email protected]",
  "adminUsername": "admin",
  "adminPassword": "secret",
  "language": "en",
  "setupVite": true
}

Or pass an explicit path:

npx @black-magic/create-craft-site --config=./path/to/config.json

CLI flags

| Flag | Description | | --------------------- | -------------------------------------- | | --config=<path> | Path to a config file | | --php-version=<ver> | Override PHP version (e.g. 8.3) | | --db-version=<ver> | Override DB version (e.g. mysql:8.0) |

Development

pnpm install
pnpm build       # compile to dist/
pnpm dev         # watch mode
pnpm typecheck   # tsc --noEmit
pnpm lint        # eslint

Run locally:

node dist/index.js
node dist/index.js --config=./craft-site.config.json

Documentation

• Plans — implementation plans and architecture notes
• Craft quickstart — manual DDEV + Craft reference