create-convex-monorepo 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # create-convex-monorepo
 
-A TypeScript CLI that generates pnpm and Turborepo workspaces with multiple frontends sharing one typed Convex backend. Choose Next.js, Vite + React, TanStack Start, Expo, or a combination, with optional Clerk authentication.
+A TypeScript CLI that generates pnpm or bun workspaces. Turborepo runs multiple frontends sharing one typed Convex backend. Choose Next.js, Vite + React, TanStack Start, React Router v7, Expo, Astro + React island, SvelteKit, Nuxt, or a combination. React apps support optional Clerk, Convex Auth, WorkOS AuthKit, or Better Auth authentication on their supported frameworks. SvelteKit and Nuxt support auth `none` only.
 
 The generator composes framework templates and auth adapters. It does not copy a single starter and delete unwanted pieces. Choose blank apps or a messages example. The example includes a query and mutation, plus compile-time assertions for the shared API's argument and return types.
 
@@ -10,7 +10,7 @@ Convex already generates an API from your backend functions. Sharing that API be
 
 ## Usage
 
-Requires Node.js 22.12 or newer and pnpm for the generated workspace.
+Requires Node.js 22.12 or newer and pnpm or bun for the generated workspace.
 
 ```sh
 pnpm create convex-monorepo@latest
@@ -22,60 +22,85 @@ Or use npx:
 npx create-convex-monorepo@latest
 ```
 
-Both commands run the same CLI. You can also install it globally with `npm install --global create-convex-monorepo` and run `create-convex-monorepo` directly. Running through npx does not change the generated workspace's package manager, which is pnpm.
+Both commands run the same CLI. You can also install it globally with `npm install --global create-convex-monorepo` and run `create-convex-monorepo` directly. Running through npx does not change the generated workspace's package manager. The default is pnpm; select bun with `--package-manager bun` or the interactive prompt.
 
 Contributors can run the checkout with `pnpm dev`; see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Manage an existing workspace
 
-The same npm package also provides the `convex-monorepo` command. Install it in the generated workspace:
+Run the same CLI from the workspace root or any subdirectory. No global or project installation is needed:
 
 ```sh
-pnpm add -Dw create-convex-monorepo@latest
-pnpm exec convex-monorepo add
+npx create-convex-monorepo@latest
+```
+
+With a terminal attached, it detects `convex-monorepo.json` and offers a menu to add an app, add a shared package, add authentication, check the workspace, sync frontend URLs, update dependencies, or check for updates. Without a terminal, it prints management help without changing files.
+
+You can also run each command directly:
+
+```sh
+npx create-convex-monorepo@latest add app admin --framework vite --example none --dry-run
+npx create-convex-monorepo@latest add app admin --framework vite --example none --install
+npx create-convex-monorepo@latest add app mobile --framework expo --no-install
+npx create-convex-monorepo@latest add package shared --dry-run
+npx create-convex-monorepo@latest add package shared --no-install
+npx create-convex-monorepo@latest add auth clerk --dry-run
+npx create-convex-monorepo@latest add auth clerk --install
+npx create-convex-monorepo@latest add auth convex-auth --dry-run
+npx create-convex-monorepo@latest add auth convex-auth --install
+npx create-convex-monorepo@latest add auth better-auth --dry-run
+npx create-convex-monorepo@latest add auth better-auth --install
+npx create-convex-monorepo@latest add auth workos --dry-run
+npx create-convex-monorepo@latest add auth workos --install
+npx create-convex-monorepo@latest env sync --app mobile
+npx create-convex-monorepo@latest doctor
+npx create-convex-monorepo@latest upgrade --check
+npx create-convex-monorepo@latest upgrade --dry-run
+npx create-convex-monorepo@latest upgrade --install
 ```
 
-Or run it without installing a project dependency:
+The same commands work through pnpm:
 
 ```sh
-pnpm --package create-convex-monorepo@latest dlx convex-monorepo doctor
-npx --yes --package create-convex-monorepo@latest convex-monorepo doctor
+pnpm create convex-monorepo@latest add app admin --framework vite --no-install
+pnpm create convex-monorepo@latest doctor
 ```
 
-Run commands from the workspace root or any subdirectory:
+The separate `convex-monorepo` binary remains available for users who install the package locally or globally. For example, after `pnpm add -Dw create-convex-monorepo@latest`, run `pnpm exec convex-monorepo doctor`.
+
+To explicitly generate a new project, use `create <project-name>`. This also lets you use a command name such as `doctor` as the project name:
 
 ```sh
-pnpm exec convex-monorepo add app admin --framework vite --example none --dry-run
-pnpm exec convex-monorepo add app admin --framework vite --example none --install
-pnpm exec convex-monorepo add app mobile --framework expo --no-install
-pnpm exec convex-monorepo add auth clerk --dry-run
-pnpm exec convex-monorepo add auth clerk --install
-pnpm exec convex-monorepo env sync --app mobile
-pnpm exec convex-monorepo doctor
-pnpm exec convex-monorepo upgrade --check
+npx create-convex-monorepo@latest create doctor --apps vite --no-install --no-git
 ```
 
