|
| 1 | +# create-nitro-app |
| 2 | + |
| 3 | +CLI tool that scaffolds new [Nitro](https://nitro.build) applications with a single command. Part of the [nitrojs](https://github.com/nitrojs) ecosystem. |
| 4 | + |
| 5 | +Keep AGENTS.md updated with project structure and architecture. |
| 6 | + |
| 7 | +## Project Structure |
| 8 | + |
| 9 | +``` |
| 10 | +src/cli.ts # Main CLI entry point (single-file CLI) |
| 11 | +nitro-app/ # Reference Nitro starter template |
| 12 | +build.config.mjs # obuild config (bundles CLI + injects pkg metadata) |
| 13 | +dist/ # Compiled output (single bundled .mjs executable) |
| 14 | +``` |
| 15 | + |
| 16 | +## Architecture |
| 17 | + |
| 18 | +### CLI Flow (`src/cli.ts`) |
| 19 | + |
| 20 | +1. Display ASCII banner |
| 21 | +2. Prompt for target directory (default: `nitro-app`) |
| 22 | +3. Handle existing directory (override/rename/abort) |
| 23 | +4. Select template from registry |
| 24 | +5. Download template via `giget` from `https://raw.githubusercontent.com/nitrojs/starter/templates` |
| 25 | +6. Detect/select package manager and install dependencies |
| 26 | +7. Optionally initialize git repo |
| 27 | +8. Display next steps |
| 28 | + |
| 29 | +### CLI Arguments |
| 30 | + |
| 31 | +| Arg | Description | |
| 32 | +| ------------------------------- | ---------------------------------- | |
| 33 | +| `dir` (positional) | Target directory | |
| 34 | +| `--template/-t` | Template name | |
| 35 | +| `--force` | Overwrite existing directory | |
| 36 | +| `--forceClean` | Remove existing dir before cloning | |
| 37 | +| `--offline` / `--preferOffline` | Cache behavior | |
| 38 | +| `--install` | Install deps (default: true) | |
| 39 | +| `--packageManager/-p` | Specify PM (npm, pnpm, yarn, bun) | |
| 40 | +| `--gitInit` | Initialize git repo | |
| 41 | + |
| 42 | +### Templates |
| 43 | + |
| 44 | +Hardcoded in `src/cli.ts`: |
| 45 | + |
| 46 | +- **vite** - Full-stack with Vite |
| 47 | +- **cli** - Backend with Nitro CLI |
| 48 | + |
| 49 | +### Build System |
| 50 | + |
| 51 | +Uses **obuild** (rolldown-based bundler) to produce a single `dist/cli.mjs` executable (~793KB). Build-time injected globals: |
| 52 | + |
| 53 | +- `globalThis.__pkg_version__` |
| 54 | +- `globalThis.__pkg_name__` |
| 55 | +- `globalThis.__pkg_description__` |
| 56 | + |
| 57 | +## Key Dependencies |
| 58 | + |
| 59 | +| Package | Purpose | |
| 60 | +| ------------ | ---------------------------------------------- | |
| 61 | +| **citty** | CLI framework (commands, args) | |
| 62 | +| **consola** | Logging and interactive prompts | |
| 63 | +| **giget** | Template downloading from GitHub registry | |
| 64 | +| **nypm** | Package manager detection and dep installation | |
| 65 | +| **tinyexec** | Shell command execution (git init) | |
| 66 | + |
| 67 | +## Scripts |
| 68 | + |
| 69 | +```bash |
| 70 | +pnpm build # Bundle CLI with obuild |
| 71 | +pnpm create-nitro-app # Test CLI locally (node ./src/cli.ts) |
| 72 | +pnpm lint # ESLint + Prettier check |
| 73 | +pnpm fmt # automd + ESLint fix + Prettier format |
| 74 | +pnpm test # lint + type check |
| 75 | +pnpm release # test + changelog + publish + push |
| 76 | +``` |
| 77 | + |
| 78 | +## Conventions |
| 79 | + |
| 80 | +- ESM only (`"type": "module"`) |
| 81 | +- UnJS ESLint preset |
| 82 | +- Semantic commit messages with changelogen |
| 83 | +- TypeScript strict mode |
| 84 | +- 2-space indentation |
0 commit comments