App Builder

Compiles your validated spec into a running Next.js + Supabase app — repo, live URL and all — without leaving VibeMap. · Optional (premium)

Every other part of VibeMap turns your idea into a spec and hands it to your AI coding agent. The App Builder is the one feature that turns that spec into a running app in-app. Use it when you want a working, deployable starting point rather than a set of instructions; skip it if you'd rather your own agent write every line.

This is a premium add-on available on the Pro, Team, and Enterprise plans. On Free and Starter, the Build tab shows an upgrade prompt — see 15.1 Account & billing.

What it does

From a single Build button, the App Builder compiles your blueprint into a complete app that includes:

• A Next.js scaffold — package.json, config, Tailwind, layout, and global styles on pinned, known-good dependency versions.
• Your database schema — one migration per table (columns, foreign keys, indexes), plus typed row interfaces and list / get / create / update / delete server actions per entity.
• Access control — your access rules compiled into Postgres row-level security (RLS) policies, and your page access rules into route guards.
• Authentication — a Supabase sign-in flow matching your chosen method (email/password, social, or magic link), optional MFA, callback routes, session middleware, and a protected-route wrapper.
• Payments (optional) — if your project uses payments, a Stripe module for the model you chose (recurring subscriptions with a billing portal, or one-off orders) with a signed webhook handler.
• Your pages — route files and layout shells for every page. Pure-CRUD pages are generated end-to-end; pages needing custom logic get a shell plus an AI-filled body driven by their acceptance criteria.
• The features you toggle on — user roles, content/blog, team invitations, file storage, and marketing pages, each compiled from your architecture options.

The blueprint is used three ways at once: as the input to the compiler, as the goal for the AI fill step, and as the test oracle for verification. That's the part a prompt-only tool can't replicate.

Prerequisites

1. Your spec must be ready. The blueprint has to be prepared for development — features approved, stories tied to personas, acceptance criteria written, pages outlined, schema reviewed. The Build tab shows a readiness panel and keeps Build disabled until the project is prepared. See 10.1 Prepare for development.

2. Connect the accounts you want to use. The Build tab has a connect checklist; each provider unlocks a different part of the output:

Connecting a provider links your own account via OAuth — the repo, deployment, and database all belong to you, and your tokens are stored encrypted. If you haven't connected GitHub, the build still runs in build-only mode (you get the ZIP, no repo or deploy).

After connecting Supabase, a deploy target picker lets you choose which of your Supabase projects the app should use; the deploy stamps that project's URL and anon key into Vercel automatically. Skip it and the app deploys with placeholder env vars for you to fill in — VibeMap never substitutes its own credentials.

Apply schema (optional, per build). Once a deploy target is chosen, an "Apply schema to my Supabase project" checkbox appears. Tick it and a successful build runs the generated SQL migrations on that project, so the deployed app has a working database immediately. It's off by default, never remembered between builds, and only worth ticking on a project you're happy for VibeMap to modify. If a migration fails, the build still succeeds and names the failure so you can apply the rest by hand.

How to build

1. Open your project and go to the Build tab.
2. Work through the connect checklist — Supabase (and pick a deploy target), GitHub, Vercel (and Stripe if you have payments).
3. Confirm the readiness panel shows the project as prepared.
4. Check the build plan card — a free dry run showing how many files are deterministic, which pages need AI (and against how many criteria), anything the builder can't express, and a spec check of the blueprint's integrity. All before any tokens are spent.
5. Choose an output target (below) and optionally tick Apply schema.
6. Click Build.
7. Watch the progress stepper move through its stages.
8. When it finishes, use the results panel — open the live URL, visit the repo, or download the ZIP. It also shows the run's duration, approximate AI cost, and the build report.

Output targets

The three paths aren't mutually exclusive:

• ZIP export — the verified app as a downloadable archive with .env.example and a setup README. No deploy accounts required.
• GitHub — a new private repo with the verified code pushed to it.
• Deploy (Vercel) — a live URL, linked to the GitHub repo, with env vars stamped in. (Secrets live in Vercel, never committed.)

The build stages

The build report

Every finished run (success or failure) includes spec → app traceability:

• Per page: implemented, placeholder, or quarantined (a page whose AI body couldn't be made to compile ships as a styled placeholder rather than failing the whole build), with the acceptance-criteria refs it was built against.
• Unsupported spec items: anything the compiler can't express yet — listed, never silently dropped.
• Blocked writes: files the AI tried to modify outside its per-page sandbox (discarded; diagnostic only).

Your acceptance criteria ship as tests

The generated app contains a Vitest suite at tests/specs/ — one spec file per user story, one named test slot per acceptance criterion (as it.todo, carrying its full Given/When/Then). Run it with pnpm test. After a build verifies, the builder runs the suite itself and reports failures per page in the build report (report-only — it never fails your build).

⚡ Power-user hints

• Pick which model handles the AI fill stage from the Build button's model picker (code-capable models only). Bigger models fill complex logic more reliably; the default is a strong middle ground.
• Incremental rebuild re-uses unchanged AI-implemented pages and only regenerates what you changed — faster and cheaper. See 14.3 Continuous build.
• Edit with AI — on a successful run, every implemented page has an Edit action: describe a change and the builder patches that one page (verified before applying, then pushed). See 14.3.

↔ The traditional way

Scaffolding an authenticated SaaS from scratch — Next.js project, Supabase migrations, RLS policies, auth flows, Stripe webhooks, CRUD for every entity — is days of boilerplate before you write a line of real feature code. The App Builder compiles all of that from your validated spec deterministically, fills only the genuinely custom logic with AI, and verifies the result compiles before handing it over.

Current status & limitations

• Premium add-on — Pro, Team, and Enterprise only.
• First version targets authenticated CRUD-style SaaS apps (with optional Stripe). Broader archetypes come later.
• Rebuilds are additive — great for additive schema changes; richer migration diffing is a later phase.
• "No auth" apps are generated without login flows by design: pages still call a requireUser() guard, but it's a documented no-op, so the app runs open. Flip the architecture choice and rebuild to add real auth later.

What's next

• Pick your app's shape → 14.2 Architecture options.
• One-click plan-to-app → 14.3 Continuous build.
• Get the spec ready first → 10.1 Prepare for development.
• Plans & pricing → 15.1 Account & billing.