Intermediateainextjsreacttailwindvisual-editordesign-toolbunsupabasedocker

Onlook: Visual-first code editor for Next.js

Build and design Next.js + TailwindCSS websites visually with AI. Edit directly in the browser DOM with Figma-like UI, real-time code sync, and AI-powered development.

Step 1
What is Onlook?
Onlook is an open-source, visual-first code editor that bridges design and development for Next.js + TailwindCSS projects. Think "Cursor for Designers" — it combines a Figma-like visual interface with real-time code editing, AI-powered generation, and browser-based DOM manipulation.

Key capabilities:
- Create Next.js apps from text, images, or templates
- Visually edit with Figma-like UI while code updates in real-time
- AI chat creates or edits projects with natural language
- Draw new divs, rearrange layouts, manage components
- Branching to experiment with designs safely
- Deploy with sharable links or custom domains
What makes it unique: Unlike Bolt.new, Lovable, V0, or Webflow, Onlook runs your actual Next.js code in a sandbox, maps every DOM element back to its source location, and lets you edit either visually or in code — changes sync bidirectionally. It's code-first design, not design-first code generation.
Step 2
Technology stack
Onlook is built as a modern full-stack monorepo with cutting-edge tooling:

Frontend:
- Next.js 16 with App Router
- React 19
- TailwindCSS 4 (CSS-first config)
- tRPC for type-safe APIs
- @tanstack/react-query for data fetching
- CodeMirror for code editing
- @uiw/react-codemirror for advanced editor features
- Lucide React icons
Backend & Database:
- Supabase (PostgreSQL, Auth, Storage)
- Drizzle ORM for type-safe database access
- @supabase/ssr for server-side rendering auth
AI & Code Intelligence:
- Vercel AI SDK for LLM integration
- OpenRouter for multi-model AI chat
- Morph Fast Apply and Relace for fast code changes
- Custom parser (@onlook/parser) for code analysis
Sandbox & Hosting:
- CodeSandbox SDK for dev containers
- Freestyle for deployment hosting
- @zenfs for in-browser file system
Monorepo & Runtime:
- Bun (package manager, runtime, bundler)
- Docker for containerization
- Turborepo-style workspaces
- TypeScript 5 across all packages
```
Frontend:
├── Next.js 16 + React 19
├── TailwindCSS 4
├── tRPC (type-safe APIs)
└── CodeMirror (code editor)

Backend:
├── Supabase (DB + Auth)
├── Drizzle ORM
└── PostgreSQL

AI:
├── Vercel AI SDK
├── OpenRouter (LLM provider)
└── Morph/Relace (fast apply)

Runtime:
├── Bun (monorepo manager)
└── Docker (containers)
```
Step 3
Prerequisites
Before installing Onlook, ensure you have the following installed:

Required:
- Bun — Monorepo manager and runtime
- Node.js 20.16.0+ — Avoid v20.11.0 due to known issues
- Docker 20.10+ — For running Supabase backend
- Docker Compose 2.0+ — For orchestrating services
- Git — For cloning the repository
System requirements (for self-hosting):
- 4+ CPU cores
- 8GB+ RAM (16GB recommended for smooth development)
- 50GB+ available disk space
API Keys (required for full functionality):
- CodeSandbox API token (for dev containers)
- OpenRouter API key (for AI chat)
- Fast Apply provider key (Morph or Relace, for AI code changes)
```
# Install Bun
curl -fsSL https://bun.sh/install | bash

# Verify installations
bun --version
node --version  # Should be 20.16.0+
docker --version  # Should be 20.10+
docker compose version  # Should be 2.0+
```

Step 4

Clone and install dependencies

Start by cloning the Onlook repository and installing all workspace dependencies. Onlook uses a monorepo structure with multiple packages and apps.

# Clone the repository
git clone https://github.com/onlook-dev/onlook.git
cd onlook

# Install all dependencies
bun install

# This installs dependencies for all workspace packages:
# - apps/web (Next.js frontend)
# - apps/backend (Supabase backend)
# - packages/* (shared utilities, UI components, etc.)

Step 5

Start Supabase backend

Onlook uses Supabase for authentication, database, and storage. The backend runs in Docker containers managed by Supabase CLI.

Important: You'll need the anon key and service role key from the output for environment setup in the next step. Save these keys!

# Start Supabase (requires Docker to be running)
bun backend:start

# This starts:
# - PostgreSQL database (port 54322)
# - Supabase API (port 54321)
# - Studio Dashboard (port 54323)
# - Auth server
# - Storage server

# Look for output like:
# anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
# service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Copy these keys — you'll need them in step 6

Step 6
Get API keys
Onlook requires external API keys for AI features and development containers.

1. CodeSandbox API Token:
- Go to CodeSandbox Dashboard
- Click Settings → Your Workspace → API tab
- Click "Create API Token"
- Copy the token
2. OpenRouter API Key:
- Visit OpenRouter Settings
- Create a new API key
- Copy the key
3. Fast Apply Provider (choose one):

