Onlook Docs

https://docs.onlook.com
Admin
Onlook is a "Cursor for Designers" that allows live editing of React and TailwindCSS projects...
Tokens:12,550
Snippets:44
Trust Score:8.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Clone Repository and Install Dependencies

Source: https://docs.onlook.com/developers/running-locally

Clones the Onlook repository from GitHub and installs all necessary project dependencies using Bun.

```bash
git clone https://github.com/onlook-dev/onlook.git
cd onlook
bun install
```

--------------------------------

### Process Management with PM2

Source: https://docs.onlook.com/self-hosting/single-machine

Provides instructions for installing PM2 globally, starting the Onlook application with PM2, saving the configuration, and setting up auto-start on system boot.

```bash
# Install PM2 globally
bun add -g pm2
# Start with PM2
pm2 start .next/standalone/apps/web/client/server.js --name onlook
# Save PM2 configuration
pm2 save
# Setup auto-start on boot
pm2 startup
```

--------------------------------

### Start Onlook Backend

Source: https://docs.onlook.com/developers/running-locally

Starts the backend services for Onlook using the Bun package manager. This command requires Docker to be running.

```bash
bun backend:start
```

--------------------------------

### Run Onlook Development Server

Source: https://docs.onlook.com/developers/running-locally

Starts the Next.js development server for the Onlook application. Access the running application at http://localhost:3000.

```bash
bun dev
```

--------------------------------

### Start Backend Services

Source: https://docs.onlook.com/self-hosting/single-machine

Starts the local Supabase services, including the PostgreSQL database, authentication, and storage. Provides URLs for accessing these services.

```bash
bun backend:start
```

--------------------------------

### Interactive Environment Setup

Source: https://docs.onlook.com/developers/running-locally

Executes an interactive script to set up the necessary environment variables for the Onlook development environment.

```bash
bun run setup:env
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://docs.onlook.com/self-hosting/single-machine

Clones the Onlook repository from GitHub and installs project dependencies using Bun.

```bash
git clone https://github.com/onlook-dev/onlook.git
cd onlook
# Install dependencies
bun install
```

--------------------------------

### Start Backend Services

Source: https://docs.onlook.com/self-hosting/docker-compose

Starts backend services, including Supabase with PostgreSQL, authentication, and storage, using a separate Docker Compose service.

```bash
bun backend:start
```

--------------------------------

### Seed Database with Test Data

Source: https://docs.onlook.com/developers/running-locally

Populates the database with initial test data, including test users and projects, to facilitate development and testing.

```bash
bun db:seed
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://docs.onlook.com/self-hosting/docker-compose

Clones the Onlook repository and installs project dependencies using Bun.

```bash
git clone https://github.com/onlook-dev/onlook.git
cd onlook
# Install dependencies
bun install
```

--------------------------------

### Setup Environment Variables

Source: https://docs.onlook.com/self-hosting/docker-compose

Initiates an interactive setup to create the environment file for Docker Compose deployment, requiring Supabase, OpenRouter API Key, and CodeSandbox Token.

```shell
# Run interactive environment setup
bun run setup:env
```

--------------------------------

### Setup Environment Variables

Source: https://docs.onlook.com/self-hosting/single-machine

Initiates an interactive script to set up environment variables required for Onlook, including Supabase credentials, OpenRouter API Key, and CodeSandbox Token.

```bash
# Run interactive environment setup
bun run setup:env
```

--------------------------------

### Initialize Database Schema

Source: https://docs.onlook.com/developers/running-locally

Applies the database schema to the Supabase backend. This command should be re-run whenever the database schema changes.

```bash
bun db:push
```

--------------------------------

### Initialize Database

Source: https://docs.onlook.com/self-hosting/single-machine

Pushes the database schema to the Supabase instance, ensuring the database structure is up-to-date.

```bash
# Push database schema
bun db:push
```

--------------------------------

### Install Project Dependencies with Bun

Source: https://docs.onlook.com/contributing/developers/running-locally

Installs all necessary project dependencies using the Bun package manager. Ensure Bun is installed and the repository has been cloned before running this command.

```shell
bun install
```

--------------------------------

### Initialize Database

