@dotcms/create-app 1.2.5 → 1.2.6-next.1

package/README.md

@@ -1,238 +1,174 @@
-# 🚀 create-dotcms-app
+# @dotcms/create-app
 
-> 🚧 **Beta Notice:**
-> This CLI is currently in **beta**. Features and APIs may change as we continue improving the tool.
+CLI to scaffold a dotCMS frontend project or start a local dotCMS Docker stack.
 
-With a single command, you can bootstrap a fully functional frontend (Next.js, Angular, Astro, etc.) connected to dotCMS APIs — including the following:
+## Status
 
--   Spinning up dotCMS using Docker with intelligent pre-flight checks
--   Universal Visual Editor pre-configured
--   Generating site ID and authentication token (just copy paste them in frontend .env and enjoy)
--   Comprehensive validation and helpful error messages
+Beta. Behavior and flags may change.
 
----
+## Requirements
 
-## ✨ What is `create-dotcms-app`?
+- Node.js + npm
+- Git
+- Docker (for `--local` or `--starter`)
+- Internet access (downloads templates and docker-compose)
 
-`create-dotcms-app` is a command-line tool that helps developers quickly spin up headless frontends powered by **dotCMS**.
-
-It automates the tedious work of:
-
--   Setting up a framework with best practices
--   Connecting to dotCMS REST & GraphQL APIs
--   Providing content-fetching helpers
--   Adding example components & pages
--   Creating environment variable templates
--   Optionally setting up local dotCMS instance using Docker
--   Validating your environment (Docker, ports, URLs)
-
-This tool lets you focus on **building**, not configuring.
-
----
-
-## 🎯 Why this project exists
-
-dotCMS is a hybrid headless CMS with powerful APIs — but initializing a frontend manually takes time.
-
-This CLI solves that by offering:
-
--   **Frictionless onboarding**
--   **Standardized project setup**
--   **Fast prototyping & demos**
--   **DevRel-friendly scaffolding for workshops & tutorials**
--   **Production-ready integration patterns**
-
----
-
-## 🛠️ Installation
-
-Run using npx (recommended):
+## Quick Start
 
 ```sh
-npx @dotcms/create-app <project-name>
+npx @dotcms/create-app my-app
 ```
 
-Or install cli globally
+Global install:
 
 ```sh
 npm install -g @dotcms/create-app
+create-dotcms-app my-app
 ```
 
-## Usage
+## CLI
 
 ```sh
-npx @dotcms/create-app <project-name>
+create-dotcms-app [projectName] [options]
 ```
 
-This will:
+| Option | Description |
+|---|---|
+| `-f, --framework <framework>` | Framework: `nextjs`, `astro`, `angular`, `angular-ssr` |
+| `-d, --directory <path>` | Parent or target directory |
+| `--local` | Use local dotCMS with Docker |
+| `--starter <url>` | Custom starter ZIP URL (local-only; sets `CUSTOM_STARTER_URL`) |
+| `--url <url>` | dotCMS URL for cloud mode |
+| `-u, --username <username>` | dotCMS username for cloud mode |
+| `-p, --password <password>` | dotCMS password for cloud mode |
+| `-V, --version` | Show CLI version |
 
--   Ask for the target directory
--   Ask which frontend framework you want (Next.js, Angular, Astro, etc.)
--   Ask if you're using dotCMS Cloud or Local Docker dotCMS
--   **For local Docker setup:**
-    -   Check if Docker is installed and running
-    -   Verify required ports are available (8082, 8443, 9200, 9600)
-    -   Provide specific error messages and solutions if issues are found
--   Automatically scaffold your project
--   Configure UVE (Edit Mode Anywhere)
--   Start dotCMS (if using Docker)
--   Print required environment variables for your frontend
+Framework aliases:
 
-## Env variables
+- `next`, `next.js` -> `nextjs`
+- `ng` -> `angular`
+- `angular-server` -> `angular-ssr`
 
-You will get the following env variables generated by cli **just copy and replace them in the frontend of the env and enjoy dotCMS in headless mode**.
+## Behavior by Mode
 
-```sh
-Host (site) : http://localhost:8082
-Site ID : 59bb8831-6706-4589-9ca0-ff74016e02b2
-API Token : YOUR_API_TOKEN
-```
-
-## CLI Syntax
+### 1) Cloud mode (existing dotCMS instance)
 