Fast apply models are used for AI-powered code changes. Pick one:
- MorphLLM: morphllm.com/dashboard
- Relace: app.relace.ai/settings/api-keys
You only need one Fast Apply provider key, not both.
```
Required API Keys:
1. CodeSandbox Token → codesandbox.io/dashboard
2. OpenRouter Key → openrouter.ai/settings/keys
3. Morph OR Relace Key → morphllm.com or relace.ai

Also needed from previous step:
4. Supabase anon key (from backend:start output)
5. Supabase service role key (from backend:start output)
```
Step 7
Configure environment variables
Onlook provides an interactive script to set up all required environment variables. This creates a .env file with your API keys and configuration.

The script will prompt you for:
- Supabase keys (from step 5)
- CodeSandbox token
- OpenRouter API key
- Fast Apply provider key (Morph or Relace)
Troubleshooting: If the interactive script fails, you can manually create a .env file. See the Onlook appendix docs for the full environment variable template.
```
# Run interactive environment setup
bun run setup:env

# Follow the prompts to enter:
# - NEXT_PUBLIC_SUPABASE_URL
# - NEXT_PUBLIC_SUPABASE_ANON_KEY
# - SUPABASE_SERVICE_ROLE_KEY
# - CODESANDBOX_TOKEN
# - OPENROUTER_API_KEY
# - MORPH_API_KEY or RELACE_API_KEY

# The script creates apps/web/client/.env
```
Step 8
Initialize and seed database
Apply the database schema and seed with test data. The schema includes tables for users, projects, branches, and more.

Note: If prompted to choose an option during db:push, you can cd packages/db && bun run db:push to use interactive mode.
```
# Push database schema to Supabase
bun db:push

# Seed database with test data
# This creates test users and example projects
bun db:seed

# Run these commands from the repository root
# You'll need to run db:push again whenever the schema changes
```

Step 9

Run development server

Start the Onlook development server. This runs the Next.js app with Turbopack for fast hot module replacement.

The dev server starts both the client and preload packages in parallel.

# Start development server
bun dev

# This runs:
# - Next.js dev server (port 3000)
# - Turbopack bundler for fast HMR
# - Type checking in watch mode

# Open your browser
open http://localhost:3000

# You should see the Onlook dashboard
# Try creating a new project or importing an existing one

Step 10
Docker deployment (production)
For production deployments, use Docker Compose to run Onlook as a containerized application. This is suitable for self-hosting on VMs or small teams.

Prerequisites:
- Docker Compose running
- Supabase backend started (bun backend:start)
- Environment variables configured
- Database schema pushed
Note: The Docker setup uses network_mode: host to connect to the local Supabase instance. For production with remote Supabase, update the Supabase URLs in .env.
```
# Build and start production container
docker compose up -d

# This:
# - Builds the Next.js app for production
# - Starts the container on port 3000
# - Enables auto-restart on failure
# - Runs health checks

# Verify deployment
docker compose ps
curl http://localhost:3000

# View logs
docker compose logs -f

# Stop container
docker compose down
```
Step 11
Using Onlook
Once running, Onlook offers multiple workflows for building Next.js applications:

1. Create a new project:
- Start from text description or image
- Use prebuilt templates
- AI generates a complete Next.js app
2. Import existing project:
- Import your Next.js + TailwindCSS repo
- Onlook indexes the code and enables visual editing
3. Visual editing:
- Click any element to select it
- Use the toolbar to adjust Tailwind styles
- Drag-and-drop to rearrange layouts
- Draw new divs and containers
- Right-click → "Open in code" to jump to source
4. AI chat:
- Ask AI to create features or modify designs
- Queue multiple AI tasks at once
- AI has full code access and editing tools
5. Branching:
- Create branches to experiment safely
- Compare different design approaches
- Merge or discard changes
6. Deploy:
- Generate sharable preview links
- Connect custom domains
- Deploy to Freestyle hosting
```
Workflow:
1. Create/Import → Start with a Next.js project
2. Edit Visually → Figma-like interface + live preview
3. AI Chat → Natural language code generation
4. Branch → Experiment with designs safely
5. Deploy → Share links or custom domains

All changes sync bidirectionally:
Visual edit → Code updates
Code edit → Visual preview updates
```
Step 12
Monorepo structure
Onlook uses a Bun workspaces monorepo. Understanding the structure helps when contributing or debugging:

apps/web — Main Next.js application
- client/ — Frontend React app
- server/ — Backend API routes
- preload/ — Preload scripts for iframes
apps/backend — Supabase backend
- supabase/ — Database migrations and functions
packages/ — Shared packages
- @onlook/ui — Shared UI components
- @onlook/parser — Code analysis and AST parsing
- @onlook/db — Drizzle ORM schema and queries
- @onlook/models — TypeScript type definitions
- @onlook/constants — Shared constants
- @onlook/utility — Helper functions
tooling/ — Build and development tools
- @onlook/eslint — Shared ESLint config
- @onlook/typescript — Shared TypeScript config
```
onlook/
├── apps/
│   ├── web/           # Next.js app
│   │   ├── client/    # Frontend
│   │   ├── server/    # API routes
│   │   └── preload/   # Iframe scripts
│   └── backend/       # Supabase
├── packages/          # Shared code
│   ├── ui/            # Components
│   ├── parser/        # Code analysis
│   ├── db/            # Drizzle ORM
│   └── models/        # Types
├── tooling/           # Dev tools
└── docs/              # Documentation
```