Source: https://docs.onlook.com/self-hosting/docker-compose

Pushes the database schema to the Supabase instance.

```bash
# Push database schema
bun db:push
```

--------------------------------

### Start Onlook Backend with Bun

Source: https://docs.onlook.com/contributing/developers/running-locally

Starts the Onlook backend services, typically managed by Docker. This command requires Docker to be running and accessible. It outputs Supabase keys needed for later configuration.

```shell
bun backend:start
```

--------------------------------

### Deploy with Docker Compose

Source: https://docs.onlook.com/self-hosting/docker-compose

Builds and starts the production Onlook container using Docker Compose in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Run Standalone Application

Source: https://docs.onlook.com/self-hosting/single-machine

Demonstrates different methods to run the standalone Onlook application, including direct execution, using a Bun script, and managing with PM2.

```bash
# Option 1: Direct command
bun .next/standalone/apps/web/client/server.js
# Option 2: Use bun script
bun run start:standalone
# Option 3: With PM2 for process management
pm2 start .next/standalone/apps/web/client/server.js --name onlook
```

--------------------------------

### Testing with Bun

Source: https://docs.onlook.com/developers

Command to run tests using the Bun package manager. Assumes Bun is installed and configured for the project.

```bash
bun test
```

--------------------------------

### Verify Deployment

Source: https://docs.onlook.com/self-hosting/single-machine

Checks if the Onlook application and Supabase services are running correctly by sending HTTP requests to their respective local endpoints.

```bash
# Check application
curl http://localhost:3000
# Check Supabase API
curl http://localhost:54321/rest/v1/
```

--------------------------------

### Verify Deployment

Source: https://docs.onlook.com/self-hosting/docker-compose

Checks the status of the deployed services and verifies the main application is running.

```bash
docker-compose ps
curl http://localhost:3000
```

--------------------------------

### Clone Onlook Repository

Source: https://docs.onlook.com/contributing/developers/running-locally

Clones the official Onlook repository from GitHub to your local machine. This is the first step to get the project files for local development.

```shell
git clone https://github.com/onlook-dev/onlook.git
cd onlook
```

--------------------------------

### Troubleshooting Build Failures

Source: https://docs.onlook.com/self-hosting/single-machine

Resolves build failures by cleaning the node_modules directory and reinstalling dependencies. This is a common step when encountering issues during the build process.

```bash
rm -rf node_modules && bun install
```

--------------------------------

### Database Package Environment Variables

Source: https://docs.onlook.com/developers/appendix

Configuration for the database package's environment variables. This includes Supabase database URL, Supabase URL, and Supabase service role key, which should be obtained from the `bun backend:start` command output.

```env
SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
SUPABASE_URL=http://localhost:54321
SUPABASE_SERVICE_ROLE_KEY=<Your service role key from Supabase>
```

--------------------------------

### Build Standalone Application

Source: https://docs.onlook.com/self-hosting/single-machine

Builds a self-contained production deployment of the Onlook application, including a standalone Node.js server, bundled static assets, and optimized configurations.

```bash
# Build standalone production deployment
bun run preview:standalone
```

--------------------------------

### Set Environment Variables with Bun Script

Source: https://docs.onlook.com/contributing/developers/running-locally

Runs an interactive script to set up the necessary environment variables for the project. This script guides you through providing API keys and other configurations.

```shell
bun run setup:env
```

--------------------------------

### Run Onlook Development Server with Bun

Source: https://docs.onlook.com/contributing/developers/running-locally

Starts the local development server for the Onlook application. After running this, you can access the application via the provided URL, typically http://localhost:3000.

```shell
bun dev
```

--------------------------------

### Importing Templates into Onlook

Source: https://docs.onlook.com/tutorials/importing-templates

Onlook allows direct import of React, NextJS, or Tailwind projects. This feature enables faster project starts with pre-designed templates.

```general
You can now import your React, NextJS, or Tailwind projects directly into Onlook Web. This unlocks easy access to templates, so you can start new projects faster with ready-made designs.
```

--------------------------------

### AI SDK Provider Integration

Source: https://docs.onlook.com/self-hosting/external-services

