create-rudder-app 0.0.19 → 0.0.20

package/README.md

@@ -1,19 +1,47 @@
 # create-rudder-app
 
-Interactive CLI scaffolder for [RudderJS](https://github.com/rudderjs/rudder) — a Laravel-inspired, framework-agnostic Node.js meta-framework built on Vike + Vite.
+**Spin up a production-ready [RudderJS](https://github.com/rudderjs/rudder) app in under 60 seconds** — with auth that works, a database wired, SSR views rendering, and optional AI / OAuth / real-time / cache / queue, all bootstrapped through Vite + Vike.
 
-## Usage
+```bash
+pnpm create rudder-app my-app
+cd my-app
+pnpm exec prisma generate && pnpm exec prisma db push
+pnpm dev
+# → http://localhost:3000 — welcome page + register/login working end-to-end
+```
+
+---
+
+## Install
 
-The installer auto-detects your package manager from the command you use:
+All four major package managers work. The installer detects which one you used and adapts every generated file, install command, and post-scaffold hint.
 
 ```bash
-pnpm create rudder-app
-npm create rudder-app@latest
-yarn create rudder-app
-bunx create-rudder-app
+pnpm create rudder-app [name]
+npm create rudder-app@latest [name]
+yarn create rudder-app [name]
+bunx create-rudder-app [name]
 ```
 
-All four package managers are fully supported — generated files, install commands, and next-step instructions adapt automatically.
+Skip `[name]` to be prompted for one.
+
+---
+
+## What you get out of the box
+
+With the **default choices** (Prisma + SQLite + Auth + Cache + React + Tailwind + shadcn/ui), you get a working fullstack app you can register into, log into, and sign out of — without writing any code:
+
+- **Welcome page at `/`** — controller-returned view, Tailwind + shadcn styled, with Log in / Register links or a signed-in user + Sign out button.
+- **Auth flow that works** — `/login`, `/register`, `/forgot-password`, `/reset-password` pages vendored into `app/Views/Auth/` (so you can customize them freely) and wired to `POST /api/auth/sign-in/email` / `sign-up/email` / `sign-out` / `request-password-reset` / `reset-password` endpoints.
+- **Database ready** — Prisma schema with a `User` + `PasswordResetToken` model, SQLite by default, a `User` ORM model.
+- **Session-based auth** — cookie sessions via `@rudderjs/session`, `AuthMiddleware` applied globally, ghost-user-safe (see the [mental model guide](https://github.com/rudderjs/rudder/blob/main/docs/guide/mental-model.md)).
+- **Rate limiting** — 10 req/min on auth endpoints out of the box.
+- **Bootstrap you can read** — `bootstrap/app.ts` in 25 lines, `bootstrap/providers.ts` shows auto-discovery, `config/` has one file per concern.
+- **Rudder CLI** — `pnpm rudder --help` lists framework commands; `routes/console.ts` shows you how to add your own.
+
+If you tick **AI** you get a `/ai-chat` demo. If you tick **MCP**, `POST /mcp/echo`. If you tick **Passport**, a full OAuth 2 server at `/oauth/authorize` / `/oauth/token`. Everything is opt-in and pay-as-you-go.
+
+---
 
 ## Prompts
 
@@ -21,7 +49,7 @@ The installer walks you through up to 9 prompts (several are conditional):
 
 | # | Prompt | Options | Default | Condition |
 |---|--------|---------|---------|-----------|
-| 1 | Project name | any string | — | always |
+| 1 | Project name | any string | — | always (skipped if passed as argv) |
 | 2 | Database ORM | Prisma · Drizzle · None | Prisma | always |
 | 3 | Database driver | SQLite · PostgreSQL · MySQL | SQLite | only if ORM selected |
 | 4 | Package checklist | multiselect (see below) | Auth + Cache | always |
@@ -31,6 +59,8 @@ The installer walks you through up to 9 prompts (several are conditional):
 | 8 | Add shadcn/ui? | yes / no | yes | only if React + Tailwind |
 | 9 | Install dependencies? | yes / no | yes | always |
 
+> **Not sure what to pick?** Accept every default — it produces the most-used stack (Prisma + SQLite + Auth + Cache + React + Tailwind + shadcn/ui) and is the best-tested path. You can always add packages later.
+
 ### Package checklist (prompt 4)
 
 | Choice | Description | Package |
@@ -44,20 +74,22 @@ The installer walks you through up to 9 prompts (several are conditional):
 | Scheduler | Cron-like task scheduling | `@rudderjs/schedule` |
 | WebSocket | Real-time channels | `@rudderjs/broadcast` |
 | Real-time Collab | Yjs CRDT sync | `@rudderjs/live` |
-| AI | LLM providers (Anthropic, OpenAI, Google, Ollama) | `@rudderjs/ai` |
+| AI | LLM providers (Anthropic, OpenAI, Google, Ollama, Groq, DeepSeek, xAI, Mistral, Azure) | `@rudderjs/ai` |
 | MCP | Model Context Protocol servers — expose tools/resources to LLMs | `@rudderjs/mcp` |
 | Passport (OAuth2) | OAuth 2 server with JWT — **requires Auth + Prisma** | `@rudderjs/passport` |
 | Localization | i18n — `trans()`, `setLocale()` | `@rudderjs/localization` |
 
-When **ai** is selected, generates `config/ai.ts`, `ai()` provider, an AI chat demo page at `/ai-chat`, and `POST /api/ai/chat` route.
+Package-specific behavior:
 
-When **mcp** is selected, generates `app/Mcp/EchoServer.ts` and wires a `POST /mcp/echo` route.
+- **AI** — generates `config/ai.ts`, AI chat demo at `/ai-chat`, `POST /api/ai/chat`.
+- **MCP** — generates `app/Mcp/EchoServer.ts` and wires `POST /mcp/echo`.
+- **Passport** — generates `config/passport.ts`, OAuth 2 routes (`/oauth/authorize`, `/oauth/token`, etc.), and `OAuthClient` + `OAuthAccessToken` Prisma models. Fails fast if Auth or Prisma isn't also selected.
 
-When **passport** is selected, generates `config/passport.ts`, OAuth 2 routes (`/oauth/authorize`, `/oauth/token`, etc.), and the `OAuthClient` + `OAuthAccessToken` Prisma models. Selecting this option fails fast if Auth or Prisma isn't also selected.
+Only selected packages get their dependencies, providers, config files, and schema files. Always-included base packages: `core`, `router`, `server-hono`, `middleware`, `vite`, `rudder`, `cli`, `log`. `session` + `hash` are pulled in automatically with Authentication.
 
-Only selected packages get their dependencies, providers, config files, and schema files added to the generated project. Base packages (`core`, `router`, `server-hono`, `middleware`, `vite`, `rudder`, `cli`, `log`) are always included. `session` + `hash` are pulled in automatically when **Authentication** is selected.
+---
 
-## What gets generated
+## Generated structure
 
 ```
 my-app/
@@ -96,7 +128,12 @@ my-app/
 └── package.json
 ```
 
-### Framework combinations
+---
+
+## Reference — framework combinations, CSS, PM differences
+
+<details>
+<summary>Framework selection → page extension + tsconfig</summary>
 
 | Selection | Page extension | tsconfig jsx |
 |-----------|---------------|--------------|
@@ -107,25 +144,31 @@ my-app/
 | React + Solid | `.tsx` — Vite plugins use include/exclude to disambiguate | `react-jsx` |
 | All three | `.tsx` or `.vue` depending on primary | `react-jsx` |
 
-**Single framework:** the renderer (`vike-react`, `vike-vue`, or `vike-solid`) is included directly in the root `+config.ts` — no per-page `+config.ts` needed.
+**Single framework:** the renderer (`vike-react`, `vike-vue`, or `vike-solid`) is included directly in the root `+config.ts`.
 
-**Multiple frameworks:** the root `+config.ts` has no renderer. Each page/folder declares its own `+config.ts` extending the appropriate renderer. Secondary frameworks get a minimal demo page at `pages/{fw}-demo/`.
+**Multiple frameworks:** the root `+config.ts` has no renderer. Each page folder declares its own `+config.ts` extending the appropriate renderer. Secondary frameworks get a minimal demo page at `pages/{fw}-demo/`.
+</details>
 
-### CSS variants
+<details>
+<summary>CSS variants based on Tailwind / shadcn selection</summary>
 
 | Selection | `src/index.css` content |
 |-----------|------------------------|
 | Tailwind + shadcn | Full shadcn CSS variables + `@import "shadcn/tailwind.css"` |
 | Tailwind only | `@import "tailwindcss"; @import "tw-animate-css";` |
 | No Tailwind | File not generated |
+</details>
 
-## Local development / testing
+<details>
+<summary>Package-manager differences in generated files</summary>
 
-```bash
-cd create-rudder-app
-pnpm build
-node dist/index.js          # launches the interactive CLI
-```
+| File | pnpm | npm / yarn | bun |
+|------|------|-----------|-----|
+| `pnpm-workspace.yaml` | generated | not generated | not generated |
+| `package.json` native-build field | `pnpm.onlyBuiltDependencies` | *(not needed)* | `trustedDependencies` |
+</details>
+
+---
 
 ## After scaffolding
 
@@ -141,11 +184,88 @@ The installer prints the exact commands for your package manager. For reference:
 | Passport keys (if Passport) | `pnpm rudder passport:keys` | `npm run rudder passport:keys` | `yarn rudder passport:keys` | `bun rudder passport:keys` |
 | Start dev server | `pnpm dev` | `npm run dev` | `yarn dev` | `bun dev` |
 
-When you let the installer run `Install dependencies`, it also runs `rudder providers:discover` automatically so the app boots on first `dev`. If you skipped install, run both manually before `dev`.
+When you let the installer run **Install dependencies**, it also runs `rudder providers:discover` automatically so the app boots on first `dev`. If you skipped install, run both manually before `dev`.
 
-## Package manager differences in generated files
+---
 
-| File | pnpm | npm / yarn | bun |
-|------|------|-----------|-----|
-| `pnpm-workspace.yaml` | generated | not generated | not generated |
-| `package.json` native-build field | `pnpm.onlyBuiltDependencies` | *(not needed)* | `trustedDependencies` |
+## Troubleshooting
+
+<details>
+<summary><strong>“[RudderJS] @rudderjs/X listed in the provider manifest but not installed”</strong></summary>
+
+The auto-discovery manifest (`bootstrap/cache/providers.json`) references a package you no longer have. Regenerate:
+
+```bash
+pnpm rudder providers:discover
+```
+</details>
+
+<details>
+<summary><strong>Register or login returns 500 with a Prisma error</strong></summary>
+
+Usually means the schema wasn't pushed. Run:
+
+```bash
+pnpm exec prisma generate
+pnpm exec prisma db push
+```
+</details>
+
+<details>
+<summary><strong>Passport endpoints 500 with “no private key found”</strong></summary>
+
+You skipped the key generation step. Run:
+
+```bash
+pnpm rudder passport:keys
+```
+
+Keys land in `storage/oauth-{private,public}.key`. They're gitignored — never commit them.
+</details>
+
+<details>
+<summary><strong>Port 3000 or HMR port 24678 already in use</strong></summary>
+
+```bash
+lsof -ti :24678 -ti :3000 | xargs kill -9
+```
+</details>
+
+<details>
+<summary><strong>Auth views didn't get copied — “run vendor:publish manually”</strong></summary>
+
+The installer tries to vendor `@rudderjs/auth/views/{react,vue}/` into `app/Views/Auth/`. If the copy fails (rare), run:
+
+```bash
+pnpm rudder vendor:publish --tag=auth-views-react   # or auth-views-vue
+```
+</details>
+
+---
+
+## Related
+
+- **Main framework**: [github.com/rudderjs/rudder](https://github.com/rudderjs/rudder)
+- **Docs**: [Mental model](https://github.com/rudderjs/rudder/blob/main/docs/guide/mental-model.md) · [Provider auto-discovery](https://github.com/rudderjs/rudder/blob/main/docs/guide/auto-discovery.md) · [Your first app](https://github.com/rudderjs/rudder/blob/main/docs/guide/your-first-app.md)
+- **Report issues**: [github.com/rudderjs/rudder/issues](https://github.com/rudderjs/rudder/issues)
+
+---
+
+## Contributing to the scaffolder
+
+```bash
+git clone https://github.com/rudderjs/rudder.git
+cd rudder/create-rudder-app
+pnpm install
+pnpm build
+node dist/index.js         # launches the interactive CLI from source
+pnpm test                  # 111 template tests
+```
+
+Template logic lives in `src/templates.ts` (pure — returns `Record<path, content>`, no filesystem). The entrypoint `src/index.ts` handles prompts + writes + installs. Adding a new package option touches both files + `templates.test.ts`.
+
+---
+
+## License
+
+MIT © [Suleiman Shahbari](https://github.com/rudderjs/rudder)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rudder-app",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "license": "MIT",
   "repository": {
     "type": "git",