Contributing to Bubble Lab - Important Notice

January 20, 2026 · View on GitHub

⚠️ UPDATE (January 20, 2026): We are no longer accepting contributions to this project at this time. Thank you to everyone who has contributed and shown interest in Bubble Lab.

Contributing to Bubble Lab (Prior to Jan 20, 2026)

Thank you for your interest in contributing to Bubble Lab! We welcome all kinds of contributions from the community. AI-powered search tools such as Cursor's ask mode can significantly speed up the process of understanding each part of the codebase.

Getting Started

Before contributing, please:

Join our Discord community for discussions and support
Check existing issues or open a new one to discuss your idea
Read through this guide to set up your development environment

Prerequisites

Make sure you have the following installed:

Bun - Required for running the backend API server
pnpm - Package manager for monorepo management
Node.js - v18 or higher

Development Setup

Quick Setup (Mac/Linux)

Run Bubble Studio locally in 2 commands:

# 1. Install dependencies
pnpm install

# 2. Start everything
pnpm run dev

That's it! The setup script automatically:

✅ Creates .env files from examples
✅ Configures dev mode (no auth required)
✅ Sets up SQLite database
✅ Builds core packages
✅ Starts both frontend and backend

Open http://localhost:3000 and start building workflows!

What Gets Started

Frontend: http://localhost:3000 (Bubble Studio)
Backend: http://localhost:3001 (API Server)

Windows Setup (Separate Steps)

Some scripts use Unix commands (cp, bash), so Windows requires manual steps:

1. Install Dependencies

pnpm install

2. Build Core Packages

pnpm build:core

3. Copy Required Files

Copy-Item "packages/bubble-core/dist/bubble-bundle.d.ts" "apps/bubble-studio/public/bubble-types.txt" -Force
Copy-Item "packages/bubble-core/dist/bubbles.json" "apps/bubble-studio/public/bubbles.json" -Force

4. Start Servers (Two Terminals)

Terminal 1 – Backend (API):

cd apps/bubblelab-api
& "$env:USERPROFILE\.bun\bin\bun.exe" run src/index.ts

Runs on: http://localhost:3001

Terminal 2 – Frontend (Studio):

cd apps/bubble-studio
pnpm vite --host 0.0.0.0 --port 3000

Runs on: http://localhost:3000

⚠ If you get "TypeScript validation failed," rebuild core packages.

Environment Configuration

Required API Keys

⚠️ IMPORTANT: To run any flows in self-hosted mode, you MUST configure these API keys in apps/bubblelab-api/.env:

GOOGLE_API_KEY=your_google_api_key        # Required for AI flow execution
OPENROUTER_API_KEY=your_openrouter_key    # Required for AI flow execution

Without these keys, you can use the visual builder but cannot execute flows. Get your keys:

Google AI API: https://aistudio.google.com/apikey
OpenRouter: https://openrouter.ai/keys

Environment Files

The setup script creates these files with sensible defaults:

apps/bubble-studio/.env:

VITE_API_URL=http://localhost:3001
VITE_CLERK_PUBLISHABLE_KEY=
VITE_DISABLE_AUTH=true  # Dev mode: no auth needed

apps/bubblelab-api/.env:

BUBBLE_ENV=dev  # Creates mock user automatically
DATABASE_URL=file:./dev.db  # SQLite

Optional API Keys

Enable specific features in apps/bubblelab-api/.env:

# AI Model Providers
OPENAI_API_KEY=           # OpenAI API key for GPT models

# Communication & Storage
RESEND_API_KEY=           # Resend API key for email notifications
FIRE_CRAWL_API_KEY=       # FireCrawl API key for web scraping

# Authentication (optional, only needed for production mode)
CLERK_SECRET_KEY_BUBBLELAB=  # Clerk secret key for authentication

# OAuth (optional)
GOOGLE_OAUTH_CLIENT_ID=      # Google OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET=  # Google OAuth client secret

# Cloud Storage (optional)
CLOUDFLARE_R2_ACCESS_KEY=    # Cloudflare R2 access key
CLOUDFLARE_R2_SECRET_KEY=    # Cloudflare R2 secret key
CLOUDFLARE_R2_ACCOUNT_ID=    # Cloudflare R2 account ID

# Other
PYTHON_PATH=              # Custom Python path (optional)
CREDENTIAL_ENCRYPTION_KEY=8VfrrosUTORJghTDpdTKG7pvfD721ChyFt97m3Art1Y=  # Encryption key for storing user credentials
BUBBLE_CONNECTING_STRING_URL=  # Database connection string (optional, defaults to SQLite)

Development vs Production Mode

Development Mode (Default)

By default, the app runs in development mode with:

🔓 No authentication required - Uses mock user dev@localhost.com
💾 SQLite database - Auto-created at apps/bubblelab-api/dev.db
🎯 Auto-seeded dev user - Backend creates the user automatically

Production Mode

To run with real authentication:

Get your Clerk keys at clerk.com
Update .env files:

Frontend (apps/bubble-studio/.env):

VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
VITE_DISABLE_AUTH=false

Backend (apps/bubblelab-api/.env):

BUBBLE_ENV=prod
CLERK_SECRET_KEY=sk_test_...

Restart with pnpm run dev

Available Commands

# Run only the setup script
pnpm run setup:env

# Start development servers
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm test

# Lint code
pnpm lint