Information on integrating custom AI providers using the AI SDK. It provides links to guides for OpenAI compatible providers and community providers.

```APIDOC
Supports any provider from the [AI SDK providers](https://ai-sdk.dev/providers/ai-sdk-providers).
Add a custom provider by following these guides:
- [OpenAI compatible](https://ai-sdk.dev/providers/openai-compatible-providers/custom-providers)
- [Community](https://ai-sdk.dev/providers/community-providers/custom-providers)
```

--------------------------------

### Configure Database Package Environment Variables

Source: https://docs.onlook.com/contributing/developers/appendix

Configures environment variables for the Onlook database package. This involves setting the Supabase database URL, Supabase URL, and the Supabase service role key, typically obtained from the `bun backend:start` command output.

```env
SUPABASE_DATABASE_URL=postgresql://postgres:[email\u00a0protected]:54322/postgres
SUPABASE_URL=http://localhost:54321
SUPABASE_SERVICE_ROLE_KEY=<Your service role key from Supabase>
```

--------------------------------

### Check Node.js Version

Source: https://docs.onlook.com/contributing/developers/running-locally

Checks the currently installed Node.js version. This is useful for verifying prerequisites, as Onlook recommends Node.js v20.16.0 or later and warns against v20.11.0 due to potential issues.

```shell
node --version
```

--------------------------------

### Onlook Project Creation Steps

Source: https://docs.onlook.com/getting-started/first-project

Detailed steps for creating a new project in Onlook, including interface exploration, component management, styling, and export options.

```markdown
# Creating Your First Project
This tutorial will guide you through creating your first project in Onlook.

## Step 1: Create a New Project
  1. Open Onlook
  2. Click on "New Project" in the welcome screen
  3. Choose a template or start from scratch
  4. Enter a name for your project
  5. Click "Create"

## Step 2: Explore the Interface
Take some time to explore the Onlook interface:
  * **Canvas** : The central area where you see and interact with your components
  * **Layers Panel** : Shows the component hierarchy
  * **Properties Panel** : Edit properties of the selected component
  * **Style Editor** : Modify Tailwind styles
  * **Code Panel** : View and edit the generated code

## Step 3: Add Components
  1. Click the "+" button in the toolbar
  2. Choose a component from the library
  3. Drag it onto the canvas
  4. Use the Properties Panel to customize it

## Step 4: Style Your Components
  1. Select a component on the canvas
  2. Use the Style Editor to apply Tailwind classes
  3. Adjust spacing, colors, typography, and other properties

## Step 5: Preview and Export
  1. Click "Preview" to see how your project looks
  2. Make any final adjustments
  3. Click "Export" to export your project
  4. Choose your export options (code, images, etc.)
```

--------------------------------

### Run Tests with Bun

Source: https://docs.onlook.com/contributing/developers

Execute the project's test suite using the Bun runtime. This command initiates all defined tests to ensure code quality and functionality.

```shell
bun test
```

--------------------------------

### Onlook App Deployment

Source: https://docs.onlook.com/tutorials/figma-to-onlook

Instructions for deploying a React application built with Onlook. This covers the one-click deployment process and sharing the application.

```Onlook
Push your app live with one click.
Share your application with your team or users.
Iterate based on feedback.
```

--------------------------------

### Increasing Node.js Memory Limit

Source: https://docs.onlook.com/self-hosting/single-machine

Increases the memory limit for Node.js processes to prevent memory-related issues during operation. This is useful for applications that consume significant memory.

```bash
NODE_OPTIONS="--max-old-space-size=4096"
```

--------------------------------

### Initialize Database with Bun

Source: https://docs.onlook.com/contributing/developers/running-locally

Initializes or updates the database schema based on the project's definitions. This command should be run whenever database schema changes occur. It might require interactive mode if prompted.

```shell
bun db:push
```

--------------------------------

### Seed Database with Test Data using Bun

Source: https://docs.onlook.com/contributing/developers/running-locally

Populates the database with initial test data, including users and projects. This is crucial for testing and development workflows.

```shell
bun db:seed
```

--------------------------------

### Onlook Keyboard Shortcuts

Source: https://docs.onlook.com/getting-started/ui-overview

