Contextile

Quickstart · ~5 minutes

Use a coding agent to add a component to your page in 5 minutes

Contextile apps consist of pages assembled at runtime from independent components. Each component has a frontend and a dedicated backend function, with a codebase small enough to fit entirely within a coding agent’s context window. In this quickstart, the agent does most of the work.

00

Prerequisites

01

Create and run the app

~1 min
npx create-contextile my-app
cd my-app && npm run dev

Your browser opens http://127.0.0.1:4242/p/demo automatically. The demo page already contains two components: a greeting card and a live stats card. This is a real page assembled from components. Edit components/hello-card/frontend/index.tsx and save the file; Contextile republishes the page, and your browser reloads it.

02

Hand the task to the agent

~1 min

Open Claude Code (or Cursor) in the project directory and approve the Contextile MCP server when prompted. You only need to approve it once. Then enter:

“Add a weather card component to the demo page.”

03

Watch the agent handle the entire workflow

~3 min

The agent scaffolds the component, writes its frontend and backend function, and deploys it with deploy_component. During deployment, it builds the component, publishes the assets, activates the function, and creates a new page version, reporting a clear status at each step. The agent then uses render_page_screenshot to render the page in a real browser, posts the screenshot in the conversation, and iterates if needed.

Refresh the page—or wait for it to reload automatically—and you’ll see the weather card.

Checkpoints

TimeYou should see
T+1 minthe demo page is open in your browser with two cards
T+2 minthe agent is working and tool calls are streaming
T+5 minthe new component is on the page, and the agent has posted a screenshot

Stuck?

Start by running the diagnostic command:

npx contextile doctor

It checks your Node.js version, project files, dev server, the browser used by the simulator, MCP configuration, and spec version. Every failed check includes a suggested fix. The three most common issues are:

  1. Port already in use: contextile dev automatically tries the next available port. Use the URL shown in the terminal; doctor identifies the conflicting process so you can stop it.
  2. No browser (screenshots unavailable): run npx playwright install chromium to install Chromium. An existing Chrome installation works too.
  3. The agent doesn’t see the Contextile tools: Contextile configures MCP separately for each project; the .mcp.json file lives in the project directory. Make sure you opened the agent session from that directory and approved the server when prompted. If you ran npm install after starting the agent, restart the session.

Next