This is a starter application using NextJS and Convex, managed with Turbo for monorepo capabilities.
- Node.js 22 or later
- pnpm package manager
- Convex account - Register at https://www.convex.dev/
-
Run
pnpm installto install the dependencies -
Run
pnpm run setupto initialize the Convex backend and configure the webapp- Bumps minor version — When branding is customized, increments the minor version across all workspace
package.jsonfiles (root is canonical). This updatesservices/backend/package.json, which triggers the Production Deployment workflow on push tomaster.
This script will:
- Check and update branding - Detects if you're using template branding and prompts you to customize:
- Application name and short name
- App description
- Landing page title
- Package name
- Initialize the Convex backend using
npx convex dev --once - Extract the CONVEX_URL from the backend's .env.local file
- Create/update the webapp's .env.local file with the NEXT_PUBLIC_CONVEX_URL
- Assign a random
PORTin the IANA ephemeral range (49152–65535) toapps/webapp/.env.localif not already configured
The setup script is idempotent - you can run it multiple times safely. It will:
- Show ✅ CONFIGURED for branding that's already customized
- Show
⚠️ TEMPLATE for branding that still uses default values - Only prompt for updates if template values are detected
Non-Interactive Mode: For CI/CD or automated setups:
bun scripts/setup.ts --non-interactive \ --app-name "My App" \ --app-short-name "MyApp" \ --app-description "Description" \ --landing-page-title "Welcome" \ --package-name "my-app" # Or skip branding entirely bun scripts/setup.ts --skip-branding # Show all options bun scripts/setup.ts --help
- Bumps minor version — When branding is customized, increments the minor version across all workspace
-
Run
pnpm devin the root directory to start the NextJS application and Convex backendAfter pulling schema changes, run
pnpm migratewhileconvex devis running (see AGENTS.md).
If you prefer to set up manually:
- Go to
services/backendand runnpx convex dev --once- this should prompt you to login to Convex and create a new project. Note: This will create a .env.local file with the CONVEX_URL environment variable. - Create a
.env.localfile in theapps/webappdirectory and add the following:NEXT_PUBLIC_CONVEX_URL=<your-convex-project-url> # copy this from the backend .env.local file
- Run
pnpm devin the root directory to start both services
The included production workflow deploys Convex and runs pending migrations. Frontend deployments are handled by Vercel's GitHub integration for this project. The workflow retains a commented Vercel GitHub Actions path for projects that do not use that integration; before enabling it, add support for multiple collaborators so deployment access and ownership do not depend on a single collaborator's Vercel key.
- In the Convex dashboard, open the production deployment and copy its deployment URL. Generate a production deploy key from Project Settings → Settings → General.
- Import the repository into Vercel and set its Root Directory to
apps/webapp. Configure the productionNEXT_PUBLIC_CONVEX_URLenvironment variable in Vercel for deployments from its GitHub integration. - If you plan to enable the optional commented Vercel GitHub Actions path,
create a Vercel access token. Run
pnpm exec vercel link --repofrom the repository root if needed, then read theapps/webappentry in.vercel/repo.jsonto obtain itsorgIdandid. Do not commit the.verceldirectory.
Open GitHub repository → Settings → Secrets and variables → Actions → New repository secret and add:
| Secret | Value |
|---|---|
CONVEX_DEPLOY_KEY_PROD |
Convex production deploy key |
VERCEL_TOKEN |
Vercel access token for the optional Actions path |
Then open the Variables tab, create these repository variables, and add:
| Variable | Value |
|---|---|
NEXT_PUBLIC_CONVEX_URL |
Convex production deployment URL |
VERCEL_TEAM_ID |
orgId from Vercel project metadata (optional Actions path) |
VERCEL_PROJECT_ID |
projectId from Vercel project metadata (optional Actions path) |
VERCEL_USER_EMAIL |
Email of a Vercel team member (required only when the optional Vercel GitHub Actions path is enabled) |
The active workflow requires CONVEX_DEPLOY_KEY_PROD for the backend deployment.
The Vercel token and Vercel metadata variables are required only if you
intentionally re-enable the commented frontend jobs. Additional build-time
values can follow the same pattern: store them as GitHub Actions secrets and
expose them only to the optional frontend build job. Values that must remain
available to server functions at runtime should be configured in Vercel or
passed explicitly by a customized deploy step.
The optional Vercel GitHub Actions path rewrites the latest commit's author
email only in the CI runner's local checkout before invoking the Vercel CLI. Set
VERCEL_USER_EMAIL to an email address associated with a member of the Vercel
team so Vercel can identify the deployment author. The amended commit is local
to the workflow, is never pushed back to the repository, and is not performed
by the current default workflow.
When the optional Actions path is enabled, the workflow recreates Vercel's
repository-level monorepo link in
.vercel/repo.json. It also writes the transient, settings-only project metadata
that vercel build expects beneath apps/webapp; project identity remains in
the repository link. Both build and deploy run from the repository root. The
optional path intentionally does not run vercel pull, so Vercel project
environment variables are not downloaded into CI.
Push a deployment-related change to master. The active workflow then:
- Deploys Convex and runs pending idempotent migrations.
Vercel's GitHub integration handles the frontend deployment separately. If you intentionally enable the optional commented Vercel GitHub Actions path, it also builds the Vercel production output exactly once and promotes that prebuilt output only after the requested backend deployment and migrations succeed.
The workflow runs for changes under apps/webapp, packages/shared, or
services/backend, as well as workspace and deployment configuration files. It
can also be started from GitHub Actions → Production Deployment → Run
workflow, where backend deployment can be enabled or skipped.
If you forked this template with existing git history, workflows only run on new pushes after the workflow file exists; they are not replayed for old commits.
To create a system administrator:
- Login anonymously via the login page
- Set admin privileges in Convex Dashboard:
- Go to Data >
userstable - Find your user record and set
accessLevelto"system_admin"
- Go to Data >
- Access admin dashboard by clicking your username → "System Admin"
System admins can configure Google OAuth, manage authentication providers, and access system settings.
To enable Google OAuth authentication:
- Configure Google OAuth in your app's admin dashboard:
- Login with your system admin account
- Go to your username → "System Admin" → "Google Auth Config"
- Follow the instructions to set up Google OAuth credentials
- Transfer admin role to Google account (Recommended):
- After Google Auth is configured, sign in with your Google account
- In Convex Dashboard, go to Data >
userstable - Find your Google account user record and set
accessLevelto"system_admin" - Remove the
system_adminaccess level from the temporary anonymous account
This ensures your system admin access is tied to a verified Google account for better security.
apps/webapp: The frontend NextJS applicationservices/backend: The Convex backend service
To run both the frontend and backend in parallel:
pnpm run devThis will start:
- The webapp at http://localhost: (see
PORTinapps/webapp/.env.local, assigned during setup) - The Convex backend development server
- Shadcn → Base UI Migration Guide — upgrading UI components from Radix-based shadcn to Base UI (
base-vega); includes a downstream migration playbook for forks built on this template. - Testing Guide
- AGENTS.md — development guidelines for agents and contributors
This project uses Vitest for testing across both frontend and backend.
Run all tests:
pnpm testRun tests in watch mode:
pnpm test:watchFor comprehensive testing guidelines, conventions, and examples, see the Testing Guide.
This project uses Turbo to manage the monorepo and run tasks in parallel. The main configuration files are:
turbo.json: Main Turbo configurationapps/webapp/package.json: Webapp project configurationservices/backend/package.json: Backend project configuration
The dev command is configured to run both services in parallel without dependencies between them, allowing for independent development.
To add a new project to the monorepo:
- Create the project in the appropriate directory (
apps/orservices/) - Add a
project.jsonfile to define the project's targets - Update the root
package.jsonto include the new project in the dev command if needed
Convex is chosen as the backend service for the following reasons:
-
Simplicity of code generation and architecture
Convex follows a reactive paradigm that allows reactive queries from the client to cause automatic re-renders when a dataset has been updated. This significantly reduces complexity and amount of code required, while solving the problem of cache invalidation.
Simple and less code required for a feature also means fewer chances for AI generated code to be incorrect.
-
Transactionality and consistency
All convex mutations run "inside" of the database. Any error thrown in the mutation will result in an automatic rollback. This ensures that we are able to use a single language for both querying data and business logic, while maintaining transactionality.
-
Simple end to end reactivity
Many platforms offer subscription to DB events (e.g. firebase, supabase). However, it still leaves a significant amount of code to transform the event into the actual state for your application. Convex solves this by simply providing the full state for the query's data, and does a re-render of that state when the data has been updated.
-
Single language for frontend and backend