Bubble to Next.js: Complete Migration Guide

Why Next.js Is the Right Target for Bubble Apps

Bubble is not a website builder. It's a full application platform — with databases, workflows, user authentication, and business logic baked into a visual editor. That means migrating from Bubble is fundamentally different from migrating from tools like Framer or Webflow. You're not just recreating a frontend. You're rebuilding an entire application stack.

Next.js is the ideal target because it covers the full spectrum. React components handle your UI. API routes replace Bubble workflows. Server actions handle form submissions and data mutations. PostgreSQL (via Prisma or Drizzle) replaces Bubble's built-in database. And Next.js deploys as a single, cohesive application — no stitching together five different services.

The migration is significant, but the result is transformative: an application that loads in under a second instead of five, costs a fraction to host, and can be maintained and extended by AI coding tools like Claude Code. Every feature you build after migration happens at 10x the speed compared to Bubble's visual editor.

Step 1: Audit Your Bubble Application

Before writing a single line of code, you need a complete inventory of what your Bubble app does. Bubble apps tend to accumulate complexity in ways that aren't immediately visible — hidden workflows, conditional logic, scheduled tasks, and API integrations buried in the visual editor.

Create a document that covers:

• Pages and reusable elements. List every page in your Bubble app. Note which ones are public, which require authentication, and which use URL parameters. Document every reusable element — these become React components.
• Data types and fields. Export your complete data schema. Every data type in Bubble becomes a database table. Every field becomes a column. Pay special attention to linked data types — these become foreign key relationships.
• Workflows. This is the most critical audit step. Go through every page and list every workflow: button clicks, page loads, input changes, custom events. Document what each workflow does, step by step. These become API routes, server actions, or client-side event handlers.
• API connections. List every external API your Bubble app calls via the API Connector plugin. Note the endpoints, authentication methods, and how the responses are used. These become fetch calls or dedicated API client modules.
• Plugins. Document every Bubble plugin you use. Some have direct npm equivalents. Others represent custom functionality you'll need to rebuild. Plugins like Stripe, Google Maps, and SendGrid have well-maintained JavaScript SDKs that are actually easier to work with than Bubble's plugin wrappers.

Step 2: Export and Migrate Your Data

Bubble lets you export data as CSV files from the App Data tab. This is your primary extraction method. For each data type:

1. Go to the App Data tab in your Bubble editor
1. Select the data type you want to export
1. Click "Export data" and download the CSV
1. Repeat for every data type in your application

The CSV export includes Bubble's unique IDs, creation dates, modification dates, and all field values. However, there are several gotchas to watch for:

• Linked data types export as Bubble IDs. If a "Order" has a field "Customer" that links to a "User" data type, the CSV contains the Bubble unique ID of that user, not the user's name or email. You'll need to map these IDs to your new database's IDs during import.
• Lists export as comma-separated values. Bubble's list fields (like tags or categories) export as comma-separated strings within a single CSV cell. You'll need to parse these and create proper many-to-many relationships in PostgreSQL.
• File and image fields export as URLs. These point to Bubble's S3 storage. Download every file before your Bubble subscription ends — these URLs will stop working when you cancel.
• Geographic address fields need special handling. Bubble stores addresses as a composite type with latitude, longitude, and formatted address. You'll need to decide how to structure this in PostgreSQL — typically as separate columns or a JSON field.

Setting Up PostgreSQL

Design your PostgreSQL schema based on your Bubble data types. Each data type becomes a table. Each field becomes a column with an appropriate PostgreSQL type:

• Bubble text → PostgreSQL VARCHAR or TEXT
• Bubble number → PostgreSQL INTEGER, BIGINT, or NUMERIC
• Bubble yes/no → PostgreSQL BOOLEAN
• Bubble date → PostgreSQL TIMESTAMP WITH TIME ZONE
• Bubble file/image → PostgreSQL TEXT (store the URL after re-hosting)
• Bubble geographic address → PostgreSQL JSONB or separate lat/lng columns
• Bubble list → PostgreSQL ARRAY or junction table for many-to-many
• Bubble linked data type → PostgreSQL FOREIGN KEY reference

Use an ORM like Prisma or Drizzle to define your schema in TypeScript and generate migrations. This gives you type-safe database access throughout your Next.js application — a massive upgrade from Bubble's untyped data access.

Step 3: Recreate the UI with React Components

Bubble's visual elements map to React components and HTML elements. The translation is straightforward once you understand the pattern:

