Bubble.io → Code Migration Agent

An AI-powered migration tool that extracts your Bubble.io application's architecture, generates comprehensive documentation for rebuilding it in code, and renders the generated files in a browser preview. Uses the OpenAI TypeScript SDK with the Responses API for LLM-powered documentation generation, and can target OpenAI-compatible providers through environment variables.

What It Produces

Given a .bubble export file and an output directory, the agent generates:

<output-dir>/
├── your-app.bubble          ← original export (copied here)
├── architecture.md          ← full architecture breakdown with ER diagrams
├── backend/
│   ├── schema.prisma        ← PostgreSQL data model (snake_case, enums, relations)
│   └── openapi.yaml         ← Swagger/OpenAPI 3.0 spec for all API endpoints
└── frontend/
    ├── sitemap.md           ← every route, UI elements, workflows & triggers
    └── design.md            ← typography, colors, spacing, component styles

Prerequisites

• Node.js ≥ 18
• AI provider API key — for OpenAI, create one in the OpenAI dashboard

Installation

Install globally for a system-wide bubble-migrator command:

npm install -g @goodspeedstudio/bubble-migrator

Or install locally in a project and invoke via npx:

npm install @goodspeedstudio/bubble-migrator
npx bubble-migrator ./your-app.bubble ./output

Configuration

Set your API key as an environment variable before running:

export AI_KEY=sk-...
# Optional:
export AI_MODEL=gpt-5.4

OpenAI-compatible providers

Set AI_URL to use another provider that exposes an OpenAI-compatible Responses API:

export AI_KEY=your-provider-key
export AI_URL=https://your-provider.example/v1
export AI_MODEL=provider-model-name

Usage

Both the .bubble file path and the output directory are required for migration.

# Generate files only
bubble-migrator ./your-app.bubble ./output

# Generate files, then start the renderer on port 3000
bubble-migrator ./your-app.bubble ./output --serve

# Generate files, then start the renderer on a custom port
bubble-migrator ./your-app.bubble ./output --serve --port 8080

# Render an existing migration output directory
bubble-migrator render ./output

# Render an existing migration output directory on a custom port
bubble-migrator render ./output 8080

Example

bubble-migrator ~/Downloads/my-app.bubble ./my-app-migration

This creates:

my-app-migration/
├── my-app.bubble
├── architecture.md
├── backend/
│   ├── schema.prisma
│   └── openapi.yaml
└── frontend/
    ├── sitemap.md
    └── design.md

To preview the generated files:

bubble-migrator render ./my-app-migration 3000

Then open http://localhost:3000.

Programmatic use

You can also import the migration and renderer entry points directly:

import { extractAll, runMigrationAgent, createServer } from "@goodspeedstudio/bubble-migrator";

How It Works

Phase 1: Deterministic Extraction (No LLM)

Pure TypeScript parsing of the .bubble JSON file:

• Resolves all internal Bubble IDs to human-readable names
• Maps Bubble field types to PostgreSQL/Prisma equivalents
• Extracts pages, workflows, API endpoints, styles, and reusable elements
• Generates the Prisma schema deterministically (zero hallucination risk)

Phase 2: LLM-Powered Documentation

Feeds clean, structured data to the configured AI model in manageable chunks:

• Generates natural-language descriptions of workflows and their purposes
• Writes the sitemap with workflow trigger documentation
• Produces OpenAPI specs with inferred request/response schemas
• Creates the design system document from style tokens
• Writes the architecture overview with Mermaid ER diagrams

Phase 3: Browser Preview

Serves the generated output directory through the integrated renderer:

• Renders .md files as HTML with syntax-highlighted code blocks and Mermaid diagrams
• Renders .yaml / .yml OpenAPI files through Swagger UI
• Renders .prisma and other source-like files as highlighted code
• Hides the copied .bubble export, dotfiles, and .DS_Store from the file tree

Bubble Type → Prisma/PostgreSQL Mapping

| Bubble Type | Prisma Type | Notes | |-------------|-------------|-------| | text | String | | | number | Float | | | boolean | Boolean | | | date | DateTime | | | file / image | String | Stored as URL | | option.<name> | Enum | Generates a Prisma enum | | custom.<name> | Relation | Foreign key + @relation | | list.<type> | Type[] | Array of the mapped type | | user | Relation → User | FK to built-in User model | | api.* | Json | API connector data |

Limitations

• No actual data migration — extracts the schema and docs, not your database records. Export data separately via Bubble's CSV export or Data API.
• Workflow logic is interpreted, not compiled — the LLM describes what workflows do; it doesn't generate executable code.
• Complex expressions — deeply nested Bubble expressions are represented as raw JSON. The architecture doc helps interpret them.
• Plugin logic — third-party Bubble plugin behavior isn't captured in the export file.

License

MIT