onlook Documentation

File: apps/web/client/src/components/store/editor/ast/README.md Copy Chapter

How the AST algorithm works?

The AST manager allows us to map for component usages using a combination of the DOM tree and the AST tree we build using the index step.
It works on the limitation that the DOM tree only has partial information and the AST has overlapping partial information. The DOM tree does not have instance information and the AST does not have the tree information.

For example, We have a component called Child and a component called Parent:

export function Child () {
    return <div data-oid="child">Hi I'm Child</div>
}

import { Child } from './child.jsx'

export function Parent () {
    return (
        <div data-oid="parent">
            <Child data-oid="instance"/>
        </div>
    )
}

On the DOM tree, we'd actually get this. Notice that the data-oid="instance" is missing:

<div data-oid="parent">
    <div data-oid="child">
        Hi I'm Child
    </div>
</div>

But what if we want to find where the child instance is used using the DOM, how can we do that given we have access to the code as files and the data-oid map to the files?

- child.jsx
- parent.jsx

We can do that when parsing through the AST using this algorithm:

1. Parse the AST, storing the reference into a map of data-oid to code location and component name. The component name is either the Jsx tag name or the last function name we see.
2. Walk down the DOM tree, look at the parent of each node. If the component name differs, the node is an instance used by its parent.
3. If instance, look up the parent's code and find the child with the same index and component name. If those match, the instance location is found!

Applying the algorithm to our case we will get this:

1. Parse through the files, getting this map:

{
    "parent": ["parent.jsx", "start and end location", "Parent"],
    "instance": ["parent.jsx", "start and end location", "Child"],
    "child": ["child.jsx", "start and end location", "Child"],
}

2. Walk through the DOM tree:
   1. `` - No parent, continue
   2. `` - Look up itself, finding the component Child. Look up parent, finding the component Parent
3. Look up the parent's code, parse its children at the index 0, finding <Child data-oid="instance"/>. Since this matches our index and component name, we found the instance!

File: apps/web/client/README.md Copy Chapter

Create T3 App

This is a T3 Stack project bootstrapped with
create-t3-app.

What's next? How do I make an app with this? Copy Chapter

We try to keep this project as simple as possible, so you can start with just
the scaffolding we set up for you, and add additional things later when they
become necessary.

If you are not familiar with the different technologies used in this project,
please refer to the respective docs. If you still are in the wind, please join
our Discord and ask for help.

• Next.js
• Drizzle
• Tailwind CSS
• tRPC

Learn More Copy Chapter

To learn more about the T3 Stack, take a look at the
following resources:

• Documentation
• Learn the T3 Stack
  — Check out these awesome tutorials

You can check out the
create-t3-app GitHub repository —
your feedback and contributions are welcome!

How do I deploy this? Copy Chapter

Follow our deployment guides for
Vercel,
Netlify and
Docker for more information.

File: apps/web/preload/README.md Copy Chapter

What is this?

This is the preload script that will be injected into template project.
Dependencies to this package is REQUIRED to be browser compatible in order to
prevent runtime errors. Please keep external deps to a minimal and DO NOT IMPORT
node dependencies.

File: apps/web/server/README.md Copy Chapter

server

To install dependencies:

bun install

To run:

bun run index.ts

This project was created using bun init in bun v1.2.9. Bun is a fast all-in-one JavaScript runtime.

File: apps/web/README.md Copy Chapter

Web project

Structure

• Client - Next.js client that is served as app front-end
• Server - The control server that will be used to interact with the template
  app
• Shared - All the shared packages for the web project
• Preload - The script that gets injected into Template app. This allows
  communnicating directly with the app DOM through iframe

File: apps/backend/README.md Copy Chapter

Why a backend stack? Copy Chapter

This is our server stack built in Supabase which you can also run locally or
self-host.

Used to enable online capabilities such as managing users, collaborating,
persisting data, etc.

We will offer this as a hosted instance at some point. Ideally, the product
should still work offline with no backend connection.

Usage Copy Chapter

Running locally Copy Section

1. Make sure you have [Docker] installed
2. Install necessary packages

bun install

3. Run the supabase instance locally

bun run start

4. Set up the latest snapshot of the database

bun run reset

File: docs/content/docs/developers/appendix.mdx Copy Chapter

title: Appendix Copy Chapter

Set up environment variables manually (optional) Copy Chapter

1. In `apps/web/client`

Create a copy of the .env.example file under the apps/web/client directory and name it .env. Fill in the values with your own API keys.

It should look like this:

# ------------- 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>"
SUPABASE_DATABASE_URL=postgresql://postgres:[email protected]:54322/postgres
SUPABASE_SERVICE_ROLE_KEY="<Your Supabase service role key>"

