{
  "markdown": "# NextJS Convex Starter App\n\nThis is a starter application using NextJS and Convex, managed with Turbo for monorepo capabilities.\n\n## Getting Started\n\n### Pre-requisites\n\n- Node.js 22 or later\n- pnpm package manager\n- Convex account - Register at https://www.convex.dev/\n\n### Setup\n\n1. Run `pnpm install` to install the dependencies\n2. Run `pnpm run setup` to initialize the Convex backend and configure the webapp\n\n   - **Bumps minor version** — When branding is customized, increments the minor version across all workspace `package.json` files (root is canonical). This updates `services/backend/package.json`, which triggers the Production Deployment workflow on push to `master`.\n\n   This script will:\n   - **Check and update branding** - Detects if you're using template branding and prompts you to customize:\n     - Application name and short name\n     - App description\n     - Landing page title\n     - Package name\n   - Initialize the Convex backend using `npx convex dev --once`\n   - Extract the CONVEX_URL from the backend's .env.local file\n   - Create/update the webapp's .env.local file with the NEXT_PUBLIC_CONVEX_URL\n   - Assign a random `PORT` in the IANA ephemeral range (49152–65535) to `apps/webapp/.env.local` if not already configured\n\n   The setup script is **idempotent** - you can run it multiple times safely. It will:\n   - Show ✅ CONFIGURED for branding that's already customized\n   - Show ⚠️ TEMPLATE for branding that still uses default values\n   - Only prompt for updates if template values are detected\n\n   **Non-Interactive Mode**: For CI/CD or automated setups:\n\n   ```bash\n   bun scripts/setup.ts --non-interactive \\\n     --app-name \"My App\" \\\n     --app-short-name \"MyApp\" \\\n     --app-description \"Description\" \\\n     --landing-page-title \"Welcome\" \\\n     --package-name \"my-app\"\n\n   # Or skip branding entirely\n   bun scripts/setup.ts --skip-branding\n\n   # Show all options\n   bun scripts/setup.ts --help\n   ```\n\n3. Run `pnpm dev` in the root directory to start the NextJS application and Convex backend\n\n   After pulling schema changes, run `pnpm migrate` while `convex dev` is running (see [AGENTS.md](AGENTS.md#database-migrations)).\n\n#### Manual Setup (Alternative)\n\nIf you prefer to set up manually:\n\n1. Go to `services/backend` and run `npx convex dev --once` - this should prompt you to login to Convex and create a new project.\n   Note: This will create a .env.local file with the CONVEX_URL environment variable.\n2. Create a `.env.local` file in the `apps/webapp` directory and add the following:\n   ```sh\n   NEXT_PUBLIC_CONVEX_URL=<your-convex-project-url> # copy this from the backend .env.local file\n   ```\n3. Run `pnpm dev` in the root directory to start both services\n\n## Deployment\n\nThe included [production workflow](.github/workflows/deploy-prod.yml) deploys both\nConvex and Vercel. Deployment credentials and environment-specific values are\nkept together as GitHub Actions repository secrets and variables, so they do\nnot need to be committed or duplicated across repository files.\n\n### 1. Create the production projects\n\n1. In the [Convex dashboard](https://dashboard.convex.dev), open the production\n   deployment and copy its deployment URL. Generate a production deploy key from\n   **Project Settings → Settings → General**.\n2. Import the repository into Vercel and set its **Root Directory** to\n   `apps/webapp`. No application environment variables need to be added in\n   Vercel for the default template deployment; the workflow supplies\n   `NEXT_PUBLIC_CONVEX_URL` during the production build.\n3. Create a Vercel access token. Run `pnpm exec vercel link --repo` from the\n   repository root if needed, then read the `apps/webapp` entry in\n   `.vercel/repo.json` to obtain its `orgId` and `id`. Do not commit the\n   `.vercel` directory.\n\n### 2. Configure GitHub Actions secrets and variables\n\nOpen **GitHub repository → Settings → Secrets and variables → Actions → New\nrepository secret** and add:\n\n| Secret                   | Value                                          |\n| ------------------------ | ---------------------------------------------- |\n| `CONVEX_DEPLOY_KEY_PROD` | Convex production deploy key                   |\n| `VERCEL_TOKEN`           | Vercel access token with access to the project |\n\nThen open the **Variables** tab, create these repository variables, and add:\n\n| Variable                 | Value                                    |\n| ------------------------ | ---------------------------------------- |\n| `NEXT_PUBLIC_CONVEX_URL` | Convex production deployment URL         |\n| `VERCEL_TEAM_ID`         | `orgId` from Vercel project metadata     |\n| `VERCEL_PROJECT_ID`      | `projectId` from Vercel project metadata |\n\nThese are the only production deployment values required by the default\nworkflow. Additional build-time values can follow the same pattern: store them\nas GitHub Actions secrets and expose them only to the frontend build job. Values\nthat must remain available to server functions at runtime should be configured\nin Vercel or passed explicitly by a customized deploy step.\n\nThe workflow recreates Vercel's repository-level monorepo link in\n`.vercel/repo.json`. It also writes the transient, settings-only project metadata\nthat `vercel build` expects beneath `apps/webapp`; project identity remains in\nthe repository link. Both build and deploy run from the repository root. The\nworkflow intentionally does not run `vercel pull`, so Vercel project environment\nvariables are not downloaded into CI.\n\n### 3. Deploy\n\nPush a deployment-related change to `master`. Convex deployment and the Vercel\nbuild start in parallel, so the backend is not blocked by frontend CLI setup or\nbuild time. The workflow then:\n\n1. Deploys Convex and runs pending idempotent migrations.\n2. Builds the Vercel production output exactly once.\n3. Promotes that prebuilt output only after the requested backend deployment and\n   migrations succeed.\n\nThe workflow runs for changes under `apps/webapp`, `packages/shared`, or\n`services/backend`, as well as workspace and deployment configuration files. It\ncan also be started from **GitHub Actions → Production Deployment → Run\nworkflow**, where backend and frontend deployment can be enabled independently.\n\n> If you forked this template with existing git history, workflows only run on\n> new pushes after the workflow file exists; they are not replayed for old\n> commits.\n\n## System Administration Setup\n\nTo create a system administrator:\n\n1. **Login anonymously** via the login page\n2. **Set admin privileges** in [Convex Dashboard](https://dashboard.convex.dev):\n   - Go to Data > `users` table\n   - Find your user record and set `accessLevel` to `\"system_admin\"`\n3. **Access admin dashboard** by clicking your username → \"System Admin\"\n\nSystem admins can configure Google OAuth, manage authentication providers, and access system settings.\n\n## Google Auth Setup\n\nTo enable Google OAuth authentication:\n\n1. **Configure Google OAuth** in your app's admin dashboard:\n   - Login with your system admin account\n   - Go to your username → \"System Admin\" → \"Google Auth Config\"\n   - Follow the instructions to set up Google OAuth credentials\n2. **Transfer admin role to Google account** (Recommended):\n   - After Google Auth is configured, sign in with your Google account\n   - In [Convex Dashboard](https://dashboard.convex.dev), go to Data > `users` table\n   - Find your Google account user record and set `accessLevel` to `\"system_admin\"`\n   - Remove the `system_admin` access level from the temporary anonymous account\n\nThis ensures your system admin access is tied to a verified Google account for better security.\n\n## Project Structure\n\n- `apps/webapp`: The frontend NextJS application\n- `services/backend`: The Convex backend service\n\n## Development\n\nTo run both the frontend and backend in parallel:\n\n```bash\npnpm run dev\n```\n\nThis will start:\n\n- The webapp at http://localhost:<PORT> (see `PORT` in `apps/webapp/.env.local`, assigned during setup)\n- The Convex backend development server\n\n## Documentation\n\n- **[Shadcn → Base UI Migration Guide](docs/developer/shadcn-base-ui-migration.md)** — upgrading UI components from Radix-based shadcn to Base UI (`base-vega`); includes a downstream migration playbook for forks built on this template.\n- [Testing Guide](guides/testing/testing.md)\n- [AGENTS.md](AGENTS.md) — development guidelines for agents and contributors\n\n## Testing\n\nThis project uses [Vitest](https://vitest.dev/) for testing across both frontend and backend.\n\n### Quick Start\n\nRun all tests:\n\n```bash\npnpm test\n```\n\nRun tests in watch mode:\n\n```bash\npnpm test:watch\n```\n\nFor comprehensive testing guidelines, conventions, and examples, see the [Testing Guide](guides/testing/testing.md).\n\n## Turbo Configuration\n\nThis project uses Turbo to manage the monorepo and run tasks in parallel. The main configuration files are:\n\n- `turbo.json`: Main Turbo configuration\n- `apps/webapp/package.json`: Webapp project configuration\n- `services/backend/package.json`: Backend project configuration\n\nThe dev command is configured to run both services in parallel without dependencies between them, allowing for independent development.\n\n## Adding New Projects\n\nTo add a new project to the monorepo:\n\n1. Create the project in the appropriate directory (`apps/` or `services/`)\n2. Add a `project.json` file to define the project's targets\n3. Update the root `package.json` to include the new project in the dev command if needed\n\n<br/>\n\n# FAQ\n\n## Why Convex?\n\nConvex is chosen as the backend service for the following reasons:\n\n1. **Simplicity of code generation and architecture**\n\n   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.\n\n   Simple and less code required for a feature also means fewer chances for AI generated code to be incorrect.\n\n2. **Transactionality and consistency**\n\n   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.\n\n3. **Simple end to end reactivity**\n\n   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.\n\n4. **Single language for frontend and backend**\n",
  "bytes": 10718,
  "sha": "30e7d65d52b313ca9fdbbd9b3204e247dc5fa741bcf84a2fe4e6ada65cb7aae8",
  "repo_slug": "conradkoh/next-convex-starter-app",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_conradkoh_next_convex_starter_app_memory_f7e7986b/readme"
}