create-vexcms 0.1.0-alpha.2 → 0.1.0-alpha.21

package/README.md

@@ -1,5 +1,15 @@
 # create-vexcms
 
+> [!WARNING]
+> `create-vexcms` is pre-release software, published only under the `alpha` npm
+> dist-tag (`0.1.0-alpha.x`) — the `latest` tag on npm still points at an old,
+> unrelated `0.0.20` line, so always scaffold with an explicit tag:
+> `pnpm create vexcms@alpha`. Use it for experiments and evaluation only; the
+> projects it scaffolds should not carry production traffic or real user data.
+> Breaking changes land between alpha releases without deprecation cycles, and
+> there is no migration path between alphas. See the
+> [roadmap](https://docs.vexcms.dev) for what is and is not shipped.
+
 Scaffolding CLI for [VexCMS](https://github.com/ianyimi/vex) projects. Creates a complete
 Next.js application with a Convex backend, Better Auth authentication, and a self-hosted admin
 panel — ready to run.
@@ -7,19 +17,19 @@ panel — ready to run.
 ## Usage
 
 ```bash
-pnpm create vexcms@latest
+pnpm create vexcms@alpha
 ```
 
 Or with a project name:
 
 ```bash
-pnpm create vexcms@latest my-project
+pnpm create vexcms@alpha my-project
 ```
 
 Supports relative paths, including scaffolding straight into a monorepo app directory:
 
 ```bash
-pnpm create vexcms@latest apps/website
+pnpm create vexcms@alpha apps/website
 ```
 
 ## Flags
@@ -33,16 +43,16 @@ pnpm create vexcms@latest apps/website
 
 ```bash
 # Empty project, no pre-built collections
-pnpm create vexcms@latest my-app --bare
+pnpm create vexcms@alpha my-app --bare
 
 # Project with multi-tenant organizations
-pnpm create vexcms@latest my-app --orgs
+pnpm create vexcms@alpha my-app --orgs
 
 # Non-interactive, defaults only
-pnpm create vexcms@latest my-app --yes
+pnpm create vexcms@alpha my-app --yes
 
 # Inside a pnpm workspace, catalog-aware
-pnpm create vexcms@latest my-app --monorepo --yes
+pnpm create vexcms@alpha my-app --monorepo --yes
 ```
 
 ## Interactive prompts
@@ -90,6 +100,17 @@ site:
 - `convex/seed.ts` — an idempotent `init` mutation seeding site settings, a header, a footer, the
   starter palettes, and a complete home page from the blocks' own defaults (`pnpm seed`)
 
+### Configuration
+
+Every scaffold ships two config files: `src/vex.config.ts` — client-safe, holds collections,
+globals, media collections, access rules, and the auth collections
+`betterAuthCollections(authSchema)` derives from `src/auth/schema.ts` — and
+`src/vex.config.server.ts`, which layers the Better Auth adapter and the storage adapter(s)
+onto it via `defineServerConfig`. Nothing is generated for auth: `src/auth/schema.ts` is the
+one source of truth for model names and fields (organizations on or off, per the `--orgs`
+flag) — the client config calls `betterAuthCollections()` on it directly, and
+`src/auth/options.ts` spreads it into the real Better Auth options.
+
 ## Getting started
 
 After scaffolding:
@@ -110,13 +131,25 @@ First run only — links or creates a Convex project and prints your real
 replacing the generated placeholder values so the app stops pointing at
 `https://placeholder.convex.cloud`. Leave `Ctrl-C` once it reports functions are ready.
 
+`next.config.ts` derives `images.remotePatterns` from `NEXT_PUBLIC_CONVEX_URL`
+automatically, so `next/image` picks up the real deployment's hostname without any
+further edits.
+
 ### 2. Configure environment variables
 
 The installer writes `.env.local` with a generated `BETTER_AUTH_SECRET`,
 `NEXT_PUBLIC_SITE_URL`, and `SITE_URL` already filled in — only the two Convex URLs above need
-replacing for local dev. In the [Convex Dashboard](https://dashboard.convex.dev), add
-`BETTER_AUTH_SECRET` and `SITE_URL` under **Settings → Environment Variables** using the same
-values so server-side auth checks and email links resolve correctly.
+replacing for local dev.
+
+Better Auth runs *inside* the Convex deployment, not the Next.js server, so it never reads
+`.env.local`. Push the same two values to the deployment itself:
+
+```bash
+npx convex env set SITE_URL http://localhost:3010
+npx convex env set BETTER_AUTH_SECRET <the BETTER_AUTH_SECRET value from .env.local>
+```
+
+Skipping this step is the most common cause of a `403` on the first sign-in attempt.
 
 ### 3. Run the dev servers
 
@@ -145,7 +178,7 @@ Run from inside an existing pnpm workspace to scaffold a new app under it instea
 standalone project:
 
 ```bash
-pnpm create vexcms@latest my-app --monorepo --yes
+pnpm create vexcms@alpha my-app --monorepo --yes
 ```
 
 The installer walks up from the current directory for the nearest `pnpm-workspace.yaml`, targets
@@ -156,11 +189,12 @@ versions), and skips both `git init` and dependency install — the root workspa
 ## Versioning
 
 `create-vexcms` is versioned alongside every `@vexcms/*` package. Running
-`pnpm create vexcms@latest` always scaffolds with the latest package versions; pin a specific
-release the same way:
+`pnpm create vexcms@alpha` always scaffolds with the newest pre-release. The npm
+`latest` tag still points at an old, unrelated `0.0.20` line, so `@alpha` — or an
+exact version — is the only way to get the current API:
 
 ```bash
-pnpm create vexcms@0.1.0
+pnpm create vexcms@0.1.0-alpha.10
 ```
 
 The scaffolded project's `@vexcms/*` dependencies match the version of `create-vexcms` used to