Essential keyboard shortcuts for speeding up workflow in Onlook, covering actions like saving, undoing, copying, pasting, and deleting components.

```APIDOC
Onlook Keyboard Shortcuts:

  Ctrl/Cmd + S : Save changes
  Ctrl/Cmd + Z : Undo
  Ctrl/Cmd + Shift + Z : Redo
  Ctrl/Cmd + C : Copy selected component
  Ctrl/Cmd + V : Paste component
  Delete : Remove selected component
  Escape : Deselect current selection
```

--------------------------------

### Figma Design Structuring for Onlook

Source: https://docs.onlook.com/tutorials/figma-to-onlook

Guidelines for organizing Figma designs to ensure a smooth import process into Onlook. This includes using Auto-Layout, naming layers descriptively, building reusable components, and adopting design system principles.

```Figma
Use Auto-Layout for all parent containers.
Apply proper padding, spacing, and resizing rules.
Set horizontal/vertical resizing for responsive layouts.
Name layers descriptively (e.g., 'Header', 'CTA Button').
Avoid symbols and nested clutter in layer names.
Group similar components logically.
Build reusable components with consistent styling.
Think in design systems by applying global styles.
```

--------------------------------

### Linting and Formatting with Bun

Source: https://docs.onlook.com/developers

Commands to run ESLint for linting and Prettier for code formatting. These commands are typically executed on every commit to maintain code quality and consistency.

```bash
bun lint
bun format
```

--------------------------------

### Onlook Technologies

Source: https://docs.onlook.com/faq

Details the core technologies used in the development of Onlook, including the framework, database, and runtime environment.

```text
Onlook is built with:
  * Next.js
  * Drizzle
  * Supabase
  * Bun
```

--------------------------------

### Web Client Environment Variables

Source: https://docs.onlook.com/developers/appendix

Configuration for the web client's environment variables. This includes Supabase URL and anon key, Drizzle ORM connection string, Anthropic API key, Codesandbox API key, and API keys for MorphLLM and Relace.

```env
# ------------- Required Keys ?-------------
# Supabase - Enables our backend such as database and auth
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY="<Fill in from content after running supabase start>"
# Drizzle - Our ORM for accessing the database
SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
# Anthropic - Enables AI chat. Other providers are optional below
ANTHROPIC_API_KEY="<Your api key from https://console.anthropic.com/settings/keys>"
# Codesandbox - Used to host user apps. Other providers may be supported in the future. May be optional in the future.
CSB_API_KEY="<Your api key from https://codesandbox.io/t/api>"
# Fast apply model providers to reliably resolve code changes. Either will work since we will fall back.
# Option 1: MorphLLM
MORPH_API_KEY="<Your api key from https://morphllm.com/dashboard>"
# Option 2: Relace
RELACE_API_KEY="<Your api key from https://app.relace.ai/settings/api-keys>"
```

--------------------------------

### Configure Web Client Environment Variables

Source: https://docs.onlook.com/contributing/developers/appendix

Sets up essential environment variables for the Onlook web client. This includes Supabase URL and anonymous key, Drizzle database URL, Anthropic API key, Codesandbox API key, and API keys for MorphLLM or Relace for AI chat and code resolution.

```env
# ------------- Required Keys -------------

# Supabase - Enables our backend such as database and auth
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY="<Fill in from content after running supabase start>"

# Drizzle - Our ORM for accessing the database
SUPABASE_DATABASE_URL=postgresql://postgres:[email\u00a0protected]:54322/postgres

# Anthropic - Enables AI chat. Other providers are optional below
ANTHROPIC_API_KEY="<Your api key from https://console.anthropic.com/settings/keys>"

# Codesandbox - Used to host user apps. Other providers may be supported in the future. May be optional in the future.
CSB_API_KEY="<Your api key from https://codesandbox.io/t/api>"

# Fast apply model providers to reliably resolve code changes. Either will work since we will fall back.
# Option 1: MorphLLM
MORPH_API_KEY="<Your api key from https://morphllm.com/dashboard>"
# Option 2: Relace
RELACE_API_KEY="<Your api key from https://app.relace.ai/settings/api-keys>"
```

