create-vexcms 0.0.20 → 0.1.0-alpha.3

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "create-vexcms",
-  "version": "0.0.20",
+  "version": "0.1.0-alpha.3",
+  "description": "Scaffold a new VexCMS project",
+  "keywords": [
+    "cms",
+    "headless-cms",
+    "convex",
+    "typescript",
+    "create",
+    "scaffold"
+  ],
+  "license": "Apache-2.0",
+  "author": "Isaiah Anyimi",
+  "homepage": "https://docs.vexcms.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ianyimi/vex.git",
+    "directory": "packages/create-vexcms"
+  },
+  "sideEffects": false,
   "type": "module",
   "bin": {
     "create-vexcms": "./dist/index.js"
@@ -10,24 +28,26 @@
     "templates"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "alpha"
   },
   "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "execa": "^9.5.2",
-    "fs-extra": "^11.2.0",
-    "@inquirer/prompts": "^7.2.0",
-    "ora": "^8.1.0",
-    "sort-package-json": "^2.10.0",
-    "validate-npm-package-name": "^5.0.0"
+    "chalk": "5.3.0",
+    "commander": "12.1.0",
+    "execa": "9.6.1",
+    "fs-extra": "11.3.6",
+    "@inquirer/prompts": "7.10.1",
+    "ora": "8.1.0",
+    "sort-package-json": "2.10.0",
+    "validate-npm-package-name": "5.0.0",
+    "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@types/fs-extra": "^11.0.4",
-    "@types/validate-npm-package-name": "^4.0.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.0"
+    "@types/fs-extra": "11.0.4",
+    "@types/validate-npm-package-name": "4.0.2",
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",

package/templates/base-nextjs/README.md

@@ -1,173 +1,65 @@
-# Next.js + Better Auth + Convex + shadcn/ui Template
+# {{PROJECT_NAME}}
 
