Add Convex Backend Support to Dyad

Generated by swarm planning session on 2026-02-12

Summary

Add Convex as a third backend option in Dyad (alongside Supabase and Neon), enabling users to build apps with real-time reactive data, serverless functions, and file storage — all without SQL. This positions Dyad as the long-term successor to Chef (the Convex-native builder in chef/), porting Chef's battle-tested prompts and patterns into Dyad's backend-flexible architecture.

Problem Statement

Dyad users currently have two backend options: Supabase and Neon, both PostgreSQL-based. Users building apps that need real-time reactivity, serverless functions, or document-based data models are forced into SQL paradigms or must leave Dyad entirely (using Chef or building manually). Adding Convex expands Dyad's addressable use cases and aligns with the Backend-Flexible design principle.

Target users:

1. Existing Dyad users wanting reactive, real-time apps without managing WebSocket infrastructure
2. Convex developers seeking an AI-assisted builder for their preferred backend
3. New users attracted by Convex's simpler DX (no SQL, no ORM, no migrations — just TypeScript)

Scope

In Scope (MVP)

• Deploy key connection flow — User pastes a Convex deploy key + deployment URL to connect an existing Convex project to a Dyad app. "Open Convex Dashboard" link via ipc.system.openExternalUrl for easy key retrieval. Deploy key field uses type="password" with show/hide toggle. Inline validation errors (not toasts).
• Convex-aware agent prompts — High-fidelity port of Chef's convexGuidelines.ts (~960 lines) and solutionConstraints.ts for Dyad's tool set and execution model. This is the highest-value item. Since Dyad is the long-term Chef successor, invest in prompt quality (budget 3-4 days, not a quick copy).
• Convex context injection — Before each chat turn, read convex/schema.ts from the app's files and inject schema context into the AI prompt.
• Dual dev server via concurrently — Template start script runs both npx convex dev and npx vite via concurrently --names "vite,convex". Uses existing startCommand column — no process manager changes needed. Console output prefixed with process names for error attribution.
• Deploy approval gate — After the AI generates/modifies Convex schema or functions, show a confirmation before running npx convex deploy. Leverages existing tool consent system.
• Convex template — Fork Chef's template (chef/template/) as starting point. Pre-wired with convex/ directory, convex.config.ts, ConvexProvider, correct start scripts, convex + concurrently npm dependencies, Tailwind + shadcn/ui compatibility. Production-quality since Dyad replaces Chef long-term.
• IPC contracts and handlers — Following the Neon pattern for connect/disconnect/get-project-info/deploy/get-schema.
• ConvexConnector UI — Card-based integration on App Details page with two primary states: disconnected (key input + dashboard link + connect button) and connected (project badge + dashboard link + disconnect button). Simpler than Supabase connector since no team/project selection needed.
• Connection status indicator — Small status badge in preview panel toolbar or chat header showing Convex connection state at a glance (ported from Chef's ConvexConnection.tsx pattern).
• Backend mutual exclusivity — Convex is mutually exclusive with Supabase/Neon per app in v1. Gray out other backend connectors when one is active.
• Onboarding card — First-time "What to expect" card explaining: Convex requires internet, schema deploys automatically in dev mode, functions are TypeScript not SQL.
• Dashboard link — "View in Convex Dashboard" link in connected state (trivially cheap, improves connected state UX).
• Agent tools — get_convex_project_info, get_convex_schema, deploy_convex for local-agent mode. Also <dyad-add-integration provider="convex"> support in agent responses for suggesting Convex when appropriate.
• Disconnect flow — Confirmation dialog: "Disconnect from Convex? Your local Convex files will be kept. The Convex project will not be deleted." Unlinks project reference without deleting anything (matches Supabase handleUnsetProject pattern).
• Dependency management — Agent prompt instructs npm install convex when adding Convex to an app. Template includes convex and concurrently as dependencies.

Out of Scope (Follow-up)

• OAuth authentication — Replace deploy key paste with OAuth flow via oauth.dyad.sh (v2)
• Auto-provision new Convex projects — Requires account-level auth; v1 is "connect existing" only
• Convex Auth integration — @convex-dev/auth with username/password/OAuth login (v2)
• Convex Components support — ProseMirror, presence, and other library-level features
• Production vs. development deployment management — Dev-only in v1
• Environment variable management UI — Users set env vars in Convex Dashboard for v1
• Functions viewer — Listing queries/mutations/actions requires TS parsing or deployment API; defer to v2
• Backend switching — No switching from Supabase/Neon to Convex or vice versa. Users create new apps.
• Convex-specific templates in template gallery — v1 uses a single starter template; showcase templates (real-time chat, collaborative todo) are follow-ups

User Stories

1. As a Dyad user, I want to connect my existing Convex project to a Dyad app so that I can build apps with real-time data and serverless functions.
2. As a Dyad user, I want the AI agent to generate correct Convex code (schema, queries, mutations, actions) so that my app works without manual debugging.
3. As a Dyad user, I want my Convex functions to auto-sync during development (via npx convex dev) so that I see live data in the preview immediately.
4. As a Dyad user, I want to approve schema deployments before they push to production so that I understand what's changing.
5. As a Dyad user, I want the AI to know my current Convex schema so that it generates code consistent with my existing tables and indexes.
6. As a first-time Convex user, I want clear guidance on what Convex is and how it differs from SQL so that I can make an informed backend choice.

UX Design

User Flow

Primary flow: Connecting Convex to an existing app

1. User navigates to App Details page for their app
2. User sees Convex integration card in disconnected state with Convex branding and description: "Real-time reactive backend — no SQL needed"
3. User clicks "Connect to Convex" button
4. Dyad opens Convex Dashboard deploy key page in browser (via ipc.system.openExternalUrl) with inline instructions: "Copy your deployment URL and deploy key from the Convex Dashboard"
5. User pastes deployment URL and deploy key into two input fields
6. Dyad validates the credentials (test API call)
7. Connected state shows: project name badge, team name, "View in Convex Dashboard" link, disconnect button
8. First-time onboarding card appears (dismissable): explains Convex requires internet, uses TypeScript functions not SQL, schema syncs automatically in dev mode
9. User describes their app in chat. AI generates Convex-specific code.

Key States

• Disconnected: Convex logo, "Connect to Convex" button, one-line value prop
• Connecting: Spinner with "Validating Convex credentials..." label
• Connected: Project name badge, team name, dashboard link, disconnect button
• Error: Error callout with specific message, retry button, "Try different credentials" option
• First-run: Onboarding card with "What to expect" content (dismissable, shown once via hasSeenConvexOnboarding flag)

Interaction Details

• Deploy key input: Two text fields (deployment URL + deploy key) with paste support and clear labels
• Schema viewer: "View Schema" button opens convex/schema.ts in the existing CodeView panel (Monaco editor, read-only). No custom schema visualization component needed — the schema IS the TypeScript file.
• Deploy approval: After AI modifies Convex files, a chat card shows schema diff with "Deploy to Convex" button. Uses existing tool consent system (mcp_tool_consents).
• Console output: Convex dev server logs interleaved with Vite logs. Convex lines tagged with [Convex] prefix for visual differentiation. Console component can filter/color-code based on source tag.
• Disconnect: Confirmation dialog: "This will disconnect the Convex project. Your Convex project and local files will not be deleted." Unlinks project without deleting anything.

Accessibility

• Deploy key input fields: proper <label> elements, placeholder text, aria-describedby for instructions
• Connection status changes announced via aria-live region
• Team/project info: semantic headings and landmarks
• Onboarding card: dismissable via keyboard (Escape), focus trapped while visible
• Console log source indicators: not color-only — include text prefix [Convex]

Technical Design

Architecture

Follows Dyad's existing layered IPC pattern:

UI (ConvexConnector.tsx) → IPC Contracts (convex.ts) → Handlers (convex_handlers.ts) → CLI/API

CLI-driven approach (not full API client): Use npx convex CLI commands for deploy operations, read convex/schema.ts directly for schema introspection. This mirrors how Chef works and minimizes API surface risk.

Dual dev server: Template's package.json uses concurrently to run both npx convex dev and npx vite. Dyad's existing startCommand column supports custom start scripts — no changes to app_handlers.ts process management.

Components Affected

New files (6 + template):

Note: No convex_return_handler.ts needed (no OAuth). No separate ConvexIntegration.tsx needed (folded into ConvexConnector since scope is simpler). Deploy key storage is per-app in the apps table, NOT in global settings.

Modified files:

Data Model Changes

SQLite schema (apps table) — new nullable text columns:

ALTER TABLE apps ADD COLUMN convex_deployment_url TEXT;
ALTER TABLE apps ADD COLUMN convex_deploy_key TEXT;
ALTER TABLE apps ADD COLUMN convex_project_slug TEXT;
ALTER TABLE apps ADD COLUMN convex_team_slug TEXT;

Deploy keys stored at the app level (not settings level) since Convex uses per-deployment keys. This differs from Supabase (org-level) and Neon (account-level) credential storage.

Drizzle migration required — straightforward ALTER TABLE ADD COLUMN for nullable text fields.

Security note: Deploy keys are stored as plain text in SQLite for v1 (same trust model as local git credentials). For v2, consider using Electron's safeStorage API to encrypt sensitive tokens at rest — this would benefit all backend integrations, not just Convex.

Settings additions:

• hasSeenConvexOnboarding: boolean — tracks whether user has dismissed onboarding card

API Changes

New IPC contracts (src/ipc/types/convex.ts):

• convex:connect-project — Validate and store deploy key + deployment URL for an app
• convex:disconnect-project — Remove Convex association from an app
• convex:get-project-info — Return deployment URL, project slug, team slug
• convex:deploy — Execute npx convex deploy in the app directory
• convex:get-schema — Read and return contents of convex/schema.ts

New agent tools:

• get_convex_project_info — Returns deployment info for context
• get_convex_schema — Returns schema file contents
• deploy_convex — Triggers npx convex deploy (with approval gate)

Key Technical Decisions

1. CLI-driven, not API client: Use npx convex for operations. No official management SDK exists for Convex. Raw HTTP calls where needed.
2. Schema = file read: No SQL introspection needed. convex/schema.ts IS the schema. Simpler than Supabase/Neon.
3. concurrently for dual process: Template start script handles both dev servers. Existing startCommand column supports this without architecture changes.
4. High-fidelity prompt port, not copy-paste: Chef's convexGuidelines.ts and solutionConstraints.ts reference WebContainer and Chef-specific tools. Needs dedicated adaptation for Dyad's tool set (3-4 days). Since Dyad replaces Chef long-term, invest in prompt quality and track Chef's prompt updates for backporting improvements.
5. convex/_generated/ directory: Must be in .gitignore, agent prompt must say "never edit files in convex/_generated/", file tree UI should hide or gray out generated files.
6. Use "backend" not "database" in UI: Convex is a reactive backend platform, not a database. Audit all labels to avoid "database" when referring to Convex.

Implementation Plan

Estimated effort: 14-20 engineering days (3-4 weeks). Checkpoint at week 2 to assess pace.

Phase 1: Template + Foundation (Week 1)

• Fork Chef's template (chef/template/), adapt for Dyad: convex/ directory, convex.config.ts, ConvexProvider setup, concurrently --names "vite,convex" in start script, convex + concurrently dependencies, Tailwind + shadcn/ui compatibility
• Add Convex columns to apps table (convex_deployment_url, convex_deploy_key, convex_project_slug, convex_team_slug) via Drizzle migration
• Define IPC contracts in src/ipc/types/convex.ts following Neon pattern
• Implement convex_handlers.ts with connect/disconnect/get-info/deploy/get-schema handlers
• Implement convex_management_client.ts for deploy key validation
• Build ConvexConnector.tsx with deploy key paste flow (type="password" input, inline validation, "Open Convex Dashboard" link)

Phase 2: AI Integration (Weeks 2-3)

• High-fidelity port of Chef's convexGuidelines.ts + solutionConstraints.ts to src/prompts/convex_prompt.ts — systematically replace WebContainer/Chef tool references with Dyad equivalents (budget 3-4 days)
• Implement convex_context.ts — reads convex/schema.ts and formats for AI prompt
• Wire Convex context injection into chat_stream_handlers.ts (mutually exclusive with Supabase/Neon)
• Add Convex-specific instructions to local_agent_prompt.ts
• Implement agent tools: get_convex_project_info, get_convex_schema, deploy_convex
• Add <dyad-add-integration provider="convex"> support in agent responses
• Add ConvexConnector to App Details page integrations section
• Implement onboarding card ("What to expect with Convex")
• Add connection status indicator in preview panel toolbar
• Add "View in Convex Dashboard" link in connected state
• Implement deploy approval gate via tool consent system
• Add Convex logo/branding assets (light + dark variants)

Phase 3: Testing + Hardening (Week 4)

• Unit tests for IPC contracts (Zod schema validation)
• Unit tests for convex_management_client.ts (mocked HTTP)
• Create fakeConnect test-only handlers following Neon/Supabase pattern
• E2E Playwright tests for ConvexConnector UI flow
• Integration test: create app → connect Convex → AI generates code → deploy
• Prompt regression tests: verify Convex prompt generates valid Convex code
• Console log tagging: recognize Convex-prefixed output in Console component
• Handle convex/_generated/ in gitignore, agent prompts, and file tree UI
• Disconnect flow with confirmation dialog
• Error handling: invalid deploy key, network failure during dev, Convex CLI not found

Testing Strategy

• Unit tests: IPC contracts (Zod validation), management client (mocked HTTP responses), context generator (mock file reads)
• Integration tests: Full flow from connect → AI generation → deploy, using fakeConnect pattern from existing backends
• E2E tests: Playwright tests for ConvexConnector UI component (connect, disconnect, error states)
• Prompt regression: Verify AI generates valid Convex code patterns (schema with validators, queries/mutations with correct function signatures, proper ConvexProvider setup)
• Error scenarios: Invalid deploy key, network failure during deploy, Convex CLI not installed, convex/schema.ts not found, destructive schema changes

Risks & Mitigations

Open Questions

1. Convex branding assets — Do we need permission from Convex to use their logo in Dyad? Check trademark guidelines.
2. Template hosting — Should the Convex template be a new GitHub repo (like existing templates) or a fork of Chef's template adapted for Dyad?
3. Token budget for Convex prompt — The ~960-line prompt from Chef is substantial. May need to be selective for smaller LLM models. Profile token usage and trim if needed.
4. Vercel deployment + Convex — When deploying to Vercel, the CONVEX_URL env var needs to be set. Should this be automated or manual? (Follow-up work.)
5. Chef feature parity roadmap — Since Dyad is the long-term Chef successor, define concrete feature parity milestones. Chef has capabilities Dyad doesn't: WebContainer-based sandboxed execution, sharing/forking projects, social shares with thumbnails, Convex Components support (proseMirror, presence, resend). Plan a follow-up session after MVP ships to create a "Chef parity checklist."

Decision Log

Generated by dyad:swarm-to-plan