## File: apps/web/client/src/components/store/editor/ast/README.md # 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: ```jsx export function Child () { return
Hi I'm Child
} ``` ```jsx import { Child } from './child.jsx' export function Parent () { return (
) } ``` On the DOM tree, we'd actually get this. Notice that the `data-oid="instance"` is missing: ```html
Hi I'm Child
``` 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: ```json { "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 ``. Since this matches our index and component name, we found the instance! --- ## File: apps/web/client/README.md # Create T3 App This is a [T3 Stack](https://create.t3.gg/) project bootstrapped with `create-t3-app`. ## What's next? How do I make an app with this? 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](https://t3.gg/discord) and ask for help. - [Next.js](https://nextjs.org) - [Drizzle](https://orm.drizzle.team) - [Tailwind CSS](https://tailwindcss.com) - [tRPC](https://trpc.io) ## Learn More To learn more about the [T3 Stack](https://create.t3.gg/), take a look at the following resources: - [Documentation](https://create.t3.gg/) - [Learn the T3 Stack](https://create.t3.gg/en/faq#what-learning-resources-are-currently-available) — Check out these awesome tutorials You can check out the [create-t3-app GitHub repository](https://github.com/t3-oss/create-t3-app) — your feedback and contributions are welcome! ## How do I deploy this? Follow our deployment guides for [Vercel](https://create.t3.gg/en/deployment/vercel), [Netlify](https://create.t3.gg/en/deployment/netlify) and [Docker](https://create.t3.gg/en/deployment/docker) for more information. --- ## File: apps/web/preload/README.md # 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 # server To install dependencies: ```bash bun install ``` To run: ```bash bun run index.ts ``` This project was created using `bun init` in bun v1.2.9. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime. --- ## File: apps/web/README.md # 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 ## Why a backend stack? 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 ### Running locally 1. Make sure you have [Docker] installed 2. Install necessary packages ```bash bun install ``` 3. Run the supabase instance locally ```bash bun run start ``` 4. Set up the latest snapshot of the database ```bash bun run reset ``` --- ## File: docs/content/docs/developers/appendix.mdx --- title: Appendix --- ## Set up environment variables manually (optional) ##### 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: ```properties # ------------- 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="" SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres SUPABASE_SERVICE_ROLE_KEY="" # OpenRouter - Enables AI chat. Other providers are optional below OPENROUTER_API_KEY="" # Codesandbox - Used to host user apps. Other providers may be supported in the future. May be optional in the future. CSB_API_KEY="" ``` ##### 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. ```properties SUPABASE_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres SUPABASE_URL=http://localhost:54321 SUPABASE_SERVICE_ROLE_KEY= ``` --- ## File: docs/content/docs/developers/architecture.mdx --- title: Architecture --- # 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 ``` 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 ### Visual editing 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 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 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 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 ### How edits work How edits happen between the DOM, and writing to code Walkthrough video: https://youtu.be/aGUD9xS1XvA Timestamps: * [00:00](https://www.youtube.com/watch?v=aGUD9xS1XvA&t=0s) Intro * [00:15](https://www.youtube.com/watch?v=aGUD9xS1XvA&t=15s) Editing element * [00:56](https://www.youtube.com/watch?v=aGUD9xS1XvA&t=56s) How the edits work * [02:10](https://www.youtube.com/watch?v=aGUD9xS1XvA&t=130s) Other details ## References 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 --- title: Developer Docs & Contributing --- # 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 Onlook is structured as a monorepo with several interconnected apps and packages, primarily built using Next.js, React, TypeScript, and Vite. ## Contributing to Onlook 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](https://github.com/onlook-dev/onlook/issues), [Discord](https://discord.gg/hERDfFZCsH), [email](mailto:contact@onlook.com), or any other method with the owners of this repository before making a change. Please note we have a [code of conduct](https://github.com/onlook-dev/onlook/blob/main/CODE_OF_CONDUCT.md), please follow it in all your interactions with the project. ### Running the project locally You can build the project from source using instructions [here](/developers/running-locally). ### Pull Request Process 1. To create a Pull Request (PR), [create a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) of the project. 2. Create your changes in your fork and [open a PR from that fork.](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork). 5. Request a review of one of the maintainers. Once accepted, they will be able to merge your PR. ### Style guide We try to follow guidelines from [Clean Code](https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29) and the boy scoute rule: "Leave the code cleaner, not messier, than how you found it". ### Testing We use [Bun](https://bun.sh/) for testing. ```bash bun test ``` ### Linting We use [ESLint](https://eslint.org/) for linting and [Prettier](https://prettier.io/) for formatting. This runs on every commit. ```bash bun lint bun format ``` ### Type safety We use [TypeScript](https://www.typescriptlang.org/) for type safety. To check types of the web client, run: ```bash cd apps/web/client && bun run typecheck ``` --- ## File: docs/content/docs/developers/running-locally.mdx --- title: Development Setup --- # 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](/self-hosting). ## Prerequisites These are the prerequisites for setting up Onlook development environment. - [Bun](https://bun.sh) - Enables running the monorepo - [Docker](https://docs.docker.com/get-started/get-docker/) - Enables running the Supabase backend - [Node](https://nodejs.org/en/download/) – Minimum version `v20.16.0` or latest ## Setup ### 1. Clone the repository ```bash git clone https://github.com/onlook-dev/onlook.git cd onlook bun install ``` ### 2. Run backend Make sure you have Docker running from the instructions above. ```bash 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 #### a. Get Codesandbox API key 1. Go to [Codesandbox Dashboard](https://codesandbox.io/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 Run the interactive environment setup script: ```bash 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](/developers/appendix) ### 5. Initialize the database 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. ```bash bun db:push ``` ### 6. Seed the database with test data Seed the database with test data. This will create test users and projects. ```bash bun db:seed ``` ### 7. Run development server ```bash bun dev ``` Go to [http://localhost:3000](http://localhost:3000) to see the app running. You're all set for development! ## What's Next? 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 --- title: Troubleshooting --- # Common Issues ### Codesandbox Preview 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 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. ```bash node --version ``` You may have to delete cookies to clear the authentication state. ### "Column not found" error 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 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 --- title: Feature Overview --- # 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 ## Visual Editor 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 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 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 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*