# OpenRouter - Enables AI chat. Other providers are optional below
OPENROUTER_API_KEY="<Your api key from https://openrouter.ai/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>"

2. In `packages/db`

Create a copy of the .env.example file under the packages/db directory and name it .env. Fill in the values with the values from the output of the bun backend:start command.

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

File: docs/content/docs/developers/architecture.mdx Copy Chapter

title: Architecture Copy Chapter

Onlook Architecture

Onlook is structured as a monorepo with several interconnected apps and packages, primarily built using Next.js, Supabase, TailwindCSS, and Drizzle.

Directory Structure Copy Chapter

onlook/
|
├── apps/
│   ├── web/                       # Web application components
│   │   ├── client/                # Client-side application (Next.js)
│   │   ├── preload/               # Preload scripts (TypeScript)
│   │   └── 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)

High-level overview Copy Chapter

Visual editing Copy Section

Onlook is technically a browser that points to your localhost running the app. It can manipulate the DOM like a Chrome Devtool, and all these changes are injected into the page through a CSS stylesheet or DOM manipulation. The changes are non-persistent until written to code.

Write to code Copy Section

To translate the changes to code, we inject an attribute into the DOM elements at build-time that points back to the code like a sourcemap. The attribute gives us the location of the code block, and the component scope. We then find the code, parse it into an AST, inject the styles, then write it back.

Framework support Copy Section

This technique is framework agnostic as we can swap in a different compiler for another framework. It can work for any codebase as we’re just using open standards that don’t require any custom code. The code generated is written directly into your codebase, locally, so you can always take the output without being locked-in to the tool.

Actions Copy Section

All the changes made are stored as actions. This allows them to be serialized, stored, and reproduced. We did it this way so eventually, we can introduce online collaboration or let an agent generate actions. To do this, we’d just need to serve the locally running page and resolve incoming actions.

How the canvas works Copy Section

How edits work Copy Section

How edits happen between the DOM, and writing to code

Walkthrough video: https://youtu.be/aGUD9xS1XvA

Timestamps:

• 00:00 Intro
• 00:15 Editing element
• 00:56 How the edits work
• 02:10 Other details

References Copy Chapter

Old electron architecture doc. Still relevant, replace webview with iframe: https://github.com/onlook-dev/desktop/wiki/Architecture

File: docs/content/docs/developers/index.mdx Copy Chapter

title: Developer Docs & Contributing Copy Chapter

Developer Docs & Contributing

This section provides technical documentation for developers who want to understand Onlook's architecture, contribute to the project, or extend its functionality.

Overview Copy Chapter

Onlook is structured as a monorepo with several interconnected apps and packages, primarily built using Next.js, React, TypeScript, and Vite.

Contributing to Onlook Copy Chapter

We welcome contributions to Onlook! This guide will help you get started with contributing to the project.

When contributing to this repository, please first discuss the change you wish to make via issues,
Discord, email, or any other method with the owners of this repository before making a change.

Please note we have a code of conduct, please follow it in all your interactions with the project.

Running the project locally Copy Section

You can build the project from source using instructions here.

Pull Request Process Copy Section

1. To create a Pull Request (PR), create a fork of the project.

2. Create your changes in your fork and open a PR from that fork.

3. Update the PR description with details of the changes. Link the issue if relevant.

4. Be sure to check the box to "Allow edits from maintainer". This allows maintainers to update your PR if necessary which speeds up the review process. See more here.

5. Request a review of one of the maintainers. Once accepted, they will be able to merge your PR.

Style guide Copy Section

We try to follow guidelines from Clean Code and the boy scoute rule:

"Leave the code cleaner, not messier, than how you found it".

Testing Copy Section

We use Bun for testing.

bun test

Linting Copy Section

We use ESLint for linting and Prettier for formatting. This runs on every commit.

bun lint
bun format

Type safety Copy Section

We use TypeScript for type safety.

To check types of the web client, run:

cd apps/web/client && bun run typecheck

File: docs/content/docs/developers/running-locally.mdx Copy Chapter

title: Development Setup Copy Chapter

Development Setup

This guide will set you up with a local development environment for Onlook. This involves a Next.js app, a Supabase backend, and the ability to run dev containers with Codesandbox.

Note: This guide is for development and contributing to Onlook. For deploying Onlook for production use, see Self-Hosting.

Prerequisites Copy Chapter

These are the prerequisites for setting up Onlook development environment.

• Bun - Enables running the monorepo
• Docker - Enables running the Supabase backend
• Node – Minimum version v20.16.0 or latest

Setup Copy Chapter

1. Clone the repository Copy Section

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

2. Run backend Copy Section

