vibld 开源：把自然语言描述构建成可带走的 React 与 TypeScript 项目

Website · Docs · Examples · Styles · Roadmap · Discussions · Sign in

Describe a website or an app. Watch it being built. Keep the code.

_{The builder on vibld.com's home page, recorded from the site's own production build.}

vibld turns plain words into a conventional React and TypeScript project. It picks a direction with you, writes the design down, builds in bounded steps, checks its own work against what it wrote, proves the result compiles, and hands you code you can read line by line, run anywhere and take with you.

Note

vibld is early. The hosted service is a public beta that anyone can sign up for, and the status section says plainly what works and what does not yet.

Contents

• Three ways to use it
• How it works
• What it has built
• Designed, not templated
• Features
• Status
• Quick start
• Architecture
• Running it yourself
• Documentation
• Contributing
• License

Three ways to use it

_{pnpm generate --build from a clean clone with one DeepSeek key, replayed from the weekly proof run's own log (13 minutes, shown faster).}

How it works

The builder, screen by screen

_{Describe it. The message box, with Style, Reference, Media and Preferences beside it.}

_{Watch it build. Each step as it happens, with every event in the console.}

_{Read it. Every file, as written.}

_{These screenshots are from a local checkout, which uses a deterministic fake provider instead of a model (tagged vibld · fake), so the files shown are fixture output.}

What it has built

Real builds from the evaluation suite, published exactly as the model wrote them, with no hand edits. Each links to its live copy; the prompt, the run and anything worth knowing are on vibld.com/examples, and the source is in examples/generated.

Two hand-built starter templates ship alongside, each under its own MIT license: templates/marketing, a plain prerendered marketing site, and templates/luminous, a product site with a cursor-reactive glow, dressed for an invented SaaS called Emberline.

Designed, not templated

Every build starts from a written design, not a theme. There are 24 style presets, 16 surface treatments from Editorial and Brutalism to Liquid glass, and 8 complete color systems. Each carries mood tags (luxe, calm, technical, organic, playful, brutal), so the picker can suggest the ones your request describes.

_{The style presets on vibld.com/styles.}

Ask for an aurora, a starfield, a smoky gradient or any "animated background", and the build imports one of four backgrounds written once and tested, rather than improvising a canvas loop. Each takes the project's own color tokens, caps its pixel ratio, pauses off screen and holds still for anyone who asks for reduced motion.

_{The four backgrounds in packages/ai/src/backdrops.ts, bundled from the exact source a project is given and run in Chromium.}

Features

Building

• A conversation, not a form: the agent answers questions, asks its own when a request is thin, and builds when you say so. Follow-ups ("make the hero navy") change the project rather than starting over.
• Model providers behind one contract in packages/ai: Anthropic, OpenAI and DeepSeek adapters, chosen per run.
• Bounded, multi-step builds: a plan, then files in groups, each with its own ceiling on tokens and time, that keep running when you close the tab.
• Three directions to compare before the first build, 24 style presets with mood suggestions, a reference page whose text, colors, fonts and spacing the spec measures, and your own uploaded images and video.
• Four tested animated backgrounds a build imports when a request asks for motion.

Checking

• Design checks against the project's own DESIGN.md: palette, type, breakpoints, alt text, labels, contrast, reduced motion, media, copy and canvas performance.
• A verification build of every result, with one repair patch when it fails, and a badge that says which: checking, fixing, does not build or not checked.
• A spend ceiling reserved before each run starts, not counted after it finishes.

Previewing, sharing and shipping

• A live preview in a private sandboxed container running the real dev server, updated in place as the project changes, with revocable share links (apps/preview).
• On a copy without Containers, the same preview bundled in the viewer's browser, in a frame with no origin of its own (apps/web/src/browser-preview).
• Projects: save, rename, archive, duplicate and delete, a read-only share link, and Remix for anyone you send it to.
• One Ship menu: download a .zip, create or push to a GitHub repository for each project, or publish to <name>.vibld-preview.dev with safe default security headers (apps/publish).
• A Runs tab: every run's model, tokens, cost and why it stopped.

Accounts and operations

• Sign-in with Clerk, or on a copy of your own with an owner password or Cloudflare Access; projects in Cloudflare D1, R2 and a per-user Durable Object; builds as Cloudflare Workflows.
• Plans and model-spend credit with Stripe, referrals, an access gate that is invite-only unless a deployment opens it, an admin panel with credit grants, bans and an audit log, and operator takedown for abuse reports.
• An evaluation suite (packages/eval) and a model bakeoff, so model choices are measured, not guessed.

Status

What runs today. Everything above, deployed at app.vibld.com as a public beta. Paid plans are live; the Free plan builds with GPT-6 Luna, and a new account gets $1.00 of build credit once it adds a card, which is saved and not charged. From a checkout, pnpm generate --build builds a real project with your own provider key, and a weekly workflow proves that from a clean clone.

What does not exist yet.

• Repository search over an existing codebase (internal issue 12).
• A bakeoff result strong enough to recommend one model over another. The harness exists and has run; the evidence does not settle it yet.
• Sandbox output in the builder's own panes. The console shows generation events, and Problems shows the design checks and the verification build, not the install, build and type errors from a live preview.
• A self-hosting path validated outside the project. A workflow deploys a separately named copy from the docs, checks it refuses a signed-out caller, then signs in with the owner's password and builds one site on it with a real model, on Cloudflare and under Docker. Nobody outside the project has deployed their own copy yet.
• The builder's interface against a real model from pnpm dev, which runs the fake provider. Its model path needs sign-in, D1, R2 and a Workflow, which a Cloudflare deployment has and so does the Docker setup, with a key or a local model.

What to be careful of. It is a beta, not a place for work you cannot afford to lose. Very little of it has been used by anyone other than its author, which is a different kind of risk from a missing feature and not one a feature list shows.

The accepted decisions, the architecture decision records and the roadmap say where it is going and why.

Quick start

You need Node.js 24 (the LTS release CI uses; 22.15 or newer also works) and pnpm. The version is pinned in package.json, and corepack enable provides it.

git clone https://github.com/vibld/vibld.git
cd vibld
pnpm install --frozen-lockfile

Generate a real project with your own key

One provider key is all this needs: no account, database or Cloudflare. It runs the same bounded build as app.vibld.com, prints each step and what it cost in tokens, and writes the project it built.

export DEEPSEEK_API_KEY=...   # or ANTHROPIC_API_KEY, or OPENAI_API_KEY

pnpm generate "A one-page site for a neighbourhood bakery, with opening hours and a menu" --out ./my-site --build

cd my-site
npm run dev                   # the generated project, with no vibld dependency

The calls are billed to your key. The weekly proof run, a one-page bakery site on DeepSeek's default model, has taken 7 to 17 minutes and cost $0.15 to $0.31, most of it the model's reasoning. A larger request or a costlier model costs more: Claude Opus 5.5, Anthropic's default here, costs many times what DeepSeek Flash does. packages/ai/README.md has the details.

Run the builder locally

pnpm --filter @vibld/web dev   # the builder, at http://localhost:5173

Locally, the builder runs with no sign-in and a deterministic fake provider, so you can go through the whole flow at no cost and no model is called. apps/web/README.md covers deploying it with a real model provider, sign-in, the sandbox and the rest.

Before you open a pull request

pnpm format:check   # Prettier
pnpm check:style    # house style, including no em-dashes
pnpm typecheck      # every workspace, through Turborepo
pnpm test
pnpm test:scripts   # the repository scripts
pnpm build          # every app's production build

Architecture

flowchart LR
  user([You]) --> web["apps/web<br/>builder SPA + Worker"]
  web -->|plan, stage, check| ai["packages/ai<br/>model adapters"]
  ai --> models[("Anthropic · OpenAI · DeepSeek")]
  web --> core["packages/core<br/>contracts, state machine,<br/>run budget"]
  web --> state[("D1 · R2 · Durable Object<br/>· Workflow")]
  web -->|run in sandbox| preview["apps/preview<br/>sandbox Worker + containers"]
  web -->|publish| publish["apps/publish<br/>published sites"]
  web -->|branch + pull request| gh[(Your GitHub repo)]
  web -->|export| zip[(.zip)]

Loading

VIBLD.md is the product and architecture charter behind all of it.

Running it yourself

Self-hosting is possible, and still needs validation outside the project: a workflow deploys a separately named copy from the docs, signs in to it and builds one site on it, on Cloudflare and under Docker, but nobody else has deployed their own copy yet. A deployment needs:

• Cloudflare, for three Workers (the builder, the sandbox and the publish service) plus D1, R2, a Durable Object and a Workflow behind the builder. Publishing, and live previews in a sandbox, run generated code in Containers, which need the Workers Paid plan, and building the sandbox image needs Docker. Without Containers, the Preview pane bundles the project in the viewer's browser instead (esbuild-wasm, packages from esm.sh, Tailwind compiled in the browser).
• A model provider API key. Without one, generation refuses rather than degrading. The builder's configuration ships VIBLD_MODEL as gpt-6-sol: set it to a model your key serves. A copy that names a model none of its keys serves refuses to build and says why (D91). scripts/self-host.mjs, Docker and Render leave it unset, so they use the model your key serves.
• A way to sign in, one of three: an owner password (VIBLD_AUTH=owner, one person), Cloudflare Access in front of the builder (VIBLD_AUTH=access, free for up to 50 users), or Clerk (for sign-ups from the public, as app.vibld.com uses). There is no mode without sign-in, because the endpoints spend money.
• An open door. A deployment is invite-only until VIBLD_ACCESS_MODE is open: before that, only the verified emails in VIBLD_PLATFORM_ADMINS and the people they invite get in, so list your own. The owner of an owner-password copy is always let in. Under Clerk, its session token has to carry email and email_verified for that match to work.
• Your own names. The Worker names, database, bucket, Workflow, routes and Clerk domain in the wrangler.jsonc files are vibld's. node scripts/self-host.mjs <settings.json> writes a wrangler.self-host.jsonc beside each with all of them derived from a prefix of yours, and refuses to write one that still names vibld's (Deploying).
• Stripe only if you intend to charge anybody, a GitHub App only if you want push-to-repository, and Resend only for email. Each optional piece left unset reports itself unavailable rather than running without its check.

Run it with Docker

The whole builder also runs on one machine under Docker, with no Cloudflare account (docs/decisions.md D126). It needs Docker with Compose, a model key or a local model, and a password to sign in with.

cp .env.example .env    # set VIBLD_OWNER_PASSWORD and a model key or a local model
docker compose up --build

Then open http://localhost:8787 and sign in with that password. Previews open at http://<...>.localhost:8788 and published sites at http://<slug>.localhost:8789; browsers send any *.localhost name to this machine.

• What runs. The builder, previews and publishing are three Workers under workerd (wrangler dev), with their database, files, Durable Objects and Workflow in the vibld-data volume. Secrets they share are made on first start and kept there.
• Previews run on your Docker (D137). Each preview's sandbox is its own container, started through the Docker socket the compose file mounts, the same way it runs on Cloudflare. Anything in control of the vibld container can control your Docker.
• Host networking. The vibld container uses the host's network, so the sandboxes it starts can reach it and it can reach them. On Docker Desktop (macOS, Windows), turn on host networking first: Settings, Resources, Network, "Enable host networking".
• Sign-in is the owner's password (VIBLD_AUTH=owner); Clerk and Cloudflare Access are services outside the box.
• Keys can be set in .env or later on the admin page under Provider keys. A local model is set in .env.
• Not under Docker: the nightly jobs (scheduled cleanups and the billing pass), which wrangler dev does not run on a schedule; and Stripe, GitHub push and email, whose keys the Docker setup does not pass on.

Local models

A copy can build with a model running on your own machine instead of, or as well as, a provider key (docs/decisions.md D124). Anything that answers OpenAI's chat completions API works: Ollama, LM Studio or llama.cpp's server. Set two settings, in .env under Docker or as Worker variables on Cloudflare:

The builder then offers it as "Local: ", and with no provider key set it is the default. It costs nothing per token, so it does not draw on anybody's allowance. pnpm generate uses it too, with VIBLD_PROVIDER=local.

• Give it a context window of 32,768 tokens or more. Ollama's default is smaller, and Ollama cuts a longer prompt without saying so. When it cuts a fifth or more, vibld notices and stops the build with a message saying so; a smaller cut it cannot tell from the difference between tokenizers. Start Ollama with OLLAMA_CONTEXT_LENGTH=32768, or set the context length in LM Studio's model settings.
• Size matters more than anything else. A model too small for the work writes files that do not build, or replies that are not the shape asked for, and vibld says so plainly. On a 4-core CPU with no GPU, Qwen2.5 Coder 1.5B planned and wrote a one-page bakery site in 6 minutes, and most of its files were a single line of markup with no imports, which does not build.
• Speed is your machine's. Each step is sized for a model that writes about 12 tokens a second, and is given twice the time that needs. A slower machine can run out of time on a large step.
• Under Docker, vibld uses your machine's network, so localhost in these settings is your machine. On Cloudflare, the Worker can only reach an address on the public internet, so the server has to be reachable from there.

Deploy to a container host

A host that runs one container on one port, such as Render, can run the same image with VIBLD_SANDBOX=off (docs/decisions.md D141). render.yaml sets it up: Render asks for your password and a model key, and keeps your projects on a 5 GB disk at /data. A disk needs a paid Render instance type.

• The builder runs alone. Such a host gives no Docker socket, so there is no sandbox: previews bundle in the viewer's browser (as on Cloudflare without Containers), builds are not checked in a sandbox, and publishing reports itself unavailable.
• It listens on PORT, which the host sets.
• Checked so far: CI starts the image this way and signs in. Nobody has deployed it to Render yet.

Run it on a server

On a server of your own on the internet, vibld runs as it does under Docker, sandbox previews and publishing included, with a proxy in front that ends TLS (docs/decisions.md D141). infrastructure/vps/cloud-init.yaml sets up a new Ubuntu 24.04 server in one paste. A server with 4 GB of memory or more is a reasonable start: it builds the image and runs each preview's sandbox.

1. Two domains. One for the builder, such as build.example.com, and one of its own for previews and published sites, such as example-preview.dev. Previews run code nobody has reviewed, so they never share the builder's domain (L8). The previews' domain needs its DNS on Cloudflare, which issues its wildcard certificate.
2. A Cloudflare token at https://dash.cloudflare.com/profile/api-tokens: "Create Custom Token", permissions Zone / DNS / Edit and Zone / Zone / Read, zone resources: the previews' domain.
3. The server. Fill in the settings at the top of cloud-init.yaml and paste the whole file as user data: https://cloud.digitalocean.com/droplets/new ("Advanced options", "Add Initialization scripts") or https://console.hetzner.cloud ("Cloud config").
4. DNS, with the server's address: an A record for the builder's domain, and A records for the previews' domain and *. the previews' domain (on Cloudflare, "DNS only", not proxied).

Then open https://<builder domain> and sign in with the password you set. The first start builds the image, which takes a few minutes.

• Only 22, 80 and 443 are open. The Workers listen on 127.0.0.1 behind the proxy, and firewall.sh keeps the internet out of the preview containers and keeps them away from the cloud's metadata service, which holds the user data and the keys in it.
• Updating: cd /opt/vibld && git pull && docker compose -f docker-compose.yml -f infrastructure/vps/compose.yml up --build --detach.
• Checked so far: CI starts it behind the proxy with made-up domains, signs in through the proxy and checks the Workers' ports are closed. Nobody has run cloud-init.yaml on a real server yet.

Read next: what self-hosting involves, every setting and secret, deploying your own copy and hosted or self-hosted. The exact commands are in apps/web/README.md, apps/preview/README.md and apps/publish/README.md, beside the code they deploy. The workflows that deploy vibld's own hosted service run only in the maintainers' working repository, since a copy has none of their secrets.

Documentation

Contributing

Issues, discussions and pull requests are welcome. Start with CONTRIBUTING.md, which also explains how a change reaches this repository, and the code of conduct. Questions and ideas go to Discussions; bugs go to issues.

Found a vulnerability? Report it privately through SECURITY.md, never in a public issue.

License

Built by Chris Brock (@cbrock84), the lead maintainer (GOVERNANCE.md); CITATION.cff says how to cite it.

The core is licensed under Apache-2.0; see also NOTICE. The starter templates in templates/marketing and templates/luminous each carry their own MIT LICENSE at their own boundary, which does not relicense the core (ADR-0008). THIRD_PARTY_NOTICES.md lists the projects whose material is adapted here, with the license text each one publishes.