--------------------------------

### Database Synchronization Commands

Source: https://docs.onlook.com/developers/troubleshooting

Commands to synchronize your database with the application schema. 'bun db:push' attempts to push schema changes, while 'bun db:reset' fully resets the database and re-runs migrations, which will delete all existing data.

```javascript
bun db:push
```

```javascript
bun db:reset
```

--------------------------------

### AI Assistance Functionality

Source: https://docs.onlook.com/getting-started/core-features

Onlook's AI assistance helps generate components from descriptions, provides suggestions for improvements, converts designs to code, and aids in debugging.

```AI
// Example of AI Assistance functionality (conceptual)
// Generate components from descriptions, get suggestions for improvements, convert designs to code, debug issues.
```

--------------------------------

### Format Code with Prettier

Source: https://docs.onlook.com/contributing/developers

Format code according to project standards using Prettier. This command ensures consistent code style and readability.

```shell
bun format
```

--------------------------------

### Onlook Import and Refinement Process

Source: https://docs.onlook.com/tutorials/figma-to-onlook

Steps to import Figma designs into Onlook and refine them into functional React applications. This involves exporting assets, importing into Onlook, using AI prompts, adding interactivity, and connecting to data sources.

```Onlook
1. Export Figma design as SVG or PNG.
2. Create a new project in Onlook.
3. Import design assets into Onlook.
4. Recreate the design as React components using Onlook's tools.
5. Use AI prompts to improve components.
6. Preview changes in real-time.
7. Add interactions and functionality.
8. Connect to data sources if necessary.
```

--------------------------------

### Onlook Directory Structure

Source: https://docs.onlook.com/developers/architecture

Illustrates the monorepo structure of Onlook, detailing the organization of applications (web, backend) and shared packages (models, ui, ai, schema).

```bash
onlook/
| 
├── apps/
|   ├── web/                       # Web application components
|   │   ├── client/                # Client-side application (Next.js)
|   │   ├── preload/               # Preload scripts (TypeScript)
|   │   ├── template/              # Template used for creating a new project (Next.js)
|   │   └── server/                # Server-side code (Fastify.js - unused for now)
|   │
|   └── backend/                   # Backend (Supabase)
|   
├── packages/
|   ├── models/                    # Shared data models and types
|   ├── ui/                        # Reusable UI components and theming (ShadCN + TailwindCSS)
|   ├── ai/                        # AI integration utilities (AI SDK)
|   └── schema/                    # Shared schema for the application (Drizzle ORM)
|   
└── docs/                          # Documentation (Fumadocs + Nextjs)

```

--------------------------------

### Configure Custom AI Providers

Source: https://docs.onlook.com/self-hosting/external-services

Instructions on how to configure custom AI providers for Onlook. This involves updating provider configurations, usages, and API keys. It references specific files and search queries within the Onlook repository.

```typescript
1. Update the providers in `packages/ai/src/chat/providers.ts`. We already support Anthropic and OpenRouter as examples. You can follow the same format to add a new provider.
2. Update the usages by searching for `await initModel`.
3. Update your API keys in the `apps/web/client/.env` file to the provider's expected API keys.
```

--------------------------------

### Type Check Web Client

Source: https://docs.onlook.com/contributing/developers

Perform type checking for the web client using TypeScript. Navigate to the client directory and run the typecheck script via Bun.

```shell
cd apps/web/client && bun run typecheck
```

--------------------------------

### Check Node Version

Source: https://docs.onlook.com/developers/troubleshooting

Verify your Node.js version to ensure compatibility. A minimum version of v20.16.0 or the latest is recommended. Avoid v20.11.0 due to known issues.

```bash
node --version
```

--------------------------------

### Onlook Architecture Overview

Source: https://docs.onlook.com/self-hosting

Details the core components of the Onlook application, including the web client and backend services. The web client is built with Next.js, and the backend utilizes Supabase for database, authentication, and storage functionalities.

```APIDOC
Onlook Architecture:
  Web Client:
    Framework: Next.js
  Backend:
    Database: Supabase
    Authentication: Supabase
    Storage: Supabase
```
Tokens:
Raw