-```sh
-create-dotcms-app <project-name> [options]
-```
+Used when you do not pass `--local` or `--starter` and choose cloud in prompts.
 
-| Option                   | Description                                                                                                                                                           |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `-f, --framework <name>` | Skip prompts and directly choose a framework. Supported: `nextjs`, `angular`, `angular-ssr`, `astro`. Case-insensitive. Aliases: `next`, `ng`, `next.js`, `angular-server` |
-| `-d, --directory`        | Project Directory                                                                                                                                                     |
-| `--local`                | Use local dotCMS instance using docker                                                                                                                                |
-| `-u, --username`         | dotCMS instance username (skip in case of local)                                                                                                                      |
-| `-p, --password`         | dotCMS instance password (skip in case of local)                                                                                                                      |
-| `--url`                  | dotCMS instance URL (skip in case of local). Must include protocol (http:// or https://)                                                                              |
-| `-V, --version`          | Show CLI version                                                                                                                                                      |
+Flow:
 
-### Framework Aliases
+1. Validates URL, project name, and flags.
+2. Checks dotCMS health at `/api/v1/appconfiguration`.
+3. Authenticates (up to 3 attempts).
+4. Reads `defaultSite` from `/api/v1/site/defaultSite`.
+5. Configures UVE via `/api/v1/apps/dotema-config-v2/{siteId}`.
+6. Scaffolds selected frontend and runs `npm install`.
+7. Prints framework-specific env setup instructions.
 
-For convenience, the CLI accepts common framework name variations (case-insensitive):
+### 2) Local mode (`--local`)
 
-- `next`, `next.js`, `Next.js` → `nextjs`
-- `ng`, `Angular` → `angular`
-- `angular-server` → `angular-ssr`
-- `angular-server` → `angular-ssr`
+Flow:
 
-### URL Format
+1. Validates Docker availability.
+2. Validates required ports: `8082`, `8443`, `9200`, `9600`.
+3. Downloads docker-compose from dotCMS main repo.
+4. Runs `docker compose up -d`.
+5. Waits for local health check.
+6. Authenticates with default local credentials (`admin@dotcms.com` / `admin`).
+7. Reads `defaultSite`, configures UVE, scaffolds frontend, runs `npm install`.
+8. Prints framework-specific env setup instructions.
 
-When using `--url`, make sure to include the full URL with protocol:
+### 3) Starter-only local mode (`--starter <url>`)
 
-✅ **Valid:** `https://demo.dotcms.com`, `http://localhost:8082`
-❌ **Invalid:** `demo.dotcms.com`, `localhost:8082` (missing protocol)
+`--starter` implies local mode.
 
----
+Flow:
 
-## 🛡️ Built-in Validation & Error Handling
+1. Same Docker and port checks as local mode.
+2. Downloads docker-compose.
+3. Rewrites `CUSTOM_STARTER_URL` in `docker-compose.yml`.
+4. Also passes `CUSTOM_STARTER_URL` in compose environment at runtime.
+5. Starts containers and waits for health check.
+6. Skips frontend scaffold and dotCMS frontend settings flow (token, default site lookup, UVE setup).
 
-The CLI includes comprehensive validation to help you avoid common setup issues:
+Use this when your starter is not compatible with the default frontend sample flow.
 
-### Input Validation
-- **Project names:** Validates against filesystem limitations, reserved names, special characters, and path traversal
-- **Framework names:** Supports aliases and case-insensitive matching
-- **URLs:** Ensures proper protocol and format
-- **Conflicting parameters:** Warns when mixing `--local` with cloud parameters
+## Examples
 
-### Docker Environment Checks
-When using local Docker setup, the CLI performs pre-flight checks:
+Interactive:
 
-1. **Docker Availability**
-   - Verifies Docker is installed and running
-   - Provides installation instructions if not found
-   - Direct link to Docker Desktop download
+```sh
+npx @dotcms/create-app my-blog
+```
 
-2. **Port Availability**
-   - Checks all required ports before starting containers
-   - Lists which specific ports are busy
-   - Provides platform-specific commands to identify blocking processes
-   - Suggests `docker compose down` to stop existing containers
+Local + specific framework:
 
-3. **Container Health**
-   - Monitors dotCMS startup with intelligent retries
-   - Shows detailed diagnostics if startup fails
-   - Displays container status and recent logs
+```sh
+npx @dotcms/create-app my-blog --local --framework nextjs
+```
 
-### Error Messages
-All error messages include:
-- **Clear problem description** - What went wrong
-- **Specific suggestions** - How to fix it
-- **Alternative solutions** - Other ways to proceed
-- **Platform-specific commands** - Commands tailored to your OS
+Starter-only local:
 
-### Debug Mode
-Run with `DEBUG=1` to see detailed stack traces:
 ```sh
-DEBUG=1 npx @dotcms/create-app my-project
+npx @dotcms/create-app my-blog --starter https://repo.example.com/path/starter.zip
 ```
 
----
+Cloud with flags:
 
-## 🔧 Troubleshooting
+```sh
+npx @dotcms/create-app my-blog \
+  --framework angular \
+  --url https://demo.dotcms.com \
+  --username admin@dotcms.com \
+  --password admin
+```
 
-### Docker Issues
+Debug errors with stack traces:
 
-**"Docker is not available"**
-- Ensure Docker Desktop is installed and running
-- Check the Docker icon in your system tray
-- Download from: https://www.docker.com/products/docker-desktop
+```sh
+DEBUG=1 npx @dotcms/create-app my-blog --local
+```
 
-**"Required ports are already in use"**
-- Check what's using the ports:
-  - macOS/Linux: `lsof -i :8082`
-  - Windows: `netstat -ano | findstr ":8082"`
-- Stop existing dotCMS containers: `docker compose down`
-- Stop conflicting services or choose a different port mapping
+## Validation Rules
 
-**"dotCMS failed to start properly"**
-- Check container logs: `docker logs <container-name>`
-- Verify sufficient system resources (RAM, disk space)
-- Review Docker diagnostics output from the CLI
+- URLs must include protocol (`http://` or `https://`).
+- Project names are validated for path traversal, invalid characters, reserved Windows names, and length.
+- If local mode is selected (`--local` or `--starter`), cloud flags are ignored with a warning.
+- Existing non-empty target directory requires confirmation before cleanup.
 
-### Validation Errors
+## Troubleshooting
 
-**"Invalid project name"**
-- Avoid special characters: `< > : " | ? *`
-- Don't use Windows reserved names: `CON`, `PRN`, `AUX`, `NUL`, etc.
-- Maximum 255 characters
-- No path traversal patterns (`..`)
+Docker not available:
 
-**"Invalid URL format"**
-- Include protocol: `https://` or `http://`
-- Verify hostname is correct
-- For localhost, default port is 8082
+- Install/start Docker Desktop, then retry.
 
----
+Ports already in use:
 
-## 🚀 Examples
+- macOS/Linux: `lsof -i :8082`
+- Windows: `netstat -ano | findstr ":8082"`
+- Stop conflicting services or run `docker compose down`.
 
-### Quick Start with Interactive Prompts
-```sh
-npx @dotcms/create-app my-blog
-```
+`zip END header not found` during starter load:
 
-### Using CLI Flags (Skip Prompts)
-```sh
-# Local Docker setup
-npx @dotcms/create-app my-blog --framework nextjs --local
+- Starter URL is reachable but not returning a valid ZIP payload.
+- Verify artifact URL, repository permissions, and response content type/body.
 
-# Cloud instance
-npx @dotcms/create-app my-blog \
-  --framework angular \
-  --url https://demo.dotcms.com \
-  --username admin@dotcms.com \
-  --password mypassword
-```
+## Development (this repo)
+
+Build:
 
-### Debug Mode
 ```sh
-DEBUG=1 npx @dotcms/create-app my-blog --framework nextjs --local
+yarn nx build sdk-create-app --skip-nx-cache
 ```
 
----
+Lint:
 
-## 🔒 Security Notes
+```sh
+yarn nx lint sdk-create-app
+```
 
-- Never commit API tokens or passwords to version control
-- The CLI validates all inputs to prevent injection attacks
-- Project names are sanitized to prevent path traversal
-- Shell commands are properly escaped for cross-platform safety
+Dist output:
 
+- `dist/libs/sdk/create-app/index.js`
+- ESM Node CLI bundle with shebang in production build
+- Publishable package includes JavaScript files and `README.md` only (no type declarations)