-| Command           | Behavior                                                                                                                                                  |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add app`         | Creates an app using the existing backend and auth, updates root scripts and metadata, and links the public backend URL when configured.                  |
-| `add auth clerk`  | Adds Clerk to generated app providers and the backend auth configuration. Customized files that need replacement cause a conflict.                        |
-| `env sync`        | Links only the public backend URL, using each framework's variable prefix. Supports `--app` and `--dry-run`.                                              |
-| `doctor`          | Checks workspace configuration, installed dependencies, environment settings, and shared API types. Supports `--json`; errors exit with status 1.         |
-| `upgrade --check` | Compares generator versions with npm's latest stable release and reports the running CLI's tested dependency baseline through `--json`. Makes no changes. |
+| Command           | Behavior                                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `add app`         | Creates an app using the existing backend and auth, updates root scripts and metadata, and links the public backend URL when configured.                                        |
+| `add package`     | Creates a blank shared TypeScript package under `packages/<name>` and records it in metadata.                                                                                   |
+| `add auth`        | Adds Clerk, Convex Auth, WorkOS AuthKit, or Better Auth to generated app providers and the backend auth configuration. Customized files that need replacement cause a conflict. |
+| `env sync`        | Links only the public backend URL, using each framework's variable prefix. Supports `--app` and `--dry-run`.                                                                    |
+| `doctor`          | Checks workspace configuration, installed dependencies, environment settings, and shared API types. Supports `--json`; errors exit with status 1.                               |
+| `upgrade`         | Updates existing exact dependency pins and the recorded package-manager version to the running CLI's tested baseline. Keeps newer pins and rejects non-exact customizations.    |
+| `upgrade --check` | Compares generator versions with npm's latest stable release and reports the running CLI's tested dependency baseline through `--json`. Makes no changes.                       |
 
-The add commands support `--dry-run`, `--install`, `--no-install`, and `--yes`. Without prompts, provide the app name and framework; dependency installation defaults to off. `--yes` enables installation unless `--no-install` is set, and never overrides conflicts. A dry run shows file paths without printing environment values or installing dependencies.
+The `add app`, `add package`, `add auth`, and `upgrade` commands support `--dry-run`, `--install`, `--no-install`, and `--yes`. Without prompts, provide the app name and framework for `add app`, the package name for `add package`, or `clerk`, `convex-auth`, `workos`, or `better-auth` for `add auth`. Dependency installation defaults to off. `--yes` enables installation unless `--no-install` is set, and never overrides conflicts. A dry run shows file paths without printing environment values or installing dependencies.
 
-Existing workspaces with metadata version 1, including projects created with 0.2.1, are supported. Preserve `convex-monorepo.json`; the CLI reads it rather than guessing which directories belong to your project. Per-app starter choices are recorded there when they differ from the original selection.
+Existing pnpm workspaces with metadata version 1, including projects created with 0.2.1, are supported. Bun workspaces also use metadata version 1. Preserve `convex-monorepo.json`; the CLI reads it rather than guessing which directories belong to your project. Per-app starter choices are recorded there when they differ from the original selection. Shared packages added by the CLI are recorded in the optional `packages` list as `{ "name": "shared" }` entries.
 
 ### Changes and conflicts
 
-Commands plan every file before applying changes. They reject unsafe paths, symlinks, existing app directories, conflicting scripts or dependencies, and customized auth files that would need replacement. App addition requires the generated `apps/*` and `packages/*` workspace layout and Turbo dev script. Adding a messages UI also requires the generated messages backend contract; use `--example none` with a customized backend.
+Commands plan every file before applying changes. They reject unsafe paths, symlinks, existing app or package paths, conflicting scripts or dependencies, and customized auth files that would need replacement. App addition requires the generated `apps/*` and `packages/*` workspace layout and Turbo dev script. Adding a messages UI also requires the generated messages backend contract; use `--example none` with a customized backend. Adding SvelteKit also updates an unchanged older URL setup script and adds formatter ignores for its generated output; customized setup scripts cause a conflict. Adding Astro or Nuxt to an older workspace also updates its recognized setup helper, adds the framework's public environment prefix to Turbo settings, and ignores its generated output. Astro adds `PUBLIC_*` and `.astro/`; Nuxt adds `NUXT_PUBLIC_*`, `.nuxt/`, and `.output/`. A customized setup helper that cannot be upgraded causes a conflict before writes. Restore the generated helper, add the app, then reapply custom changes.
+
+Package addition creates plain TypeScript source with shared lint and typecheck settings. Add `"@<scope>/<name>": "workspace:*"` to each consuming app's dependencies, then run `pnpm install`. Next configs are updated when they match the generated config apart from the `transpilePackages` string list, so repeated `add package` calls keep appending. A missing config or any other customization produces a note with the required manual edit. Other frameworks need no config change.
 
-Auth addition supports `none` to Clerk. It preserves backend schemas, functions, generated internals, unrelated package fields, and existing README content. Follow the new `CLERK_SETUP.md` for account configuration. Existing public messages do not acquire an owner automatically and will not appear in authenticated accounts. Review stored-data migration separately. Already configured Clerk is a no-op; replacing an auth provider is not supported.
+Auth addition supports `none` to Clerk, Convex Auth, WorkOS AuthKit, or Better Auth. It preserves user functions, generated internals, unrelated package fields, and existing README content. Convex Auth adds `authTables` to a generated schema or a customized schema with a single `defineSchema` call taking an object literal. Other schema shapes need the two manual edits named in the conflict. A customized HTTP router needs a manual `auth.addHttpRoutes(http)` call. Follow the new `CLERK_SETUP.md`, `CONVEX_AUTH_SETUP.md`, `WORKOS_SETUP.md`, or `BETTER_AUTH_SETUP.md` for setup. For Convex Auth, run `pnpm install`, then `pnpm convex:auth-keys`; refresh generated types with `pnpm convex:dev` or `convex codegen`. Existing public messages do not acquire an owner automatically and will not appear in authenticated accounts. Review stored-data migration separately. Adding the configured provider again is a no-op; replacing an auth provider is not supported.
 
 A workspace lock prevents two CLI edits from running together. Each planned file is checked again before writing. Failed edits roll back files that still contain this command's output; observed concurrent edits are preserved and reported. Filesystem checks are optimistic, so avoid editing affected files while a command is applying. A failed dependency installation leaves the applied files available for retry with `pnpm install`.
 
-Doctor is read-only and uses an in-memory TypeScript probe. It does not run application scripts, start services, configure a deployment, validate a real Clerk session, or prove a native Expo build works. Missing installation or environment configuration is reported with suggested steps. The upgrade command does not rewrite files, migrate templates, or update dependency versions.
+Doctor is read-only and uses an in-memory TypeScript probe. It does not run application scripts, start services, configure a deployment, validate a real Clerk session, or prove a native Expo build works. Missing installation or environment configuration is reported with suggested steps.
+
+Upgrade updates matching dependency entries in root, app, and shared-package manifests and records the running CLI version in metadata. It never downgrades exact pins. Non-exact managed pins, such as `^` ranges, cause a conflict before any writes. User-added dependencies and unrelated package fields are preserved; missing tested dependencies are reported but not added. Manifests are rewritten from parsed JSON, so comments are not supported and integer values above 2^53 lose precision. Upgrade does not migrate template files or write the lockfile itself. Run `pnpm install` afterward, or use `--install`, to update the lockfile.
 
 ## Interactive usage
 
@@ -83,14 +108,15 @@ With a terminal attached, the CLI asks for missing choices:
 
 ```text
 Project name?           my-app
-Package manager?        pnpm
+Package manager?        pnpm / bun (default: pnpm)
 Application framework?  Next.js
 Application name?       web
 Add another frontend?   Yes
 Application framework?  Expo / React Native
 Application name?       mobile
 Add another frontend?   No
-Authentication?         Clerk
+Authentication?         Convex Auth (email + password)
+OAuth providers?        None
 Starter content?        Blank project
 Initialize git?         Yes
 Initialize Convex and link frontend URLs?   Yes
@@ -107,20 +133,43 @@ pnpm create convex-monorepo@latest my-app --apps web:next,admin:vite --no-instal
 pnpm create convex-monorepo@latest my-app --apps app:tanstack-start,dashboard:next --auth none --package-manager pnpm --yes
 ```
 
-| Option                              | Meaning                                                     |
-| ----------------------------------- | ----------------------------------------------------------- |
-| `--apps`                            | Comma-separated framework IDs or `name:framework` entries   |
-| `--auth`                            | `none`, the default, or `clerk`                             |
-| `--example`                         | `messages`, the default, or `none` for blank projects       |
-| `--package-manager`                 | `pnpm`; other managers are rejected in v0.1                 |
-| `--install`, `--no-install`         | Enable or skip dependency installation                      |
-| `--init-convex`, `--no-init-convex` | Initialize Convex and link URLs; enables installation       |
-| `--git`, `--no-git`                 | Enable or skip `git init`; no commit is created             |
-| `--yes`, `-y`                       | Skip prompts and accept defaults, including install and git |
-| `--help`, `--version`               | Show usage or the generator version                         |
+| Option                              | Meaning                                                                 |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `--apps`                            | Comma-separated framework IDs or `name:framework` entries               |
+| `--auth`                            | `none`, the default, `clerk`, `convex-auth`, `workos`, or `better-auth` |
+| `--oauth`                           | Optional comma list `github,google`; requires `--auth convex-auth`      |
+| `--example`                         | `messages`, the default, or `none` for blank projects                   |
+| `--package-manager`                 | `pnpm`, the default, or `bun`; npm and yarn are rejected                |
+| `--install`, `--no-install`         | Enable or skip dependency installation                                  |
+| `--init-convex`, `--no-init-convex` | Initialize Convex and link URLs; enables installation                   |
+| `--git`, `--no-git`                 | Enable or skip `git init`; no commit is created                         |
+| `--yes`, `-y`                       | Skip prompts and accept defaults, including install and git             |
+| `--help`, `--version`               | Show usage or the generator version                                     |
 
 Without a terminal, prompts are disabled and install/git default to off unless explicitly enabled or `--yes` is passed. Explicit negative flags override `--yes`. Convex initialization defaults to off when prompts are skipped, including with `--yes`; request it explicitly with `--init-convex`. That flag still lets Convex prompt for an account or deployment, and conflicts with `--no-install`. The default app is Next.js. Project and app names must be lowercase letters, digits, and hyphens, at most 100 characters, with no path separators or reserved device names.
 
+## Bun workspaces
+
+Select bun in the "Package manager?" prompt or pass the flag:
+
+```sh
+npx create-convex-monorepo@latest my-app --apps next,expo --package-manager bun --install --no-git
+cd my-app
+bun run convex:setup
+bun run dev
+bun run typecheck
+bun run lint
+bun run build
+```
+
+If installation was skipped, run `bun install` first. Use `bun run convex:link`, `bun run convex:dev`, for Convex Auth, `bun run convex:auth-keys`, and for Better Auth, `bun run convex:better-auth-env`. The pnpm script examples in this README use `bun run <script>` in bun workspaces. Run backend binaries from the root with `bun run --cwd packages/backend convex <command>`.
+
+Bun workspaces put `apps/*` and `packages/*` in the root manifest's `workspaces` list and pin bun in `packageManager`. They keep Turborepo and `workspace:*` dependencies. Commit `bun.lock`; no `pnpm-workspace.yaml` is generated. Existing-workspace commands read the recorded manager, including when invoked through npx or pnpm. `--install` uses that manager, and upgrade updates its version pin. This does not migrate existing pnpm workspaces.
+
+Keep Node.js 22.12+ installed for the CLI and framework tools. Bun's dependency lifecycle policy differs from pnpm's; the template trusts only esbuild, sharp, and unrs-resolver, matching the pnpm template's build allowlist. Review scripts before trusting additional dependencies. Expo keeps its default Metro configuration; JavaScript export does not verify native Xcode or Gradle builds. See [bun and Expo findings](docs/research.md#bun-workspaces).
+
+Metadata stays at version 1. Older CLI releases that validate the manager as pnpm-only reject bun workspaces; use a CLI release with bun support to manage them.
+
 ## Blank projects
 
 Choose **Blank project** in the starter-content prompt, or pass `--example none`:
@@ -129,22 +178,34 @@ Choose **Blank project** in the starter-content prompt, or pass `--example none`
 pnpm create convex-monorepo@latest my-app --apps next,expo --example none --yes
 ```
 
-Every selected app starts with a minimal page or screen showing its name. Convex providers, workspace dependencies, environment setup, and the selected auth integration remain configured. The backend has an empty schema and official generated types. There are no example tables, messages functions, access helpers, query/mutation screens, or demo-specific type-test files to remove.
+Every selected app starts with a minimal page or screen showing its name. Convex providers, workspace dependencies, environment setup, and the selected auth integration remain configured. The backend has official generated types and an empty schema, except Convex Auth projects retain their auth tables and functions. Better Auth keeps its tables in the component and exposes the current-user query. There are no example tables, messages functions, access helpers, query/mutation screens, or demo-specific type-test files to remove.
 
-Add your tables to `packages/backend/convex/schema.ts` and your functions beside it. Run `pnpm convex:dev` to generate their shared API references. With Clerk, add server-side identity and authorization checks to your protected functions. The blank starter retains sign-in controls and the existing authenticated provider behavior.
+Add your tables to `packages/backend/convex/schema.ts` and your functions beside it. Run `pnpm convex:dev` to generate their shared API references. With any auth provider, add server-side identity and authorization checks to your protected functions. The blank starter retains sign-in controls and the existing authenticated provider behavior.
 
 The choice applies to the whole workspace. `--example messages` keeps the existing query/mutation demo and remains the default, including with `--yes`.
 
 ## Supported frameworks
 
-| ID               | Application              | Public Convex variable   |
-| ---------------- | ------------------------ | ------------------------ |
-| `next`           | Next.js App Router       | `NEXT_PUBLIC_CONVEX_URL` |
-| `vite`           | Vite + React             | `VITE_CONVEX_URL`        |
-| `tanstack-start` | TanStack Start with Vite | `VITE_CONVEX_URL`        |
-| `expo`           | Expo / React Native      | `EXPO_PUBLIC_CONVEX_URL` |
+| ID               | Application                                                         | Public Convex variable   | Convex data loading                                    |
+| ---------------- | ------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------ |
+| `next`           | Next.js App Router                                                  | `NEXT_PUBLIC_CONVEX_URL` | Client React hooks                                     |
+| `vite`           | Vite + React                                                        | `VITE_CONVEX_URL`        | Client React hooks                                     |
+| `tanstack-start` | TanStack Start with Vite                                            | `VITE_CONVEX_URL`        | Client React hooks, no server prefetch                 |
+| `react-router`   | React Router v7 framework mode, SSR enabled                         | `VITE_CONVEX_URL`        | Client React hooks, no server prefetch or data loaders |
+| `expo`           | Expo / React Native                                                 | `EXPO_PUBLIC_CONVEX_URL` | Client React hooks                                     |
+| `astro`          | Astro + React island                                                | `PUBLIC_CONVEX_URL`      | Client React hooks in a client-only island             |
+| `sveltekit`      | SvelteKit with Svelte 5                                             | `PUBLIC_CONVEX_URL`      | Client Svelte queries, no server preloading            |
+| `nuxt`           | Nuxt, auth `none` only; Node `^22.19.0 \|\| ^24.11.0 \|\| >=26.0.0` | `NUXT_PUBLIC_CONVEX_URL` | Client Vue composables inside `ClientOnly`             |
 
-Versions are pinned in the templates. Start uses ordinary Convex React hooks; server-side Convex prefetching is not configured. Expo's build command exports JavaScript, not native application binaries. See [research and upstream caveats](docs/research.md).
+Nuxt uses Vue and supports only `--auth none`, including workspaces that mix Nuxt, SvelteKit, and React apps. Adding Nuxt to an authenticated workspace or adding auth to a workspace containing Nuxt is rejected before files change.
+
+Nuxt keeps SSR enabled, but its Convex plugin and messages component run only in the browser. `NUXT_PUBLIC_CONVEX_URL` maps to `runtimeConfig.public.convexUrl`. Dev, build, and preview read `.env.local`; production servers accept the variable at runtime. Typechecking runs `nuxt prepare`, then `vue-tsc --noEmit` against both `.nuxt/tsconfig.json` and `.nuxt/tsconfig.server.json` to check app and server code. Lint uses `eslint-plugin-vue` with the shared TypeScript rules.
+
+SvelteKit currently supports only `--auth none`, for both starters. It can share a workspace with any of the React frameworks when auth is `none`. Adding SvelteKit to an authenticated workspace or adding auth to a workspace containing SvelteKit fails before files are written.
+
+Astro generates a static page with a React island mounted through `client:only="react"`. Convex and auth run in the browser. Its `typecheck` script uses `astro check`; Clerk uses the official `@clerk/astro` integration and middleware. No SSR adapter is needed for the static page.
+
+Versions are pinned in the templates. React Router follows the Vite framework scaffold with `app/root.tsx`, `app/routes.ts`, and `app/routes/home.tsx`. Its typecheck script generates route types before running TypeScript. Its root loader handles auth only; Convex queries and mutations use the shared client components. Expo's build command exports JavaScript, not native application binaries. See [research and upstream caveats](docs/research.md).
 
 ## Generated architecture
 
@@ -164,7 +225,7 @@ my-app/
 │   ├── typescript-config/
 │   └── eslint-config/
 ├── convex-monorepo.json
-├── pnpm-workspace.yaml
+├── pnpm-workspace.yaml                 # pnpm only
 ├── turbo.json
 └── package.json
 ```
@@ -179,7 +240,7 @@ Use explicit names to choose folders and repeat a framework:
 pnpm create convex-monorepo@latest acme --apps web:next,admin:next,mobile:expo --yes
 ```
 
-Apps become `@acme/web`, `@acme/admin`, and `@acme/mobile`. All depend on `@acme/backend` through `workspace:*`. The generator assigns distinct web development ports. v0.1 creates a new workspace; adding an app to an existing workspace is not implemented.
+Apps become `@acme/web`, `@acme/admin`, and `@acme/mobile`. All depend on `@acme/backend` through `workspace:*`. The generator assigns distinct web development ports. Use `npx create-convex-monorepo@latest add app` to add another frontend later.
 
 ## First run and development
 
@@ -203,7 +264,20 @@ pnpm lint
 pnpm build
 ```
 
-Complete setup in a normal terminal before starting Turbo. Stop a separately running backend watcher before `pnpm dev`, which starts its own. Public environment values are embedded at build time; rebuild frontends when they change. Backend build checks types and does not deploy.
+Complete setup in a normal terminal before starting Turbo. Stop a separately running backend watcher before `pnpm dev` or `bun run dev`, which starts its own. SvelteKit reads `PUBLIC_CONVEX_URL` from `$env/static/public`, so set it before typechecking or building. Its root layout mounts the Svelte Convex provider; messages subscribe with `useQuery`.
+
+Public environment values are embedded at build time; rebuild frontends when they change. Backend build checks types and does not deploy.
+
+## Code formatting
+
+Generated source and configuration files are formatted with Prettier before they are written, including when using `--no-install`. New workspaces include a pinned Prettier dependency and matching configuration:
+
+```sh
+pnpm format
+pnpm format:check
+```
+
+Svelte components use the pinned `prettier-plugin-svelte` formatter. Convex `_generated` files, TanStack's generated route tree, React Router's `.react-router` types, SvelteKit's generated files, build output, lockfiles, and environment files are excluded. Adding an app formats its new files; it does not reformat existing application code. Auth migration accepts formatting differences in older starters while still rejecting customized code that would be replaced.
 
 ## Convex backend sharing
 
@@ -218,7 +292,153 @@ Dynamic Convex declarations refer to backend source modules. Client TypeScript p
 
 ## Authentication
 
-`--auth clerk` adds SDK-specific bindings, a Convex auth configuration, and provider wiring. The messages example also includes backend identity checks and an owner index that keeps messages private. With `--auth none`, that example is a public message board. Blank projects have no data or functions; add authorization checks when writing protected functions. UI visibility alone is not authorization.
+New projects accept `none`, `clerk`, `convex-auth`, or `better-auth` across the six React frameworks and both starters. SvelteKit and Nuxt support only `none`; the generator has no Svelte or Vue binding for Clerk, Convex Auth, WorkOS, or Better Auth. Existing no-auth workspaces without Nuxt or SvelteKit accept `add auth clerk`, `add auth convex-auth`, `add auth workos`, or `add auth better-auth`. All providers support `add app` for their supported frameworks. WorkOS AuthKit supports Next.js, Vite, and TanStack Start with both starters. Expo, Astro, React Router, SvelteKit, and Nuxt are rejected before writing files. Expo has no official React Native AuthKit SDK. The [official Astro SDK](https://github.com/workos/authkit-astro) requires a server adapter and on-demand rendering; this generator uses static Astro output.
+React Router has an official SDK, but this generator has no binding for it yet.
+
+`--auth convex-auth` and `add auth convex-auth` configure email and password sign-up/sign-in, sign-out, and per-user backend access. Web apps use the client ConvexAuthProvider; Expo persists tokens with expo-secure-store. No frontend public auth keys or password-flow redirect scheme are needed. Next.js, TanStack Start, and React Router do not configure server-side authentication or authenticated SSR. GitHub and Google OAuth are opt-in with `--oauth github,google`. Magic links, email verification, password reset, and MFA are outside this starter.
+
+Run `pnpm convex:setup`, then `pnpm convex:auth-keys`. The key script generates an RSA 2048 key pair and sets `JWT_PRIVATE_KEY` and `JWKS` on the deployment through the installed Convex CLI. It never stores the key locally or prints either value. The initial push can finish before keys exist, but sign-in fails until they are configured. Run `pnpm convex:auth-keys --prod` to set a separate pair for production. `SITE_URL` is a deployment setting for redirects and is optional for this Password-only flow. The generated `.env.convex-auth.example` belongs to the backend package. See the [official manual setup](https://labs.convex.dev/auth/setup/manual).
+
+### Optional GitHub and Google OAuth
+
+Keep Password sign-in and add either or both providers:
+
+```sh
+pnpm create convex-monorepo@latest my-app --apps next,expo --auth convex-auth --oauth github,google
+npx create-convex-monorepo@latest add auth convex-auth --oauth google --install
+```
+
+OAuth supports both package managers. The examples below use pnpm. For bun workspaces, use `bun install`, replace `pnpm <script>` with `bun run <script>`, and replace `pnpm --filter @my-app/backend exec convex` with `bun run --cwd packages/backend convex`. Generated setup instructions use the selected manager.
+
+The interactive OAuth multiselect defaults to none. `--oauth` is valid only with Convex Auth; unknown providers fail before generation. Both starters and all six React frameworks support it, including the Astro React island. Nuxt and SvelteKit reject Convex Auth, including OAuth, before generation or workspace changes. Metadata version 1 records the selected providers in an optional `oauth` array. `add auth` accepts this flag only on a no-auth workspace. Adding OAuth to a workspace with authentication already configured requires the manual edits below.
+
+For OAuth, `SITE_URL` is required on the Convex deployment. Generated OAuth workspaces include a helper that leaves signing keys unchanged:
+
+```sh
+pnpm convex:auth-site http://localhost:3000
+pnpm convex:auth-site https://your-app.example --prod
+```
+
+Set `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, `AUTH_GOOGLE_ID`, and `AUTH_GOOGLE_SECRET` for the selected providers with `pnpm --filter @my-app/backend exec convex env set <name> <value>` or the Convex dashboard. These are deployment settings, never frontend public environment variables. The backend `.env.convex-auth.example` lists the selected settings.
+
+Create the OAuth applications in GitHub's developer settings and Google's Cloud console. Register the callback for each selected provider:
+
+| Provider | Callback URL                                 |
+| -------- | -------------------------------------------- |
+| GitHub   | `<CONVEX_SITE_URL>/api/auth/callback/github` |
+| Google   | `<CONVEX_SITE_URL>/api/auth/callback/google` |
+
+`CONVEX_SITE_URL` is the deployment's HTTPS `.convex.site` URL. Use separate provider applications and credentials for development and production. Web buttons start `signIn('github')` or `signIn('google')`; successful sign-ins return to `SITE_URL`. Browser OAuth must start on the SITE_URL origin so the returning page can read its stored verifier. For additional web origins, change the web handler to `signIn(provider, { redirectTo: window.location.href })` and allow those origins in the backend redirect callback. Changing only the callback is insufficient.
+
+Expo uses the scheme already defined in `app.json`, `ccm-<project>-<app>`, with return URL `ccm-<project>-<app>://auth`. Use `pnpm ios` or `pnpm android` in the app directory to create a development build. Expo Go cannot handle this custom scheme. The provider console uses the HTTPS Convex callback above, then Convex redirects to the app scheme. Register the scheme return URL in any native redirect allowlist required by the provider console. Do not replace the GitHub or Google web client's HTTPS callback with the app scheme.
+
+The generated native handler uses `expo-linking` to create the return URL and `expo-web-browser` to open the URL returned by `signIn(provider, { redirectTo })`. It completes successful browser sessions with `signIn(provider, { code })`. The backend allows only the generated native return URLs and the configured web origin. Keep those URLs and the app scheme aligned if you rename an app. See [Convex Auth OAuth](https://labs.convex.dev/auth/config/oauth) and [Expo authentication](https://docs.expo.dev/guides/authentication/).
+
+### Add OAuth to an existing Convex Auth workspace
+
+This is a manual edit. In `packages/backend/convex/auth.ts`, retain Password and add the selected imports and array entries. These OAuth providers come from the existing pinned `@auth/core` dependency; `@convex-dev/auth@0.0.95` does not export GitHub or Google provider modules.
+
+```ts
+import { convexAuth } from '@convex-dev/auth/server';
+import { Password } from '@convex-dev/auth/providers/Password';
+import GitHub from '@auth/core/providers/github';
+import Google from '@auth/core/providers/google';
+
+export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
+  providers: [Password, GitHub, Google],
+});
+```
+
+Remove the import and array entry for any provider you do not want. In each web app's `src/auth-controls.tsx`, add these buttons inside the signed-out form, beside the Password controls:
+
+```tsx
+<button type="button" disabled={pending} onClick={() => {
+  void signIn('github').catch(() => setError('Could not sign in. Try again.'));
+}}>Sign in with GitHub</button>
+<button type="button" disabled={pending} onClick={() => {
+  void signIn('google').catch(() => setError('Could not sign in. Try again.'));
+}}>Sign in with Google</button>
+```
+
+For Expo, add exact dependencies `"expo-web-browser": "57.0.3"` and `"expo-linking": "57.0.10"` to the app's `package.json`, then run `pnpm install`. Confirm the `expo.scheme` value in `app.json`. Add these imports to `src/auth-controls.tsx`:
+
+```ts
+import * as Linking from 'expo-linking';
+import { openAuthSessionAsync } from 'expo-web-browser';
+```
+
+Add this handler inside `AuthControls`, replacing `ccm-my-app-mobile` with the actual scheme:
+
+```tsx
+async function authenticateOAuth(provider: 'github' | 'google') {
+  if (pending) return;
+  setPending(true);
+  setError(null);
+  try {
+    const redirectTo = Linking.createURL('auth', {
+      scheme: 'ccm-my-app-mobile',
+    });
+    const { redirect } = await signIn(provider, { redirectTo });
+    if (!redirect) throw new Error('Missing sign-in URL.');
+    const result = await openAuthSessionAsync(redirect.toString(), redirectTo);
+    if (result.type === 'success') {
+      const code = new URL(result.url).searchParams.get('code');
+      if (!code) throw new Error('Missing sign-in code.');
+      await signIn(provider, { code });
+    }
+  } catch (cause) {
+    setError(cause instanceof Error ? cause.message : 'Could not sign in.');
+  } finally {
+    setPending(false);
+  }
+}
+```
+
+Add native buttons inside the signed-out `View`:
+
+```tsx
+<Button title="Sign in with GitHub" disabled={pending} onPress={() => { void authenticateOAuth('github'); }} />
+<Button title="Sign in with Google" disabled={pending} onPress={() => { void authenticateOAuth('google'); }} />
+```
+
+For a shared web and native backend, add this `callbacks` property beside `providers` in `convexAuth`. Replace the example native URL with the actual scheme, adding each native app's exact return URL to the array:
+
+```ts
+callbacks: {
+  async redirect({ redirectTo }) {
+    const siteUrl = process.env.SITE_URL;
+    if (!siteUrl) throw new Error('Set SITE_URL on the Convex deployment.');
+    if (['ccm-my-app-mobile://auth'].includes(redirectTo)) return redirectTo;
+    const target = new URL(redirectTo, siteUrl);
+    if (target.origin === new URL(siteUrl).origin && ['http:', 'https:'].includes(target.protocol)) {
+      return target.toString();
+    }
+    throw new Error('Invalid OAuth redirect destination.');
+  },
+},
+```
+
+To enable OAuth from multiple web frontends, pass `{ redirectTo: window.location.href }` as the second argument to each web `signIn` call. Replace the callback's same-origin condition above with an explicit list of trusted origins, using your actual addresses:
+
+```ts
+const allowedOrigins = [new URL(siteUrl).origin, 'http://localhost:3001'];
+if (
+  allowedOrigins.includes(target.origin) &&
+  ['http:', 'https:'].includes(target.protocol)
+) {
+  return target.toString();
+}
+```
+
+Use production origins in production. Do not allow arbitrary URLs supplied by the client.
+
+Configure credentials and callbacks as above. Set `SITE_URL` with `pnpm --filter @my-app/backend exec convex env set SITE_URL http://localhost:3000`, or use the scheme return URL for a mobile-only workspace. Add `"oauth": ["github", "google"]` to `convex-monorepo.json`, omitting unselected providers. Add `# SITE_URL is required for OAuth` and the selected `AUTH_*` variable names to `packages/backend/.env.convex-auth.example`. Run `pnpm convex:dev` to push the auth configuration, then rebuild the frontends and native development client. The backend module set is unchanged, so no codegen asset edits are needed.
+
+Convex Auth message owners are `users` table IDs returned by `getAuthUserId`. Clerk owners are `tokenIdentifier` values. WorkOS owners are `identity.subject` values from `ctx.auth.getUserIdentity()`. Switching providers changes these keys and needs a data migration; the CLI does not replace auth providers.
+
+`--auth workos` and `add auth workos` configure hosted AuthKit sign-in, SDK token refresh, sign-out, and Convex identity validation. The blank starter keeps the providers and sign-in controls. Append each app's `.env.workos.example` to `.env.local` and follow the generated README's WorkOS setup section, or `WORKOS_SETUP.md` after adding auth. The client ID uses each framework's public prefix. Next.js and TanStack Start also need its unprefixed server SDK value, plus server-only `WORKOS_API_KEY` and `WORKOS_COOKIE_PASSWORD`. Vite receives no server secrets. See [WorkOS research and configuration constraints](docs/research.md#workos-authkit).
+
+`--auth clerk` adds SDK-specific bindings, a Convex auth configuration, and provider wiring. The messages example also includes backend identity checks and an owner index that keeps messages private. With `--auth none`, that example is a public message board. Blank projects omit the messages example; Convex Auth retains its auth tables and functions. Add authorization checks when writing protected functions. UI visibility alone is not authorization.
 
 Use one Clerk application across the frontends. Configure Clerk's Convex integration and a JWT template named `convex`. Set `CLERK_JWT_ISSUER_DOMAIN` on the Convex deployment:
 
@@ -228,7 +448,34 @@ pnpm --filter @my-app/backend exec convex env set CLERK_JWT_ISSUER_DOMAIN https:
 
 On a fresh deployment, first run `pnpm convex:setup` to select it. If the push reports a missing issuer, set that value and rerun setup. Repeat the configuration for production.
 
-Append the variables from each app's `.env.clerk.example` to its `.env.local`, alongside the Convex URL. Publishable keys belong in the appropriate public variables. Next.js and Start use a server-only `CLERK_SECRET_KEY`; Vite and Expo must never receive that secret. See [Convex's Clerk guide](https://docs.convex.dev/auth/clerk).
+Append the variables from each app's `.env.clerk.example` to its `.env.local`, alongside the Convex URL. Publishable keys belong in the appropriate public variables. Next.js, Start, and React Router use a server-only `CLERK_SECRET_KEY`; Vite and Expo must never receive that secret. React Router uses `@clerk/react-router`, `clerkMiddleware`, and `rootAuthLoader`, with `v8_middleware` enabled. Its provider receives the root loader's session data and connects Convex through `ConvexProviderWithClerk`. For production, set `VITE_CLERK_PUBLISHABLE_KEY` at build time and both Clerk keys in the server runtime environment; `react-router-serve` does not load `.env.local` automatically. See [Convex's Clerk guide](https://docs.convex.dev/auth/clerk) and [Clerk's React Router setup](https://clerk.com/docs/react-router/getting-started/quickstart).
+
+## Better Auth setup
+
+Astro uses Better Auth inside its React island with `PUBLIC_CONVEX_URL` and `PUBLIC_CONVEX_SITE_URL`. React Router uses client authentication. Both support messages and blank starters. `--oauth` is only supported with Convex Auth.
+
+`--auth better-auth` uses the official `@convex-dev/better-auth` component for email and password sign-up, sign-in, and sign-out on Next.js, Vite, TanStack Start, React Router, Expo, and Astro. Both starters include loading and error states. Next.js, TanStack Start, and React Router use client authentication. Social providers, magic links, email verification, and authenticated SSR are not configured.
+
+Both package managers are supported. The examples below use pnpm; for bun workspaces, replace `pnpm <script>` with `bun run <script>`. Generated setup instructions use the selected manager.
+
+Run `pnpm convex:setup` to select a deployment. If its first push requests auth configuration, set the deployment variables below and rerun setup. From the generated workspace root, configure your primary web origin and any additional frontend origins or native schemes:
+
+```sh
+pnpm convex:better-auth-env --site-url http://localhost:3000 --trusted-origins http://localhost:3001,ccm-my-app-mobile://
+pnpm convex:better-auth-env --site-url https://example.com --trusted-origins https://admin.example.com,ccm-my-app-mobile:// --prod
+```
+
+Use the actual scheme from the Expo app's `app.json`. For Expo-only development, use its web origin for `SITE_URL` and include its native scheme in the trusted origins. Use a cloud deployment for physical devices and a development build for your custom scheme.
+
+The script generates `BETTER_AUTH_SECRET` in memory and sets it, `SITE_URL`, and `BETTER_AUTH_TRUSTED_ORIGINS` through the installed Convex CLI. It does not store or print the secret. Run the production command separately for production. Re-running rotates the secret, which can invalidate existing sessions. Convex supplies the backend's `CONVEX_SITE_URL`.
+
+Set the public HTTP endpoint in every app's `.env.local`: `NEXT_PUBLIC_CONVEX_SITE_URL` for Next.js, `VITE_CONVEX_SITE_URL` for Vite, TanStack Start, and React Router, `PUBLIC_CONVEX_SITE_URL` for Astro, and `EXPO_PUBLIC_CONVEX_SITE_URL` for Expo. Use your deployment's HTTP URL, normally ending in `.convex.site`. Keep the existing public `CONVEX_URL` setting, normally ending in `.convex.cloud`. `convex:link` and `env sync` copy only `CONVEX_URL`; enter the site URL yourself. Never put `BETTER_AUTH_SECRET` in frontend files.
+
+Better Auth stores its tables inside the component. Message ownership uses the Better Auth user ID returned by `authComponent.getAuthUser(ctx)`. Blank projects keep an empty application schema and the auth query. Expo uses `@better-auth/expo` with SecureStore on native platforms and the cross-domain client on web.
+
+`add auth better-auth` writes `BETTER_AUTH_SETUP.md` and preserves your schema and generated internals. A missing `convex/convex.config.ts` is created. An existing component config or HTTP router that needs integration produces a conflict with the exact manual edit. After installation and configuration, run `pnpm convex:dev` to refresh component types. Provider replacement and stored-data migration remain manual.
+
+See the [official React guide](https://labs.convex.dev/better-auth/framework-guides/react), [Expo guide](https://labs.convex.dev/better-auth/framework-guides/expo), and [email/password documentation](https://www.better-auth.com/docs/authentication/email-password).
 
 ## Expo notes
 
@@ -242,7 +489,7 @@ Typechecking and Metro export checks do not establish that real OAuth, device pe
 
 - **Destination already exists:** choose a new or empty directory. The CLI refuses non-empty directories and symlinks. Template failures remove staging output; install/git/Convex setup failures preserve the completed project and print a retry command.
 - **Missing URL screen:** run `pnpm convex:setup`, or `pnpm convex:link` if the backend is already configured, then restart development.
-- **Authentication never connects:** check the `convex` JWT template and deployment issuer. Use the same Clerk application across frontends.
+- **Authentication never connects:** for Better Auth, check deployment `BETTER_AUTH_SECRET`, `SITE_URL`, trusted origins, and each frontend's public `CONVEX_SITE_URL`. For Convex Auth, check deployment signing keys and the generated auth modules. For Clerk, check the `convex` JWT template and deployment issuer, and use the same Clerk application across frontends.
 - **Missing API types:** keep both generated JavaScript and declarations, run the backend watcher, and verify matching Convex versions. Do not fix this by casting the API.
 - **Missing Start route tree:** run that app's `routes:generate` script. Its typecheck script runs route generation automatically.
 - **Metro resolution after dependency changes:** run `pnpm --filter @my-app/mobile exec expo start --clear`. Check SDK-compatible dependency versions before changing resolver settings.
@@ -255,7 +502,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md), [adding a framework](docs/adding-a-frame
 
 ## Roadmap
 
-The next release should add `doctor` to check deployment URLs, generated types, version alignment, and auth setup in an existing workspace. Later candidates are `add app`, another auth provider, and additional package-manager adapters. These commands are not available in v0.1.
+Next candidates are Convex Auth installation in existing workspaces, reviewed upgrade migrations, and more package-manager adapters. `upgrade` updates dependency pins; template migrations remain manual.
 
 MIT licensed. See [LICENSE](LICENSE).
 

package/assets/backend-better-auth/PROVENANCE.md

@@ -0,0 +1,3 @@
+Generated files under convex/\_generated were produced unchanged by convex@1.45.0 using CONVEX_AGENT_MODE=anonymous pnpm exec convex dev --once on 2026-09-18, after pnpm install in a temporary generated workspace. Dynamic JS/declaration output. Auth dependencies: @convex-dev/better-auth@0.12.5, better-auth@1.6.15 and @better-auth/expo@1.6.15. Input modules: convex.config.ts, schema.ts, auth.ts, http.ts, messages.ts, access.ts. auth.config.ts configures the issuer and is excluded from the generated function API. No internal codegen entry point was called. Run normal convex dev after changing backend modules.
+
+Convex SDK source is Apache-2.0 licensed: https://github.com/get-convex/convex-js/blob/main/LICENSE.

package/assets/backend-better-auth/convex/_generated/api.d.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as access from "../access.js";
+import type * as auth from "../auth.js";
+import type * as http from "../http.js";
+import type * as messages from "../messages.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  access: typeof access;
+  auth: typeof auth;
+  http: typeof http;
+  messages: typeof messages;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {
+  betterAuth: import("@convex-dev/better-auth/_generated/component.js").ComponentApi<"betterAuth">;
+};

package/assets/backend-better-auth/convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();