Repository: onlook-dev/onlook

Stars: 25226

CLAUDE.md

Onlook Agents Guide

Actionable rules for repo agents—keep diffs minimal, safe, token‑efficient.

Purpose & Scope

- Audience: automated coding agents working within this repository.
- Goal: small, correct diffs aligned with the project’s architecture.
- Non-goals: editing generated artifacts, lockfiles, or node_modules.

Repo Map

- Monorepo managed by Bun workspaces (see root package.json).
- App: apps/web/client (Next.js App Router + TailwindCSS).
- API routes: apps/web/client/src/server/api/routers/*, aggregated in
apps/web/client/src/server/api/root.ts.
- Shared utilities: packages/* (e.g., packages/utility).

Stack & Runtimes

- UI: Next.js App Router, TailwindCSS.
- API: tRPC + Zod (apps/web/client/src/server/api/*).
- Package manager: Bun only — use Bun for all installs and scripts; do not use
npm, yarn, or pnpm.

Agent Priorities

- Correctness first: minimal scope and targeted edits.
- Respect client/server boundaries in App Router.
- Prefer local patterns and existing abstractions; avoid one-off frameworks.
- Do not modify build outputs, generated files, or lockfiles.
- Use Bun for all scripts; do not introduce npm/yarn.
- Avoid running the local dev server in automation contexts.
- Respect type safety and

Next.js App Router

- Default to Server Components. Add use client when using events,
state/effects, browser APIs, or client-only libs.
- App structure: apps/web/client/src/app/ (page.tsx, layout.tsx,
route.ts).
- Client providers live behind a client boundary (e.g.,
apps/web/client/src/trpc/react.tsx).
- Example roots: apps/web/client/src/app/layout.tsx (RSC shell, providers
wired, scripts gated by env).
- Components using mobx-react-lite's observer must be client components
(include use client).

tRPC API

- Routers live in apps/web/client/src/server/api/routers/ and must be
exported from apps/web/client/src/server/api/root.ts.
- Use publicProcedure/protectedProcedure from
apps/web/client/src/server/api/trpc.ts; validate inputs with Zod.
- Serialization handled by SuperJSON; return plain objects/arrays.
- Client usage via apps/web/client/src/trpc/react.tsx (React Query + tRPC
links).

Auth & Supabase

- Server-side client: apps/web/client/src/utils/supabase/server.ts (uses Next
headers/cookies). Use in server components, actions, and routes.
- Browser client: apps/web/client/src/utils/supabase/client/index.ts for
client components.
- Never pass server-only clients into client code.

Env & Config

- Define/validate env vars in apps/web/client/src/env.ts via
@t3-oss/env-nextjs.
- Expose browser vars with NEXT_PUBLIC_* and declare in the client schema.
- Prefer env from @/env. In server-only helpers (e.g., base URL in
src/trpc/helpers.ts), read process.env only for deployment vars like
VERCEL_URL/PORT. Never use process.env in client code; in shared
modules, guard with typeof window === 'undefined'.
- Import ./src/env in apps/web/client/next.config.ts to enforce validation.

Imports & Paths

- Use path aliases: @/ and ~/ map to apps/web/client/src/* (see
apps/web/client/tsconfig.json).
- Do not import server-only modules into client components. Limited exception:
editor modules that already use path; reuse only there. Never import
process in client code.
- Split code by environment if needed (server file vs client file).

MobX + React Stores

- Create store instances with useState(() => new Store()) for stability across
renders.
- Keep active store in useRef; clean up async with
setTimeout(() => storeRef.current?.clear(), 0) to avoid route-change races.
- Avoid useMemo for store instances; React may drop memoized values leading to
data loss.
- Avoid putting the store instance in effect deps if it loops; split concerns
(e.g., project vs branch).
- observer components are client-only. Place one client boundary at the
feature entry; child observers need not include use client (e.g.,
apps/web/client/src/app/project/[id]/_components/main.tsx).
- Example store: apps/web/client/src/components/store/editor/engine.ts:1 (uses
makeAutoObservable).

Styling & UI

- TailwindCSS-first styling; global styles are already imported in
apps/web/client/src/app/layout.tsx.
- Prefer existing UI components from @onlook/ui and local patterns.
- Preserve dark theme defaults via ThemeProvider usage in layout.

Internationalization

- next-intl is configured; provider lives in
apps/web/client/src/app/layout.tsx.
- Strings live in apps/web/client/messages/*. Add/modify keys there; avoid
hardcoded user-facing text.
- Keep keys stable; prefer additions over breaking renames.

Common Pitfalls

- Missing use client where needed (events/browser APIs) causes unbound events;
a single boundary at the feature root is sufficient.
- New tRPC routers not exported in src/server/api/root.ts (endpoints
unreachable).
- Env vars not typed/exposed in src/env.ts cause runtime/edge failures. Prefer
env; avoid new process.env reads in client code.
- Importing server-only code into client components (bundling/runtime errors).
Note: path is already used in specific client code-editor modules; avoid
expanding Node API usage beyond those areas.
- Bypassing i18n by hardcoding strings instead of using message files/hooks.
- Avoid useMemo to create MobX stores (risk of lost references); avoid
synchronous cleanup on route change (race conditions).

Context Discipline (for Agents)

- Search narrowly with ripgrep; open only files you need.
- Read small sections; avoid node_modules, .next, large assets.
- Propose minimal diffs aligned with existing conventions; avoid wide refactors.

Notes

- Unit tests can be run with bun test
- Run type checking with bun run typecheck
- Apply database updates to local dev with bun run db:push
- Refrain from running the dev server
- DO NOT run db:gen. This is reserved for the maintainer.
- DO NOT use any type unless necessary

README.md

<div align="center">
<img width="800" alt="header image" src="assets/web-preview.png">
<h3 align="center">Onlook</h3>
<p align="center">
Cursor for Designers
<br />
<a href="https://docs.onlook.com"><strong>Explore the docs »</strong></a>
<br />
</p>
<p align="center">
👨‍💻👩‍💻👨‍💻
<a href="https://www.ycombinator.com/companies/onlook/jobs/e4gHv1n-founding-engineer-fullstack">We're hiring engineers in SF!</a>
👩‍💻👨‍💻👩‍💻
</p>
<br />
<a href="https://youtu.be/RSX_3EaO5eU?feature=shared">View Demo</a>
·
<a href="https://github.com/onlook-dev/onlook/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
·
<a href="https://github.com/onlook-dev/onlook/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
</p>

[![Discord][discord-shield]][discord-url]
[![LinkedIn][linkedin-shield]][linkedin-url]
[![Twitter][twitter-shield]][twitter-url]

</div>

An Open-Source, Visual-First Code Editor

Craft websites, prototypes, and designs with AI in Next.js + TailwindCSS. Make
edits directly in the browser DOM with a visual editor. Design in realtime with
code. An open-source alternative to Bolt.new, Lovable, V0, Replit Agent, Figma
Make, Webflow, etc.

🚧 🚧 🚧 Onlook is still under development 🚧 🚧 🚧

We're actively looking for contributors to help make Onlook for Web an
incredible prompt-to-build experience. Check the
open issues for a full list of
proposed features (and known issues), and join our
Discord to collaborate with hundreds of other
builders.

What you can do with Onlook:

- [x] Create Next.js app in seconds
- [x] Start from text or image
- [x] Use prebuilt templates
- [ ] Import from Figma
- [ ] Import from GitHub repo
- [ ] Make a PR to a GitHub repo
- [x] Visually edit your app
- [x] Use Figma-like UI
- [x] Preview your app in real-time
- [x] Manage brand assets and tokens
- [x] Create and navigate to Pages
- [x] Browse layers
- [x] Manage project Images
- [x] Detect and use Components – _Previously in
Onlook Desktop_
- [ ] Drag-and-drop Components Panel
- [x] Use Branching to experiment with designs
- [x] Development Tools
- [x] Real-time code editor
- [x] Save and restore from checkpoints
- [x] Run commands via CLI
- [x] Connect with app marketplace
- [x] Deploy your app in seconds
- [x] Generate sharable links
- [x] Link your custom domain
- [ ] Collaborate with your team
- [x] Real-time editing
- [ ] Leave comments
- [ ] Advanced AI capabilities
- [x] Queue multiple messages at once
- [ ] Use Images as references and as assets in a project
- [ ] Setup and use MCPs in projects
- [ ] Allow Onlook to use itself as a toolcall for branch creation and iteration
- [ ] Advanced project support
- [ ] Support non-NextJS projects
- [ ] Support non-Tailwind projects

!Onlook-GitHub-Example

Getting Started

Use our hosted app or
run locally.

Usage

Onlook will run on any Next.js + TailwindCSS project, import your project into
Onlook or start from scratch within the editor.

Use the AI chat to create or edit a project you're working on. At any time, you
can always right-click an element to open up the exact location of the element
in code.

<br>

Draw-in new divs and re-arrange them within their parent containers by
dragging-and-dropping.

<br>

Preview the code side-by-side with your site design.

<br>

Use Onlook's editor toolbar to adjust Tailwind styles, directly manipulate
objects, and experiment with layouts.

Documentation

For full documentation, visit docs.onlook.com

To see how to Contribute, visit
Contributing to Onlook in our docs.

How it works

1. When you create an app, we load the code into a web container
2. The container runs and serves the code
3. Our editor receives the preview link and displays it in an iFrame
4. Our editor reads and indexes the code from the container
5. We instrument the code in order to map elements to their place in code
6. When the element is edited, we edit the element in our iFrame, then in code
7. Our AI chat also has code access and tools to understand and edit the code

This architecture can theoretically scale to any language or framework that
displays DOM elements declaratively (e.g. jsx/tsx/html). We are focused on
making it work well with Next.js and TailwindCSS for now.

For a full walkthrough, check out our
Architecture Docs.

Our Tech Stack

#### Front-end

- Next.js - Full stack
- TailwindCSS - Styling
- tRPC - Server interface

#### Database

- Supabase - Auth, Database, Storage
- Drizzle - ORM

#### AI

- AI SDK - LLM client
- OpenRouter - LLM model provider
- Morph Fast Apply - Fast apply model provider
- Relace - Fast apply model provider

#### Sandbox and hosting

- CodeSandboxSDK - Dev sandbox
- Freestyle - Hosting

#### Runtime

- Bun - Monorepo, runtime, bundler
- Docker - Container management

Contributing

!image

If you have a suggestion that would make this better, please fork the repo and
create a pull request. You can also
open issues.

See the CONTRIBUTING.md for instructions and code of conduct.

#### Contributors

Contact

!image

- Team: Discord -
Twitter -
LinkedIn -
Email
- Project:
https://github.com/onlook-dev/onlook
- Website: https://onlook.com

License

Distributed under the Apache 2.0 License. See LICENSE.md for more
information.

[contributors-shield]: https://img.shields.io/github/contributors/onlook-dev/studio.svg?style=for-the-badge
[contributors-url]: https://github.com/onlook-dev/onlook/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/onlook-dev/studio.svg?style=for-the-badge
[forks-url]: https://github.com/onlook-dev/onlook/network/members
[stars-shield]: https://img.shields.io/github/stars/onlook-dev/studio.svg?style=for-the-badge
[stars-url]: https://github.com/onlook-dev/onlook/stargazers
[issues-shield]: https://img.shields.io/github/issues/onlook-dev/studio.svg?style=for-the-badge
[issues-url]: https://github.com/onlook-dev/onlook/issues
[license-shield]: https://img.shields.io/github/license/onlook-dev/studio.svg?style=for-the-badge
[license-url]: https://github.com/onlook-dev/onlook/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?logo=linkedin&colorB=555
[linkedin-url]: https://www.linkedin.com/company/onlook-dev
[twitter-shield]: https://img.shields.io/badge/-Twitter-black?logo=x&colorB=555
[twitter-url]: https://x.com/onlookdev
[discord-shield]: https://img.shields.io/badge/-Discord-black?logo=discord&colorB=555
[discord-url]: https://discord.gg/hERDfFZCsH
[React.js]: https://img.shields.io/badge/react-%2320232a.svg?logo=react&logoColor=%2361DAFB
[React-url]: https://reactjs.org/
[TailwindCSS]: https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?logo=tailwind-css&logoColor=white
[Tailwind-url]: https://tailwindcss.com/
[Electron.js]: https://img.shields.io/badge/Electron-191970?logo=Electron&logoColor=white
[Electron-url]: https://www.electronjs.org/
[Vite.js]: https://img.shields.io/badge/vite-%23646CFF.svg?logo=vite&logoColor=white
[Vite-url]: https://vitejs.dev/
[product-screenshot]: assets/brand.png
[weave-shield]: https://img.shields.io/endpoint?url=https%3A%2F%2Fapp.workweave.ai%2Fapi%2Frepository%2Fbadge%2Forg_pWcXBHJo3Li2Te2Y4WkCPA33%2F820087727&cacheSeconds=3600&labelColor=#131313
[weave-url]: https://app.workweave.ai/reports/repository/org_pWcXBHJo3Li2Te2Y4WkCPA33/820087727

Repository: onlook-dev/onlook

Stars: 25226

CLAUDE.md Copy Chapter

Onlook Agents Guide Copy Chapter

Purpose & Scope Copy Section

Repo Map Copy Section

Stack & Runtimes Copy Section

Agent Priorities Copy Section

Next.js App Router Copy Section

tRPC API Copy Section

Auth & Supabase Copy Section

Env & Config Copy Section

Imports & Paths Copy Section

MobX + React Stores Copy Section

Styling & UI Copy Section

Internationalization Copy Section

Common Pitfalls Copy Section

Context Discipline (for Agents) Copy Section

Notes Copy Section

README.md Copy Chapter

An Open-Source, Visual-First Code Editor

🚧 🚧 🚧 Onlook is still under development 🚧 🚧 🚧 Copy Section

What you can do with Onlook: Copy Chapter

Getting Started Copy Chapter

Usage Copy Section

Documentation Copy Chapter

How it works Copy Chapter

Our Tech Stack Copy Section

Contributing Copy Chapter

Contact Copy Chapter

License Copy Chapter

CLAUDE.md

Onlook Agents Guide

Purpose & Scope

Repo Map

Stack & Runtimes

Agent Priorities

Next.js App Router

tRPC API

Auth & Supabase

Env & Config

Imports & Paths

MobX + React Stores

Styling & UI

Internationalization

Common Pitfalls

Context Discipline (for Agents)

Notes

README.md

🚧 🚧 🚧 Onlook is still under development 🚧 🚧 🚧

What you can do with Onlook:

Getting Started

Usage

Documentation

How it works

Our Tech Stack

Contributing

Contact

License