-A modern, production-ready SaaS template built with:
-
-- **[Next.js](https://nextjs.org)** - The React framework for production with App Router
-- **[Better Auth](https://www.better-auth.com/)** - Modern authentication with email/password and OAuth providers
-- **[Convex](https://convex.dev/)** - Real-time database and backend
-- **[shadcn/ui](https://ui.shadcn.com/)** - Beautifully designed components built on Radix UI
-- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
+A VexCMS project built with Next.js, Better Auth, and Convex.
 
 ## Getting Started
 
-### 1. Prerequisites
-
-- Node.js 18+ and npm/pnpm/yarn installed
-- A Convex account (free at [convex.dev](https://convex.dev))
-
-### 2. Clone and Install
+### 1. Install dependencies
 
 ```bash
-# Clone this template
-git clone <your-repo-url>
-cd <your-project-name>
-
-# Install dependencies
-npm install
-# or
 pnpm install
-# or
-yarn install
 ```
 
-### 3. Environment Setup
-
-Copy the example environment file:
-
-```bash
-cp .env.example .env
-```
-
-### 4. Generate Better Auth Secret
-
-Generate a secure secret for Better Auth:
-
-```bash
-npm run secret:create
-# or
-pnpm secret:create
-# or
-yarn secret:create
-```
-
-This will generate a random 32-character hex string and copy it to your clipboard.
-
-### 5. Configure Convex
-
-#### Set up Convex project
+### 2. Start Convex
 
 ```bash
 npx convex dev
 ```
 
-This will:
-
-- Create a new Convex project (or link to an existing one)
-- Generate your `CONVEX_URL` and `NEXT_PUBLIC_CONVEX_URL`
-- Start the Convex development server
-
-#### Add environment variables to Convex
-
-You need to add two critical environment variables to your Convex deployment via the [Convex Dashboard](https://dashboard.convex.dev):
+On first run this creates (or links) a Convex project and prints your
+deployment's URL and site URL.
 
-1. **BETTER_AUTH_SECRET**: Paste the secret you generated in step 4
-2. **SITE_URL**: Set to your application URL
-   - Development: `http://localhost:3000` (or whatever port your dev server uses)
-   - Production: Your production domain (e.g., `https://yourdomain.com`)
+### 3. Fill in your environment variables
 
-To add these in the Convex Dashboard:
-
-1. Go to your project at [dashboard.convex.dev](https://dashboard.convex.dev)
-2. Navigate to "Settings" → "Environment Variables"
-3. Add both `BETTER_AUTH_SECRET` and `SITE_URL`
-
-### 6. Update Your .env File
-
-Update your `.env` file with the values from Convex setup:
+`.env.local` already has a generated `BETTER_AUTH_SECRET` and a
+`http://localhost:3010` `SITE_URL`/`NEXT_PUBLIC_SITE_URL` pair, so the app
+builds and typechecks immediately. Replace the placeholder Convex URLs with the
+real ones `npx convex dev` printed:
 
 ```env
-NODE_ENV=development
-
-# From Convex setup
-CONVEX_URL=https://your-deployment.convex.cloud
 NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
-CONVEX_SITE_URL=https://your-deployment.convex.site
 NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
-
-# Better Auth (same secret you added to Convex Dashboard)
-BETTER_AUTH_SECRET=your-generated-secret-here
-NEXT_PUBLIC_SITE_URL=http://localhost:3000
 ```
 
-### 7. Start Development
+Better Auth runs inside your Convex deployment, not in the Next.js server —
+it does **not** read `.env.local`. Set the same two values on the
+deployment itself:
 
 ```bash
-# Terminal 1: Run Convex dev server
-npx convex dev
-
-# Terminal 2: Run the application
-npm run dev
-# or
-pnpm dev
-# or
-yarn dev
+npx convex env set SITE_URL http://localhost:3010
+npx convex env set BETTER_AUTH_SECRET <the BETTER_AUTH_SECRET value from .env.local>
 ```
 
-Visit `http://localhost:3000` to see your application running.
+Skipping this step is the most common cause of a `403` on your first sign-in
+attempt.
 
-## Authentication Setup
-
-This project uses Better Auth for authentication.
-
-<!-- {{OAUTH_SETUP_GUIDE}} -->
+### 4. Run the dev servers
 
-## Customizing Authentication
-
-### Adding OAuth Providers
-
-To add or modify OAuth providers:
-
-1. **Update Better Auth configuration** in `convex/auth/index.ts`:
+```bash
+# Terminal 1
+pnpm vex:dev
 
-```typescript
-export const createAuth = (ctx: GenericActionCtx<DataModel>) => {
-  return betterAuth({
-    socialProviders: {
-      google: {
-        clientId: process.env.GOOGLE_CLIENT_ID!,
-        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-        redirectURI: `${process.env.SITE_URL}/api/auth/callback/google`,
-      },
-      // Add more providers
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      },
-    },
-    // ... rest of config
-  })
-}
+# Terminal 2
+pnpm dev
 ```
 
-2. **Add credentials to Convex Dashboard** as environment variables
-
-3. **Consult the Better Auth documentation** for provider-specific configuration:
-   - [Better Auth Providers](https://www.better-auth.com/docs/authentication/social-login)
-
-### Customizing User Schema
-
-To add custom fields to your user model:
+### 5. Create your admin account
 
-1. Update the `user.additionalFields` in `convex/auth/index.ts`
-2. Update your Convex schema accordingly
-3. See [Better Auth User Management](https://www.better-auth.com/docs/concepts/user-management) for details
+Visit `http://localhost:3010`, click "Create Admin Account", and sign up. The
+first user to sign up on a fresh project is automatically promoted to admin —
+see `convex/vex/firstUser.ts`. From there, "Go to Admin Panel" opens `/admin`.
 
-### Email/Password Configuration
-
-The template has email/password authentication enabled by default. To customize:
-
-- [Better Auth Email/Password Docs](https://www.better-auth.com/docs/authentication/email-password)
-- [Email Verification Setup](https://www.better-auth.com/docs/authentication/email-verification)
+<!-- {{OAUTH_SETUP_GUIDE}} -->
 
 ## Project Structure
 
@@ -175,82 +67,46 @@ The template has email/password authentication enabled by default. To customize:
 .
 ├── src/
 │   ├── app/                    # Next.js App Router
-│   │   ├── (frontend)/        # Frontend routes group
-│   │   ├── api/               # API routes
-│   │   └── layout.tsx         # Root layout
-│   ├── auth/                  # Authentication components
-│   ├── components/            # React components
-│   ├── lib/                   # Utilities and helpers
-│   └── env.mjs                # Typed environment variables
-├── convex/                    # Convex backend
-│   ├── auth/                  # Better Auth integration
-│   ├── schema.ts              # Database schema
-│   └── *.ts                   # Convex functions (queries, mutations, actions)
-├── public/                    # Static assets
-└── .env                       # Environment variables (not committed)
+│   │   ├── (frontend)/         # Public site routes
+│   │   ├── (vexcms)/admin/     # Admin panel routes
+│   │   └── layout.tsx          # Root layout
+│   ├── auth/                   # Auth client + server helpers, access control
+│   ├── components/             # React components
+│   ├── vexcms/collections/     # Collection definitions
+│   ├── vex.config.ts           # VexCMS config
+│   └── env.mjs                 # Typed environment variables
+├── convex/                     # Convex backend
+│   ├── auth/                   # Better Auth config + plugins
+│   ├── vex/                    # Bootstrap, media, globals endpoints
+│   └── schema.ts               # Database schema
+└── .env.local                  # Environment variables (not committed)
 ```
 
-## Development Scripts
+## Scripts
 
 ```bash
-npm run dev              # Start development server
-npm run build            # Build for production
-npm run start            # Start production server
-npm run lint             # Lint code
-npm run typecheck        # Type check without emitting
-npm run format           # Format code with Prettier
-npm run format:check     # Check code formatting
-npm run secret:create    # Generate a Better Auth secret
+pnpm dev              # Start the Next.js dev server
+pnpm vex:dev           # Start VexCMS's schema watcher + convex dev
+pnpm vex:generate      # Regenerate the Convex schema and types once
+pnpm build             # Build for production
+pnpm typecheck         # Type check without emitting
+pnpm lint              # Lint
+pnpm format            # Format with Prettier
+pnpm secret:create     # Generate a Better Auth secret
 ```
 
-## Documentation Resources
-
-### Core Technologies
+## Documentation
 
+- **VexCMS**: [docs.vexcms.dev](https://docs.vexcms.dev)
 - **Next.js**: [nextjs.org/docs](https://nextjs.org/docs)
 - **Better Auth**: [better-auth.com/docs](https://www.better-auth.com/docs)
 - **Convex**: [docs.convex.dev](https://docs.convex.dev)
-- **shadcn/ui**: [ui.shadcn.com](https://ui.shadcn.com)
-- **Tailwind CSS**: [tailwindcss.com/docs](https://tailwindcss.com/docs)
-
-### Integration Guides
-
-- **Better Auth + Convex**: [better-auth.com/docs/integrations/convex](https://www.better-auth.com/docs/integrations/convex)
-- **Better Auth + Next.js**: [better-auth.com/docs/integrations/nextjs](https://www.better-auth.com/docs/integrations/nextjs)
 
 ## Deployment
 
-### Deploy to Production
-
-1. **Deploy Convex Backend**:
-
-```bash
-npx convex deploy
-```
-
-2. **Update Convex environment variables** in production:
-   - Set `SITE_URL` to your production domain
-   - Keep `BETTER_AUTH_SECRET` the same (or rotate it)
-
-3. **Deploy your application** to your hosting provider (Vercel recommended):
-
-For Vercel:
-
-```bash
-npm install -g vercel
-vercel
-```
-
-Or connect your GitHub repository to Vercel for automatic deployments.
-
-4. **Update environment variables** in your hosting provider with production values:
-   - `NEXT_PUBLIC_CONVEX_URL`
-   - `NEXT_PUBLIC_CONVEX_SITE_URL`
-   - `NEXT_PUBLIC_SITE_URL`
-   - `BETTER_AUTH_SECRET`
-
-See [Next.js Deployment](https://nextjs.org/docs/app/building-your-application/deploying) and [Convex Production Deployment](https://docs.convex.dev/production/hosting) for detailed deployment instructions.
-
-## License
-
-MIT
+1. `npx convex deploy`
+2. In the Convex Dashboard, set `SITE_URL` to your production domain (keep
+   `BETTER_AUTH_SECRET` the same, or rotate it and update both places).
+3. Deploy the Next.js app (e.g. Vercel) with `NEXT_PUBLIC_CONVEX_URL`,
+   `NEXT_PUBLIC_CONVEX_SITE_URL`, `NEXT_PUBLIC_SITE_URL`, and
+   `BETTER_AUTH_SECRET` set to their production values.

package/templates/base-nextjs/_env.example

@@ -1,18 +1,16 @@
-# Since the ".env" file is gitignored, you can use the ".env.example" file to
-# build a new ".env" file when you clone the repo. Keep this file up-to-date
-# when you add new variables to `.env`.
+# Since the ".env.local" file is gitignored, use this file to build a new one
+# when you clone the repo. Keep it up to date when you add new variables to
+# `.env.local`.
 
-# This file will be committed to version control, so make sure not to have any
-# secrets in it. If you are cloning this repo, create a copy of this file named
-# ".env" and populate it with your secrets.
+# This file is committed to version control — never put secrets in it.
 
-# When adding additional environment variables, the schema in "/src/env.js"
-# should be updated accordingly.
+# When adding new environment variables, update the schema in "src/env.mjs".
 
 NEXT_PUBLIC_CONVEX_URL=""
 NEXT_PUBLIC_CONVEX_SITE_URL=""
 
-NEXT_PUBLIC_SITE_URL="http://localhost:3000"
+NEXT_PUBLIC_SITE_URL="http://localhost:3010"
+SITE_URL="http://localhost:3010"
 BETTER_AUTH_SECRET=""
 
 # {{ENV_OAUTH_VARS}}

package/templates/base-nextjs/_gitignore

@@ -1,2 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 
-.env.local
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env
+.env.*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/templates/base-nextjs/convex/_generated/api.d.ts

@@ -8,45 +8,17 @@
  * @module
  */
 
-import type * as auth_adapter_index from "../auth/adapter/index.js";
-import type * as auth_adapter_utils from "../auth/adapter/utils.js";
 import type * as auth_api from "../auth/api.js";
-import type * as auth_config from "../auth/config.js";
 import type * as auth_db from "../auth/db.js";
 import type * as auth_index from "../auth/index.js";
 import type * as auth_options from "../auth/options.js";
 import type * as auth_plugins_index from "../auth/plugins/index.js";
 import type * as auth_sessions from "../auth/sessions.js";
 import type * as http from "../http.js";
-import type * as vex_api_articles from "../vex/api/articles.js";
-import type * as vex_api_categories from "../vex/api/categories.js";
-import type * as vex_api_footers from "../vex/api/footers.js";
-import type * as vex_api_headers from "../vex/api/headers.js";
-import type * as vex_api_index from "../vex/api/index.js";
-import type * as vex_api_media from "../vex/api/media.js";
-import type * as vex_api_pages from "../vex/api/pages.js";
-import type * as vex_api_posts from "../vex/api/posts.js";
-import type * as vex_api_themes from "../vex/api/themes.js";
-import type * as vex_api_user from "../vex/api/user.js";
-import type * as vex_auth from "../vex/auth.js";
-import type * as vex_collections from "../vex/collections.js";
-import type * as vex_impersonation from "../vex/impersonation.js";
+import type * as vex from "../vex.js";
+import type * as vex_firstUser from "../vex/firstUser.js";
+import type * as vex_globals from "../vex/globals.js";
 import type * as vex_media from "../vex/media.js";
-import type * as vex_migrate from "../vex/migrate.js";
-import type * as vex_model_api_articles from "../vex/model/api/articles.js";
-import type * as vex_model_api_categories from "../vex/model/api/categories.js";
-import type * as vex_model_api_footers from "../vex/model/api/footers.js";
-import type * as vex_model_api_headers from "../vex/model/api/headers.js";
-import type * as vex_model_api_media from "../vex/model/api/media.js";
-import type * as vex_model_api_pages from "../vex/model/api/pages.js";
-import type * as vex_model_api_posts from "../vex/model/api/posts.js";
-import type * as vex_model_api_themes from "../vex/model/api/themes.js";
-import type * as vex_model_api_user from "../vex/model/api/user.js";
-import type * as vex_model_collections from "../vex/model/collections.js";
-import type * as vex_model_media from "../vex/model/media.js";
-import type * as vex_model_versions from "../vex/model/versions.js";
-import type * as vex_previewSnapshot from "../vex/previewSnapshot.js";
-import type * as vex_versions from "../vex/versions.js";
 
 import type {
   ApiFromModules,
@@ -55,45 +27,17 @@ import type {
 } from "convex/server";
 
 declare const fullApi: ApiFromModules<{
-  "auth/adapter/index": typeof auth_adapter_index;
-  "auth/adapter/utils": typeof auth_adapter_utils;
   "auth/api": typeof auth_api;
-  "auth/config": typeof auth_config;
   "auth/db": typeof auth_db;
   "auth/index": typeof auth_index;
   "auth/options": typeof auth_options;
   "auth/plugins/index": typeof auth_plugins_index;
   "auth/sessions": typeof auth_sessions;
   http: typeof http;
-  "vex/api/articles": typeof vex_api_articles;
-  "vex/api/categories": typeof vex_api_categories;
-  "vex/api/footers": typeof vex_api_footers;
-  "vex/api/headers": typeof vex_api_headers;
-  "vex/api/index": typeof vex_api_index;
-  "vex/api/media": typeof vex_api_media;
-  "vex/api/pages": typeof vex_api_pages;
-  "vex/api/posts": typeof vex_api_posts;
-  "vex/api/themes": typeof vex_api_themes;
-  "vex/api/user": typeof vex_api_user;
-  "vex/auth": typeof vex_auth;
-  "vex/collections": typeof vex_collections;
-  "vex/impersonation": typeof vex_impersonation;
+  vex: typeof vex;
+  "vex/firstUser": typeof vex_firstUser;
+  "vex/globals": typeof vex_globals;
   "vex/media": typeof vex_media;
-  "vex/migrate": typeof vex_migrate;
-  "vex/model/api/articles": typeof vex_model_api_articles;
-  "vex/model/api/categories": typeof vex_model_api_categories;
-  "vex/model/api/footers": typeof vex_model_api_footers;
-  "vex/model/api/headers": typeof vex_model_api_headers;
-  "vex/model/api/media": typeof vex_model_api_media;
-  "vex/model/api/pages": typeof vex_model_api_pages;
-  "vex/model/api/posts": typeof vex_model_api_posts;
-  "vex/model/api/themes": typeof vex_model_api_themes;
-  "vex/model/api/user": typeof vex_model_api_user;
-  "vex/model/collections": typeof vex_model_collections;
-  "vex/model/media": typeof vex_model_media;
-  "vex/model/versions": typeof vex_model_versions;
-  "vex/previewSnapshot": typeof vex_previewSnapshot;
-  "vex/versions": typeof vex_versions;
 }>;
 
 /**

package/templates/base-nextjs/convex/_generated/server.d.ts

@@ -21,6 +21,17 @@ import {
 } from "convex/server";
 import type { DataModel } from "./dataModel.js";
 
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+type Env = {
+  readonly CONVEX_CLOUD_URL: string;
+  readonly CONVEX_SITE_URL: string;
+};
+
 /**
  * Define a query in this Convex app's public API.
  *
@@ -95,6 +106,14 @@ export declare const internalAction: ActionBuilder<DataModel, "internal">;
  */
 export declare const httpAction: HttpActionBuilder;
 
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+export declare const env: Env;
+
 /**
  * A set of services for use within Convex query functions.
  *

package/templates/base-nextjs/convex/_generated/server.js

@@ -91,3 +91,11 @@ export const internalAction = internalActionGeneric;
  * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
  */
 export const httpAction = httpActionGeneric;
+
+/**
+ * Typesafe environment variables.
+ *
+ * This includes platform-provided env vars and any variables declared in
+ * `convex.config.ts`.
+ */
+export const env = process.env;

package/templates/base-nextjs/convex/auth/api.ts

@@ -1,8 +1,54 @@
-import { query } from "../_generated/server"
+import { get } from "@vexcms/core/server";
+import { v } from "convex/values";
+
+import {
+  type OrganizationID,
+  type SessionID,
+  TABLE_SLUG_ORGANIZATIONS,
+  TABLE_SLUG_SESSIONS,
+  TABLE_SLUG_USERS,
+  type UserID,
+} from "~/db/constants";
+
+import { query } from "../_generated/server";
 
 export const identifyCurrentUser = query({
   args: {},
   handler: async (ctx) => {
-    return ctx.auth.getUserIdentity()
+    return ctx.auth.getUserIdentity();
+  },
+});
+
+export const getUserOrg = query({
+  args: {
+    noOrgs: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const empty = { user: null, organization: undefined };
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) {
+      return empty;
+    }
+    const session = await get({
+      ctx,
+      id: identity.sessionId as SessionID,
+      collection: TABLE_SLUG_SESSIONS,
+    });
+    if (!session) {
+      return empty;
+    }
+    const user = await get({ ctx, id: identity.subject as UserID, collection: TABLE_SLUG_USERS });
+    if (!user) {
+      return empty;
+    }
+    if (!session.activeOrganizationId || args.noOrgs) {
+      return { user, organization: undefined };
+    }
+    const organization = await get({
+      ctx,
+      id: session.activeOrganizationId as OrganizationID,
+      collection: TABLE_SLUG_ORGANIZATIONS,
+    });
+    return { user, organization: organization ?? undefined };
   },
-})
+});