• Bubble Group → div with Flexbox or Grid. Bubble's groups are layout containers. In React, these become div elements styled with CSS Flexbox or Grid. The group's alignment, padding, and gap settings translate directly to CSS properties.
• Bubble Repeating Group → Array.map() in React. This is one of the most-used Bubble elements. In React, you fetch your data and map over it, rendering a component for each item. You get pagination, filtering, and sorting through your database queries rather than Bubble's limited repeating group options.
• Bubble Text → HTML elements (h1-h6, p, span). Use semantic HTML elements for better SEO and accessibility. Bubble's dynamic expressions within text elements become JavaScript template literals or React state variables.
• Bubble Input → HTML input with React state. Form inputs become controlled React components. Use React Hook Form or Formik for complex forms with validation, conditional fields, and multi-step flows.
• Bubble Popup → Modal component. Bubble's popup element becomes a React modal using Headless UI, Radix, or a custom component with portal rendering.
• Bubble Reusable Element → React component. This is a one-to-one mapping. Every reusable element in Bubble becomes a React component with props replacing Bubble's custom states.

Handling Responsive Design

Bubble's responsive engine uses a constraint-based system that is notoriously difficult to work with. Elements have minimum and maximum widths, and the responsive behavior is often unpredictable. In Next.js with Tailwind CSS, you use a mobile-first breakpoint system that is far more predictable. Define your mobile layout first, then add responsive modifiers for tablet and desktop. The result is cleaner, more maintainable responsive design.

Step 4: Convert Workflows to Code

This is the heart of the migration. Bubble workflows are sequences of actions triggered by events. In Next.js, these become:

• Button click workflows → onClick handlers or form actions. Simple workflows that update the UI become React event handlers. Workflows that modify data become server actions or API route calls.
• Page load workflows → useEffect hooks or server components. Data fetching on page load happens in server components (preferred) or useEffect hooks. Conditional redirects happen in middleware.
• Conditional workflows → JavaScript if/else or switch statements. Bubble's "Only when" conditions become standard JavaScript conditionals. This is actually easier to reason about in code than in Bubble's visual condition builder.
• Backend workflows → API routes. Bubble's backend workflows (triggered by API or scheduled) become Next.js API routes in app/api/. These can be called from your frontend or from external services.
• Scheduled workflows → Cron jobs. Bubble's scheduled workflows become cron jobs. Use Vercel Cron, a self-hosted cron service, or a library like node-cron to run tasks on a schedule.

Step 5: Rebuild Authentication

Bubble has built-in user authentication — sign up, log in, password reset, email verification. In Next.js, you need to implement this yourself, but excellent libraries make it straightforward:

• NextAuth.js (Auth.js) — the most popular authentication library for Next.js. Supports email/password, OAuth providers (Google, GitHub, etc.), magic links, and session management. For most Bubble migrations, NextAuth covers everything you need.
• Clerk — a managed authentication service with pre-built UI components. Drop-in replacement for Bubble's auth with additional features like multi-factor authentication and organization management.
• Lucia Auth — a lightweight, database-backed auth library for developers who want full control. Pairs well with Prisma and PostgreSQL.

Migrating user accounts requires special care. You cannot export password hashes from Bubble, which means existing users will need to reset their passwords after migration. The standard approach is to send a password reset email to all users on launch day, or implement a "first login" flow that prompts for a new password.

Step 6: Handle Bubble-Specific Patterns

Privacy Rules → Row-Level Security

Bubble's privacy rules control which users can see and modify which data. In PostgreSQL, this translates to row-level security policies or application-level authorization checks. For most apps, checking user permissions in your API routes is the simplest approach. For applications with complex multi-tenant requirements, PostgreSQL's built-in row-level security is more robust.

Custom States → React State

Bubble's custom states are element-level variables that control UI behavior. In React, these become useState hooks or state management with Zustand or Jotai. The migration is conceptually simple — every custom state becomes a React state variable — but you'll find that React's state model is more powerful and predictable than Bubble's.

URL Parameters → Next.js Dynamic Routes

Bubble uses URL parameters to pass data between pages. In Next.js, dynamic route segments ([slug], [id]) serve the same purpose but with better SEO and cleaner URLs. Combine with searchParams for filter and sort parameters.

Testing and Launch Checklist

Before switching from Bubble to your new Next.js application, verify:

1. Every page renders correctly on mobile, tablet, and desktop
1. User registration, login, and password reset work end-to-end
1. All data from Bubble has been imported correctly, with relationships intact
1. Every workflow has been converted and produces the same results
1. File uploads work and previously uploaded files are accessible
1. Email notifications send correctly (transactional emails, password resets)
1. Payment processing works if you have Stripe or payment integrations
1. API integrations with external services function correctly
1. Performance is measurably better — run Lighthouse on every key page
1. 301 redirects are in place for any URL structure changes

Keep your Bubble app running for at least 30 days after launch as a safety net. You can always revert your domain if a critical issue surfaces during the transition period.