create-vexcms 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,161 @@
+# create-vexcms
+
+Scaffolding CLI for [VEX CMS](https://github.com/ianyimi/vex) projects. Creates a complete Next.js application with Convex backend, Better Auth authentication, and an admin panel — ready to run.
+
+## Usage
+
+```bash
+pnpm create vexcms@latest
+```
+
+Or with a project name:
+
+```bash
+pnpm create vexcms@latest my-project
+```
+
+Supports relative paths:
+
+```bash
+pnpm create vexcms@latest apps/website
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--bare` | Skip the marketing site template. Scaffolds an empty VEX CMS project with no collections. |
+| `--orgs` | Enable multi-tenant organizations (adds Better Auth organizations plugin). |
+
+```bash
+# Empty project with no pre-built collections
+pnpm create vexcms@latest my-app --bare
+
+# Project with organizations support
+pnpm create vexcms@latest my-app --orgs
+```
+
+## Interactive Prompts
+
+The CLI walks you through:
+
+1. **Project name** — validates npm package name rules, supports `.` for current directory
+2. **Framework** — Next.js (recommended) or TanStack Start (coming soon)
+3. **Email/password auth** — enable or disable (default: yes)
+4. **OAuth providers** — multi-select from 30+ Better Auth providers (Google, GitHub, Discord, etc.)
+5. **Organizations** — enable multi-tenant support (default: no, skipped if `--orgs` passed)
+6. **Git repository** — initialize git (default: yes)
+7. **Install dependencies** — run package install (default: no)
+
+## Templates
+
+### Marketing Site (default)
+
+Pre-built collections for a marketing website:
+
+- **Pages** — with title, slug, richtext content, draft/publish versioning, and live preview
+- **Headers** — name, logo upload, sticky option
+- **Footers** — name, richtext content, copyright text
+- **Themes** — name, colors, font family
+- **Site Settings** — site name, description, favicon upload
+
+Also includes:
+
+- Landing page with sign-in/sign-up flow
+- First-user auto-admin promotion
+- Admin panel onboarding tour (driver.js)
+- Preview routes at `/preview/[slug]` with live preview support
+- Public page routes at `/[slug]` (published pages only)
+- Draft-aware queries using `vexQuery`
+
+### Bare (`--bare`)
+
+Empty VEX CMS project with:
+
+- Authentication setup (Better Auth + Convex adapter)
+- Admin panel wired at `/admin`
+- Empty `collections: []` in `vex.config.ts`
+- No onboarding tour
+
+## Getting Started
+
+After scaffolding your project:
+
+### 1. Install dependencies
+
+```bash
+cd my-project
+pnpm install
+```
+
+### 2. Generate a Better Auth secret
+
+```bash
+pnpm secret:create
+```
+
+This generates a random 32-character string and copies it to your clipboard.
+
+### 3. Configure environment variables
+
+The CLI creates a `.env.local` file with `NEXT_PUBLIC_SITE_URL` set to your chosen port. Add the auth secret:
+
+```env
+# .env.local (auto-generated)
+NEXT_PUBLIC_SITE_URL=http://localhost:3010
+
+# Add manually:
+BETTER_AUTH_SECRET=your-generated-secret-here
+```
+
+### 4. Start VEX dev server
+
+```bash
+pnpm vex:dev
+```
+
+This starts the VEX CLI watcher (generates schema, types, and queries) and the Convex dev server. On first run, it will prompt you to create or select a Convex project.
+
+### 5. Add environment variables to Convex
+
+In the [Convex Dashboard](https://dashboard.convex.dev), navigate to your project's **Settings > Environment Variables** and add:
+
+- `BETTER_AUTH_SECRET` — the same secret from step 2
+- `SITE_URL` — `http://localhost:3010` (or your chosen port)
+
+### 6. Start the Next.js dev server
+
+In a separate terminal:
+
+```bash
+pnpm dev
+```
+
+### 7. Create your admin account
+
+Open `http://localhost:3010` in your browser. Click **"Create Admin Account"** to sign up. The first user is automatically promoted to admin and redirected to the admin panel.
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm dev` | Start Next.js development server |
+| `pnpm vex:dev` | Start VEX CLI watcher + Convex dev server |
+| `pnpm vex:generate` | One-shot schema/type/query generation |
+| `pnpm vex:update` | Update all `@vexcms/*` packages to latest |
+| `pnpm secret:create` | Generate a random 32-character secret and copy to clipboard |
+| `pnpm build` | Production build |
+
+## Versioning
+
+`create-vexcms` is versioned alongside all `@vexcms/*` packages. Running `pnpm create vexcms@latest` always scaffolds with the latest package versions. You can also pin a specific version:
+
+```bash
+pnpm create vexcms@0.0.3
+```
+
+The scaffolded project's `@vexcms/*` dependencies match the version of `create-vexcms` used.
+
+## License
+
+MIT

package/dist/index.js

@@ -98,7 +98,9 @@ async function copyTemplate(framework, targetPath) {
     overwrite: false,
     errorOnExist: false,
     filter: (src) => {
-      return !src.endsWith("_gitignore");
+      const basename = src.split("/").pop() ?? "";
+      const skipFiles = ["_gitignore", "_env.example", "_prettierrc", "_prettierignore"];
+      return !skipFiles.includes(basename);
     }
   });
   const sourceGitignore = join(templatePath, "_gitignore");
@@ -109,6 +111,18 @@ async function copyTemplate(framework, targetPath) {
       errorOnExist: false
     });
   }
+  const dotfileRenames = [
+    ["_env.example", ".env.example"],
+    ["_prettierrc", ".prettierrc"],
+    ["_prettierignore", ".prettierignore"]
+  ];
+  for (const [from, to] of dotfileRenames) {
+    const source = join(templatePath, from);
+    const target = join(targetPath, to);
+    if (await fs2.pathExists(source)) {
+      await fs2.copy(source, target, { overwrite: false, errorOnExist: false });
+    }
+  }
 }
 async function overlayTemplate({ overlayDir, targetDir }) {
   await fs2.copy(overlayDir, targetDir, { overwrite: true });
@@ -157,6 +171,27 @@ var VexFrameworkInstaller = class {
     }
     await fs3.writeJson(pkgPath, pkg, { spaces: 2 });
   }
+  /**
+   * Configure the dev server port.
+   * Updates package.json dev script and creates .env.local with NEXT_PUBLIC_SITE_URL.
+   */
+  async configurePort(port) {
+    const pkgPath = path.join(this.targetPath, "package.json");
+    const pkg = await fs3.readJson(pkgPath);
+    if (pkg.scripts?.dev) {
+      if (pkg.scripts.dev.includes("--port")) {
+        pkg.scripts.dev = pkg.scripts.dev.replace(/--port[= ]\d+/, `--port=${port}`);
+      } else {
+        pkg.scripts.dev = `${pkg.scripts.dev} --port=${port}`;
+      }
+    }
+    await fs3.writeJson(pkgPath, pkg, { spaces: 2 });
+    const envLocalPath = path.join(this.targetPath, ".env.local");
+    const envContent = `NEXT_PUBLIC_SITE_URL=http://localhost:${port}
+BETTER_AUTH_SECRET=""
+`;
+    await fs3.writeFile(envLocalPath, envContent);
+  }
   /**
    * Detect the package manager used to invoke the CLI
    */
@@ -330,6 +365,7 @@ var VexFrameworkInstaller = class {
     const nameSpinner = ora("Configuring project...").start();
     try {
       await this.updatePackageName(options.projectName);
+      await this.configurePort(options.port);
       nameSpinner.succeed("Project configured");
     } catch (error) {
       nameSpinner.fail("Failed to configure project");
@@ -2308,7 +2344,7 @@ async function main() {
     inputArg = args[0];
   } else {
     inputArg = await input({
-      message: "What is your project named?",
+      message: "(1/8) What is your project named?",
       default: "my-vexcms-app",
       validate: (value) => {
         const name = value.includes("/") ? path2.basename(value) : value;
@@ -2336,7 +2372,7 @@ async function main() {
   let framework;
   while (true) {
     framework = await select({
-      message: "Select a framework:",
+      message: "(2/8) Select a framework:",
       choices: [
         { name: "Next.js (Recommended)", value: "nextjs" },
         { name: "TanStack Start (Coming Soon)", value: "tanstack" }
@@ -2348,8 +2384,18 @@ async function main() {
     }
     break;
   }
+  const portInput = await input({
+    message: "(3/8) Dev server port:",
+    default: "3010",
+    validate: (value) => {
+      const num = parseInt(value, 10);
+      if (isNaN(num) || num < 1 || num > 65535) return "Must be a valid port number (1-65535)";
+      return true;
+    }
+  });
+  const port = parseInt(portInput, 10);
   const emailPasswordAuth = await confirm({
-    message: "Enable email/password authentication?",
+    message: "(4/8) Enable email/password authentication?",
     default: true
   });
   const popularProviders = getPopularProviders();
@@ -2366,25 +2412,26 @@ async function main() {
     }))
   ];
   const oauthProviders = await checkbox({
-    message: "Select OAuth providers (space to toggle, enter to confirm):",
+    message: "(5/8) Select OAuth providers (space to toggle, enter to confirm):",
     choices: allProviderChoices
   });
   const orgs = opts.orgs ?? await confirm({
-    message: "Enable multi-tenant (organizations)?",
+    message: "(6/8) Enable multi-tenant (organizations)?",
     default: false
   });
   const initGit = await confirm({
-    message: "Initialize a Git repository?",
+    message: "(7/8) Initialize a Git repository?",
     default: true
   });
   const installDependencies = await confirm({
-    message: "Install dependencies?",
+    message: "(8/8) Install dependencies?",
     default: false
   });
   const options = {
     projectName,
     projectDir: targetDir,
     framework,
+    port,
     bare,
     orgs,
     emailPasswordAuth,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vexcms",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "bin": {
     "create-vexcms": "./dist/index.js"

package/templates/base-nextjs/_env.example

@@ -0,0 +1,19 @@
+# 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`.
+
+# 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.
+
+# When adding additional environment variables, the schema in "/src/env.js"
+# should be updated accordingly.
+
+NEXT_PUBLIC_CONVEX_URL=""
+NEXT_PUBLIC_CONVEX_SITE_URL=""
+
+NEXT_PUBLIC_SITE_URL="http://localhost:3000"
+BETTER_AUTH_SECRET=""
+
+# {{ENV_OAUTH_VARS}}
+