Step 13

Useful commands

Common development and maintenance commands for working with Onlook.

# Development
bun dev                 # Start dev server
bun dev:client          # Client only
bun dev:admin           # Admin dashboard

# Backend
bun backend:start       # Start Supabase
bun backend:stop        # Stop Supabase

# Database
bun db:push             # Apply schema changes
bun db:seed             # Seed with test data
bun db:reset            # Reset database
bun db:gen              # Generate Drizzle types

# Build
bun build               # Build for production
bun start               # Start production server

# Docker
bun docker:build        # Build containers
bun docker:up           # Start containers
bun docker:down         # Stop containers
bun docker:logs         # View logs

# Code quality
bun lint                # Lint all packages
bun format              # Format code
bun typecheck           # Type check
bun test                # Run tests

# Cleanup
bun clean               # Remove node_modules
bun clean:workspaces    # Clean all workspaces

Step 14
Architecture overview
How Onlook works under the hood:

1. Project Creation: When you create an app, the code loads into a WebContainer (CodeSandbox SDK). This is an in-browser Node.js environment that runs your Next.js app.

2. Container Serving: The container builds and serves your code. It provides a preview URL that Onlook displays in an iframe.

3. Code Indexing: Onlook's parser reads and indexes all your code from the container. It builds a map of every component, element, and style.

4. Instrumentation: The code is instrumented with metadata that maps each DOM element back to its exact location in source files (file path, line number, JSX node).

5. Bidirectional Sync: When you edit visually:
- Onlook updates the element in the iframe
- The parser finds the source location
- The code file is edited
- The change triggers a hot reload
When you edit code:
- The file system detects the change
- The container rebuilds
- The iframe refreshes with the new preview
6. AI Integration: The AI chat has direct access to the code and specialized tools to understand and edit files. It can create components, modify styles, add features, or refactor code.

This architecture can theoretically scale to any framework that renders DOM declaratively (JSX, TSX, HTML), but Onlook is optimized for Next.js + TailwindCSS.
```
Flow:
1. Load code → WebContainer (CodeSandbox)
2. Serve → Preview URL in iframe
3. Index → Parse all source files
4. Instrument → Map DOM ↔ source location
5. Edit → Visual or code (syncs both ways)
6. AI Chat → Code access + editing tools

Element → Source Mapping:
DOM node → { file, line, jsxNode }
  ↓
Click element → Jump to exact code location
Edit style → Update source file → HMR
```
Step 15
Troubleshooting
Common issues and solutions when running Onlook:

Backend won't start:
- Ensure Docker is running: docker ps
- Check port conflicts (54321, 54322, 54323): lsof -i :54321
- Try resetting: bun backend:stop && bun backend:start
Environment setup fails:
- Manually create .env file in apps/web/client/
- Copy template from Onlook docs
- Ensure all API keys are valid
Database errors:
- Run bun db:reset to rebuild from scratch
- Verify Supabase is running: curl http://127.0.0.1:54321
- Check migrations in apps/backend/supabase/migrations/
Dev server issues:
- Clear cache: rm -rf .next node_modules/.cache
- Reinstall: bun clean && bun install
- Check Node version: node --version (avoid 20.11.0)
Docker deployment fails:
- Prune Docker: docker system prune -a
- Verify network mode in docker-compose.yml: network_mode: "host"
- Check Supabase is accessible from container: docker exec <container> curl http://127.0.0.1:54321
Port 3000 already in use:
```
# Find process using port 3000
lsof -ti:3000
# Kill the process
kill -9 $(lsof -ti:3000)
```
Step 16
Resources and community
Official Documentation: https://docs.onlook.com

GitHub Repository: https://github.com/onlook-dev/onlook

Hosted App: https://onlook.com (no local setup required)

Community:
- Discord: https://discord.gg/hERDfFZCsH
- Twitter: https://twitter.com/onlookdev
- LinkedIn: https://www.linkedin.com/company/onlook-dev/
Contributing: See Contributing Guide and Architecture Docs

Video Demo: https://youtu.be/RSX_3EaO5eU

Hiring: Onlook is hiring engineers in SF! Check YC Jobs
```
Links:
- Docs: https://docs.onlook.com
- GitHub: https://github.com/onlook-dev/onlook
- Hosted: https://onlook.com
- Discord: https://discord.gg/hERDfFZCsH
- Demo: https://youtu.be/RSX_3EaO5eU

License: Apache 2.0
Stars: 25,819+
Status: Active development (YC-backed)
```

Onlook: Visual-first code editor for Next.js

What is Onlook?

Technology stack

Prerequisites

Clone and install dependencies

Start Supabase backend

Get API keys

Configure environment variables

Initialize and seed database

Run development server

Docker deployment (production)

Using Onlook

Monorepo structure

Useful commands

Architecture overview

Troubleshooting

Resources and community

Feature requests

Discussion