create-vfactor-app

Reusable setup wizard for generating a Next.js starter with Clerk auth, ReUI-first components installed through shadcn, and optional Supabase or Convex wiring.

One Command

Run this from the generator repo:

npm run setup

It asks for a project folder name, creates that folder in this repo, runs the setup wizard, then asks whether to start the dev server.

The wizard asks users to choose resources, then performs the required wiring automatically. Clerk application setup is required. When Supabase or Convex is selected, the database schema or backend functions and Clerk user sync are also configured without separate yes/no questions.

The interactive setup keeps the main terminal output compact. Press Y or N once for confirmation prompts; Enter is not required. Provider pickers keep all of the useful paths available:

• Clerk can link an existing application or create a new one.
• Supabase can use or create organizations and projects.
• Convex can use or create projects, and can hand off team creation to Convex.

Resource lists show names by default and only reveal a shortened identifier when duplicate names need disambiguation. Add --verbose when you want commands, generated files, and full setup diagnostics inline.

On macOS, setup unlocks the saved Supabase CLI credential once and keeps it only in memory for the duration of the run. Every Supabase command receives the token through its child-process environment. A generated database password is forwarded the same way, so Keychain should not prompt repeatedly.

npm run setup -- --verbose

If you do not start the server immediately, run:

cd your-project-name
npm run dev

npm run new is the same command.

Structure

• scripts/setup.mjs - rerunnable setup wizard
• scripts/create.mjs - published CLI entrypoint
• scripts/new.mjs - local one-command project creator
• templates/ - base app, Supabase, and Convex templates
• starter/ - local generated fixture used to dogfood the output

Published CLI

Create a new app folder:

npm create vfactor-app@latest

Or pass the folder name directly:

npx create-vfactor-app@latest my-app

To generate into the current folder:

npx create-vfactor-app@latest .

The generated app owns its later setup scripts:

cd my-app
npm run setup:doctor
npm run setup:supabase
npm run setup:convex
npm run dev

Publish

Test the packed package locally:

npm pack
mkdir -p /tmp/vfactor-create-test
cd /tmp/vfactor-create-test
npx /path/to/create-vfactor-app-0.1.0.tgz

Publish publicly:

npm publish --access public

Local Fixture

The starter/ fixture can still be updated directly when testing template changes.

npm run starter:setup

If starter/ does not exist, the wizard creates a fresh Next.js app there first, configures shadcn, adds the ReUI registry and starter ReUI component set, adds Clerk, then asks which database provider to wire up.

Provider shortcuts:

npm run setup:supabase
npm run setup:convex
npm run setup:doctor

Hosted user-sync receivers:

npm run supabase:webhook:deploy
npm run convex:webhook:deploy

Run the app:

npm run starter:dev

Open http://localhost:3000.

App Checks

npm run starter:lint
npm run starter:build
npm run starter:typecheck
npm run setup:doctor