Skip to main content
Add totalmod to a Next.js app: a Request a feature button for your users, an AI interviewer that turns a request into a spec, a GitHub Action that builds it on a branch, a private preview on mock data, and a merge that only you can make. Plan for about an hour, most of it in the GitHub and Vercel settings.

Before you start

You need:
  • A Next.js app using the App Router, on React 19 and Node 24 or later.
  • A GitHub repository for the app. The build runs in GitHub Actions.
  • Vercel preview deployments from that repository, through Vercel’s GitHub integration. That’s how requesters get a preview of their feature.
  • An Anthropic API key. The interviewer and the build agent use Claude.
  • A sign-in system. totalmod asks your app who the signed-in user is.

Set up

1

Add totalmod to your app

In your app’s folder, run:
It adds these files and never edits your existing ones. If a file already exists, it’s kept unless you pass --force.If your app uses a src/ folder, the app files go under src/. These files are licensed MIT-0, so they’re yours to change.Then install the runtime packages:
2

Tell totalmod who is asking

Open lib/totalmod.ts and make getRequester return the signed-in user, or null for a signed-out visitor:
lib/totalmod.ts
The id is hashed before it leaves your app. plan and role are optional, and decide who may send requests.The same file sets where requests are stored. Implement RequestStore against a table in your own database before going live. It has five methods: create, get, update, countSince and latestByUser. The demo app has a Drizzle version.
The generated memoryRequestStore() is fine for trying totalmod out, but it loses requests on restart.
3

Show the widget

Render the widget once, in your root layout:
app/layout.tsx
It renders nothing for users who can’t send requests. To match your brand, set the --tms-* custom properties (--tms-accent, --tms-bg, --tms-text, …) on .tms-root.Then add two packages to serverExternalPackages. The flag provider must not be bundled:
next.config.ts
4

Set up mock data for previews

Every preview runs on mock data, with no way to reach production. Your app has to support this:
  • With TOTALMOD_MODE=mock, use an in-memory database seeded from seed/mock.ts, never DATABASE_URL. Fill seed/mock.ts with users shaped like your real ones: one per plan and role, at realistic volumes.
  • Add a /totalmod/preview route that turns the requester’s signed link into a mock session:
app/totalmod/preview/route.ts
The demo app’s preview route is a complete example.
5

Set your policy

totalmod.config.yaml is enforced by deterministic checks in CI, not by prompts:Specs and fix requests that touch auth, billing, migrations, admin, secrets or CI are declined.
6

Connect GitHub

Create two secrets first. Any long random string works:
A token. Create a fine-grained personal access token for this one repository, with read and write access to Contents, Issues and Pull requests. Issues and PRs are created as you. For a team, a GitHub App with the same permissions is better; the server README shows how.Actions settings. In the repository, under Settings → Secrets and variables → Actions, add:Webhook. Under Settings → Webhooks → Add webhook:
  • Payload URL: https://<your app>/api/totalmod/webhooks/github
  • Content type: application/json
  • Secret: your TOTALMOD_WEBHOOK_SECRET
  • Events: choose individual events, then Pull requests and Deployment statuses
7

Set the environment variables

In your Vercel project, under Settings → Environment Variables. Production and Preview get different values on purpose:
Uncheck Preview on every production variable. A preview has no path to production data because it never gets the credentials.
8

Check your setup

It checks your config, flags file and workflows, and lists the secrets to set. To also check the Vercel environment, set VERCEL_TOKEN and VERCEL_PROJECT_ID first (plus VERCEL_TEAM_ID for a team project). It fails if a credential is in Preview, or if TOTALMOD_MODE or TOTALMOD_PREVIEW_SECRET is missing there.Fix anything it reports, then deploy.

Try the loop

Sign in to your deployed app as a normal user and click Request a feature:
  1. Request. Describe a feature in a sentence. The interviewer asks up to four questions, then shows a spec to confirm or edit once.
  2. Build. Confirming files a GitHub issue labelled totalmod:build, holding only the spec. The build workflow checks the policy and budgets, has Claude Code build it on totalmod/req-<id>, checks the changed paths, and opens a draft PR with a risk summary.
  3. Preview. Vercel deploys the branch on mock data. The widget shows the requester a private Try it link that only they can open, valid for 24 hours.
  4. Fix rounds. The requester can ask for changes, up to iterations.max times. Each one is rewritten into concrete changes before it reaches the build agent.
  5. Approval. Looks good marks the PR ready for your review.
  6. Release. You review and merge. The feature turns on for the requester first, behind a flag. Add a label to the merged PR to go further: totalmod:rollout-25 for 25% of users (any number from 1 to 99), totalmod:ga for everyone, or totalmod:off to switch it off. After flags.removeAfterDays at full rollout, a PR removes the flag.
Features are wrapped in isRequestEnabled(user.id, reqId) from @totalmod/flags. The build agent adds this for you.

Try it without an API key

The interviewer can run on Ollama or LM Studio, so you can try the request flow with a model you already have. From a clone of the totalmod repo:
Then open 127.0.0.1:3200, sign in and click Request a feature.
GitHub is stubbed in this demo, and only a model on the same machine is accepted, so this is for testing, not production.

If something doesn’t work

getRequester returned null, or requesters in totalmod.config.yaml excludes this user.
Check that TOTALMOD_TRUSTED_ACTORS matches the account the issue was filed as, and that budgets aren’t spent. The workflow comments on the issue when it stops.

Telemetry and license

totalmod sends anonymous counts, such as requests submitted and previews ready, and never request text, code, prompts or user ids. The CLI says so on first run. Turn it off with DO_NOT_TRACK=1 or telemetry: false. totalmod is free under the AGPL-3.0, or available under a commercial license for closed-source products. Files that npx totalmod init adds are MIT-0.