create-aron-app 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # create-aron-app
 
-> CLI scaffolding tool for the Convex + Next.js + Clerk + Nx monorepo template.
+> CLI scaffolding tool that stamps out a production-ready Nx monorepo with Convex, Clerk, and either Next.js 15 or React Router v7.
 
 ## Usage
 
@@ -14,54 +14,66 @@ bunx create-aron-app
 
 The CLI will ask a few questions and scaffold a new project:
 
-- **Project name** — used as the directory name
-- **Output directory** — where to create the project (defaults to `./<name>`)
-- **Package manager** — Bun, pnpm, npm, or Yarn
+- **Project name** — lowercase alphanumeric + hyphens
+- **Framework** — Next.js 15 (App Router) or React Router v7 (SPA/Vite)
+- **Output directory** — where to create the project (defaults to `~/Desktop/<name>`)
+- **Package manager** — Bun (recommended), pnpm, npm, or Yarn
 - **Install dependencies** — run install automatically
 - **Initialize git** — create an initial commit
 
-## Development
-
-### Point to your GitHub repo
+## What gets scaffolded
 
-Edit `src/index.ts` and update `TEMPLATE_SOURCE`:
+The output is an **Nx monorepo** with two apps:
 
-```ts
-const TEMPLATE_SOURCE = "github:YOUR_USERNAME/project-template";
+```
+my-app/
+├── apps/
+│   ├── api/          # Convex backend (convex-ents + Zod validation)
+│   └── web/          # Next.js 15 or React Router v7 frontend
+├── shared/
+│   ├── ui/           # ~20 shadcn/Radix UI components + hooks
+│   ├── utils/        # Convex client helpers, date utils
+│   └── assets/       # global.css (Tailwind 4)
+├── emails/           # React Email templates
+├── scripts/          # sync_convex_env.ts
+├── .cursor/          # Pre-configured Cursor AI rules and skills
+└── .github/
+    └── workflows/ci.yml
 ```
 
-It uses [`giget`](https://github.com/unjs/giget) under the hood, which supports:
+A working **Todos** feature is wired end-to-end as the canonical example of the data model pattern.
 
-| Format | Example |
-|--------|---------|
-| GitHub | `github:user/repo` |
-| GitHub branch | `github:user/repo#main` |
-| GitHub subdirectory | `github:user/repo/subdir` |
-| GitLab | `gitlab:user/repo` |
-| Bitbucket | `bitbucket:user/repo` |
+## Stack
 
-For local testing, you can point it at a local path instead:
+- **Backend** — [Convex](https://docs.convex.dev) with [`convex-ents`](https://labs.convex.dev/convex-ents) for relational modeling and Zod-validated function wrappers
+- **Frontend** — [Next.js 15](https://nextjs.org) (App Router) or [React Router v7](https://reactrouter.com) (SPA/Vite)
+- **Auth** — [Clerk](https://clerk.com) wired to both Convex and the frontend
+- **Data fetching** — [TanStack Query v5](https://tanstack.com/query)
+- **UI** — Radix UI + Tailwind CSS 4 + shared component library
+- **Monorepo** — [Nx](https://nx.dev) with Bun workspaces
+- **Linting** — [Biome](https://biomejs.dev)
+- **AI** — Pre-baked Cursor rules and skills for the entire stack
 
-```ts
-const TEMPLATE_SOURCE = "/absolute/path/to/project-template";
-```
+## Development
 
 ### Build
 
 ```bash
-cd create
 bun run build
 ```
 
-Bundles `src/index.ts` into `dist/index.js` (a single Node.js-compatible file).
+Bundles `src/index.ts` into `dist/index.js` (a single Node.js-compatible file with a shebang).
 
 ### Test locally
 
 ```bash
-# Run the built file directly:
+# Run the CLI directly with Bun (no build needed):
+bun run start
+
+# Or build and run the output file:
 node dist/index.js
 
-# Or link globally for the full npm create experience:
+# Or link globally for the full `npm create` experience:
 npm link
 npm create aron-app
 
@@ -69,23 +81,46 @@ npm create aron-app
 npm unlink -g create-aron-app
 ```
 
-### Publish to npm
+### Publish
 
 ```bash
+# Patch release (bumps version + publishes):
+npm run release
+
+# Or manually:
 npm publish --access public
 ```
 
-## What happens after scaffolding
+Publishing is also automated via GitHub Actions — creating a GitHub Release triggers `.github/workflows/publish.yml`, which builds and publishes to npm.
 
-1. Template is downloaded from GitHub (no git history)
-2. Optionally: `git init` + initial commit
-3. Optionally: `bun install` (or your chosen package manager)
+### Project structure
 
-## Stack
+```
+create-aron-app/
+├── src/
+│   ├── index.ts          # CLI entrypoint (prompts + orchestration)
+│   ├── types.ts          # Shared TS types
+│   └── utils/
+│       ├── constant.ts   # Framework/PM options + dependency lists
+│       └── helpers.ts    # File ops, template merging helpers
+├── templates/
+│   ├── _base/            # Shared monorepo skeleton (copied first)
+│   ├── nextjs/           # Next.js 15 App Router variant
+│   └── react-router/     # React Router v7 SPA variant
+├── dist/                 # Built CLI output
+└── .github/
+    └── workflows/
+        └── publish.yml   # Auto-publish on GitHub Release
+```
 
-- **Backend** — [Convex](https://docs.convex.dev) with `convex-ents` for relational modeling
-- **Frontend** — [Next.js 15](https://nextjs.org) (App Router) + [TanStack Query](https://tanstack.com/query)
-- **Auth** — [Clerk](https://clerk.com)
-- **UI** — Radix UI + Tailwind CSS 4 + custom component library
-- **Monorepo** — [Nx](https://nx.dev) with Bun workspaces
-- **Linting** — [Biome](https://biomejs.dev)
+### How scaffolding works
+
+1. Copy `templates/_base/` into the output directory
+2. Copy the framework-specific template into `apps/web/`
+3. Rename `_gitignore` files to `.gitignore` (npm strips dotfiles on publish)
+4. Merge framework deps into the root `package.json`
+5. Inject the right Nx plugins into `nx.json`
+6. Replace the `project:` placeholder with the actual project name in all `project.json` files
+7. Promote `apps/web/.env.example` to the root as `.env.example`
+8. Optionally: `git init` + initial commit
+9. Optionally: `<pm> install`