Make sure you have Docker running from the instructions above.

bun backend:start

Grab the `anon key` and `service role key` from the output. We'll use these in the environment setup step.

3. Get API keys Copy Section

a. Get Codesandbox API key

1. Go to Codesandbox Dashboard
2. Click on settings in the left menu, your workspace setting should open
3. Navigate to the "API" tab
4. Click "Create API Token" and generate an API token
5. Copy the token and save it for the environment setup step

Note: We plan on enabling running the dev containers with Docker Desktop in the future after we figure out the best API integration.

b. Get OpenRouter API key

Request an API key from OpenRouter. This is used for chatting with your project. https://openrouter.ai/settings/keys

c. Get Fast Apply API key

For applying AI code, SOTA is to use fast apply models in order to resolve the code change. There are two options for Fast Apply providers:

- [MorphLLM](https://morphllm.com/dashboard)
- [Relace](https://app.relace.ai/settings/api-keys)

You only need to get one of the keys and set it in the environment variables in later steps.

4. Set environment variables Copy Section

Run the interactive environment setup script:

bun run setup:env

Troubleshooting: If you run into issues with the interactive environment setup script, use this instruciton to set the environment variables manually: appendix

5. Initialize the database Copy Section

Set up the database schema. You will need to run this command every time there's a change to the database schema.

Note: If prompted for interaction such as choosing an option, cd into packages/db and run bun run db:push to use interactive mode.

bun db:push

6. Seed the database with test data Copy Section

Seed the database with test data. This will create test users and projects.

bun db:seed

7. Run development server Copy Section

bun dev

Go to http://localhost:3000 to see the app running. You're all set for development!

What's Next? Copy Chapter

Now that you have Onlook running locally, explore these resources to make your first contribution or learn more about the architecture. Understanding how Onlook works will help you contribute more effectively to this visual editor for React and TailwindCSS.

File: docs/content/docs/developers/troubleshooting.mdx Copy Chapter

title: Troubleshooting Copy Chapter

Common Issues

Codesandbox Preview Copy Section

Codesandbox may ask you to confirm to proceed. You can click the button by switching to Preview mode in onlook, and click the "Yes, proceed to preview" link and switch back. The UI should render properly inside the iframe after that.

Authentication Issues Copy Section

If you encounter issues with reloading pages and being unauthenticated then check your node version, install a more recent version, re-install dependencies and restart the project.
Minimum version v20.16.0 or latest is recommended.

Avoid version v20.11.0 of Node as it has shown this issue in the past.

node --version

You may have to delete cookies to clear the authentication state.

"Column not found" error Copy Section

If you encounter issues such as "Column not found" error, your database may be out of sync with the schema. There are 2 things to try to get it back in sync:

1. Run bun db:push to push the schema to the database. If there are conflicts, you can try step 2.
2. Run bun db:reset to fully reset the database and re-run the migrations. WARNING: This will delete all data in the database.

Testing the Preload Script Copy Section

If you want to update the preload script and test it with Onlook, follow these steps:

1. Run bun bun run dev from the root of the project.
2. Copy the file apps/web/client/public/onlook-preload-script.js into to public/onlook-preload-script.js in the code tab in onlook or the codesandbox interface.
3. Refresh the localhost tab. You should now be able to test the preload script.

If you want to update the preload script and test any changes, you need to refresh the localhost tab.

File: docs/content/docs/getting-started/core-features.mdx Copy Chapter

title: Feature Overview Copy Chapter

Onlook Features

Onlook provides a range of features to help designers and developers work together more efficiently.

{/* */}
Onlook offers powerful features to streamline your design-to-code workflow

Key Features Copy Chapter

Visual Editor Copy Chapter

The Visual Editor allows you to edit React components visually, similar to design tools like Figma. You can:

• Drag and drop components
• Resize and position elements
• Edit text and images
• Apply styles using Tailwind CSS

{/* */}
Onlook's Visual Editor provides a familiar design tool interface

Code Integration Copy Chapter

Onlook integrates seamlessly with your code, allowing you to:

• See code changes in real-time
• Edit code directly
• Import and export components
• Integrate with your existing workflow

{/* */}
Watch your design changes reflect immediately in the code

AI Assistance Copy Chapter

Onlook's AI assistance helps you:

• Generate components from descriptions
• Get suggestions for improvements
• Convert designs to code
• Debug issues

{/* */}
Let AI help you create and improve your designs

Figma to Onlook Copy Chapter

Import your Figma designs directly into Onlook to:

• Convert designs to working React components
• Maintain design fidelity
• Make designs interactive
• Connect to data sources

{/* */}
Seamlessly transition from Figma designs to working code