# midcode

> midcode is a macOS app that turns a website built in code into a visual editor. You open the project folder that's on your Mac, midcode runs it and shows it live at every breakpoint on a canvas, and every edit you make (text, styles, images, layout, new sections) is written into your own source files as a minimal diff. It is the mid between code and no-code.

Key facts:

- Platform: macOS 13 or later, Apple silicon and Intel. Current version: 1.1.2.
- Price: one payment of $199 (launch price $119 for the first buyers), no subscription, every update included, on up to 3 Macs. Free trial: 3 days, no card.
- Runs locally. No account is needed, and nothing is uploaded: midcode edits the files on your Mac.
- Nothing is installed in the project and no config is changed. Comments and layer names live in a .midcode folder.
- It never reformats or reprints a file: only the range that was edited changes, and every edit can be undone.
- AI agents (Claude Code, Codex, Gemini CLI, OpenCode, Cursor) run beside the canvas with the user's own account. midcode sells no model usage.
- Made by Akila Studio (https://akilastudio.com).
- Download: https://midcode.app/download — Homebrew: `brew install --cask agusdellaquila/midcode/midcode`

---

# midcode docs

> What midcode is, how it edits the code you already have, and where each thing is explained.

- Page: https://midcode.app/docs
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode is a Mac app that opens a site you built in code and lets you edit it by looking at it. Click an element and change its text, its size or its color, move it, add a section. Every change is written into your project's own files, as the code you would have typed.

There is no export and no format of its own. Your project stays a normal repository: you keep working on it in your editor or with an AI agent, and midcode shows whatever is there.

## How it works, in four steps

1. **Open your project's folder.** midcode starts the project's dev server and shows the running site on a canvas, at every breakpoint side by side.
2. **Click something.** The right panel shows where that element is written, as `file:line`, and everything you can change about it.
3. **Change it.** midcode edits only the characters that change. Nothing else in the file is touched, so `git diff` shows exactly your edit.
4. **Undo it or publish it.** Every edit is one step of `⌘Z`. Publish lists what changed, commits the files you choose and pushes them.

This is what changing a section's padding from the panel leaves in your code:

```diff title="app/page.tsx"
-<section className="px-6 py-16">
+<section className="px-6 py-24">
```

[How midcode works](https://midcode.app/docs/start/how-it-works.md) follows one click all the way from the canvas to the file.

## What it works with

The version you can download today edits React (Next.js, Vite, React Router, Remix, and Preact or Solid with Vite) and Svelte. The next release adds Vue, Nuxt, Astro, Angular, plain HTML, Laravel, WordPress, Django, Rails, Hugo, Jekyll and Shopify themes, among others. How much it can do depends on the stack: a Next.js project gets everything, and a site that a server renders is edited where its templates write it.

[What works with what](https://midcode.app/docs/start/supported-stacks.md) has the whole table, with what's released and what's next, and each stack has its own page under Frameworks.

Styles are written as classes: Tailwind's own in a Tailwind 4 project, and midcode's `mid:` utilities [everywhere else](https://midcode.app/docs/styling/without-tailwind.md), compiled to plain CSS with nothing installed in your project.

## Where to start

- [Install and license](https://midcode.app/docs/start/install.md): the download, the three-day trial and where the key goes.
- [Open a project](https://midcode.app/docs/start/open-a-project.md): what midcode needs from a folder, and what to do when a project doesn't start.
- [The canvas and breakpoints](https://midcode.app/docs/editor/canvas.md): the place where you'll spend your time.
- [What midcode adds to your project](https://midcode.app/docs/start/project-files.md): every file it may write, and what each one is for.

## For AI agents

midcode runs your own agent beside the canvas ([Your agent in midcode](https://midcode.app/docs/agents/overview.md)), and these docs are written to be read by one too:

- Every page has a **Copy for AI** button. It copies the page as Markdown, ready to paste into a chat.
- Every page is also served as Markdown at its own address with `.md` at the end: `midcode.app/docs/styling/tailwind.md`.
- [`/llms.txt`](https://midcode.app/llms.txt) lists every page, and [`/llms-full.txt`](https://midcode.app/llms-full.txt) is all of them in one file.
- [The midcode skill](https://midcode.app/docs/agents/skill.md) puts all of this inside your agent, so it knows how to write code that stays editable on the canvas.

## What midcode is not

- It isn't a hosting service. Your site is deployed the way it already is; [Publish](https://midcode.app/docs/publish/publish.md) is a commit and a push.
- It isn't a site builder with its own runtime. What it inserts is plain markup in your files, and its interactive components are written into your project as source you own.
- It doesn't sell AI usage. An agent runs with your own account.
- It doesn't need an account, and it doesn't upload your code. It edits the files on your Mac. [Privacy and security](https://midcode.app/docs/reference/privacy.md) lists everything that does go over the network.

---

# Install and license

> Install midcode on a Mac with Homebrew or the disk image, how it updates itself, how the 3-day trial and the license key work, and what's in Settings.

- Page: https://midcode.app/docs/start/install
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode is a Mac app. It runs on macOS 13 or later, on Apple silicon and Intel. It's free for 3 days. After that it's one payment, with every update included, and a license key that works on up to 3 Macs.

## What you need

- A Mac with macOS 13 or later.
- A project: a folder with a site built in code. [Open a project](https://midcode.app/docs/start/open-a-project.md) says what midcode recognizes, and [What works with what](https://midcode.app/docs/start/supported-stacks.md) how much of each it edits.
- Git, if you want to [publish](https://midcode.app/docs/publish/publish.md) from midcode. Everything else works without it.

Node.js is optional for running a project. midcode starts your dev server with the Node your terminal uses, and with its own when the Mac has none. A few things run `npm` or `npx` and do need Node installed: installing a project's dependencies from midcode, the Claude Code and Codex chats in the [Agent tab](https://midcode.app/docs/agents/overview.md), and, from the next release, [New project](https://midcode.app/docs/start/new-project.md).

## Install with Homebrew

```bash
brew install --cask agusdellaquila/midcode/midcode
```

The cask lives in midcode's own tap and is updated with every release.

## Install from the disk image

1. [Download midcode](https://midcode.app/download). That link gives the Apple silicon build; on an Intel Mac use `midcode.app/download?arch=x64`. Every release, with both files, is at `github.com/agusdellaquila/midcode/releases`.
2. Open the `.dmg` and drag midcode to Applications.
3. Open it from Applications.

If you open midcode straight from the disk image, or from Downloads, the first thing it shows is "Move midcode to Applications". Click "Move to Applications": midcode moves itself there, sends an older copy to the Trash and opens again from Applications. "Not now" skips the move, but midcode only updates itself from Applications.

The app is signed and notarized.

## Updates

midcode updates itself. It looks for a new version a few seconds after it opens and every four hours after that, downloads it in the background and checks its signature. A banner under the tabs says where it is:

| Banner | What to do |
| --- | --- |
| "midcode … is available. Downloading… …%" | Nothing. Keep working. |
| "midcode … is ready. Restart to update: your work is saved." | Click "Restart now". If you close the banner instead, the update is installed the next time you quit. |
| "Updated to midcode …." | "What's new" opens the [changelog](https://midcode.app/changelog). |

Updates come from the same public releases on GitHub as the download. There's no midcode server in between. The version you have is at the bottom of Settings.

## The free trial

The first time midcode opens it shows "Welcome to midcode", with three ways forward:

- Type your email and click "Start 3-day free trial".
- "Buy midcode".
- "I have a license key".

The trial is the whole app for 3 days, counted from the moment you start it. The email is where news of a new version goes, and you can unsubscribe. The trial starts with no connection too: the address is sent the next time midcode opens with one.

While the trial runs, a badge at the top of the window says how long is left: "Trial · 2 days left", then hours, then minutes. Click it to buy, or to paste a key.

When the trial ends, midcode shows "Your free trial has ended" and waits for a purchase or a key. Nothing happens to your projects: every edit you made is already in their files. Reinstalling midcode doesn't start a new trial on the same Mac.

## Buy and activate

"Buy midcode" opens the checkout at `midcode.app/buy`. It's one payment: the app, every update, and a license key that works on up to 3 Macs. The launch price is $119. The regular price is $199.

After you pay, the key is on the page you land on, and in your email. To activate it:

1. Open midcode.
2. Click "I have a license key" on the welcome screen. If the trial is still running, click the trial badge at the top instead.
3. Paste the key and click "Activate".

> [!NOTE]
> Settings shows your license but has no field for a key. A key is pasted on the welcome screen or in the trial badge.

Activating needs a connection: the key is checked with the license server of Polar, the service that sells midcode. From then on:

- midcode checks the key again about once a day, in the background.
- Offline, the last good answer stands for 30 days. Past that, the license waits until midcode reaches the server again.
- A fourth Mac is refused: "This key is already active on 3 Macs. Free one from the Polar customer portal (the link is in your order email), then try again."

### Move the license to another Mac

1. On the Mac you're leaving, press `⌘,`.
2. In the "License" row, click "Deactivate" and confirm.

That frees one of the 3 Macs on your key. Paste the key again whenever you want that Mac back.

## Settings

`⌘,` opens Settings from anywhere. On the hub there's also a gear at the top right.

| Setting | What it does |
| --- | --- |
| Language | The language of midcode itself: English or Español. |
| Code editor | Where "Open in your code editor" takes you: Automatic (the first of Cursor, Visual Studio Code, Windsurf or Zed that's installed), one of those four, or "Default app for the file". midcode has [its own code view](https://midcode.app/docs/editor/code.md) too. |
| Nudge amount | How many px `⇧` plus an arrow key moves an element, or adds to a size. A plain arrow is 1. From 1 to 1000; it starts at 10. |
| License | During the trial: when it ends, and "Buy midcode". Once activated: the key, shortened, and "Deactivate". |
| Connections | [GitHub](https://midcode.app/docs/publish/github.md) and [Vercel](https://midcode.app/docs/publish/vercel.md). Optional: midcode works without them. |

The version is at the bottom of the sheet. Settings are kept in midcode's own folder, `~/Library/Application Support/midcode/settings.json`, never in a project.

## Limits

- macOS only. There is no Windows or Linux build.
- The trial can't be extended or paused: it's 3 days from the moment it starts.
- A key activates on 3 Macs at a time. Free one with "Deactivate", or from the Polar customer portal linked in your order email.
- Activating a key needs a connection. Working afterwards doesn't, for up to 30 days at a stretch.

If something goes wrong on the way, see [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md). What midcode sends to the license server, and what it keeps on your Mac, is in [Privacy and security](https://midcode.app/docs/reference/privacy.md).

---

# Open a project

> How midcode opens a project folder, what it detects, how it starts your dev server, where the log is, and why a project can be view-only.

- Page: https://midcode.app/docs/start/open-a-project
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode opens a folder. It works out what runs the site in it, starts that dev server on a port of its own, and shows the running site at every breakpoint, side by side. Nothing is imported or converted: the canvas is your dev server.

## Open a folder

Any of these opens a project:

- Press `⌘O` (File → "Open Folder…") and choose the folder.
- Click "Open folder" on the hub, or the + at the end of the tab strip. From the next release the + starts a [new project](https://midcode.app/docs/start/new-project.md) instead: it goes to the hub with "New project" open, and "Open an existing folder…" in that dialog opens a folder.
- Drop the folder on the hub.

Choose the project's root: the folder with its `package.json`, or with its `index.html` when it's plain HTML.

The hub lists the projects you've opened, each with a picture of the site and when you last opened it. The ⋯ on a card has "Open", "Open in Finder", "Open in code editor", "Copy path" and "Remove from recents". Removing one only takes it off the list. From the next release it reads "Remove from the list", and the hub can be arranged your way: [Organize the hub](#organize-the-hub).

### Tabs

Each project opens in its own tab, like a browser. Every tab has its own dev server, and it keeps running while another tab is in front. `⇧⌘H` (File → "Back to Projects") goes to the hub without closing anything. Closing a tab stops that project's dev server, its terminals and its agent.

A project opens once: opening it again brings its tab forward.

## Organize the hub (next release)

The hub keeps every project you've opened, and you arrange it your way. The arrangement is midcode's own list: no folder is moved, renamed or changed on your disk.

- Groups. The + beside "Groups" in the sidebar makes a group and lets you type its name. Drag a project's card onto a group to put it there, or use "Move to group…" in the card's ⋯ menu (a right-click on the card opens the same menu). A project is in one group at a time. "Ungrouped" shows the ones in none, and a card dropped on it leaves its group.
- Pins. The pin on a card, or "Pin to the top" in its menu, keeps the project first, under "Pinned", in every view.
- Order. The menu at the top right orders the cards by "Last opened", by "Name" or in a "Custom order". Drag a card beside another one to set your own: the order becomes "Custom order", starting from what was on screen, so only the card you dragged moves. Pinned cards are ordered among themselves.
- Search. "Search projects" filters the open view by name or by path.

A group's row has its own ⋯ (and right-click) with "Rename" and "Delete group". Double-click a group to rename it, and drag it to reorder the groups. Deleting a group keeps its projects on the hub, in no group.

Dragging a card out of midcode, onto a terminal or an editor, drops the project's path.

All of it is one file in midcode's own data folder, never in a project:

```json title="~/Library/Application Support/midcode/hub.json"
{
  "groups": [{ "id": "531a1d5e", "name": "Clients" }],
  "where": { "05393af05cce": "531a1d5e" },
  "pinned": ["5968533421fe"],
  "order": ["05393af05cce", "74cd0d0aa0b1"],
  "sort": "manual"
}
```

Projects are known there by an id made from their path. "Remove from the list" also takes a project out of its group, its pin and its place in the order. A project whose folder is missing (an unplugged disk) isn't listed, and finds its group again when the folder is back.

## What midcode detects

midcode reads the dependencies in `package.json`. The first one it finds, in this order, decides how the project runs:

| In `package.json` | Opens as | On the canvas |
| --- | --- | --- |
| `next` | [Next.js](https://midcode.app/docs/frameworks/nextjs.md) | Edited. |
| `@react-router/dev` | [React Router](https://midcode.app/docs/frameworks/react-router.md) | Edited. |
| `@remix-run/dev` | [Remix](https://midcode.app/docs/frameworks/react-router.md) | Edited. |
| `astro` | [Astro](https://midcode.app/docs/frameworks/astro.md) | Its React, Preact and Solid islands are edited. `.astro` files: next release. |
| `@sveltejs/kit` | [SvelteKit](https://midcode.app/docs/frameworks/svelte.md) | Edited. |
| `nuxt` | [Nuxt](https://midcode.app/docs/frameworks/nuxt.md) | View-only. Edited in the next release. |
| `vite` | [Vite](https://midcode.app/docs/frameworks/react-vite.md) | Edited with `react`, `preact`, `solid-js` or `svelte` in the dependencies. With `vue` or Qwik: next release. Otherwise view-only. |
| none of these, and a `dev` script | Your `dev` script | View-only. |
| no `package.json` (or none of the above in it), and an `index.html` | [Plain HTML](https://midcode.app/docs/frameworks/html.md) | View-only. Edited in the next release. |

[What works with what](https://midcode.app/docs/start/supported-stacks.md) has the whole list, with how much of each stack midcode edits.

### More stacks, and any folder (next release)

In the released version, a folder that matches no row of the table above (no known framework, no `dev` script and no `index.html`) is refused: "midcode couldn't tell what runs this folder." From the next release, any folder opens:

- Stacks midcode knows by their files run with their own command: Laravel, Django, Flask, FastAPI, Rails, Hugo, Jekyll, WordPress, plain PHP, Angular, a Shopify theme and more. The list and each command are in [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).
- Sites built with webpack or Rspack (Rsbuild among them) run with their own script, on midcode's port where the tool takes `--port`, and are edited: [Create React App, Vue CLI, Gatsby, Docusaurus](https://midcode.app/docs/frameworks/webpack.md).
- Sites a server renders from templates are edited too, in a different way: [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md).
- The top of a repository with one site inside (`apps/web`, `frontend/`) opens that site. See [Monorepos](https://midcode.app/docs/frameworks/monorepos.md).
- When midcode can't tell how a folder runs, the canvas asks. See [Change how it runs](#change-how-it-runs).

## Dependencies

If the project has a `package.json` and no `node_modules`, the canvas shows "Dependencies are missing" with one button: "Install with pnpm" (or npm, yarn, bun). The package manager is the one your lockfile names: `pnpm-lock.yaml`, `bun.lockb` or `bun.lock`, `yarn.lock`, `package-lock.json`. With no lockfile it's npm.

The button runs `<package manager> install` in your login shell, in the project folder, and then starts the server. What it prints goes to the log.

## How the dev server starts

midcode picks a free port, starting at 4310, so it never takes the port your own terminal uses. It runs the server with the Node your terminal has (it asks your login shell for its `PATH`, so nvm, fnm and Homebrew setups are found), or with its own Node when the Mac has none.

| Project | What midcode runs |
| --- | --- |
| Next.js | `next dev --port <port>`, with midcode's hook preloaded |
| Vite, SvelteKit | `vite dev --port <port>`, with a config that loads yours and adds midcode's plugin |
| React Router | `react-router dev --port <port>`, the same way |
| Remix | `remix vite:dev --port <port>`, the same way |
| Astro | `astro dev --port <port>`, the same way |
| Nuxt | `nuxi dev --port <port>`. Next release: with a layer that adds midcode's plugin |
| Plain HTML | midcode's own static server, which reloads the page when a file changes |
| Anything else | `<package manager> run dev`, and the address is read from what it prints |

The hook and the plugin are what tell the canvas where each element is written. They're added from outside, on the command line: your `next.config`, `vite.config` and `package.json` are not changed. [How midcode works](https://midcode.app/docs/start/how-it-works.md) follows that road end to end.

From the next release, a Vite project is also started with the options its own `dev` script gives Vite (`vite --mode ssr` keeps `--mode ssr`). The port, the host and the config stay midcode's.

For that process midcode also sets `PORT`, sets `BROWSER=none` so no browser window opens, and turns off Next.js and Astro telemetry.

The server is ready when the site answers. The first line of the log says what was run and with which Node:

```text
$ next dev --port 4310  (/Users/you/.nvm/versions/node/v22.11.0/bin/node)
```

### When midcode's way doesn't start

Some projects need something only their own script sets up: an env file, a second process, a toolchain that wraps Vite. For Vite, SvelteKit, React Router, Remix, Astro and Nuxt projects, if the server stops or doesn't answer in 45 seconds, midcode stops it and runs your own `dev` script instead, with 2 minutes to come up.

The site then shows, but without midcode's plugin there's nothing to edit by, so the project is view-only for that session. A message says so: "midcode couldn't start this project its own way, so it runs your dev script: the site shows, but editing on the canvas needs midcode's plugin. The log says why." Its "Send report" button opens the feedback form with the report attached.

Next.js has no fallback. It always runs with the hook.

## The server log

The button at the right of the top bar, a dot beside a terminal icon, opens the dev server's log. The dot is green while the server runs. While it starts, installs or fails, a word sits beside it: "Starting", "Installing", "Error", "Stopped".

The log panel has "Send report", "Copy report", "Restart" and a close button. An error opens it by itself. [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md) says what a report contains.

## One Next.js dev server per folder

Next.js allows one `next dev` per project folder. If yours is already running in a terminal, midcode's stops and the canvas shows "A Next server is already running for this project", with the address and process id of the other one.

- "Stop it and use midcode" stops that process (midcode checks first that it is a Next.js server) and starts its own.
- Or stop it yourself in your terminal, then click "Restart" in the log.

midcode needs its own server: the one in your terminal runs without the hook, so its pages don't say where each element is written.

## HTTPS and other hosts

- A dev server that serves `https` with a certificate it made for itself (Vite's basic-ssl plugin, mkcert) works. midcode reads the address from the server's "Local:" line, `http` or `https`, and accepts a self-made certificate for `localhost`, `127.0.0.1` and `*.localhost` only.
- The released version only shows a site at `localhost` or `127.0.0.1`. From the next release a site can live on another host (`app.test` under Herd or Valet), which needs a certificate macOS trusts.
- A Laravel app with Vite is shown at the `APP_URL` of its `.env`, as served by Herd, Valet or `php artisan serve`, with Vite running beside it. If `APP_URL` is a plain `http` address on this Mac and nothing answers there, midcode starts `php artisan serve` itself. In the released version a Laravel site is shown only when that address is `localhost` or `127.0.0.1`, and it's view-only: see [Laravel](https://midcode.app/docs/frameworks/laravel.md).

## Change how it runs (next release)

When a server fails, the error card has a "Change how it runs" link. It opens the same form the canvas shows for a folder it can't work out: "How does this site run?"

- "Command": what starts the site, for example `bin/rails server -p $PORT`. `$PORT` is the free port midcode picked.
- "Address": where it answers, for example `http://localhost:$PORT`.

Give one or both. With an address and no command, midcode starts nothing and only shows a site that's already running (under Herd, Docker, another terminal). "Start" saves it in the project:

```json title=".midcode/server.json"
{
  "command": "bin/rails server -b 127.0.0.1 -p $PORT",
  "url": "http://127.0.0.1:$PORT"
}
```

What's in that file comes before anything midcode would do by itself. "Reset" empties it and lets midcode work it out again.

> [!NOTE]
> In a project midcode already knows how to start (Next.js, Vite, Astro, Nuxt, SvelteKit, React Router, Remix), a `server.json` makes it run the project's own way, without midcode's hook or plugin: the site shows, with no marks, and it's view-only. To get midcode's own start back, delete the file and click "Restart" in the log.

[Any other stack](https://midcode.app/docs/frameworks/custom-server.md) has the details.

## Editable or view-only

A project is editable when midcode has a way to know where each element is written. When it doesn't, the right panel says so, for example "Nuxt: preview and comments", and you can still:

- see every breakpoint, and reload them;
- use the site at full size with [Preview](https://midcode.app/docs/editor/canvas.md) (`P`);
- leave [comments](https://midcode.app/docs/editor/comments.md) for your agent, each anchored to its element;
- browse the page in [Layers](https://midcode.app/docs/editor/layers.md), by its DOM;
- work on the code in [Code](https://midcode.app/docs/editor/code.md) and with [your agent](https://midcode.app/docs/agents/overview.md);
- [publish](https://midcode.app/docs/publish/publish.md).

A project is view-only when its stack isn't one midcode edits yet (the table above), when it's running with its own `dev` script because midcode's way didn't start, or, from the next release, when a `.midcode/server.json` tells a Next.js, Vite, Astro, Nuxt, SvelteKit, React Router or Remix project to run its own way.

## Limits

- midcode starts the site and nothing else. If your site needs an API or a database running beside it, start those yourself.
- With no Node on the Mac, midcode runs your dev server with its own, but it can't install dependencies: that needs your package manager.
- midcode picks the port for the servers it starts itself. A `dev` script with a fixed port still fails if that port is taken: what it prints is in the log. From the next release, a script that is only a call to a tool that takes `--port` and doesn't name one (rsbuild, rspack, webpack, vue-cli-service, docusaurus, gatsby, parcel, vitepress, vuepress, eleventy) is given midcode's port.
- The routes midcode lists as pages come from each framework's files. How they're found is on each framework's page, and in [Pages and navigation](https://midcode.app/docs/editor/pages.md).

---

# New project

> Start a site from midcode's hub, with the starters it offers, the exact command each one runs, what has to be on your Mac, and what you get.

- Page: https://midcode.app/docs/start/new-project
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

"New project" makes a project from scratch and opens it on the canvas. midcode doesn't have templates of its own: it runs the tool each framework's community uses (`create-next-app`, `create-vite`, `sv`, `ng`, `composer create-project`…) with every question already answered, in a folder you choose.

Use it when there's no project yet. If you already have one, [open its folder](https://midcode.app/docs/start/open-a-project.md).

## Make a project

1. On the hub, click "New project". With no projects yet, the same dialog is behind "Start a new project". From inside a project, the + at the end of the tab strip or `⌘N` (File → "New Project…") goes to the hub with the dialog open; your tab stays open behind it.
2. Under "Built with", choose the technology: React, Vue, Svelte, Angular, Solid, Astro, HTML, PHP, Python or Shopify.
3. Under "Start with", choose the starter. The first one is marked "Recommended".
4. Type a "Name". It becomes the folder's name, in lowercase with dashes: "My Site" makes `my-site`.
5. "Where" is the folder it's made in. Click it to choose another. midcode remembers the last one; the first time it offers `~/Developer` or `~/Documents`.
6. If more than one package manager is installed, choose it under "Package manager" (pnpm, npm, bun or yarn).
7. Click "Create project".

While it runs, the line at the bottom shows what the tool prints. "Cancel" stops it. The Node.js starters take about a minute. When it's done, midcode says "my-site is ready" and opens the project in a tab.

Making a project needs a license or a running trial, like any edit.

## Technologies and starters

| Built with | Start with | Needs on your Mac |
| --- | --- | --- |
| React | Next.js, Vite, React Router, Preact | Node.js |
| Vue | Nuxt, Vite | Node.js |
| Svelte | SvelteKit | Node.js |
| Angular | Angular | Node.js |
| Solid | Vite | Node.js |
| Astro | Astro | Node.js |
| HTML | Plain HTML | Nothing |
| HTML | Eleventy | Node.js |
| HTML | Hugo | Hugo |
| PHP | Laravel, Laravel + React, Laravel + Vue, Laravel + Livewire | PHP, Composer and Node.js |
| Python | Django, Flask | Python 3 |
| Shopify | Dawn, Skeleton, "A theme from your store" | The Shopify CLI, signed in |

"Node.js" means `node`, `npx` and at least one package manager on your shell's `PATH`.

When something is missing, the dialog says what and links to where to get it: "This needs Node.js on your Mac", "This needs Hugo on your Mac" (`brew install hugo`), "This needs PHP and Composer on your Mac" (Laravel Herd installs both), "This needs Python on your Mac". Install it and come back. For Shopify, the dialog shows the card that installs the CLI or signs you in: see [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## What each starter runs

Commands run in your login shell, with `CI=1` so nothing stops to ask: the first in the "Where" folder, the rest inside the new project. `<name>` is the folder name and `<pm>` your package manager.

### React

Next.js:

```bash
npx --yes create-next-app@latest <name> --typescript --tailwind --eslint --app --no-src-dir --import-alias "@/*" --turbopack --use-<pm> --yes
```

Vite:

```bash
npx --yes create-vite@latest <name> --template react-ts
<pm> install
<pm> add -D tailwindcss @tailwindcss/vite
```

React Router:

```bash
npx --yes create-react-router@latest <name> --yes --no-git-init --install --package-manager <pm>
```

Preact is the Vite recipe with `--template preact-ts`. With npm, the third line is `npm install -D tailwindcss @tailwindcss/vite`.

After a Vite template, midcode adds the Tailwind plugin to `vite.config.ts`, writes `@import "tailwindcss";` as the stylesheet, and replaces the template's demo with one plain page. This is what it adds to the config:

```diff title="vite.config.ts"
+import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'

 export default defineConfig({
-  plugins: [react()],
+  plugins: [react(), tailwindcss()],
 })
```

### Vue

Nuxt:

```bash
npx --yes nuxi@latest init <name> --template minimal --packageManager <pm> --no-gitInit --no-modules
<pm> add -D tailwindcss @tailwindcss/vite
```

midcode then writes `assets/css/main.css`, `app.vue` and a `nuxt.config.ts` that loads the stylesheet and the Tailwind plugin. Vite is the same recipe as React's, with `--template vue-ts`.

### Svelte, Angular, Solid, Astro

SvelteKit:

```bash
npx --yes sv@latest create <name> --template minimal --types ts --add tailwindcss="plugins:none" --install <pm>
```

Angular:

```bash
npx --yes @angular/cli@latest new <name> --defaults --style=tailwind --ssr=false --skip-git --skip-tests --ai-config=none --package-manager <pm>
```

Astro:

```bash
npx --yes create-astro@latest <name> --template minimal --no-install --no-git --yes
<pm> install
npx --yes astro add tailwind --yes
```

Solid is the Vite recipe with `--template solid-ts`. In each of these the first page (`src/routes/+page.svelte`, `src/app/app.html`, `src/pages/index.astro`, `src/App.tsx`) is replaced with the plain starting page.

### HTML

Plain HTML runs nothing. midcode writes three files: `index.html`, `style.css` and a `.gitignore`.

Eleventy is written by midcode too: a `package.json` with `@11ty/eleventy` and the scripts `dev` (`eleventy --serve`) and `build`, an `eleventy.config.js` that copies `public/` to the site's root, a layout in `_includes/base.njk`, `index.njk` and `public/style.css`. Then `<pm> install`.

Hugo:

```bash
hugo new site <name>
```

midcode adds the layouts (`layouts/_default/baseof.html`, `single.html`, `list.html`, and `layouts/index.html`) and `static/style.css`.

### PHP

Laravel:

```bash
composer create-project laravel/laravel <name> --no-interaction --prefer-dist
<pm> install
```

The three kits are the same command with Laravel's own starter kits: `laravel/react-starter-kit`, `laravel/vue-starter-kit` and `laravel/livewire-starter-kit`.

### Python

Django:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --quiet --disable-pip-version-check django
.venv/bin/django-admin startproject config .
```

midcode then adds `templates/base.html`, `templates/home.html` and `static/style.css` at the top of the project, points `config/settings.py` at them (`DIRS` and `STATICFILES_DIRS`), routes `/` to the home template in `config/urls.py`, and writes `requirements.txt`.

Flask:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --quiet --disable-pip-version-check flask
```

midcode writes `app.py` with one route, the same two templates, `static/style.css` and `requirements.txt`.

Both get a virtual environment of their own in `.venv`. It's what midcode runs the project with afterwards: see [Django, Flask and FastAPI](https://midcode.app/docs/frameworks/python.md).

### Shopify

Skeleton:

```bash
shopify theme init <name> --path <where>
```

Dawn:

```bash
shopify theme init <name> --path <where> --clone-url https://github.com/Shopify/dawn.git
```

A theme from your store:

```bash
shopify theme pull --store <store> --theme <id> --path <where>/<name>
```

For Dawn and Skeleton, "Store to work on it with" is optional ("Decide later"). For a theme from your store, choose the store and then the theme; the button reads "Download and open". The store is saved in `.midcode/shopify.json`.

## What you get

- **Tailwind 4**, set up by the tool or by midcode, in every React, Vue, Svelte, Angular, Solid, Astro and Laravel starter. It's what midcode writes styles with: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).
- **A plain stylesheet** (`style.css`) in Plain HTML, Eleventy, Hugo, Django and Flask. There, style edits use midcode's own utilities: see [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).
- **One starting page** where the tool's own is a demo to delete: a heading, a paragraph and a button, ready to click.
- **TypeScript** where the tool offers it.
- **A git repository**. If the tool didn't make one, midcode runs `git init`. There's no commit and no remote: those are yours to make. A Shopify theme is left as the Shopify CLI makes it.
- **A `.gitignore`** in the projects midcode writes itself (Plain HTML, Eleventy, Hugo, Django, Flask).

If the tool fails, or you cancel, the half-made folder is deleted and the dialog shows the tool's last lines.

While the tools run, midcode sets `NEXT_TELEMETRY_DISABLED`, `ASTRO_TELEMETRY_DISABLED`, `NUXT_TELEMETRY_DISABLED`, `NG_CLI_ANALYTICS=false` and `DO_NOT_TRACK=1`.

## Limits

- There are no options beyond the ones in the dialog. For JavaScript instead of TypeScript, a `src/` folder, or another template, run the tool yourself and open the folder.
- The name is letters, digits and dashes. A folder with that name that isn't empty is refused: "There's already a folder named … there."
- A tool that runs longer than 15 minutes is stopped.
- Qwik isn't offered: the `create-vite` Qwik template doesn't install today. A Qwik project made by hand opens and is edited like Solid.
- Tried by creating and opening each one from midcode: Next.js 16, Vite + React, Vite + Vue (with pnpm), React Router, Astro, SvelteKit, Nuxt, Plain HTML, Angular 22, Vite + Solid and Vite + Preact. All of them came up editable on the canvas.
- Eleventy, Hugo, Laravel, Laravel + React, Django and Flask were created and opened from midcode too.
- Laravel + Vue and Laravel + Livewire were made with the same command run by hand, not from the dialog.

---

# How midcode works

> The road of one click in midcode, from the canvas to the line of code it changes, through the dev server, the marks on each element, the edit and undo.

- Page: https://midcode.app/docs/start/how-it-works
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode keeps no copy of your site and has no format of its own. The canvas is your dev server, running. An edit is a change to one of your files, a few characters wide. This page follows one click from the canvas to the line it changes, so you know what midcode does to your project and what it never does.

The example is a Next.js project. Other stacks take the same road with a different first step, linked along the way.

## 1. Your dev server, with one thing added

When you [open a project](https://midcode.app/docs/start/open-a-project.md), midcode starts its dev server on a free port. For Next.js that is your own `next`, from your `node_modules`, with one file preloaded:

```bash
node --require <midcode>/next-hook.cjs node_modules/next/dist/bin/next dev --port 4310 --hostname localhost
```

The hook wraps the function Next.js loads its config with. On the config it gets back, in memory, it adds one rule: files ending in `.tsx` and `.jsx` go through midcode's loader first, under Turbopack or webpack, whichever your project uses. It also turns off the Next.js badge that would sit over the canvas.

Nothing is written to disk for this. Your `next.config` isn't edited, and nothing is installed in the project. If a future Next.js changes shape and the hook doesn't fit, it steps aside: the server runs as it always would, without selection.

Projects that run on Vite (Vite + React, React Router, Remix, SvelteKit, Astro) get the same thing through a config file kept in midcode's own folder: it loads your config and adds midcode's plugin. See [React with Vite](https://midcode.app/docs/frameworks/react-vite.md), [Svelte and SvelteKit](https://midcode.app/docs/frameworks/svelte.md) and the other pages under Frameworks.

## 2. Every element learns where it's written

The loader runs on each of your JSX files as the dev server compiles them. It adds one attribute to every element: the file, line and column where that element is written.

```tsx title="app/page.tsx, as you wrote it"
<section className="px-6 py-16">
  <h1 className="text-5xl">Built to outlast</h1>
  <Card title="Oak" />
</section>
```

```tsx title="What the dev server compiles"
<section data-mc="app/page.tsx:12:5" className="px-6 py-16">
  <h1 data-mc="app/page.tsx:13:7" className="text-5xl">Built to outlast</h1>
  <Card data-mci="Card|app/page.tsx:14:7" title="Oak" />
</section>
```

There are three marks:

| Mark | On | Says |
| --- | --- | --- |
| `data-mc="file:line:col"` | Every HTML element in your JSX | Where that element is written. |
| `data-mci="Name\|file:line:col"` | Every component instance | Which component it is, and where the instance is written. |
| `data-mcu` | The element a component returns | Where that component is used, outermost first. |

The last one is why selecting a `<section>` drawn by `<Hero />` can lead to the `<Hero />` written in the page, and why Layers can name components.

What matters about the marks:

- They exist only in what the dev server compiles. The file on disk is untouched, and the rest of its text stays exactly where it was, so line numbers stay true.
- They exist only while midcode runs the server. Your own `next dev`, your production build and your deployed site never have them.
- Files in `node_modules` are skipped. An element drawn by a library has no mark, and the panel says so: "A library draws this element: it isn't in your project's files, so there's nothing to edit here."
- Wrappers that render nothing of their own are skipped too: fragments, `Suspense`, `StrictMode`, context providers.

A site a server renders from templates (Django, Rails, Hugo, plain PHP) has no build step to hook into. From the next release, midcode finds each element in the project's templates after the page loads: see [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md). Where pages are built from Markdown (Hugo, Jekyll, Eleventy), it finds headings, paragraphs and list items in the `.md` files by their words: see [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md).

## 3. The bridge inside each frame

Each breakpoint on the canvas is a frame that loads your dev server at that width. When a frame finishes loading, midcode runs a script inside it: the bridge. The bridge draws the hover and selection outlines, in a layer of its own that your CSS can't reach, and it listens for clicks, double-clicks and drags.

A site may refuse to be shown inside a frame (`X-Frame-Options`, or `frame-ancestors` in its Content Security Policy). midcode lifts that for your dev server's address only.

When you click, the bridge finds the nearest element with a mark and tells the editor what it is: its marks, which copy it is when one line renders many (a `.map()`), and a CSS selector as a last resort. The "Code" section of the right panel then shows where it lives:

- "Element": the file and line of the element itself.
- "Instance": the component instance that drew it, if any.
- "Used at": where its component is used.
- "Inside": the nearest ancestors written in other files.

Click any of them to copy `file:line:col`. That reference is what you hand to an agent: see [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## 4. The edit goes to the file

Say you double-click the heading and type. The window sends the element's reference, the old text and the new one to midcode's main process, the only part of the app that reads and writes your files. It opens `app/page.tsx`, parses it, finds the element that starts at line 13, column 7, and checks that its text is what the canvas was showing. Then it replaces only the characters that change:

```diff title="app/page.tsx"
 <section className="px-6 py-16">
-  <h1 className="text-5xl">Built to outlast</h1>
+  <h1 className="text-5xl">Built to endure</h1>
   <Card title="Oak" />
```

A style works the same way. The [style panel](https://midcode.app/docs/editor/styles.md) works out which classes to take out and which to add, and the new one takes the old one's place:

```diff title="app/page.tsx"
-<section className="px-6 py-16">
+<section className="px-6 py-24">
```

midcode never reprints a file. It doesn't format, reorder or touch a line it wasn't asked about, so `git diff` shows exactly the edit. Edits to one project run one at a time, in order.

If the file moved on while you were looking (you or your agent saved it and the page hasn't reloaded), the element isn't where the mark says, and the edit is refused rather than guessed: "Couldn't find the element at app/page.tsx:13 (did the file change?)" or "The text in the code doesn't match the preview. Wait for it to reload and try again."

### When the text isn't where it shows

Sites often keep their words in data:

```tsx title="app/page.tsx"
{features.map((f) => (
  <h3>{f.title}</h3>
))}
```

The `<h3>` knows where it's written, but there's no text there to change. So midcode looks for the exact text as a string in the project's files: modules, JSON, Markdown, CSS. One match is the answer. With several, it keeps the ones in files the element's file imports. If it still can't tell, it names the places instead of picking one: "That text appears in 3 places (…). Open the right one in your editor."

Text a program computes has nothing to rewrite: "This text isn't written there: it comes from a variable or prop." [Text, images and video](https://midcode.app/docs/editor/text-and-media.md) has the full rules, and [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md) says how to write code that stays editable.

## 5. The page updates itself

midcode doesn't redraw anything. The file changed on disk, your dev server noticed, and its hot reload brought the change to every frame. What you see on the canvas is always your real site, built by your real toolchain.

## 6. Undo, and the list of changes

Every write is kept as a before and an after.

- `⌘Z` puts the file back as it was. `⇧⌘Z` does the edit again.
- One edit is one step, whatever it took: a class changed on five selected elements, or a component inserted along with the file midcode created for it and its import. Undoing an edit that created a file deletes that file.
- An undo only happens if the file is exactly as the edit left it. If you, your editor or your agent changed it since, midcode leaves it alone: "The file changed outside midcode, so that edit can't be undone".
- A file midcode created that something else now imports stays too.
- What your agent changes from the chat in the Agent tab goes into the same history, one step per change it makes.
- The history is kept in memory: up to 200 steps per project, until you quit midcode. After that, your undo is git.

Each edit also adds a line, in words, to the list in [Publish](https://midcode.app/docs/publish/publish.md): Text "Built to outlast" → "Built to endure". Undo takes the line out again. Publishing turns the files you choose into one commit and pushes it.

Some things midcode saves aren't code edits and have no undo: comments, layer names, breakpoints and page order (files in `.midcode/`), a page made or removed from the page menu (a removed page's file is in the Trash), rows of a database, and a Shopify store. Each page says so where it applies.

## What this means for your project

- Your project never depends on midcode. There's no runtime, no wrapper component and no build plugin left behind.
- What midcode adds is plain files you can read: [What midcode adds to your project](https://midcode.app/docs/start/project-files.md) lists every one.
- You can edit the same files in your editor or with an agent while the project is open. midcode shows whatever is there.

## Limits

- Only elements written in your project's files can be selected by their code. What a library draws can't.
- In Next.js and Vite projects the marks go on `.tsx` and `.jsx` files. JSX written in a plain `.js` file isn't marked.
- A mark is a line and a column. Between a save and the reload that follows, marks can point at the old position; edits made in that moment are refused, not misplaced.
- Undo history doesn't survive quitting midcode.
- How much can be edited depends on the stack: see [What works with what](https://midcode.app/docs/start/supported-stacks.md).

---

# What midcode adds to your project

> Every file midcode may write in your project besides your own code, from the .midcode folder to midcode.css, with their formats and what to commit.

- Page: https://midcode.app/docs/start/project-files
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Almost everything midcode does is an edit to a file you already have. This page is about the rest: the files midcode creates. All of them are plain text or plain assets that you can read, commit, ignore or delete, and that your agent can read without midcode.

On its own, midcode never edits your `package.json`, your lockfile, your framework's config or your `.gitignore`. The only install it runs is your own package manager's, when you click "Install with …" on a project whose dependencies are missing. The marks that link the canvas to your code exist only in the running dev server: see [How midcode works](https://midcode.app/docs/start/how-it-works.md).

## At a glance

| File | Appears when | Commit it? |
| --- | --- | --- |
| `.midcode/comments.json`, `.midcode/attachments/` | You leave a comment | If the comments are for people or agents working from the repo |
| `.midcode/layers.json` | You rename a layer | Yes, to keep the names |
| `.midcode/breakpoints.json` | You add, edit or remove a breakpoint, or change the primary | Yes |
| `.midcode/pages.json` | You reorder pages, or remove one | Yes, to keep the order |
| `.midcode/theme.css` | First style edit in a project without Tailwind 4 | Yes |
| `.midcode/translations.json` | You translate a site that has one language | Yes, until the languages are wired up |
| `.midcode/server.json` (next release) | You tell midcode how the site runs | If your team runs it the same way |
| `.midcode/shopify.json` (next release) | You choose the store for a theme | Either |
| `.midcode/queries/*.sql` (next release) | You save a SQL query | Yes, to share them |
| `.midcode/README.md` | With the first comment, or with `midcode.css` | Either |
| `midcode.css` | First style edit in a project without Tailwind 4 | Yes: the site needs it |
| `app/midcode-scratch/page.tsx` | You put something on the canvas outside the breakpoints (Next.js, App Router) | No. midcode never publishes it |
| `components/midcode/*` | You insert an interactive component | Yes: your pages import them |
| Files in `public/` | You add or replace an image, a video, audio or a sticker, or set a favicon or social image outside Next.js (next release) | Yes |

Files under `.midcode/` are listed in [Publish](https://midcode.app/docs/publish/publish.md) but not ticked: tick the ones you want in the commit. Tick `.midcode/theme.css` if `midcode.css` is built anywhere but your Mac, because [the midcode package](https://midcode.app/docs/styling/package.md) reads it.

## The .midcode folder

### comments.json and attachments/

[Comments](https://midcode.app/docs/editor/comments.md) you leave on the canvas. The file is a list, one object per comment:

```json title=".midcode/comments.json"
[
  {
    "id": "3f9a1c2e",
    "createdAt": 1759688400000,
    "resolvedAt": null,
    "page": "/",
    "breakpoint": "desktop",
    "viewportWidth": 1440,
    "anchor": {
      "ref": {
        "mc": "app/page.tsx:13:7",
        "mci": null,
        "i": 0,
        "sel": "body > main > section > h1",
        "mcu": null
      },
      "tag": "h1",
      "component": null,
      "text": "Built to outlast",
      "context": ["app/layout.tsx:18:9"],
      "fx": 0.42,
      "fy": 0.5
    },
    "body": "Make this fit on one line",
    "attachments": []
  }
]
```

- `anchor.ref.mc` is where the element is written, as `file:line:col`. `mci` is the component instance that drew it (`Name|file:line:col`), and `mcu` where its component is used.
- `i` tells apart the copies one line renders (a `.map()`), and `sel` is a CSS selector for elements with no place in the code.
- `context` lists where the nearest ancestors from other files are written. `fx` and `fy` are where on the element the pin sits, from 0 to 1.
- `resolvedAt` is `null` while the comment is open.

A file attached to a comment is copied to `.midcode/attachments/<id>-<name>` and listed in `attachments` with its `path`, `type` and `size`. Deleting the comment deletes its attachments.

### layers.json

The names you give [layers](https://midcode.app/docs/editor/layers.md), or that Apple Intelligence gives them.

```json title=".midcode/layers.json"
{
  "version": 1,
  "names": [
    {
      "file": "app/page.tsx",
      "tag": "section",
      "classes": "px-6 py-24",
      "text": "",
      "loc": "app/page.tsx:12:5",
      "name": "Hero"
    }
  ]
}
```

A name is found again by `loc` first. Lines move as you edit, so the file, tag and classes are kept as a second way to find the same element: an element in the same file with the same tag and the same classes takes the name. [Layers](https://midcode.app/docs/editor/layers.md) has the details.

### breakpoints.json

The project's [breakpoints](https://midcode.app/docs/editor/canvas.md). Until you change them there is no file, and midcode uses three defaults. Written out, they are:

```json title=".midcode/breakpoints.json"
{
  "version": 1,
  "list": [
    { "id": "desktop", "label": "Desktop", "width": 1440, "height": 900, "screen": "lg" },
    { "id": "tablet", "label": "Tablet", "width": 768, "height": 1024, "screen": "md" },
    { "id": "phone", "label": "Phone", "width": 390, "height": 844, "screen": "" }
  ],
  "primary": "desktop"
}
```

`screen` is the Tailwind screen each breakpoint's overrides are written at. The smallest writes with no prefix. `height` is the device height that viewport units (`vh`) mean on the canvas.

### pages.json

The order you gave the pages in the [page list](https://midcode.app/docs/editor/pages.md), as routes. The home page is always first, so it isn't listed.

```json title=".midcode/pages.json"
{
  "version": 1,
  "order": ["/work", "/about", "/contact"]
}
```

### theme.css

In a project without Tailwind 4, the colors, fonts and text styles you make under "Styles" in the Assets tab. It starts like this:

```css title=".midcode/theme.css"
/*
 * This project's theme in midcode: the colors, fonts, sizes and text styles made in the Design panel.
 * midcode builds midcode.css from this file and from the mid: classes in the code.
 *
 *   --color-brand: #ff5b2e;   →  mid:bg-brand, mid:text-brand
 *   --font-display: "Inter";  →  mid:font-display
 */
@theme {
}
```

"Design panel" in that comment is the "Styles" list of the Assets tab. [Theme and design tokens](https://midcode.app/docs/styling/theme.md) says what each control writes. In a Tailwind 4 project there is no `theme.css`: "Styles" edits the `@theme` in your own stylesheet.

### translations.json

Only for a site written in one language. Translations you make in the [Translations view](https://midcode.app/docs/data/languages.md) are kept by the site's own text until the languages are wired into the code:

```json title=".midcode/translations.json"
{
  "source": "en",
  "languages": ["es"],
  "texts": {
    "Built to outlast": {
      "es": "Hecho para durar"
    }
  }
}
```

A site that already has languages keeps its translations where it always did, and midcode edits them there.

### server.json (next release)

How the site runs, when you told midcode: a command, an address, or both. `$PORT` is the free port midcode picks.

```json title=".midcode/server.json"
{
  "command": "bin/rails server -b 127.0.0.1 -p $PORT",
  "url": "http://127.0.0.1:$PORT"
}
```

See [Any other stack](https://midcode.app/docs/frameworks/custom-server.md). Before you commit it, check that the command has nothing that's only true on your Mac. Don't add it to a project midcode starts by itself (Next.js, Vite, Astro, Nuxt, SvelteKit, React Router, Remix): with it, the site runs the project's own way, without marks, and is view-only.

### shopify.json (next release)

The store a [Shopify theme](https://midcode.app/docs/shopify/themes.md) is worked on with. No key or password is in it.

```json title=".midcode/shopify.json"
{
  "store": "your-store.myshopify.com"
}
```

### queries/ (next release)

Each query saved in the [SQL editor](https://midcode.app/docs/data/sql.md) is one file, `.midcode/queries/<name>.sql`, with the SQL as you typed it.

### README.md

A short note for whoever opens the folder, written with the first comment:

```md title=".midcode/README.md"
# .midcode

Written by midcode (the visual editor). Safe to commit or to ignore.

- `comments.json`: comments left on the site's preview. Each one is anchored to
  an element: `anchor.ref.mc` is where that element is written (`file:line:col`)
  and `anchor.ref.mci` is the component instance that rendered it, if any.
- `attachments/`: files attached to those comments, referenced by path.
```

In a project without Tailwind 4, midcode adds a "Styles" section that tells an agent how `mid:` classes work.

## midcode.css and its import

In a project without Tailwind 4, midcode writes styles as its own utilities (`mid:p-6`) and keeps their CSS in `midcode.css`. On your first style edit it creates the file and imports it where your app's stylesheets go:

| Project | Where `midcode.css` goes | Imported in |
| --- | --- | --- |
| Next.js | Next to the root layout | `app/layout.tsx` (or `pages/_app.tsx`) |
| React Router, Remix | Next to `root.tsx` | `app/root.tsx` |
| Vite | Next to the module `index.html` loads | That module, for example `src/main.tsx` |
| SvelteKit | `src/routes/` | `src/routes/+layout.svelte`, created if there is none |
| Astro | `src/` | The frontmatter of every layout in `src/layouts` (of every page, when there are none) |

```diff title="app/layout.tsx"
 import type { Metadata } from 'next'
 import './globals.css'
+import './midcode.css'
```

The import is one undoable edit. The stylesheet itself is rewritten whenever the `mid:` classes in your code change, so it's outside undo, and it shows in Publish as one entry: "Styles written by midcode (midcode.css)". Don't edit it by hand.

In the next release the same happens for plain HTML (a `<link>` in every page), Nuxt (`app.vue`), Shopify themes (`assets/midcode.css`, with its tag in `layout/theme.liquid`) and sites a server renders (a `<link>` in each layout). [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) covers all of them.

## The canvas page

In a Next.js App Router project, what you draw or drop [outside the breakpoints](https://midcode.app/docs/editor/free-canvas.md) is code too. It lives in one page:

```tsx title="app/midcode-scratch/page.tsx"
import { notFound } from 'next/navigation'

// What floats on midcode's canvas, outside the site's breakpoints. It only exists in development
// (a 404 on the live site), and midcode never publishes it.
export default function MidcodeCanvas() {
  if (process.env.NODE_ENV === 'production') notFound()
  return (
    <main data-midcode-scratch>
      <div data-midcode-item="8c21f0aa" data-midcode-at="1820 240" className="h-[200px] w-[320px] bg-white" />
    </main>
  )
}
```

The page is in `src/app/` when your project has that folder, and it's `page.jsx` in a project with no `tsconfig.json`. Each floating element carries its id and its place on the canvas. The page is left out of Publish, out of the list of changes and out of the page list. It isn't in `.gitignore`, on purpose: Tailwind doesn't scan ignored files, and the classes of what floats would never be generated.

## Components and media

- **Interactive components.** Inserting a carousel, a slideshow, a ticker, tabs, a cookie banner, a locale switcher or a shader gradient writes its source once to `components/midcode/` (`src/components/midcode/` when the project has a `src/` folder, `app/components/midcode/` in React Router and Remix). It's `.tsx` with a `tsconfig.json`, `.jsx` without. From then on the file is yours: midcode never writes over it. See [Insert](https://midcode.app/docs/editor/insert.md).
- **Images, video and audio.** A file you drop, paste or pick is copied to `public/images`, `public/videos` or `public/audio`. A replacement goes next to the file it replaces when that one is in `public/`; in Next.js, an image your code imports is replaced in place. Names are lowercased, a different file with the same name gets `-1`, `-2`, and the same file is never copied twice. SvelteKit uses `static/` instead of `public/`. See [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).
- **Stickers** are saved as `public/stickers/<set>-<name>.svg`.

## Files you ask for

These are created because a feature's job is to create them. Each feature's page has the details.

| Feature | File |
| --- | --- |
| A new [page](https://midcode.app/docs/editor/pages.md) (Next.js) | `app/<route>/page.tsx` |
| A new page in another framework (next release) | The file that framework expects: `src/pages/about.astro`, `src/routes/about/+page.svelte`, `about.html`, `content/about.md`. In React Router and Laravel, also a line in `app/routes.ts` or `routes/web.php`. [Pages and navigation](https://midcode.app/docs/editor/pages.md) has the list |
| Favicon and social image in [Site settings](https://midcode.app/docs/editor/site-settings.md) (Next.js) | `app/icon.<ext>` or `favicon.ico`, `opengraph-image.<ext>` |
| Favicon and social image outside Next.js (next release) | `favicon.<ext>` and `og-image.<ext>`, copied to the folder the site serves as it is (`public/` in most projects, `static/` in SvelteKit and Hugo, the site's root in plain HTML) |
| Metadata for a client page (Next.js) | A `layout.tsx` next to it |
| The rest of [Site settings](https://midcode.app/docs/editor/site-settings.md) outside Next.js (next release) | No new file: the title, description, language and indexing are tags in the `<head>` your site already writes (`index.html`, `src/app.html`, a layout) |
| "New collection" in the [CMS](https://midcode.app/docs/data/cms.md) | `content/<name>.ts`, or `src/content/<name>.ts` |
| "Create a database" (next release) | `data/database.db` |
| A [table change](https://midcode.app/docs/data/schema.md) (next release) | A `.sql` file in the project's migrations folder. With Prisma: an edit to `prisma/schema.prisma` and a folder in `prisma/migrations` |
| A value in [Environment variables](https://midcode.app/docs/data/env.md) (next release) | A line in `.env.local` or `.env` |

A migration file is the change in words, then its SQL:

```sql title="data/migrations/20261005183000_drop_posts_subtitle.sql"
-- Drop the column “subtitle” of the table “posts”

alter table "posts" drop column "subtitle";
```

## What stays out of your project

midcode keeps its own things in `~/Library/Application Support/midcode`, never in your repo: the list of changes waiting to be published, your recent projects and their thumbnails (from the next release, also how you grouped, pinned and ordered them on the hub), settings, the config wrappers it starts dev servers with, and anything secret. [Privacy and security](https://midcode.app/docs/reference/privacy.md) lists what's there.

## If you delete them

- `.midcode/`: comments, layer names and the page order are gone. Breakpoints go back to the three defaults; classes already written keep the prefixes they have. Without `theme.css`, the tokens and text styles you made stop producing CSS.
- `midcode.css`: styles made in midcode stop showing. It's built again with your next style edit, or with [the midcode package](https://midcode.app/docs/styling/package.md).
- `app/midcode-scratch/`: what floated on the canvas is gone. Nothing else changes.
- `components/midcode/`: the pages that import those components stop compiling.

To stop using midcode, keep `midcode.css` (or the package) if you used `mid:` classes, and delete `.midcode/` and `app/midcode-scratch/` if you like. Nothing else of the app is in your project.

---

# What works with what

> Every framework and stack midcode opens, how much of each you can edit on the canvas, and which parts ship with the next release.

- Page: https://midcode.app/docs/start/supported-stacks
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode opens any folder that holds a website. What changes from one stack to another is how much of the site it can link back to your code, and that decides how much you can edit by clicking.

There are three levels.

- **Marked while it runs.** midcode starts your dev server with a plugin of its own that tells every element where it's written. Everything on the canvas can be edited. This is React, Svelte, Vue, Astro and plain HTML. Laravel's Blade views and Shopify themes are marked as they're served too, each in its own way.
- **Found after it loads.** The site is rendered by a server midcode can't plug into (PHP, Django, Rails, a static site generator, Angular's build). midcode reads the loaded page and finds each element in your templates. What it finds is edited like any other; what it can't tell apart is left alone. See [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md).
- **View and comment.** The site runs and shows at every breakpoint. You can check it, play it and [leave comments](https://midcode.app/docs/editor/comments.md) for your agent, but not edit. This is what you get when midcode knows nothing about the stack, or when the project runs with its own command.

"Next" in the tables means it ships with the next release. In the version you can download today, those stacks open to view and comment when the folder has a `dev` script in its `package.json` or an `index.html`, and aren't opened otherwise, unless the table says otherwise.

## React

| Stack | Editing | Pages | Release |
| --- | --- | --- | --- |
| [Next.js](https://midcode.app/docs/frameworks/nextjs.md) | Everything, in `.tsx` and `.jsx` files | Read from `app/` and `pages/`. Add and remove | Released |
| [React with Vite](https://midcode.app/docs/frameworks/react-vite.md) | Everything, in `.tsx` and `.jsx` files. Also Preact and Solid; Qwik is next | Type a path. Qwik City: the folders of `src/routes`, add and remove (next) | Released |
| [React Router and Remix](https://midcode.app/docs/frameworks/react-router.md) | Everything, in `.tsx` and `.jsx` files | Read from `app/routes.ts` or the route files. Add and remove is next | Released |
| [TanStack Start](https://midcode.app/docs/frameworks/tanstack-start.md) | Everything, in `.tsx` and `.jsx` files | Read from the route files. Add and remove | Next (today: opens as React with Vite, with no pages listed) |
| [Create React App, Gatsby, Docusaurus, Rsbuild](https://midcode.app/docs/frameworks/webpack.md) | The project's own JSX, in `.js` files too | Gatsby: `src/pages`. The others: type a path | Next |

"Everything" is text, styles, attributes, images, inserting, moving, duplicating and deleting elements, components with their props, variants and states, and [variables](https://midcode.app/docs/editor/variables.md).

## Svelte, Vue, Astro, Angular

| Stack | Editing | Pages | Release |
| --- | --- | --- | --- |
| [Svelte and SvelteKit](https://midcode.app/docs/frameworks/svelte.md) | Text, styles, attributes, structure, component props, variants and states | SvelteKit: `src/routes`. Add and remove is next | Released |
| [Vue with Vite](https://midcode.app/docs/frameworks/vue.md) | Text, styles, attributes, structure, component props, variants and states | Type a path | Next |
| [Nuxt](https://midcode.app/docs/frameworks/nuxt.md) | Text, styles, attributes, structure, component props, variants and states | The files of `pages/`. Add and remove, once it has a `pages/` folder | Next |
| [Astro](https://midcode.app/docs/frameworks/astro.md) | `.astro` files: text, styles, attributes, structure, component props, variants and states. Islands as their own framework | `src/pages`. Add and remove | Next (today: its React, Preact and Solid islands only) |
| [Vue CLI](https://midcode.app/docs/frameworks/webpack.md) | The project's own `.vue` files | Type a path | Next |
| [Angular](https://midcode.app/docs/frameworks/angular.md) | Text, styles, attributes and structure in component templates, found after the page loads | The routes in `*.routes.ts` or a routing module | Next |

"Structure" is inserting, moving, duplicating and deleting elements. From the next release it also covers several selected elements at once (removed, wrapped in a stack or moved together) and `⌥`-drag, which leaves a copy. In these files a value the language computes (`{{ title }}`, `{title}`) shows on the canvas and is changed in the code.

## HTML and sites a server renders

| Stack | Editing | Pages | Release |
| --- | --- | --- | --- |
| [Plain HTML](https://midcode.app/docs/frameworks/html.md) | Text, styles, attributes, structure | Every `.html` file. Add and remove, at the top of the site | Next |
| [Laravel](https://midcode.app/docs/frameworks/laravel.md) | Blade views; Inertia pages as React or Vue; Livewire views | The GET routes of `routes/web.php`. Add and remove | Next (today: only with Vite, shown at a `localhost` address, not edited) |
| [WordPress](https://midcode.app/docs/frameworks/wordpress.md) | A classic theme's templates. A block theme has little to edit | Type a path | Next |
| [PHP and Twig](https://midcode.app/docs/frameworks/php.md) | What's written in the templates | Type a path | Next |
| [Django, Flask and FastAPI](https://midcode.app/docs/frameworks/python.md) | What's written in the templates | Django: `urls.py`. Flask: the `@app.route` lines. FastAPI: type a path | Next |
| [Ruby on Rails](https://midcode.app/docs/frameworks/rails.md) | What's written in the views | Read from `config/routes.rb` | Next |
| [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md) | Templates. In Markdown content, the words of headings, paragraphs and list items | The content files. Add and remove | Next |
| [Shopify themes](https://midcode.app/docs/shopify/themes.md) | Liquid, section settings, the store behind the theme | The theme's templates, with the store's products and collections | Next |

In these stacks, what the server fills in (a post's body from the database, a product's title, the output of a helper) is on the page but not in a template: it can't be edited from the canvas.

A stack that isn't in any table still opens. [Any other stack](https://midcode.app/docs/frameworks/custom-server.md) lists what midcode recognises by its files, and how to tell it the command that runs your site. A site inside a bigger repository is found too: see [Monorepos](https://midcode.app/docs/frameworks/monorepos.md).

## Features by kind of project

| | Next.js | Other React | Svelte, Vue, Astro | HTML and server templates |
| --- | --- | --- | --- | --- |
| Text, styles, attributes, media | Yes | Yes | Yes | Yes |
| Insert, move, duplicate, delete | Yes | Yes | Yes | Yes |
| [Insert](https://midcode.app/docs/editor/insert.md)'s interactive components | Yes | Yes | No: they're React | No |
| Component props in the panel | Yes | Yes | Yes | No |
| [Variants, states](https://midcode.app/docs/editor/components.md), [variables](https://midcode.app/docs/editor/variables.md) | Yes | Yes | Variants and states (Vue and Astro: next). Variables (next) | No |
| [Free canvas](https://midcode.app/docs/editor/free-canvas.md) | Yes (Pages Router: next) | Vite + React, Preact or Solid (next) | Plain elements, not in Nuxt (next) | Plain elements in a folder of HTML (next) |
| [Add and remove pages](https://midcode.app/docs/editor/pages.md) | Yes (new pages in the App Router) | React Router, Remix, TanStack Router, Qwik City (next) | SvelteKit, Nuxt, Astro (next) | HTML, Hugo, Jekyll, Eleventy, Laravel (next) |
| [Site settings](https://midcode.app/docs/editor/site-settings.md) | Yes (App Router) | With an `index.html` (Vite, Create React App), and Docusaurus (next) | SvelteKit, Vue, Nuxt, Astro, Angular (next) | In the page's or the layout's `<head>`; not WordPress or Shopify themes (next) |
| [CMS](https://midcode.app/docs/data/cms.md), [Languages](https://midcode.app/docs/data/languages.md) | Yes | Yes | Lists in `.ts`, JSON and Markdown files | JSON and Markdown files |
| [Database](https://midcode.app/docs/data/database.md) (next) | Yes | Yes | Yes | Yes |
| [Agent](https://midcode.app/docs/agents/overview.md), [Code](https://midcode.app/docs/editor/code.md), [Comments](https://midcode.app/docs/editor/comments.md), [Publish](https://midcode.app/docs/publish/publish.md) | Yes | Yes | Yes | Yes |

## Styles

How styles are written depends on one thing: whether the project uses Tailwind 4.

| Project | The panel writes | More |
| --- | --- | --- |
| Tailwind 4 | Tailwind's own classes, swapping only the one that changes | [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md) |
| Anything else: plain CSS, CSS modules, Bootstrap, Tailwind 3 | midcode's `mid:` utilities, compiled to a `midcode.css` in your project | [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) |

## What midcode doesn't open

- A site that isn't code on your Mac: a Webflow, Framer, Wix or Squarespace site, or a WordPress site you only reach through its admin.
- Native apps (React Native, Swift, Flutter). midcode shows web pages.
- A Next.js or Vite project that writes JSX in `.js` files opens, but its elements aren't marked: rename the files to `.jsx`.
- Parcel and Nuxt 2 projects open to view and comment only.

midcode itself runs on macOS only.

## If you're not sure

Open the folder. Nothing is added to a project by opening it, and the right panel says what you got: a file and a line when you click an element, or "preview and comments" when the site has no marks. If the project doesn't start, [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md) has the usual reasons.

---

# The canvas and breakpoints

> The canvas shows your running site at every breakpoint, side by side. How to move around it, how a breakpoint becomes a Tailwind screen, and what an override writes.

- Page: https://midcode.app/docs/editor/canvas
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

The canvas is the middle of the window: your site, running, once per breakpoint. Each frame is a real page of your dev server at that width, so what you see is what your code does. You pan and zoom over all of them like a design file.

A change made in one frame is written for that breakpoint. That's the whole model: one breakpoint is the rule, the others take overrides, and both end up as ordinary responsive classes in your code.

## What a frame is

Each frame loads the page that's open (see [Pages and navigation](https://midcode.app/docs/editor/pages.md)) from your dev server, at its breakpoint's width. On the canvas the page is in design mode:

- A click selects an element. It doesn't follow links, press buttons or submit forms. To use the site, open the [Preview](#preview).
- The frame is as tall as the whole page, so every section is on the canvas at once and the page itself never scrolls. Scrolling moves the canvas.
- Viewport units (`vh`, `svh`, `dvh`, `lvh`) mean the breakpoint's device height, not the frame's: a `min-h-screen` hero stays one screen tall. The device height is 900 px for a width of 1024 or more, 1024 px from 600, and 844 px below that.
- Motion rests while you design. Looping animations and videos are paused, and one-shot animations are shown finished, so a title that fades in is visible instead of stuck at zero opacity.
- Embeds (a YouTube player, a map, an audio player) can be hovered and selected like any other element.

Over the bottom of the canvas floats the toolbar: "Insert" (the +, see [Insert](https://midcode.app/docs/editor/insert.md)), "Inspect" (`V`), "Comment" (`C`, see [Comments](https://midcode.app/docs/editor/comments.md)) and "Preview" (`P`). Next.js App Router projects also have "Frame: draw one on the canvas" (`F`), for [the free canvas](https://midcode.app/docs/editor/free-canvas.md).

## Move around

| To | Do this |
| --- | --- |
| Pan | Scroll with two fingers or the wheel, anywhere, also over a frame. |
| Pan by dragging | Hold `Space` and drag. Or drag the empty canvas with the middle mouse button. |
| Zoom | Pinch, or hold `⌘` and scroll. It zooms on the pointer. |
| Zoom in, zoom out | `⌘=` and `⌘-` |
| Zoom to fit every frame | `⌘1`, `⇧1`, or click the percentage in the top bar. |
| Actual size (100%) | `⌘0` |
| Fit the first frame | `⇧2` |

The zoom goes from 5% to 400%. Right-click the empty canvas for the same commands as a menu: "Preview", "Zoom to fit", "Actual size", "Paste", "Show rulers" / "Hide rulers", "Reload breakpoints" and "Deselect".

Double-click a breakpoint's row in [Layers](https://midcode.app/docs/editor/layers.md) to bring that frame into view.

## Breakpoints

A project starts with three, until you change them:

| Breakpoint | Width | Tailwind screen |
| --- | --- | --- |
| Desktop | 1440 | `lg` |
| Tablet | 768 | `md` |
| Phone | 390 | none (no prefix) |

They sit on the canvas from the widest to the narrowest. Above each frame is its bar:

- The play button opens that breakpoint in the [Preview](#preview). So does a double-click on the bar.
- The name and width open "Edit breakpoint".
- "Primary" marks the primary breakpoint.
- A third number, like `× 5230`, is the page's height when it's taller than the device.
- The + on the first bar is "New breakpoint".

Right-click a bar for all of it: "Preview Desktop", "Edit breakpoint…", "Make primary", "New breakpoint…" and "Remove breakpoint".

### Add, edit and remove

1. Click the + on the first bar, or right-click any bar and choose "New breakpoint…".
2. Type a name and a width in px (240 to 3840). The name is optional: without one, the breakpoint is called by its width.
3. Click "Add".

A new frame appears at that width, in its place by size. Two breakpoints can't have the same width.

"Edit breakpoint…" changes the name or the width. A new width also gives the frame the device height that goes with it, and a new screen if the old one no longer fits. "Remove breakpoint" takes the frame away; the last breakpoint can't be removed. Removing the primary makes the widest one primary.

> [!NOTE]
> Adding, editing or removing a breakpoint changes `.midcode/breakpoints.json` and nothing else. Classes already in your code are not rewritten.

### The primary breakpoint and overrides

One breakpoint is the primary: Desktop, until you choose another with "Make primary". The rule is the one Framer uses:

- A change made in the primary frame applies to every breakpoint that doesn't say otherwise.
- A change made in any other frame is an override for that breakpoint. It also carries on to the breakpoints further from the primary that were showing the same value: override a size on Tablet and Phone follows, until Phone gets a value of its own.

Which breakpoint you're editing is the frame you selected the element in. The right panel says so in its "Breakpoint" row, where you can also switch, and picking a layer under a breakpoint in [Layers](https://midcode.app/docs/editor/layers.md) selects it there.

In a breakpoint that isn't the primary, the panel reads "Changes here override Desktop. Overridden properties show in blue." A property with an override has a blue label. Hover it to see what it overrides, and right-click it for "Remove override": the breakpoint follows its neighbour toward the primary again.

### How a breakpoint becomes a Tailwind screen

Overrides are written as Tailwind's responsive prefixes, mobile first. So each breakpoint needs a screen, and midcode picks it:

- The narrowest breakpoint writes with no prefix.
- Every other breakpoint gets a screen that starts above the next narrower breakpoint's width and no later than its own. That keeps each frame in its own range, so an override never leaks into its neighbour.
- A named screen is used when one fits (`sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536). If none fits, midcode writes an exact one in rem: a breakpoint at 1000 px gets `min-[62.5rem]`.

Screens are worked out again whenever the list changes. Add a "Laptop" at 1200 to the defaults and it takes `lg`, which moves Desktop to `xl`:

| Breakpoint | Width | Screen before | Screen after |
| --- | --- | --- | --- |
| Desktop | 1440 | `lg` | `xl` |
| Laptop | 1200 | | `lg` |
| Tablet | 768 | `md` | `md` |
| Phone | 390 | none | none |

In a project without Tailwind 4 the same prefixes go after midcode's own: `mid:md:text-4xl`. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## What midcode writes

The value at each breakpoint becomes one class at that breakpoint's screen, from the narrowest up. Neighbours with the same value share a class. Here is one heading through four edits of its font size, with the default breakpoints and Desktop as primary:

| You do | The heading's classes after |
| --- | --- |
| Set 5xl in Desktop | `font-semibold text-5xl` |
| Set 4xl in Tablet | `font-semibold text-4xl lg:text-5xl` |
| Set 3xl in Phone | `font-semibold text-3xl lg:text-5xl md:text-4xl` |
| "Remove override" in Tablet | `font-semibold text-3xl md:text-5xl` |

The second row shows the carry-on: the Tablet override reached Phone too, so the unprefixed class is the Tablet value and Desktop keeps its own behind `lg:`. As a diff:

```diff title="src/app/page.tsx"
-<h1 className="font-semibold text-5xl">Design in code</h1>
+<h1 className="font-semibold text-4xl lg:text-5xl">Design in code</h1>
```

A class that changes is swapped where it stands, and new ones go at the end of the list. The order of classes in the attribute doesn't change what the browser shows.

When a narrower breakpoint has a value and a wider one has none, the wider one gets the value that means "nothing". Padding given to a stack on Phone only:

```diff title="src/components/Card.tsx"
-<div className="flex">
+<div className="flex p-4 md:p-0">
```

Every style edit goes through this, from the [style panel](https://midcode.app/docs/editor/styles.md) to a resize handle. [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md) has the rest: arbitrary values, your theme's tokens, and classes built with `cn()`.

### .midcode/breakpoints.json

Your breakpoints are saved in the project the first time you change them. Until then the file doesn't exist and the defaults apply. This is the file after adding the Laptop breakpoint above:

```json title=".midcode/breakpoints.json"
{
  "version": 1,
  "list": [
    {
      "id": "desktop",
      "label": "Desktop",
      "width": 1440,
      "height": 900,
      "screen": "xl"
    },
    {
      "id": "laptop-1200",
      "label": "Laptop",
      "width": 1200,
      "height": 900,
      "screen": "lg"
    },
    {
      "id": "tablet",
      "label": "Tablet",
      "width": 768,
      "height": 1024,
      "screen": "md"
    },
    {
      "id": "phone",
      "label": "Phone",
      "width": 390,
      "height": 844,
      "screen": ""
    }
  ],
  "primary": "desktop"
}
```

- `height` is the device height that viewport units mean in that frame.
- `screen` is the prefix its overrides are written with. Write your own (`"screen": "xl"`) and midcode keeps it as long as it fits the rule above. One that doesn't fit is ignored, and replaced the next time midcode saves the file.
- `primary` is the `id` of the primary breakpoint.

Commit the file so everyone who opens the project gets the same frames. Delete it to go back to the defaults. [What midcode adds to your project](https://midcode.app/docs/start/project-files.md) lists every file of this kind.

## Preview

The canvas never runs the site. The Preview does: one breakpoint, full size, scrolling and taking clicks like a browser, with its animations, menus and videos.

1. Press `P`, or click "Preview" in the toolbar. That opens the primary breakpoint. The play button on a breakpoint's bar opens that one.
2. Use the site.
3. Press `Esc`, or click "Back", to return to the canvas. `P` closes it too until you click into the site: from then on the site has the keyboard and `P` is its key.

The bar over the preview has "Reload", "Hide UI (full screen)", a menu to switch breakpoint, and the width and height, which you can type. Drag either side of the frame to try any width: the breakpoint then reads "Custom". With the interface hidden, "Show UI" in the corner (or `Esc`) brings it back. A frame too big for the window is scaled down, and the scale is shown under it.

Nothing is edited in the Preview. Opened from a component, it shows that component alone: see [Components](https://midcode.app/docs/editor/components.md).

## Reload

Your dev server's hot reload brings each edit into every frame without loading the page again. When a frame gets stuck anyway, click "Reload breakpoints" in the top bar (the circular arrow), or right-click the empty canvas and choose it. Every frame loads the page again.

## The top bar

- Left: the project's name, its branch, and the page that's open. See [Pages and navigation](https://midcode.app/docs/editor/pages.md) and [Publish](https://midcode.app/docs/publish/publish.md).
- Middle: "Design" and "Code", two ways into the same project. "Code" swaps the canvas for your files, an editor and a terminal: see [Code view](https://midcode.app/docs/editor/code.md).
- Right: the dev server's log ([Open a project](https://midcode.app/docs/start/open-a-project.md)), the site's languages ([Languages](https://midcode.app/docs/data/languages.md)), "CMS" ([CMS](https://midcode.app/docs/data/cms.md)), "Site settings" in the projects that have them ([Site settings](https://midcode.app/docs/editor/site-settings.md) says which), "Reload breakpoints", the zoom, and "Publish".

"Reload breakpoints" and the zoom belong to the canvas. They're hidden in the Code view.

### CMS, Database and Store in the middle (next release)

In the next release the middle of the bar lists every place of a project: "Design", "Code", "CMS", "Database" and, in a Shopify theme, "Store". [CMS](https://midcode.app/docs/data/cms.md), [Database](https://midcode.app/docs/data/database.md) and [Store](https://midcode.app/docs/shopify/store.md) open over the canvas, which stays loaded underneath, and "Reload breakpoints" and the zoom show only while the canvas itself is on screen. In version 1.1.2, CMS is a button on the right of the bar and the other two don't exist.

## Limits

- A breakpoint is a width. There are no height breakpoints, and midcode doesn't write screens that end at a width (`max-md:`). A class in your code with a prefix it doesn't know is left where it is: the panel doesn't read it and never rewrites it.
- A frame grows to 40,000 px. A page taller than that is cut off on the canvas.
- The canvas shows one page at a time, the same in every frame.
- Text styles and link styles from your theme can't be overridden per breakpoint: they're always written for every breakpoint.

---

# Select, move and resize

> Select elements on the canvas, move, copy and resize them by hand, and line them up with snapping, rulers and guides. With the code each gesture writes.

- Page: https://midcode.app/docs/editor/select-move-resize
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Everything you do to an element on the canvas with the pointer is an edit of the file it's written in: a drag moves its lines, a handle changes a class, a nudge changes two. This page covers those gestures with the "Inspect" tool (`V`), which is the tool you're in unless you picked another.

## Select

Move the pointer over a frame and the element under it gets an outline. Click to select it. The selection shows a label with its tag (or its component's name), and its parent is outlined with a dashed line.

The right panel now shows the element. Its "Code" section says where it's written:

- "Element": the file and line of the element itself. Click it to copy `file:line:col`; the icon beside it is "Open code".
- "Instance": where the component that renders it is used, when it belongs to one.
- "Inside": the nearest ancestors written in other files.

What you can select is what your code writes. An element drawn by a library (a chart's internals, the markup of a UI kit) isn't in your files, so a click on it selects the nearest element around it that is. When nothing around it is, the panel says so: "A library draws this element: it isn't in your project's files, so there's nothing to edit here." You get the same message for JSX written in a plain `.js` file in a Next.js or Vite project: midcode marks `.tsx` and `.jsx` files there, so rename the file to `.jsx`. An SVG selects as a whole.

An element rendered by a loop is one line of code shown several times. The panel says "Item 3 of a list: editing the code changes all of them."

| To | Do this |
| --- | --- |
| Select the parent | `⌘` + click inside the selection: one level up each time. Or `⌘↑`. |
| Select from the tree | Click a layer in [Layers](https://midcode.app/docs/editor/layers.md). |
| Deselect | `Esc`, or click the empty canvas. |
| Edit a text | Double-click it. See [Text, images and video](https://midcode.app/docs/editor/text-and-media.md). |
| Open a component | Double-click one of its instances. See [Components](https://midcode.app/docs/editor/components.md). |

The same element is outlined in every frame. The frame you clicked in is the breakpoint you're editing: see [Breakpoints](https://midcode.app/docs/editor/canvas.md).

### Select several

Hold `⇧` and click another element, on the canvas or in Layers, to add it to the selection. `⇧` + click on one that's already in takes it out. `⌘A` adds every sibling of the selection.

The others are outlined without handles, and they're let go when you select something else. While several are selected:

- On a page, the style panel writes to all of them. It's one edit, so one `⌘Z` undoes it everywhere.
- Dragging one moves them all, if they sit next to each other in the same container.
- `⌫` deletes them, `⌘C` / `⌘X` / `⌘D` copy, cut and duplicate them, and `⇧A` wraps them in a stack.
- A right-click on any of them opens a menu for all: "Copy", "Cut", "Duplicate", "Delete", "Wrap in a stack" and "Copy references for your agent".

To be moved, wrapped, duplicated or deleted together, they have to be written in the same file. Otherwise midcode says "These elements are written in different files."

## Move

### Drag to another place

Press on an element and drag. It fades, and a blue line shows where it would land: before or after the element under the pointer, or between the children of the container under it. Over an empty container, the container is outlined instead and the element goes inside. Release to move it. `Esc` cancels.

Pressing inside the selection drags the selection. Pressing anywhere else drags (and selects) what's under the pointer.

You can also drag a row in [Layers](https://midcode.app/docs/editor/layers.md), which is easier when the target is small or covered.

What moves is the element's code: its lines are cut and written at the new place, with the JSX comment right above it if it has one.

```diff title="src/components/Nav.tsx"
 <ul className="flex gap-6">
-  <li>Docs</li>
   <li>Pricing</li>
+  <li>Docs</li>
 </ul>
```

A component's root moves where the component is used: drag a whole `<Hero />` section and the line that moves is the instance in the page's file.

### Moves that are refused

- **To another file.** An element moves within the file it's written in: "For now elements move within the same file (page.tsx)." The exception is [the free canvas](https://midcode.app/docs/editor/free-canvas.md), where things go in and out of pages with their imports.
- **Out of a list.** An item written inside a `.map()` uses values that exist only there, so it stays in its loop and nothing else goes into it: "This element uses values from where it's written (a list, a loop). Move it in the code."
- **Into a component instance.** `<Card />` has no place in this file to put children in: "Can't put elements inside a component instance." Open the component to edit its inside.
- **Into itself.**

### Positioned elements

An element positioned with left and top ("Position" → "Type" → "Absolute" or "Fixed" in the right panel, and no right, bottom or inset class) isn't in the flow, so dragging it doesn't reorder anything. It moves freely, a label shows its new left and top, and on release the two classes are written:

```diff
-<span className="absolute left-6 top-10 rounded-full">New</span>
+<span className="absolute left-30 top-16 rounded-full">New</span>
```

Hold `⇧` to move along one axis. It [snaps](#snapping) to its container and its siblings.

### Arrow keys

With a positioned element selected, the arrow keys move it 1 px. With `⇧` they move it by the nudge amount, 10 px unless you changed "Nudge amount" in Settings (`⌘,`). The element moves at once, and the classes are written when the keys rest, so a run of presses is one edit:

```diff
-<span className="absolute left-30 top-16 rounded-full">New</span>
+<span className="absolute left-[121px] top-16 rounded-full">New</span>
```

A value that's a multiple of half your spacing unit (2 px, with Tailwind's default of 4) is written as a scale number: `left-30` is 120 px. Anything else is written exactly, in brackets.

Arrow keys do nothing to an element in the flow: there, order is the position. They also move what floats on [the free canvas](https://midcode.app/docs/editor/free-canvas.md).

## Copy

| To | Do this |
| --- | --- |
| Duplicate in place | `⌘D`. The copy is written right after the element. |
| Copy by dragging | Hold `⌥` while you drag. The element stays where it is and a copy lands where you release. |
| Copy and paste | `⌘C`, select another element, `⌘V`. The copy goes after the selection ("Paste after"). |
| Cut | `⌘X`: a copy, then a delete. |
| Copy only the styles | `⌥⌘C` on one element, `⌥⌘V` on another. |

In JSX files a copy made by dragging can land in another file, unlike a move: it takes along the imports it uses. A paste writes the copied code as it is, so pasting an element that uses a component into a file that doesn't import it is refused: midcode says pasting there needs `<Card>`, which the file doesn't import.

`⌘C` on one element does two things. midcode keeps the element's code for `⌘V`, and the system clipboard gets the element's reference, ready to paste to an agent:

```text
<h1> "Design in code"
written at src/components/Hero.tsx:8:7
inside src/app/page.tsx:9:5
page / · Desktop 1440px
```

`⇧⌘C` ("Copy Reference" in the Element menu) copies the reference alone. With several elements selected, `⌘C` puts their code on the system clipboard instead.

"Paste styles" replaces the target's whole class list with the copied one. It's meant for two elements of the same kind.

In a Next.js App Router project, `⌘V` with nothing selected puts the copy on the free canvas, in the middle of what's in view. In other projects, select the element the copy should go after first.

`⌘V` checks the system clipboard first: with an image or files on it, it pastes those. See [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).

## Wrap in a stack

Select one or more siblings and press `⇧A`. A new `<div>` is written where the first one was, with all of them inside in their order. It runs the way their parent lays them out, with the parent's gap, so nothing moves on screen: a row inside a row, a column anywhere else. The new stack is selected.

```diff title="src/components/Pricing.tsx"
 <section className="flex flex-col gap-6">
   <h2>Pricing</h2>
-  <p>One payment, every update.</p>
-  <a href="/buy">Buy</a>
+  <div className="flex flex-col gap-6">
+    <p>One payment, every update.</p>
+    <a href="/buy">Buy</a>
+  </div>
 </section>
```

The elements have to sit next to each other in the same container: "Select elements that sit next to each other, in the same container."

## Resize

Handles show on the sides whose size is "Fixed":

- Width fixed: handles on the left and right.
- Height fixed: handles on the top and bottom.
- Both: the corners too.

An element with no handles takes its size from its content or its container ("Fit", "Fill", "Relative"). To size it by hand, set "Width" or "Height" to "Fixed" in the "Size" section of the right panel first. [The style panel](https://midcode.app/docs/editor/styles.md) explains the modes.

Drag a handle. The element takes the size as you drag and a label shows it in px. Hold `⇧` on a corner to keep the proportions. On release the size is written:

```diff
-<img className="w-80 rounded-xl" src="/images/team.jpg" alt="The team" />
+<img className="w-90 rounded-xl" src="/images/team.jpg" alt="The team" />
```

In the primary breakpoint that's the size everywhere. In another frame it's an override for that breakpoint. The same image, resized to 280 px in the Phone frame instead:

```diff
-<img className="w-80 rounded-xl" src="/images/team.jpg" alt="The team" />
+<img className="w-70 rounded-xl md:w-80" src="/images/team.jpg" alt="The team" />
```

## Snapping

A positioned element being moved lines up with what's around it:

- its edges and its center with the edges and centers of its siblings and of the container it's positioned in;
- the same distance from a neighbour as its neighbours keep between themselves.

It snaps within 6 px on screen. A line shows what it lined up with, and a number shows the distance to the neighbour on each side.

| Key | While dragging |
| --- | --- |
| `⌘` or `⌃` | No snapping: it moves freely. Press it once the drag has started. |
| `⇧` | Moves along one axis only. |

Elements floating on [the free canvas](https://midcode.app/docs/editor/free-canvas.md) snap the same way, to each other, to the breakpoints' frames and to guides, also while you resize them.

## Rulers and guides

Rulers run along the top and left of the canvas, in canvas px. `R` hides and shows them (`⇧R` does too).

1. Drag down from the top ruler for a horizontal guide, or right from the left ruler for a vertical one.
2. Drag a guide to move it. It snaps to the edges and centers of the breakpoints and of what floats on the canvas.
3. To remove one: drag it back onto its ruler, or click it and press `⌫`, or right-click it and choose "Remove guide". "Remove all guides" is in that menu and in the canvas's.

What floats on the free canvas snaps to guides. Elements inside a page don't.

Guides are yours: they're kept per project on this Mac, in midcode's own settings, and never written into the project. With the rulers hidden, guides are hidden too and nothing snaps to them. Rulers aren't shown while you edit a component.

## Right-click menus

Right-click an element, on the canvas or in Layers. It's selected, and the menu offers:

| Item | Key | What it does |
| --- | --- | --- |
| "Edit component" | | On an instance: opens its component. See [Components](https://midcode.app/docs/editor/components.md). |
| "Copy reference for your agent" | `⇧⌘C` | The text shown under [Copy](#copy). |
| "Comment" | | Starts a comment on the element. See [Comments](https://midcode.app/docs/editor/comments.md). |
| "Copy", "Cut", "Paste after" | `⌘C` `⌘X` `⌘V` | |
| "Copy styles", "Paste styles" | `⌥⌘C` `⌥⌘V` | |
| "Duplicate" | `⌘D` | |
| "Wrap in a stack" | `⇧A` | |
| "Hide" / "Show" | `⌘;` | Adds or removes the `hidden` class, for every breakpoint. |
| "Delete" | `⌫` | Removes the element's code. |
| "Rename", "Auto rename" | `⌘R` `⌥⌘R` | Names the layer. See [Layers](https://midcode.app/docs/editor/layers.md). |
| "Select parent" | `⌘↑` | |
| "Open code" | | Opens the file at the element's line. See [Code view](https://midcode.app/docs/editor/code.md). |

The same commands are in the "Edit" and "Element" menus of the menu bar. A right-click on the empty canvas, on a breakpoint's bar, on a guide or on a blue label in the panel opens that thing's own menu: see [The canvas and breakpoints](https://midcode.app/docs/editor/canvas.md).

Each command that changes your code is one edit: `⌘Z` undoes it and `⇧⌘Z` redoes it. [How midcode works](https://midcode.app/docs/start/how-it-works.md) covers the history.

## Padding, gap and radius by hand (next release)

With the pointer over the selection, three kinds of handles appear inside it:

- a blue bar in each side's padding;
- a pink bar in each space between its children, when it's a stack or a grid;
- a dot in from each corner, for the radius.

Drag one. The element shows the value as you drag, with the number in px by the pointer, and the class is written on release. Hovering a padding or a gap bar tints the areas it controls.

| Handle | Plain drag | With `⌥` | With `⌥⇧` |
| --- | --- | --- | --- |
| Padding | That side: `pt-10` | That side and the opposite one: `py-10` | All four sides: `px-10 py-10` |
| Gap | `gap-6` | | |
| Radius | Every corner: `rounded-2xl` | That corner only: `rounded-tl-2xl` | |

Starting from a card with `gap-4`, `rounded-lg` and `p-6`, and dragging the gap to 24 px, the top padding to 40 px and a corner to 16 px:

```diff
-<div className="flex gap-4 rounded-lg p-6">
+<div className="flex gap-6 rounded-2xl p-6 pt-10">
```

They're written like the panel writes them: for the breakpoint of the frame you're in, as a scale number when the value allows it, and with your theme's radius names when one matches. A radius of 0 is `rounded-none`. When a pair or all sides are set together, the single-side classes they replace are removed.

A handle is left out when there's nothing for it to show:

- No padding bars on images, videos, inputs and other elements that hold no content, or on an element with no children and no padding.
- No gap bars when the space between children isn't the gap's (`justify-between` and the like), when the element sets its two gaps apart (`gap-x-4`), or when it's rotated.
- No radius dots on an element with nothing a radius would show on: no fill, border, shadow or clipping.
- None at all when the element is small on screen (under about 40 px, 48 for the radius), with several elements selected, or in a project midcode can't write styles in.

## Limits

- Moving, wrapping and deleting several elements at once work in JSX files. In Svelte, Vue, Astro and HTML files and in server templates they arrive in the next release; in version 1.1.2 midcode says so instead. Duplicating several at once stays JSX only: in other files the next release answers "These elements are written in different files." even when they share one.
- `⌥` + drag copies in JSX files. In other files it arrives in the next release, for a copy that lands beside or inside an element of the same file.
- From the next release, headings, paragraphs and list items that come from a Markdown file (Hugo, Jekyll, Eleventy) can be selected, edited as text and deleted. They can't be moved, copied, wrapped or styled: "This is written in Markdown: its words can be changed here, not its classes or attributes. Style it from the template around it."
- `⌥` + drag doesn't copy an element positioned with left and top. Duplicate it with `⌘D` and move the copy.
- Snapping and arrow keys apply to positioned elements and to the free canvas. An element in the flow is placed by its order and its container's layout.
- Resize handles change `w-*` and `h-*`. Minimum and maximum sizes are set in [the style panel](https://midcode.app/docs/editor/styles.md).
- In a project that midcode can only show (see [Open a project](https://midcode.app/docs/start/open-a-project.md)), you can select elements and comment on them, but nothing here writes.

---

# Layers

> The Layers tab lists the page's elements under each breakpoint, then what floats on the canvas. Select, reorder and rename layers, and see where names are kept.

- Page: https://midcode.app/docs/editor/layers
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Layers is the page as a tree: every element your code writes, nested the way it's nested in the page. It's the middle tab of the left panel, next to "Agent" and "Assets". Use it to select what's hard to click on the canvas, to move elements by dragging rows, and to give layers names that mean something.

## How the list is grouped

On a page, the list has two parts:

1. **Each breakpoint**, widest first, with a device icon, its name, and its width (or "Primary" on the primary one). The primary breakpoint starts open and the others closed. Under each one are the page's layers.
2. **What floats on the canvas**, after the last breakpoint, in Next.js App Router projects. Each floating element is a top-level row with its own layers inside. See [The free canvas](https://midcode.app/docs/editor/free-canvas.md).

The page's layers are the same tree under every breakpoint, because it's the same code. What changes is where a click lands: pick a layer under "Phone" and it's selected in the Phone frame, so what you change is written for that breakpoint. See [Breakpoints](https://midcode.app/docs/editor/canvas.md).

Click a breakpoint's row to mark its frame; double-click it to bring that frame into view.

While you edit a component, the list is the component's own layers, with no breakpoints over them. See [Components](https://midcode.app/docs/editor/components.md).

## What a row shows

A layer is an element written in your project's files. An element a library draws isn't listed; what your code puts inside it is, one level up.

| Icon | Layer |
| --- | --- |
| Component mark, in purple | The root of a component instance. The row shows the component's name. React and Svelte components; from the next release, Vue and Astro components too. |
| Rows, columns or a grid | A container, by how it lays out its children: a vertical stack, a horizontal stack, or a grid. |
| Heading | `h1` to `h6`, with the tag in a small badge. |
| Image | `img`, `picture`, `video` |
| Pen | `svg` |
| Link | `a` |
| Text | A paragraph, a span, a button or a list item with text of its own. |
| Square | Anything else. |

The name is, in this order: the name you gave it, the component's name, the element's own text (the first words), an image's alt text or file name, or the tag.

A layer hidden with "Hide" (`⌘;`) is dimmed. An element rendered by a loop has one row per item it renders; they are all the same line of code.

The list and the canvas follow each other. Hover a row and the element is outlined in the frames. Hover an element and its row lights up. Select on the canvas and the tree opens down to that layer and scrolls to it.

## Select from Layers

| To | Do this |
| --- | --- |
| Select a layer | Click its row. |
| Add to the selection, or take out of it | `⇧` + click. |
| Open or close a layer | Click the arrow at its left. |
| Open the element's menu | Right-click the row. The layer is selected first. |
| Rename | Double-click the row. |

What you can do with several layers selected is in [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md).

## Drag to reorder

Press on a row and drag it over the list. A blue line shows where the layer would go, indented to the depth it would have:

- Over the top part of a row: before that layer.
- Over the bottom part: after it. If that layer is an open container, it becomes the container's first child.
- Over the middle of a container: inside it, as its last child. The container's row is outlined.

Release to move it. `Esc` cancels. A layer can't go inside itself.

Containers are `div`, `section`, `main`, `article`, `header`, `footer`, `nav`, `aside`, `form`, `figure`, `ul`, `ol`, `li`, `fieldset`, `details` and `dialog`. A component instance isn't one: open the component to change what's inside it.

A drag in Layers is the same edit as a drag on the canvas: the element's code moves, with the comment above it.

```diff title="src/app/page.tsx"
 <main>
   <Hero />
-  <Features />
   <Pricing />
+  <Features />
   <Footer />
 </main>
```

The same rules apply: within one file, never out of a `.map()`, never into an instance. They're listed in [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md). The floating part of the list is the exception to the first rule: a floating layer can be dragged into the page, and a page's layer into a floating container. Beside a floating element, at the top level, only another floating element can go.

## Rename a layer

1. Double-click a row. Or select the layer and press `⌘R`, or right-click it and choose "Rename".
2. Type a name.
3. Press `Enter`. `Esc` leaves it as it was.

Clear the name and press `Enter` to go back to the default.

A name is a label for you and for your agent. It changes nothing in the element's code. The right panel's title and the reference you copy for an agent (`⌘C`, or `⇧⌘C` for the reference alone) use it too.

### Name layers with Apple Intelligence

The colored mark at the top right of the list is "Name layers". It names the layers a tag says nothing about: containers and media that have no name yet, up to 120 at a time. "Auto rename" (`⌥⌘R`, or the element's menu) names one layer.

The model runs on your Mac. Nothing is sent anywhere and it costs nothing. What it's given for each layer is a description: its tag, a few of its classes, its text, what's inside it and the heading of the section it's in.

It needs macOS 26 or later on Apple silicon, with Apple Intelligence turned on in System Settings. Without it the button is disabled and says why.

## What midcode writes

Names are kept in the project, in `.midcode/layers.json`, so they travel with the repository and an agent working there can read them.

```json title=".midcode/layers.json"
{
  "version": 1,
  "names": [
    {
      "file": "src/app/page.tsx",
      "tag": "section",
      "classes": "mx-auto max-w-6xl px-6 py-24",
      "text": "",
      "loc": "src/app/page.tsx:14:7",
      "name": "Pricing"
    },
    {
      "file": "src/components/Hero.tsx",
      "tag": "h1",
      "classes": "text-5xl font-semibold tracking-tight",
      "text": "Design in code",
      "loc": "src/components/Hero.tsx:8:7",
      "name": "Hero title"
    }
  ]
}
```

| Field | What it is |
| --- | --- |
| `file` | The file the element is written in, from the project's root. |
| `tag` | Its tag. |
| `classes` | Its class attribute when it was named (the first 160 characters). |
| `text` | Its own text, if it has any (the first 48 characters). |
| `loc` | Where it was when it was named: `file:line:col`. |
| `name` | The name. |

### How a name is found again

Code moves: add a line above an element and its `loc` is off by one. So a name isn't tied to the line alone. For each layer, midcode looks at the names saved for the same file and tag, and takes the best match:

- same `loc`: the name is its own, whatever its classes are now;
- otherwise, same `classes`: it's the same element, on another line.

Matching text alone isn't enough. So a name holds while one of the two is still true. Once both have changed (lines were added above the element and its classes were edited), the entry no longer matches and the layer shows its default name. The entry isn't updated as the code changes: rename the layer again to save where it is now.

An entry that matches nothing stays in the file and does no harm. Delete the file to remove every name. Commit it if you want the names shared; nothing breaks if you don't.

## Limits

- Layers lists what's on the page now. A menu that isn't open or a section behind a condition isn't in the tree until it renders.
- The tree stops after about 4,000 layers on one page.
- In a project midcode can show but not edit (see [Open a project](https://midcode.app/docs/start/open-a-project.md)), Layers lists the page's elements as the browser has them. You can select them and comment on them. Names need elements that map to code, so renaming isn't available there.
- A name belongs to one place in the code. An element drawn by a loop has one name for all its items.
- Changing an element's tag (a `div` into a `section`) drops its name: names are matched within one file and one tag.

---

# Text, images and video

> Edit a text where it shows and midcode changes it where it's written, even in a data file. Replace, paste and drop images and videos, and set alt text.

- Page: https://midcode.app/docs/editor/text-and-media
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Text and media are the two things on a page that are content rather than layout. midcode edits both where they show, on the canvas, and writes the change where the content lives in your project: in the markup, in a data file, or as a file in `public/`.

## Edit a text

1. Double-click a text on the canvas. It becomes editable in place, with its words selected.
2. Type.
3. Press `Enter`, or click somewhere else, to save. `Esc` cancels.

midcode says where it went: "Saved to src/app/page.tsx". Your dev server reloads the text from the file, so what you see afterward is the code.

You can also select the element and edit the "Text" field in the right panel. It writes the same way.

The text is plain: no bold, no links, no line breaks. A line break typed with `⇧Enter` is saved as a space.

### Which elements can be edited in place

An element whose content is only text. `<h1>Design in code</h1>` is. A paragraph with an element inside is not one text:

```tsx
<p>
  Free for 3 days, then <strong>one payment</strong>.
</p>
```

Double-click "one payment" and you edit the `<strong>`. The words around it belong to the paragraph, mixed with an element, and can't be edited in place: use [Open code](https://midcode.app/docs/editor/code.md).

Double-clicking something that isn't a text does something else: on a component's instance, it opens the [component](https://midcode.app/docs/editor/components.md).

## Where the text is written

midcode looks in three places, in order, and edits the first that has the text.

### In the element

The usual case: the words are between the element's tags.

```diff title="src/app/page.tsx"
-<h1 className="text-5xl font-semibold">Design in code</h1>
+<h1 className="text-5xl font-semibold">Design, in your code</h1>
```

Only the text changes. Indentation and line breaks around it are kept. A text written as a string in braces counts too: `{'Design in code'}`.

If your new text has a character JSX would read as code (`{`, `}`, `<`, `>`), it's written as a string: `{"Save 20% when x > 3"}`. If the text you're replacing wrote its apostrophes as `&apos;`, the new one does too.

### Where the component is used

A component that renders `{children}` has no words of its own. They're written where the component is used, and that's the line midcode edits:

```diff title="src/app/page.tsx"
-<Button href="/download">Download</Button>
+<Button href="/download">Download for Mac</Button>
```

This works when the element on the page knows which use of the component drew it, which it does when the component passes its remaining props on to its element (`<a {...props}>`). A component that takes `children` and passes nothing else on leaves midcode with no way to tell which use wrote the words. It says the text comes from a prop, and you edit it in the code.

### In your data

Sites built with an agent often keep their copy apart from the markup: an array of features in `content/home.ts`, rendered with `.map()`. The element says `{feature.title}`, and the words are somewhere else.

```tsx title="src/components/Features.tsx"
import { features } from '@/content/home'

export function Features() {
  return (
    <ul>
      {features.map((feature) => (
        <li key={feature.title}>
          <h3>{feature.title}</h3>
          <p>{feature.body}</p>
        </li>
      ))}
    </ul>
  )
}
```

When the element has no literal text, midcode searches the project for the exact text as a string and edits it there:

```diff title="src/content/home.ts"
 export const features = [
-  { title: 'Edits are code', body: 'Every change is written into your files.' },
+  { title: 'Every edit is code', body: 'Every change is written into your files.' },
   { title: 'No lock-in', body: 'Your project stays a normal repository.' },
 ]
```

The message then names the data file and the line: "Saved to src/content/home.ts:2".

What's searched: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.json`, `.md`, `.mdx` and `.svelte` files, outside `node_modules`, build folders, `public/` and folders whose name starts with a dot. In code and JSON the whole string has to be the text, between its quotes. In Markdown the text can be anywhere in the file. No other kind of file is read: a text kept in a YAML or TOML file, or in a `.vue`, `.astro`, `.html` or `.php` file other than the element's own, isn't found.

That covers arrays and objects in modules, JSON files, message catalogs like `messages/en.json`, and Markdown content.

If the text appears once, that's the one. If it appears several times, midcode narrows it down: first to the files the element's file imports, then to the exported values it imports by name. If it still can't tell, it doesn't guess:

> That text appears in 3 places (src/content/home.ts:2, src/content/pricing.ts:8, messages/en.json:14). Open the right one in your editor.

For content kept as lists, the [CMS](https://midcode.app/docs/data/cms.md) shows the same data as a table. For a site in several languages, [Languages](https://midcode.app/docs/data/languages.md) edits each language's text side by side.

### What can't be edited on the canvas

- **Text put together by code.** `{count} items`, a formatted date, a template string with a value in it. There's no string in your files that equals what's on screen. midcode says: "This text isn't written there: it comes from a variable or prop. Open it in your editor."
- **Text that isn't in the project.** Posts from a headless CMS, rows from a database, anything fetched while the site runs.
- **Text in mixed content**, as above.
- **Text the dev server hasn't caught up with.** If you edit twice quickly, midcode may say "The text in the code doesn't match the preview. Wait for it to reload and try again." It checks that the code still says what the canvas showed before it writes.

In a component's own canvas, a text passed in where the component is used is the page's, not the component's: "This text is passed in where the component is used (page.tsx): edit it there." To make a component's text settable per use, see [Variables](https://midcode.app/docs/editor/variables.md).

## Replace an image or a video

Select an image, a video, or an element with a background image. The right panel shows it under "Image", "Video" or "Background image", with a preview and its path.

1. Click "Replace…" and choose a file. Or drop a file from Finder onto the preview in the panel ("Drop to replace").
2. midcode copies the file into your project and points the element at it.

Select an element that isn't media itself but has some inside (a hero with a background video) and the panel shows "Media" with "Contains an image", "Contains a video" or "Contains a background image". Click "Select" to go to it.

### What midcode writes

The file is copied into the folder your site serves as it is: `public/`, or `static/` in SvelteKit. It goes next to the file it replaces when that one is there too, otherwise into `images/`. Then the reference is rewritten:

```diff title="src/components/Hero.tsx"
-<img src="/images/hero.jpg" alt="The studio at night" className="rounded-2xl" />
+<img src="/images/hero-winter.jpg" alt="The studio at night" className="rounded-2xl" />
```

- The copy's name is the file's name in lowercase, with anything that isn't a letter, a digit, an underscore, a dot or a hyphen turned into a hyphen. `Hero Winter.JPG` becomes `hero-winter.jpg`.
- If a different file with that name is already there, the copy gets a number: `hero-winter-1.jpg`. If the very same file is there, it's reused and nothing is copied.
- The old file is left where it is.
- Both parts are in [Publish](https://midcode.app/docs/publish/publish.md): the edit, and "Add public/images/hero-winter.jpg".

The reference is found like a text is. First the element's own `src`, then the `src` given where its component is used (`<Image src="/images/hero.jpg" />`), then the exact path as a string in the same files a text is searched in: an array of slides, a JSON file.

A background image is found by its path too, including inside `url()`, and for it the search also reads `.css` files:

```diff
-<section className="bg-[url(/images/grain.png)] bg-cover">
+<section className="bg-[url(/images/paper.png)] bg-cover">
```

### Images imported in the code

In Next.js, an image can be imported instead of referenced by path:

```tsx title="src/components/About.tsx"
import portrait from './portrait.jpg'

<Image src={portrait} alt="Ana, the founder" />
```

There's no path in the code to rewrite, so midcode replaces the file itself: your new image is copied over `portrait.jpg`. Two rules keep that safe:

- The new file must have the same extension. "This image is imported as a .jpg file: pick a .jpg to replace it."
- If two files in the project have that name, midcode won't choose between them. "Several files in the project are called portrait.jpg. Replace it in your editor."

> [!WARNING]
> Replacing an imported image overwrites the file. It shows in Publish, but `⌘Z` doesn't bring the old image back. Recover it with git.

## Alt text

With an image selected, "Alt text" is under its preview. Type a description and press `Enter`. An image with no alt text shows "Missing" beside the field: screen readers and search engines read it.

```diff
-<img src="/images/team.jpg" className="rounded-2xl" />
+<img alt="The team at the studio in Lisbon" src="/images/team.jpg" className="rounded-2xl" />
```

An existing `alt` is changed in place. A new one is added right after the tag's name.

## Paste and drop

### Paste

Copy an image anywhere (a browser, a screenshot, a design tool) or copy files in Finder, then press `⌘V` in midcode.

| It goes | When |
| --- | --- |
| After the selection | An element in a page is selected. |
| On the free canvas | Nothing is selected, or something floating is, in a Next.js App Router project. It lands in the middle of what's in view. See [The free canvas](https://midcode.app/docs/editor/free-canvas.md). |
| At the end of the page | Nothing is selected, in any other project. If midcode can't tell which file the page is, it asks you to select an element first. |

A copied image with no file behind it is saved as `pasted-image.png`.

### Drop

Drag images, SVGs, videos or audio from Finder onto the canvas. Over a frame, a blue line shows where each would land, as when you [move an element](https://midcode.app/docs/editor/select-move-resize.md). Over the empty canvas, they float there in a Next.js App Router project, and go to the end of the page in any other.

Accepted: `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`, `mp4`, `webm`, `mov`, `mp3`, `wav`, `ogg`, `m4a`, `aac` and `flac`. Several files at once land one after the other.

### What a paste or a drop writes

Each file is copied into `public/images/`, `public/videos/` or `public/audio/` (in SvelteKit, under `static/`), with the naming rules above, and an element is written for it:

```tsx
<img src="/images/team-photo.png" alt="Team photo" className="w-full min-w-0 rounded-2xl object-cover" />
<video src="/videos/reel.mp4" autoPlay muted loop playsInline className="w-full min-w-0 rounded-2xl" />
<audio src="/audio/episode-12.mp3" controls className="w-full" />
```

An image's first alt text is made from its file name: `team-photo.png` becomes "Team photo". Change it to say what the picture shows. In a project without Tailwind 4, the classes carry midcode's prefix (`mid:w-full`): see [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

On the free canvas, the element is written with its own width instead (`className="w-[640px]"`): the image's real width, up to 800 px.

The "Image", "Video" and "Audio" items of the [Insert](https://midcode.app/docs/editor/insert.md) panel write the same elements, after asking for a file.

## Other files (next release)

Everything above is shown in JSX. Svelte files are edited the same way today. From the next release so are Vue, Astro and HTML files, and the templates a server renders (Blade, Liquid, Twig, ERB and others): text between tags, `src` and `alt`. What a template computes (`{{ title }}`) is treated like `{title}` in JSX: it isn't a text in that file. Each stack's page says what was tried: see [What works with what](https://midcode.app/docs/start/supported-stacks.md).

In Hugo, Jekyll and Eleventy, headings, paragraphs and list items that come from a Markdown file are found by their words and edited in that file. Only the words change (and a heading's level, with "Tag" in the right panel): Markdown has no tag to put a class or an attribute on. See [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md). In a Shopify theme, most texts live in `locales/*.json` and `templates/*.json`, where the search above finds them: see [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## Limits

- One text, one place. A text that's the same in two places midcode can't tell apart has to be edited in the code.
- The search for a text skips files over 1 MB and texts shorter than 2 characters, and reads at most 8,000 files.
- Replacing an imported image in place works for Next.js's imported images. In other projects midcode looks for the image's path as text. When there isn't one, it removes the copy it made and tells you to open the element in your editor.
- A file copied into `public/` stays there if you undo the edit that used it.
- A new file always goes to `public/` (`static/` in SvelteKit) and is referenced from the site's root (`/images/hero.jpg`). A stack that serves its files from another folder (a folder of plain HTML, Hugo's `static/`) won't find it there: after replacing or dropping an image, check that its `src` points at where the file is.
- A background image is replaced where its path is written out: in a class, a `style`, or a stylesheet. One that comes from a variable is edited in the code.
- Remote images (`https://…`) can be replaced with a local file, not with another URL. To change a URL, edit it in [Code view](https://midcode.app/docs/editor/code.md).

---

# Insert

> The Insert panel adds frames, text, media, embeds, forms, sections, components and icons to a page, written as plain code in your own files.

- Page: https://midcode.app/docs/editor/insert
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

The Insert panel is where new elements come from. Click the plus button ("Insert") in the toolbar at the bottom of the canvas and the panel opens over the left panel, with its search field ready. Close it with the ✕ in its header, or `Esc` once nothing is selected, and the tab you were on comes back.

Everything in the panel is static markup with utility classes, written into the file of the page (or the component) you're on. One insert is one `⌘Z` step and one entry in [Publish](https://midcode.app/docs/publish/publish.md), with any file it brings along.

## Add something

1. Open the panel and pick a tile.
2. **Click** it. With an element selected, the new one goes at the selection. With nothing selected, it goes at the end of the page. The line under the search field says which: "Click adds it at the selection; drag to place it" or "Click adds it at the end of the page; drag to place it".
3. Or **drag** it onto a breakpoint. The frame under the pointer draws where it would land: a line between two elements, or a box around the one it would go into.

The new element is selected as soon as the page shows it, so you can style it straight away in [the style panel](https://midcode.app/docs/editor/styles.md).

Search looks at names, descriptions and keywords ("slider" finds Carousel and Slideshow). `Enter` adds the first match, the one with the ring. With two letters or more the list also offers "Search icons", which opens the icon browser on those words.

## Shortcuts

Each of these adds the item at the selection, like a click on its tile.

| Key | Adds |
| --- | --- |
| `F` | Frame |
| `S` | Stack |
| `T` | Text |
| `⇧G` | Grid |
| `⇧I` | Image (asks for a file first) |
| `⇧V` | Video (asks for a file first) |

In a Next.js App Router project, `F` on the page canvas is the draw tool of [the free canvas](https://midcode.app/docs/editor/free-canvas.md) instead: you draw the frame where you want it. Inside a component, and in every other kind of project, `F` inserts the Frame.

## What's in the panel

| Category | Items |
| --- | --- |
| Basics | Frame, Stack, Row, Grid, Text, Heading, Button, Link, Divider, Spacer |
| Media | Image, Video, Audio, Icon, Sticker |
| Embeds | YouTube, Vimeo, Spotify, SoundCloud, Google Maps, Embed |
| Forms | Contact form, Newsletter, Input, Email, Phone, Textarea, Select, Checkbox, Radio group, Submit button |
| Sections | Navbar, Hero, Hero with image, Logo cloud, Features grid, Feature with image, Stats, Testimonials, Pricing, FAQ, Call to action, Contact, Footer |
| Components | Carousel, Slideshow, Ticker, Tabs, Cookie banner, Language switcher, Shader gradient |

### Basics

Small pieces in one neutral look: they take your site's text color and font, and draw surfaces and lines from it (`bg-current/5`, `border-current/10`).

```tsx
<div className="flex flex-col gap-4">
  <div className="h-24 rounded-2xl bg-current/5" />
  <div className="h-24 rounded-2xl bg-current/5" />
</div>
```

That's a Stack. Buttons are written with `bg-neutral-900 text-white`; if your theme has the colors `primary` and `primary-foreground` (or `foreground` and `background`), midcode writes those instead.

### Media

Image, Video and Audio ask for a file from your Mac. midcode copies it into your project's public folder (`public/images`, `public/videos`, `public/audio`) and writes the element that shows it:

```tsx
<img src="/images/hero-photo.jpg" alt="Hero photo" className="w-full min-w-0 rounded-2xl object-cover" />
```

The alt text starts as the file's name in words. If the same file is already in that folder it's used again; a different file with the same name gets a number (`hero-photo-1.jpg`). Files dropped from Finder onto a breakpoint are inserted the same way. Replacing media and pasting images are on [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).

### Icons and stickers

The Icon and Sticker tiles open a browser: choose a set (Phosphor, Lucide, Heroicons, Material Symbols, Tabler, Feather, Remix Icon, Material Design Icons, Simple Icons, SVG Logos; for stickers Fluent Emoji, Noto Emoji, Twemoji, OpenMoji), a style when the set has several, search, then click or drag one. The sets come from the Iconify API and are kept on your Mac once seen, so the first time needs a connection.

What an icon becomes depends on your `package.json`:

- If the project has the set's React package (`lucide-react`, `@phosphor-icons/react`, `@heroicons/react`, `@tabler/icons-react`), midcode imports the component. The browser's footer names the package when that's the case.
- Otherwise it writes the icon inline, as an `<svg>` that takes the text color.

```tsx title="With lucide-react installed"
import { Heart } from 'lucide-react'

<Heart className="size-6" aria-hidden="true" />
```

```tsx title="Without the package"
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" className="size-6" aria-hidden="true">...</svg>
```

A Lucide or Phosphor name that would shadow something in the page (`Image`, `Link`, `Map`) is imported under its `Icon` alias (`ImageIcon`).

A sticker is a colored SVG. It's saved as a file and shown by an `<img>`:

```tsx
<img src="/stickers/fluent-emoji-flat-rocket.svg" alt="" width="96" height="96" className="size-24" />
```

The file goes to `public/stickers/`. Every SVG midcode writes is cleaned first, so nothing in it can run or load from elsewhere: no scripts, no event handlers, no links to other sites.

### Embeds

An embed tile writes an `<iframe>` with a working example link, so you see a real player at once:

```tsx
<iframe
  src="https://www.youtube.com/embed/k3BPZ87BQmg"
  title="YouTube video"
  className="aspect-video w-full rounded-xl"
  loading="lazy"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  allowFullScreen
  referrerPolicy="strict-origin-when-cross-origin"
/>
```

Select it and paste your own link in the right panel, under "Embed" → "Link". You can paste a share link, an embed address, a whole `<iframe>` embed code, or a place name for a map. midcode turns it into the address the player needs, and changes the title, the permissions and the size classes when the new link is another kind of player. Loom and Figma links are recognized too. See [element settings](https://midcode.app/docs/editor/components.md).

### Forms

Contact form and Newsletter are whole forms; the rest are single fields with their label. A form is written with `method="post"` and no `action`: set where it sends in the right panel ("Form" → "Action"), and add fields there with "Add field".

A second copy never collides with the first: ids the file already uses get a number (`contact-form-name` becomes `contact-form-name-2`, and its label's `htmlFor` follows), and so do field names taken inside the same form.

### Sections

Whole page blocks, shown in the panel as a live, scaled render of what they write. The ones with a picture use a neutral placeholder, written once to `public/midcode/placeholder.svg`.

### Components

The Components category is interactive: a carousel, a slideshow, a ticker, tabs, a cookie banner, a language switcher, an animated gradient. These need code that runs, so midcode writes each one's source into your project the first time you use it, and imports it:

```diff title="app/layout.tsx"
 import './globals.css'
+import { CookieBanner } from '@/components/midcode/CookieBanner'
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
-      <body>{children}</body>
+      <body>
+        {children}
+        <CookieBanner />
+      </body>
     </html>
   )
 }
```

- The file goes in `components/midcode/`, next to your other sources: `src/components/midcode/` when the project keeps its code in `src/`, `app/components/midcode/` in React Router and Remix.
- It's a `.tsx` file when the project has a `tsconfig.json`, and a plain `.jsx` file (same code, types removed) when it doesn't.
- It's written once. If the file is already there, midcode uses it as it is and never writes over it: from then on it's your code.
- The import uses your `tsconfig.json` or `jsconfig.json` path alias when one covers that folder (`@/components/...`), a relative path otherwise. If the file already has something called `Carousel`, the import is `Carousel as MidcodeCarousel`.

Their options (autoplay, arrows, speed, colors) show as typed controls under [Props](https://midcode.app/docs/editor/components.md) when you select one. The Language switcher is written with your project's languages already in its props, when midcode finds them (see [Languages](https://midcode.app/docs/data/languages.md)).

## Where it lands

| You do this | The new element goes |
| --- | --- |
| Click, with a container selected | Last inside it. Containers are `div`, `section`, `main`, `article`, `header`, `footer`, `nav`, `aside`, `form`, `figure`, `ul`, `ol`, `li`, `fieldset`, `details` and `dialog`. |
| Click, with anything else selected | Right after it. Next to a component instance, never into the component's file. |
| Click a section, a Ticker or a Shader gradient | After the page's top-level block that holds the selection. |
| Click, with nothing selected | At the end of the page: last inside the element the page returns, or inside its `<main>`. |
| Add a Cookie banner | Last inside the `<body>` of the root layout: the `layout.tsx` nearest the page in the App Router, `root.tsx` in React Router and Remix. In the Pages Router it goes at the end of the page. |
| Drag | Where the line or the box shows. |
| Drop on the empty canvas | It floats there, in Next.js App Router projects. See [The free canvas](https://midcode.app/docs/editor/free-canvas.md). |

A single element added with nothing selected (a form, an embed, an image) would sit flush against the page's edge, so it comes inside a block of its own:

```tsx
<section className="mx-auto w-full max-w-6xl px-6 py-12">
  <p className="leading-relaxed">Say what matters in a sentence or two, and keep it easy to read.</p>
</section>
```

In [component mode](https://midcode.app/docs/editor/components.md) everything goes into the component's file; with nothing selected, last inside its root. A Cookie banner belongs to the site, so there midcode answers "This goes on the page: go back to the page to add it".

To add one of your own components, drag it from the [Assets tab](https://midcode.app/docs/editor/pages.md). midcode writes `<Card />` and its import.

## What midcode writes

- The code goes in with the indentation of the lines around it, in the file's own unit (two spaces, four, tabs).
- Imports go after the file's last import (after `'use client'` when there are none), with the quotes and semicolons the file already uses. A named import from a module the file already imports from joins that line.
- A page that returns a single component (`return <Home />`) gets a fragment around it and the new element.
- Nothing is written if the result wouldn't parse. You get "Couldn't insert it: the code wouldn't parse" and the file stays as it was.
- Files that come with the insert (a component, a sticker, the placeholder) are part of the same step: `⌘Z` takes the element out and deletes the files it created. If another file has started using one of them since (a second page imports the Carousel), that step can't be undone, and midcode says which file uses it.

### Projects without Tailwind 4

In a project that midcode styles itself, the same snippets are written with the `mid:` prefix, and their root gets `mid-base`, which scopes a small reset to what midcode inserted:

```tsx
<p className="mid-base mid:leading-relaxed">Say what matters in a sentence or two, and keep it easy to read.</p>
```

The components written to `components/midcode/` are prefixed the same way. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Other frameworks

In Svelte files the snippets are written as HTML: `class` and `for`, lowercase attributes, no self-closing `<div />`. Icons are always inline SVG there, and files go to `static/` in SvelteKit. The Components category is React only: on a Svelte page its tiles are dimmed and say "Needs a React page".

### Vue, Astro, HTML and templates (next release)

The next release inserts into `.vue` and `.astro` files, plain HTML and server templates the same way as into Svelte. Three things are different there:

- An insert that needs an import (an icon from a package, one of your components) gets it in a `.vue` file (in its `<script setup>`) and in an `.astro` file (in its frontmatter), created when the file has none. In a Nuxt project nothing is imported for a component under `components/`, which Nuxt finds by itself. It's still refused in a Vue component written with the Options API, in plain HTML and in server templates: "This needs an import, which midcode can't add to Hero.vue yet. Add it in the code."
- In JSX that isn't React (Solid, Preact, Qwik) the snippets follow the file and write `class` and `for`. midcode's own components are React, so without `react` in `package.json` they're refused: "This component needs a React page".
- Nothing is inserted into content that comes from a Markdown file (a post in Hugo, Jekyll or Eleventy). Select an element of the template around it instead.

## Limits

- The interactive components are React components. There are no Svelte or Vue versions.
- A click needs a place to go. On a page whose file midcode can't add to by itself it says "Select an element first: the new one goes next to it". If it can't tell what a page file renders (it returns a condition, for instance), it asks you to select an element on the canvas first.
- A section goes among the page's top-level blocks. When the page's shape can't be read, it goes next to the selection instead.
- Icons and stickers can't be browsed offline until their set has been loaded once.
- In projects midcode only shows (see [Supported stacks](https://midcode.app/docs/start/supported-stacks.md)), the tiles are disabled.

---

# The style panel

> Every group of the right panel, the utility classes each control writes, overrides per breakpoint, number fields, and copying styles between elements.

- Page: https://midcode.app/docs/editor/styles
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Select an element on the canvas and the right panel shows where it's written and everything you can change about it. The style groups never write CSS rules: each control swaps utility classes on the element, in your file, the way you would have typed them. In a project with Tailwind 4 those are Tailwind's own classes; in any other project they're the same classes with a `mid:` prefix (see [What midcode writes](#what-midcode-writes)).

The panel always shows what's on screen. When the element has a class for a property, the control shows that class's value. When it doesn't, the control shows the computed value as a placeholder.

## What the panel shows

From the top:

1. The element's name and tag, with buttons to edit its component, ask your agent about it, copy its reference and comment on it.
2. **Code**: where it's written. "Element" is the element itself, "Instance" the place its component is used, and "Inside" the nearest elements around it that are written in other files. Click a row to copy `file:line:col`; the icon that appears on hover is "Open code" (see [Code view](https://midcode.app/docs/editor/code.md)).
3. Depending on the element: [Props](https://midcode.app/docs/editor/components.md), [element settings](https://midcode.app/docs/editor/components.md) for form fields, embeds and players, and Link, Image or Video, and Text (see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md)).
4. The style groups: Position, Size, Layout, Typography, Fill, Styles, Spacing and Classes.

Layout isn't shown for images, videos, SVGs, iframes and canvases. Typography only shows where there's text to set.

An element that isn't written in your project (something a library draws) has no style groups: the panel says so, and you can edit its parent or the component that uses it.

## Which breakpoint you're editing

The first row, "Breakpoint", says which breakpoint the edit is for. It follows the frame you clicked the element in, and you can change it there.

One breakpoint is the primary: what you set there is the rule for every width. A value set at any other breakpoint is an override. Overridden properties show their label in blue; right-click the label and choose "Remove override" to follow the primary again.

midcode writes this the Tailwind way, mobile first, with one class per breakpoint where the value changes. With the default breakpoints (Desktop is the primary, Tablet writes at `md`, Phone has no prefix), setting the vertical padding to 48 in the Phone frame does this:

```diff
-<section className="px-6 py-24">
+<section className="px-6 py-12 md:py-24">
```

Phone gets `py-12`, and `md:py-24` keeps Tablet and Desktop where they were. An override also carries on to the breakpoints beyond it, away from the primary, while they were showing the same value: change the font size in the Tablet frame and Phone follows, unless Phone has its own.

```diff
-<h1 className="text-6xl">
+<h1 className="text-5xl lg:text-6xl">
```

Removing the Phone override from the first example puts back `px-6 py-24`. How a breakpoint gets its screen is on [The canvas and breakpoints](https://midcode.app/docs/editor/canvas.md). In [component mode](https://midcode.app/docs/editor/components.md) the same rows also choose a variant and a state.

## Position

| Control | What it writes |
| --- | --- |
| Type: Default, Relative, Absolute, Fixed, Sticky | `relative`, `absolute`, `fixed`, `sticky`. Default removes the class. |
| Offset (shown for Absolute, Fixed and Sticky) | The X and Y fields write `left-6` and `top-6`, or `-left-4` for a negative number. |

An element positioned with left and top can also be dragged and nudged with the arrow keys on the canvas (see [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md)).

## Size

Width and Height each have a value and a mode.

| Mode | Means | Class |
| --- | --- | --- |
| Fixed | A size in px | `w-80`, or `w-[317px]` off the scale |
| Relative | A percentage of the parent | `w-[50%]` |
| Fill | All the room the parent gives | `w-full`, `h-full` |
| Fit | As big as its content | `w-fit`, `h-fit` |
| Viewport | The size of the window | `w-screen`, `h-svh` |
| Auto | No size of its own | The class is removed |

Switching to Fixed writes the size the element has right now, so nothing jumps. Switching to Relative starts at 100%. The value field takes a number (px), a percentage, another unit (`20rem` becomes `w-[20rem]`) or a Tailwind size by name (`7xl` becomes `w-7xl`). [Resize handles](https://midcode.app/docs/editor/select-move-resize.md) on the canvas appear on the axes that are Fixed.

"Min Max" → "Add…" adds a row for Min width, Max width, Min height or Max height. Each has a value and a unit, Fixed (px) or Relative (%), and writes `min-w-*`, `max-w-*`, `min-h-*` or `max-h-*` (`max-w-full` for 100%). The minus button removes it.

Images and videos get one more row, "Fit": Fill (crop) writes `object-cover`, Fit (whole image) `object-contain`, Stretch `object-fill`, Original size `object-none`.

## Layout

Layout arranges what's inside the element. The plus button in the group's header ("Add a stack layout") writes `flex flex-col`; the minus button ("Remove layout") takes every layout class away.

| Control | What it writes |
| --- | --- |
| Type: Stack or Grid | `flex`, or `grid` with `grid-cols-2` to start |
| Direction (stack) | `flex-row` or `flex-col` |
| Columns (grid) | `grid-cols-3` |
| Distribute | `justify-start`, `justify-center`, `justify-end`, `justify-between`, `justify-around`, `justify-evenly` |
| Align | `items-start`, `items-center`, `items-end`, `items-stretch` (shown as Fill) |
| Wrap (stack) | `flex-wrap` |
| Gap | `gap-6` |

A plain block whose children are blocks (a `<main>` of sections) is already a vertical stack, so the panel shows it as one. The first thing you change writes `flex flex-col` along with it.

## Typography

| Control | What it writes |
| --- | --- |
| Tag | Changes the element itself: `<h2>` to `<h1>`, `<p>`, `<span>`… Opening and closing tag. |
| Style | One of the project's text styles, as its class. |
| Font | `font-sans`, `font-serif`, `font-mono`, or one of your theme's fonts |
| Size | `text-xl` from the scale or your theme, `text-[18px]` for a number |
| Weight | `font-thin` to `font-black` (100 to 900) |
| Line | `leading-tight`, `leading-7`, `leading-[1.4]` |
| Tracking | `tracking-tight`, `tracking-[0.02em]` |
| Align | `text-left`, `text-center`, `text-right`, `text-justify` |
| Wrap: Auto, Balance, Pretty | `text-balance`, `text-pretty`. Auto removes the class. |
| Color | `text-brand` for a theme color, `text-[#ff5b2e]` for a custom one |

Under Tag, midcode warns when the page has more than one `<h1>`, or none. Next to Style, the sliders button edits the text style itself, everywhere it's used; text styles, fonts and colors are made in the Assets tab (see [Theme and design tokens](https://midcode.app/docs/styling/theme.md)).

## Fill

Background writes `bg-brand` or `bg-[#111111]`.

Every color control opens the same picker. "Project colors" lists the colors of your theme by name, with a search field. "Custom" is a color picker: the canvas follows while you drag, and the class is written when you let go. "Remove color" takes the class away.

## Styles

| Control | What it writes |
| --- | --- |
| Opacity | `opacity-80`. 100% removes the class. |
| Visible: Yes or No | No writes `hidden` for the breakpoint you're editing (`hidden md:flex`). |
| Overflow: Visible, Hidden, Clip, Scroll when needed | `overflow-visible`, `overflow-hidden`, `overflow-clip`, `overflow-auto` |
| Radius | `rounded-lg` when the number matches a step of the scale or of your theme, `rounded-[10px]` otherwise |
| Border | Width 1, 2, 4 or 8 writes `border`, `border-2`, `border-4`, `border-8`; the color writes `border-brand`. |
| Shadow: XS to 2XL | `shadow-xs` … `shadow-2xl` |

The button at the end of Radius and of Border splits the control in four. Corners write `rounded-tl-lg`, `rounded-tr-lg`, `rounded-br-lg`, `rounded-bl-lg`; sides write `border-t`, `border-r-2`, and so on. Setting the single value again removes the per-corner or per-side classes, so it wins.

## Spacing

Padding has a horizontal and a vertical field: `px-6`, `py-24`. The button at the end splits it into the four sides, which write `pt-*`, `pr-*`, `pb-*` and `pl-*`.

## Classes

The last group lists every class the element has, as written. The ✕ on a class removes it. "Add class…" takes one or more classes and adds them when you press `Enter`. Use it for anything the panel has no control for: a margin, a transition, a `dark:` class.

## Number fields and sliders

- `↑` and `↓` in a number field change it by 1, and with `⇧` by the "Nudge amount" from Settings. The class is written when the keys rest.
- Drag a field's unit (px, %, X, Y) sideways to scrub the number, one step per pixel, with `⇧` for the nudge amount. The canvas shows the value while you drag and the class is written once, when you let go.
- A value typed in rem is converted (`1.5rem` is 24).
- Opacity, Gap and Radius are sliders. Press anywhere on the bar and drag. `⌥` while dragging moves in single units instead of the slider's steps. `←` and `→` move one step, ten with `⇧`. `Enter` or a double-click lets you type the number.

Numbers land on the spacing scale when they can. With Tailwind's default unit of 4 px, 24 becomes `px-6`, 18 becomes `px-4.5`, and 17, which isn't on the scale, becomes `px-[17px]`.

## Several elements at once

Shift-click more elements on a page and the panel writes each change to all of them: the same value on each, worked out against each element's own classes, as one edit and one `⌘Z`.

## Copy and paste styles

Right-click an element and choose "Copy styles" (`⌥⌘C`), then "Paste styles" (`⌥⌘V`) on another. Copying takes the element's whole class list; pasting replaces the target's classes with it, as one edit.

"Hide" in the same menu (`⌘;`) adds `hidden` to the element, and "Show" removes it.

## What midcode writes

One class changes at a time, in place. A class that's replaced keeps its position in the string; a class that's new goes at the end. The rest of the line isn't touched, so `git diff` shows exactly the edit.

```diff title="Tailwind 4"
-<section className="px-6 py-16">
+<section className="px-6 py-24">
```

In a project with Tailwind 4, the colors, fonts, text sizes and radii of your `@theme` are offered by name, and anything else is written as an arbitrary value (`text-[#ff5b2e]`). More on [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

```diff title="Without Tailwind 4"
-<section className="hero mid:px-6 mid:py-16">
+<section className="hero mid:px-6 mid:py-24">
```

In a project without Tailwind 4 (plain CSS, CSS modules, Bootstrap, Tailwind 3), the classes carry the `mid:` prefix, a breakpoint override is `mid:md:py-24`, and midcode compiles them into `midcode.css`. The panel reads only the `mid:` classes there: your own classes, like `hero` above, are left alone. More on [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

When the classes are passed through a helper, midcode edits the string inside it:

```diff
-<div className={cn('rounded-xl p-6', active && 'ring-2')}>
+<div className={cn('rounded-2xl p-6', active && 'ring-2')}>
```

## Limits

- Classes that aren't written as text can't be changed. If the whole `className` is a variable, midcode says "This element's classes come from a variable. Edit them in the code." If the class it has to replace isn't written in the file (it arrives through a prop, or is put together in code), it says so and writes nothing.
- A class written inside a condition (`active && 'ring-2'`, a branch of a ternary, a key of `clsx({ … })`) is found, and taken out of that branch when you change its property. The new class is written outside the condition, for every case. Check the diff when you style an element whose classes depend on state. [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md) has every case.
- The panel reads and writes classes with a breakpoint prefix, and in component mode a variant or state prefix. A class with any other prefix (`dark:`, `max-md:`, `[&>svg]:`) stays exactly as written: midcode doesn't read it and doesn't rewrite it.
- There are no controls for margins, grid rows, right and bottom offsets, transitions or transforms. Write those in Classes or in the code.
- A text style or a link style is one class of your project: it can't change per breakpoint, variant or state.
- From the next release, content that comes from a Markdown file (Hugo, Jekyll, Eleventy) can be selected, but it has no tag to put a class on. A style edit there answers "This is written in Markdown: its words can be changed here, not its classes or attributes. Style it from the template around it."
- In projects midcode only shows, the panel has no style groups. See [Supported stacks](https://midcode.app/docs/start/supported-stacks.md).

---

# Components

> Component mode puts a component alone on the canvas with its variants and states. The exact code midcode writes for each, typed props, and element settings.

- Page: https://midcode.app/docs/editor/components
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A component is edited in one place and shows everywhere it's used. midcode opens it on a canvas of its own, one step deeper than the page: its variants side by side, its states underneath, and every edit written into the component's own file, never into the page that uses it.

This page covers that canvas, the code behind variants and states, the Props section you see when you select an instance on a page, and the settings of form fields, embeds and players.

## Open a component

Any of these opens it:

- Double-click an instance on the page (on the instance itself, not on a text inside it).
- Right-click an instance → "Edit component".
- Select an instance and click the edit button in the right panel's header ("Edit Card").
- Click the component in the [Assets tab](https://midcode.app/docs/editor/pages.md).

The bar over the canvas says where you are: the page, then the component, then its file. To go back, click the arrow ("Back to the page") or the page's name, or press `Esc` once nothing is selected.

The component has to be on a page: every cell of the canvas is the real page that renders it, cropped to the component. If nothing uses it yet, midcode says "Card isn't on any page yet": drop it on a page from Assets first.

Component mode works with React components and Svelte components. A React component has to be in a file midcode marks: `.tsx` and `.jsx` in Next.js and Vite projects, not a plain `.js` file. For Svelte components the code is there, and what it writes was checked by running it on its own, but no Svelte project is on record as tried with component mode in the running app. From the next release, Vue and Astro components open on their own canvas too: see [Vue and Astro](#vue-and-astro).

## The grid

Columns are variants, rows are states.

| | Primary | Ghost |
| --- | --- | --- |
| Default | The component as it is | What Ghost changes |
| Hover | What changes on hover | Ghost, hovered |

- Click an element in a cell and the right panel edits it **for that cell**. The rows "Breakpoint", "Variant" and "State" at the top of the panel say which, and can change it.
- What a cell doesn't set, it takes from its parent: Pressed from Hover, a state from Default, a variant from Primary. Those values show dimmed. A value the cell sets itself shows its label in blue; right-click it → "Remove override" to inherit again.
- With nothing selected (or the component's root selected), the right panel's "Component" section lists the variants and states. Click one to edit there.

The bar also has the breakpoint the component is shown at, "Variables" (see [Variables](https://midcode.app/docs/editor/variables.md)), "Send to agent" (the component, its props, variants, states and where it's used, pasted into [your agent](https://midcode.app/docs/agents/overview.md)) and a button that shows the component's file beside the canvas (see [Code view](https://midcode.app/docs/editor/code.md)).

## Variants

A variant is a version of the component: Ghost, Large, Dark. It starts as a copy of the primary and keeps only what you change in it.

1. Select the component's root. A dashed box appears to the right of the last column.
2. Click it ("New variant"), or the plus beside "Variants" in the right panel.
3. Type a name. "Ghost dark" is written `ghost-dark`.

To use a variant on a page, select an instance and pick it under Props → "Variant". To rename or delete one, right-click its column header or its row in the Component section.

- **Rename** changes the name in the type, in every class that carries it, and in every instance that picks it.
- **Delete** asks first. Its classes come out of the file, and the instances that used it go back to the primary.
- The primary can't be renamed or deleted: it's the component as it is.

## States

A state is how the component looks while it's hovered, pressed or focused.

1. Select the root. A dashed box appears under the last row.
2. Click it ("New state"), or the plus beside "States", and choose Hover, Pressed or Focus.

A new row writes nothing. It shows what it inherits until you change something in it; that first change writes the first class. To take a state away, right-click its header → "Remove state". A state that already has classes in the file can't be dropped from the canvas: remove them in the code.

## Props

Select an instance of a component **on a page** and the right panel has a "Props" section: one control for each prop the component declares, typed from its code. Nothing has to be registered. midcode reads the props type, the defaults in the destructuring, and JSDoc comments.

| The prop's type | Control |
| --- | --- |
| `string` | A text field |
| `number` | A number field; a slider when it has `@min` and `@max` |
| `boolean` | A switch |
| A union of strings (`'sm' \| 'md' \| 'lg'`) | A choice |
| `string`, named like an image (`image`, `logo`, `avatar`, `heroImage`) | A path with a file picker |
| `string`, named like a color (`color`, `background`, `fill`) | A color picker |
| `string`, named like a link (`href`, `url`, `ctaHref`) | A link field that suggests your pages |
| `ReactNode`, a function, an object | Shown as code; a click opens it in the editor |

The last word of the name decides: `imageAlt` and `linkLabel` stay text.

JSDoc tags on a prop tune its control:

| Tag | Does |
| --- | --- |
| First line of the comment | The description, shown on hover |
| `@label Plan name` | The label, instead of the prop's name in words |
| `@min 0`, `@max 500`, `@step 5` | The range and step of a number |
| `@unit px` | The unit shown beside a number |
| `@control color` | Forces the control: `color`, `image`, `link`, `text`, `textarea`, `number` or `boolean` |
| `@default 24` | The default, when it isn't in the destructuring |

```tsx title="components/PricingCard.tsx"
interface PricingCardProps {
  /** @label Plan name */
  name: string
  /**
   * Monthly price
   * @unit $
   * @min 0
   * @max 500
   * @step 5
   */
  price?: number
  /** Shown as the recommended plan */
  featured?: boolean
  size?: 'sm' | 'md' | 'lg'
  /** @control color */
  accent?: string
  /** @control textarea */
  summary?: string
  ctaHref?: string
}

export function PricingCard({ name, price = 24, featured = false, size = 'md', accent = '#ff5b2e', summary, ctaHref = '/signup' }: PricingCardProps) {
```

That gives "Plan name" as a text field, "Price" as a slider from 0 to 500 in steps of 5, "Featured" as a switch, "Size" as three buttons, "Accent" as a color, "Summary" as a text area and "Cta href" as a link.

In a JavaScript project with no types, midcode goes by each prop's default and name, and a `/** @type {'sm' | 'md'} */` comment on a destructured prop makes it a choice. [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md) has the do's and don'ts for you or your agent.

A prop whose value is written as code on that instance (`price={plan.price}`) shows as code, and a click opens it. A label in full color means the prop is written on this instance; right-click it → "Reset to default" removes it.

In component mode the same section is a read-only list of what the component declares: each instance sets its own where it's used.

### Svelte

Props work the same for Svelte components, read from `let { … } = $props()` or Svelte 4's `export let`.

### Vue and Astro (next release)

The next release recognizes Vue and Astro components where they're used: [Layers](https://midcode.app/docs/editor/layers.md) names them, a click on one selects the instance, and the Props section shows the same controls, read from `defineProps` (with a type, an object or an array) in a Vue component and from `interface Props` in an Astro component. A value that's code is written the way the file binds it: `:count="3"` in Vue, `count={3}` in Astro.

They have component mode too. A `.vue` file is a component, and so is an `.astro` file outside your pages and layouts. The Assets tab lists them (pages, layouts and `App.vue` aside; Nuxt names them with their folders, so `components/base/Button.vue` is `BaseButton`), and each opens on its own canvas with the same grid of variants and states.

A state is the same classes as anywhere (`hover:`, `active:`, `focus-visible:`). A variant is a `variant` prop, declared the way the component already declares its props, with `data-variant` and a `group/<name>` class on each root:

| Component | The variant is written as |
| --- | --- |
| Vue, `defineProps<Props>()` | A `variant?: 'primary' \| 'ghost'` member in the type, its default in `withDefaults(…)` or in the destructuring, and `:data-variant="variant"` on each root of the template |
| Vue, `defineProps({ … })` | `variant: { type: String, default: 'primary' }`, with the list of variants in a JSDoc `@type` above it |
| Astro | A `variant?: 'primary' \| 'ghost'` member in `interface Props`, its default in `const { variant = 'primary' } = Astro.props`, and `data-variant={variant}` |

A component with no props yet gets the declaration it needs. Renaming or removing a variant follows the instances that set it. [Vue](https://midcode.app/docs/frameworks/vue.md), [Nuxt](https://midcode.app/docs/frameworks/nuxt.md) and [Astro](https://midcode.app/docs/frameworks/astro.md) have the details and what isn't written (a Vue component on the Options API, one that lists its props as `defineProps([...])`).

[Variables](https://midcode.app/docs/editor/variables.md) are for React components and, from the next release, Svelte, Vue and Astro components.

## Element settings

Form fields, embeds and players get a section of their own in the right panel, above the style groups. Each control writes one attribute on the element.

| Element | Section | What you set |
| --- | --- | --- |
| `<input>` | Input | Type, Name, Placeholder, Value, Min, Max, Step, Required (which ones show depends on the type) |
| `<textarea>` | Text area | Name, Placeholder, Rows, Required |
| `<select>` | Dropdown | Name, Required, and its options: add, remove, drag to reorder, with a label and a value each |
| `<form>` | Form | Action, Method, and "Add field" |
| `<button>` | Button | Type (Button, Submit, Reset), Disabled |
| `<label>` | Label | For: the id of the field it names |
| `<iframe>` | Embed | Link, Title, Full screen |
| `<video>` | Playback | Controls, Autoplay, Loop, Muted, Plays inline |
| `<audio>` | Audio | The file ("Replace…"), Controls, Autoplay, Loop, Muted |

"Add field" puts a labeled field (Text, Email, Phone, Message, Dropdown, Checkbox) before the form's last button, with an id and a name no other field has, or adds a Submit button. An embed's Link takes whatever you'd paste: a share link, an embed code, a place name (see [Insert](https://midcode.app/docs/editor/insert.md)). A select's options can only be edited when they're plain `<option>` elements, not a list rendered from code.

### Save a form to a table (next release)

In the next release the Form section also has "Save to a table…", which writes a brief for your agent to store what people send in your [database](https://midcode.app/docs/data/database.md).

## What midcode writes

Variants and states are plain Tailwind, with no JavaScript: a typed prop, a data attribute, and class prefixes. Start from this component:

```tsx title="components/Card.tsx"
interface CardProps {
  title: string
}

export function Card({ title }: CardProps) {
  return (
    <article className="rounded-2xl p-6 shadow-lg">
      <h3 className="text-xl font-semibold">{title}</h3>
    </article>
  )
}
```

### The first variant

Adding "Ghost" sets the component up, in one edit: the `variant` prop with its list and its default, `data-variant` on the root, and a named group so the elements inside can follow.

```diff title="components/Card.tsx"
 interface CardProps {
   title: string
+  variant?: 'primary' | 'ghost'
 }
 
-export function Card({ title }: CardProps) {
+export function Card({ title, variant = 'primary' }: CardProps) {
   return (
-    <article className="rounded-2xl p-6 shadow-lg">
+    <article className="rounded-2xl p-6 shadow-lg group/card" data-variant={variant}>
       <h3 className="text-xl font-semibold">{title}</h3>
     </article>
   )
 }
```

The group is named after the component (`ProductCard` gets `group/product-card`). A component that returns more than one element gets `data-variant` and the group on each. The next variant only adds its name to the list: `'primary' | 'ghost' | 'outline'`.

Without TypeScript, the list lives in a JSDoc comment that the Props section reads:

```jsx
export function Card({ title, /** @type {'primary' | 'ghost'} */ variant = 'primary' }) {
```

### A style in a variant

In the Ghost column, select the card and set Shadow to None and Border to 1. Then select the title and set its weight to 400.

```diff
-    <article className="rounded-2xl p-6 shadow-lg group/card" data-variant={variant}>
-      <h3 className="text-xl font-semibold">{title}</h3>
+    <article className="rounded-2xl p-6 shadow-lg group/card data-[variant=ghost]:shadow-none data-[variant=ghost]:border" data-variant={variant}>
+      <h3 className="text-xl font-semibold group-data-[variant=ghost]/card:font-normal">{title}</h3>
```

On the root the prefix is `data-[variant=ghost]:`. On anything inside it, `group-data-[variant=ghost]/card:`. The primary has no prefix.

Shadow → None wrote `shadow-none` rather than removing a class: the primary's `shadow-lg` would still show through. "None", "Auto" and "Default" in a variant or a state write the reset when that's the case.

### A state

In the Hover row, give the card a larger shadow and color the title. (The lines below start from the card as its first variant left it.)

```diff
-    <article className="rounded-2xl p-6 shadow-lg group/card" data-variant={variant}>
-      <h3 className="text-xl font-semibold">{title}</h3>
+    <article className="rounded-2xl p-6 shadow-lg group/card hover:shadow-xl" data-variant={variant}>
+      <h3 className="text-xl font-semibold group-hover/card:text-[#ff5b2e]">{title}</h3>
```

| State | On the root | Inside it |
| --- | --- | --- |
| Hover | `hover:` | `group-hover/card:` |
| Pressed | `active:` | `group-active/card:` |
| Focus | `focus-visible:` | `group-focus-visible/card:` |

If the component has no group yet (no variants), the first state style on an inner element also adds `group/card` to the root.

A class for a breakpoint, a variant and a state at once stacks the prefixes in that order: `lg:data-[variant=ghost]:hover:shadow-lg`.

### A prop on an instance

Each control writes one prop where the component is used, as one edit:

```diff title="app/page.tsx"
-<PricingCard name="Pro" />
+<PricingCard name="Pro" price={49} featured size="lg" accent="#111111" />
```

Text is written as a string, a number in braces, a switch that's on as the bare name and off as `featured={false}`. Setting a prop to its default removes it instead. Picking a variant is the same thing: `<Card title="Oak" variant="ghost" />`.

### Svelte components

A Svelte component gets the same setup through its props:

```svelte title="src/lib/Card.svelte"
<script lang="ts">
  let { title, variant = 'primary' }: { title: string; variant?: 'primary' | 'ghost' } = $props()
</script>

<article class="rounded-2xl p-6 shadow-lg group/card" data-variant={variant}>
```

The roots are the file's top-level elements, and the group is named after the file. In Svelte 4 syntax the prop is `export let variant = 'primary'`.

### Without Tailwind 4

In a project that midcode styles itself, every one of these classes carries the prefix first: `mid:group/card`, `mid:data-[variant=ghost]:border`, `mid:group-hover/card:text-[#ff5b2e]`. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

### Attributes

Element settings write the attribute the way the file spells it: `autoPlay` and `htmlFor` in JSX, `autoplay` and `for` in Svelte. From the next release they also write in Vue, Astro and HTML files and in server templates.

When the element passes its props on (`<input {...props} />` inside a component), midcode minds who should own the value. On a page, the attribute is written on the instance you selected, so one field's placeholder doesn't change every field. In component mode it's written on the element in the component's file, before `{...props}`: a default that each use can still override.

## Limits

- midcode's variants live in one prop, called `variant`. Other props with a list of values (a `size`) are ordinary props: they get a choice under Props, not columns on the canvas.
- Variants already written in code are recognized and left alone: `cva`, `tailwind-variants`, or conditions on the `variant` prop. The Component section lists them and says to edit them in the code or ask your agent.
- A variant can't be added when the component is a class component, returns a fragment or no element of its own, has a root whose classes are a variable (`className={classes}`), has a root that already uses `data-variant` for something else, or has another component as its root that doesn't pass its props on (`{...props}`). The right panel says which, and how to fix it.
- Variants and states are for React and Svelte components and, from the next release, Vue and Astro components. Variables are for React components and, from the next release, for Svelte, Vue and Astro components too.
- In Svelte components, variants and states have not been tried in a running project: see [Open a component](#open-a-component) and [Svelte and SvelteKit](https://midcode.app/docs/frameworks/svelte.md).
- The states are Hover, Pressed and Focus. There's no row for disabled, checked or open.
- Text styles and link styles apply to every variant and state: pick them in Primary, Default.
- Props whose value is an expression, and `children`, are edited in the code or on the canvas, not in the Props section.
- A component that no page renders can't be opened in component mode.

---

# Variables

> Turn a component's text, image, link or style into a prop from the canvas, so each use of the component sets its own. The code before and after.

- Page: https://midcode.app/docs/editor/variables
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A variable is a prop of a component that you make from the canvas instead of typing it. A card that always says "Oak House" becomes a card whose title each page sets: you press a plus beside the text, and midcode declares the prop, gives it the text as its default, and makes the markup read it.

Nothing changes on screen when you make one. The value the element had is the prop's default, so every existing use of the component looks the same until one of them sets its own.

Variables are made in [component mode](https://midcode.app/docs/editor/components.md), in React components. From the next release, in [Svelte, Vue and Astro components](#svelte-vue-and-astro) too.

## Make a variable

1. Open the component (double-click an instance, or click it in Assets).
2. Select an element inside it.
3. In the right panel, find the property and press its plus, "Make it a variable". Beside Text, Link, Image and Video the plus is in the section's header. Beside a style it shows to the left of the row when you point at it.

These are the properties that have one:

| Property | Becomes | Name it starts with |
| --- | --- | --- |
| Text | The element's text | `title` on a heading, `label` on a button or a link, `text` elsewhere |
| Link | Its `href` | `link` |
| Image, Video | Its `src` | `image`, `video` |
| Color | An inline `color` | `color` |
| Background | An inline `backgroundColor` | `background` |
| Padding | An inline `padding` | `padding` |
| Gap | An inline `gap` | `gap` |
| Opacity | An inline `opacity` | `opacity` |
| Radius | An inline `borderRadius` | `radius` |

You aren't asked for a name. If the component already has a prop called `title`, the new one is `title2`; rename it afterwards in the Variables window.

Once a property is a variable, its control is replaced by a violet chip with the variable's name: the value is no longer the component's to set. Click the chip to edit the variable, or right-click it → "Remove variable".

## Set it where the component is used

Go back to the page (`Esc`), select an instance of the component, and look under "Props" in the right panel. Each variable is a control of its kind: a text field, an image picker, a color, a number. What you set there is written on that instance:

```diff title="app/page.tsx"
-<Card href="/work/pine" />
+<Card href="/work/pine" title="Pine Cabin" image="/images/pine.jpg" radius={24} />
```

How those controls are chosen is on [Components](https://midcode.app/docs/editor/components.md).

## The Variables window

The "Variables" button in the bar over the component canvas opens a window with every variable of the component (it shows how many there are). Pick one on the left to:

- change its **Name**. The rename follows the prop everywhere: its type, where the component reads it, and every instance that sets it.
- see its **Kind**: Text, Number, Color, Image or Link (a prop you wrote by hand can also be Yes / No, Choice or Code).
- change its **Default**, the value the component shows until a use sets it.
- see what it's **Used by**: a text, an attribute, a style.
- **Remove variable**.

The list is the component's props, so props you wrote by hand are there too. Props the component only passes on (`children`, `className`, `style`), event handlers and `variant` are left out.

## What midcode writes

Each of these is one edit, and one `⌘Z`. Start from this component:

```tsx title="components/Card.tsx"
interface CardProps {
  href: string
}

export function Card({ href }: CardProps) {
  return (
    <a href={href} className="block rounded-xl p-6">
      <img src="/images/oak.jpg" alt="" className="w-full" />
      <h3 className="text-xl font-semibold">Oak House</h3>
    </a>
  )
}
```

### A text

Select the heading and press the plus beside Text.

```diff title="components/Card.tsx"
 interface CardProps {
   href: string
+  title?: string
 }
 
-export function Card({ href }: CardProps) {
+export function Card({ href, title = 'Oak House' }: CardProps) {
   return (
     <a href={href} className="block rounded-xl p-6">
       <img src="/images/oak.jpg" alt="" className="w-full" />
-      <h3 className="text-xl font-semibold">Oak House</h3>
+      <h3 className="text-xl font-semibold">{title}</h3>
     </a>
   )
 }
```

### An attribute

Select the image and press the plus beside Image. The JSDoc line tells the Props section this string is an image, so instances get a file picker. A color gets `@control color`, a link `@control link`.

```diff title="components/Card.tsx"
 interface CardProps {
   href: string
   title?: string
+  /** @control image */
+  image?: string
 }
 
-export function Card({ href, title = 'Oak House' }: CardProps) {
+export function Card({ href, title = 'Oak House', image = '/images/oak.jpg' }: CardProps) {
   return (
     <a href={href} className="block rounded-xl p-6">
-      <img src="/images/oak.jpg" alt="" className="w-full" />
+      <img src={image} alt="" className="w-full" />
       <h3 className="text-xl font-semibold">{title}</h3>
     </a>
   )
 }
```

### A style

Select the card and press the plus beside Radius. A class can't take a value that's only known when the component renders, so a style variable is written inline, and the classes that used to set it are removed.

```diff title="components/Card.tsx"
   title?: string
   /** @control image */
   image?: string
+  radius?: number
 }
 
-export function Card({ href, title = 'Oak House', image = '/images/oak.jpg' }: CardProps) {
+export function Card({ href, title = 'Oak House', image = '/images/oak.jpg', radius = 12 }: CardProps) {
   return (
-    <a href={href} className="block rounded-xl p-6">
+    <a href={href} className="block p-6" style={{ borderRadius: radius }}>
```

The default is the radius the element had, in px. If the element already has a `style={{ … }}` object, the new key joins it.

### Other ways a component takes its props

midcode declares the prop the way the component already works:

- **No TypeScript**: there's no type to add to. The kind goes on the destructured name: `{ /** @control image */ image = '/images/oak.jpg' }`.
- **Props not destructured** (`function Card(props: CardProps)`): the markup reads `{props.title ?? 'Oak House'}`, and the type's member carries the default as `/** @default 'Oak House' */` so the Props section knows it.
- **No parameter yet** (`function Card()`): midcode adds one, `{ title = 'Oak House' }: { title?: string }`.

### Renaming

Renaming `title` to `heading` changes the type's member, the destructured name, every place the component reads it, and `title="…"` on every instance in the project.

### Removing

Removing a variable takes the prop out of the type and the destructuring, takes the attribute off every instance, and writes the default back where the prop was read: `{title}` is "Oak House" again, and `src={image}` is `src="/images/oak.jpg"` again.

A style variable is the exception. The inline style stays, with the default in it (`style={{ borderRadius: 12 }}`), and the class that was removed is not put back.

## Svelte, Vue and Astro (next release)

In the next release the plus is there in a `.svelte`, `.vue` or `.astro` component too, and the Variables window works the same. What changes is how each of them writes a prop being read:

| | Svelte | Vue | Astro |
| --- | --- | --- | --- |
| Text | `<h3>{title}</h3>` | `<h3>{{ title }}</h3>` | `<h3>{title}</h3>` |
| Attribute | `src={image}` | `:src="image"` | `src={image}` |
| Style | `style:border-radius="{radius}px"` | `:style="{ borderRadius: radius + 'px' }"` | `` style={{ borderRadius: `${radius}px` }} `` |

None of the three adds `px` to a number the way React does, so a length is written with its unit. Opacity stays a plain number.

The prop is declared where the component already declares its props:

- **Svelte**: in `$props()` with its type, as an `export let` in a component written that way, or in a new `<script>` when there's none.
- **Vue**: a member in the type of `defineProps<…>()` with its default in `withDefaults(…)` (put around `defineProps` when it isn't there) or in the destructuring; a property in `defineProps({ … })`; or the whole line in a component with no props yet.
- **Astro**: a member in `interface Props` and a default in `const { … } = Astro.props`. Both are added when the component has neither.

Renaming and removing follow every use of the component, as in React (`title="…"`, `:title="…"`, and `image-url` for `imageUrl` in a Vue template). They're refused when the component's own code also reads the prop, in a condition or a computed value for instance: midcode says "is also read by the component's own code", and the change is made there.

Not written: a Vue component on the Options API or one that lists its props as `defineProps([...])`.

## Limits

- In the released version variables are for React function components written in JSX, in a file midcode marks (`.tsx` and `.jsx` in Next.js and Vite projects, not a plain `.js` file). Svelte, Vue and Astro components come with the next release. Not class components.
- The element has to be written in the component's own file. An element that comes from another component inside it has no plus.
- Only plain text can become a variable. A text with code or other elements in it is refused ("Only a plain text can become a variable: this one has code or other elements in it").
- An attribute or a style that's already set from code can't be bound from the canvas: midcode says so and leaves it.
- A style variable replaces every class that set that property on the element, including its breakpoint, variant and state classes. One value from the instance wins everywhere.
- A padding variable is one number for all four sides. It starts from the element's top padding.
- A background image has no plus.
- A variable's name starts with a lowercase letter and has only letters and numbers (`title`, `imageUrl`). Names like `children`, `className`, `style` and `variant` are taken.
- Changing a default from the Variables window needs the prop to be destructured with its default. Otherwise midcode asks you to change it in the code.

---

# The free canvas

> In Next.js App Router projects, anything you draw, drop or paste outside the breakpoints floats on the canvas. How to use it, and the page it lives in.

- Page: https://midcode.app/docs/editor/free-canvas
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

In a Next.js project that uses the App Router, the canvas around the breakpoints is a place to work. Anything you draw, drop or paste there floats, the way a frame does in Framer. Build a section before it goes into a page, park something you took out, or keep alternatives side by side.

What floats is real code, in one page of your project that exists only in development and that midcode never publishes.

## Where it works

In Next.js projects that use the App Router (an `app/` or `src/app/` folder). From the next release, also in Next.js projects on the Pages Router and in Vite apps written in React, Preact or Solid ([Other React projects](#other-react-projects)), and, for plain elements, in [Vue, Svelte, Astro and HTML projects](#vue-svelte-astro-and-html). In every other project the canvas outside the breakpoints is empty space: `F` inserts a frame into the selection instead, and dropping there puts the element at the end of the page. If you drag an element out of a frame anyway, midcode says "Things float on the canvas in Next.js App Router projects, for now".

## Other React projects (next release)

In the next release the free canvas works the same in two more kinds of project. Only the file that holds what floats is somewhere else:

| Project | The file | Why it's never published |
| --- | --- | --- |
| Next.js, App Router | `app/midcode-scratch/page.tsx` | It answers 404 in production |
| Next.js, Pages Router | `pages/midcode-scratch.tsx` | Its `getStaticProps` answers "not found" in production |
| Vite + React, Preact or Solid | `src/midcode-scratch.tsx` | Nothing in your app imports it, so it's never built |

In a Vite app there is no route for that file. While midcode runs your dev server, its plugin answers `/midcode-scratch` with your own `index.html`, with the app's entry replaced by one that draws that component and loads the stylesheets your entry imports. midcode leaves the file out of Publish in all three.

A Vite app needs an `index.html` at its root for this: TanStack Start, Qwik and a Laravel app with Vite don't have the free canvas.

## Vue, Svelte, Astro and HTML (next release)

Outside React, what floats is plain HTML, the same in every one of these: a file with only the canvas's `<main>` in it.

| Project | The file |
| --- | --- |
| Vite + Vue, Vite + Svelte, SvelteKit, Astro | `src/midcode-scratch.html` |
| A folder of HTML | `midcode-scratch.html`, beside your `index.html` |

It isn't a page of the site. While midcode runs the site it serves a page around that file, at `/midcode-scratch.html`, with your stylesheets: the ones your entry, `App.vue`, the root `+layout.svelte` or your Astro layouts import, or in a folder of HTML the `<head>` of your home page. midcode leaves the file out of Publish.

Because the file is HTML and not a `.vue`, `.svelte` or `.astro` file, only plain elements can float:

- A component can't: "A component can't float on the canvas in this kind of project: only plain elements do."
- An element with something computed in it can't either (`{{ title }}`, a `v-for`, an `{#if}`, a bound attribute): "This has code in it ({{ }}, a loop, a condition): only plain elements float on the canvas in this kind of project."

Everything else works as in React: draw a frame, drop something from Insert, drag an element out of a page and back in, copy with `⌥`, wrap several in a stack, move them with the arrows. Going into a `.svelte` or `.astro` page, an element whose text has a `{` or a `}` is refused, since the page would read it as code.

Nuxt and the templates a server renders (Laravel, Django, Rails, WordPress, Shopify themes) don't have the free canvas.

## Put something on the canvas

| To | Do this |
| --- | --- |
| Draw a frame | Press `F` (or the frame button in the toolbar) and drag on the canvas. A label shows the size. A click without dragging makes one of 200 × 200. `Esc` puts the tool away. |
| Take an element out of a page | Drag it out of its frame and release over the empty canvas. |
| Copy an element out of a page | The same, holding `⌥`: the element stays and a copy floats. |
| Add something new | Drag an item from the [Insert](https://midcode.app/docs/editor/insert.md) panel, or a component from Assets, and release over the empty canvas. |
| Add an image or a video | Drop files from Finder on the empty canvas, or press `⌘V` with an image on the clipboard and nothing selected. See [Text, images and video](https://midcode.app/docs/editor/text-and-media.md). |
| Paste an element | `⌘C` on any element, deselect (`Esc`), `⌘V`. The copy lands in the middle of what's in view. |

A floating element is designed at the primary breakpoint's width: its responsive classes show the values of that breakpoint.

An element with no width of its own is as wide as its content. A text or a stack that has nothing behind it is shown over your page's background color, so light text chosen for a dark page stays readable. Frames and images float as they are.

## Select and arrange

Click a floating element to select it. It works like any other selection: the right panel edits it, a double-click edits its text, and its own layers are in [Layers](https://midcode.app/docs/editor/layers.md), after the breakpoints.

| To | Do this |
| --- | --- |
| Move | Drag it. A label shows its position. |
| Move by 1 px | Arrow keys. With `⇧`, by the nudge amount set in Settings. |
| Resize | Drag any of its eight handles. `⇧` on a corner keeps the proportions. |
| Rotate | Drag just outside a corner. `⇧` turns in steps of 15°. |
| Select several | Drag a box over them on the empty canvas, or `⇧` + click each one. `⌘A` with nothing selected takes all of them. |
| Duplicate | `⌘D`, or hold `⌥` while dragging. |
| Delete | `⌫` |
| Wrap in a stack | Select several and press `⇧A`. |

Several selected elements move together, with the pointer or the arrow keys, and `⌘C`, `⌘X`, `⌘D` and `⌫` apply to all of them.

A copy never lands on top of its original. `⌘D` and `⌘V` put it to the right of what's selected, 40 px away. Copies of several keep their places among themselves.

`⇧A` on floating elements makes one floating stack in their place. It's a row if they sit side by side and a column if they sit one above the other, in that order, and the space between them becomes its gap.

### Snapping

While you move or resize a floating element, it lines up with the edges and centers of the other floating elements, with the breakpoints' frames, and with guides. It also snaps to the same distance its neighbours keep. Lines and distances show what it found.

Hold `⌘` or `⌃` to move freely. `⇧` keeps the move on one axis. Rulers and guides are covered in [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md).

## Into a page and back

Drag a floating element over a breakpoint. The blue line shows where it would land in the page, as when you [move an element](https://midcode.app/docs/editor/select-move-resize.md). Release, and it's written into the page's file, at that place, without its canvas marks. The imports it needs go with it.

Drag it over another floating element instead and it goes inside that one.

Going the other way, an element dragged out of a page is cut from its file and written into the canvas page, with its imports. Either direction is one edit: one `⌘Z` puts the element back where it was.

What can't cross is an element that depends on where it's written, like an item inside a `.map()` that reads the loop's values: "This element uses post from its file: move it in the code."

## What midcode writes

Everything that floats lives in one file: `app/midcode-scratch/page.tsx` (under `src/app/` if that's where your app is, and `.jsx` if the project has no `tsconfig.json`). midcode creates it the first time something floats:

```tsx title="app/midcode-scratch/page.tsx"
import { notFound } from 'next/navigation'

// What floats on midcode's canvas, outside the site's breakpoints. It only exists in development
// (a 404 on the live site), and midcode never publishes it.
export default function MidcodeCanvas() {
  if (process.env.NODE_ENV === 'production') notFound()
  return (
    <main data-midcode-scratch>
    </main>
  )
}
```

Each floating element is a direct child of that `<main>`, with two attributes: an id, and where it sits.

```tsx title="app/midcode-scratch/page.tsx"
import { notFound } from 'next/navigation'
import { PricingCard } from '@/components/PricingCard'

// What floats on midcode's canvas, outside the site's breakpoints. It only exists in development
// (a 404 on the live site), and midcode never publishes it.
export default function MidcodeCanvas() {
  if (process.env.NODE_ENV === 'production') notFound()
  return (
    <main data-midcode-scratch>
      <div data-midcode-item="3f9a1c2e" data-midcode-at="2960 80" className="h-[320px] w-[480px] bg-white" />
      <h2 data-midcode-item="b71d04aa" data-midcode-at="2960 480" className="text-4xl font-semibold">
        Simple pricing
      </h2>
      <div data-midcode-item="0c5e77d1" data-midcode-at="3520 80" data-midcode-wrap>
        <PricingCard plan="Studio" />
      </div>
    </main>
  )
}
```

| Attribute | What it is |
| --- | --- |
| `data-midcode-scratch` | Marks the `<main>` that holds everything floating. |
| `data-midcode-item` | The element's id on the canvas: eight characters, unique in the file. |
| `data-midcode-at` | Its position, `x y`, in canvas px. `0 0` is the top left corner of the first breakpoint's frame. The rulers show the same coordinates. |
| `data-midcode-wrap` | On the `<div>` around a component. A component might not pass unknown attributes on to its element, so the marks go on a wrapper. |

The first element above is a frame drawn with `F`: a `<div>` with its size and a white fill.

Every gesture is an edit of that file:

- Moving changes `data-midcode-at`. That's why `⌘Z` moves an element back.
- Resizing writes `w-*` and `h-*`. From the left or the top it changes the position too.
- Rotating writes a class: `rotate-[12deg]`. Back at 0°, the class is removed.
- Going into a page removes the two attributes (and the wrapper around a component) and moves the code to the page's file.

### Never published

- The page calls `notFound()` when `NODE_ENV` is `production`. On your live site, `/midcode-scratch` answers 404.
- midcode leaves it out of [Publish](https://midcode.app/docs/publish/publish.md): it's never in the list of files, and its edits aren't in the list of changes.
- It isn't in the Pages list or in the texts of [Languages](https://midcode.app/docs/data/languages.md).

> [!NOTE]
> The file is not in `.gitignore`, on purpose. Tailwind doesn't scan files that git ignores, so the classes of what floats would never be generated: a drawn frame would have no size. That means `git add -A` in a terminal does stage it. Committing it is harmless (it's a page that answers 404 in production), but if you'd rather not, leave it out of your own commits, don't ignore it.

### Editing the file by hand

You or your agent can write in it. The rules are the ones above: everything directly inside `<main data-midcode-scratch>` needs its own `data-midcode-item` and a `data-midcode-at`. When midcode reads a file that breaks them, it repairs it:

- two elements with the same id: the second gets a new one;
- an element with no marks: it gets them, where what's inside it was, or below everything else;
- marks on an element nested inside a floating one: removed.

Delete the file (or the `midcode-scratch` folder) to clear the canvas. midcode makes a new one the next time something floats.

## Limits

- In the released version, Next.js App Router only. The next release adds the Pages Router, Vite apps in React, Preact or Solid, and, for plain elements, Vue, Svelte, Astro and folders of HTML. Nuxt and server templates don't have it yet.
- A floating element shows the primary breakpoint's styles. To see something at other widths, put it in a page.
- A component floats inside a wrapper `<div>` that is as wide as its content, unless you give the wrapper a width.
- Dragging into another floating element works for one element at a time, not for several selected together.
- The canvas page is a page of your app: it renders inside your root layout, so the layout's providers, fonts and global styles apply to what floats.

---

# Pages and navigation

> The page menu of the top bar, the page tree and its order, creating and removing pages, the pages of a dynamic route, and the Assets tab.

- Page: https://midcode.app/docs/editor/pages
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

The canvas shows one page of your site at a time. Which one is in the top bar, next to the branch: the page's path ("Home" for `/`). Click it and a menu opens with a search field, the page tree, and, on a dynamic route, the list of that route's pages.

Pages aren't something midcode keeps: the tree is read from your project's files, the way your framework reads them.

## Go to a page

- Click the page in the top bar, then click a page in the tree.
- Type in the field to filter the tree.
- Type a path that starts with `/` and press `Enter` to go straight there, listed or not. That's how you reach a page midcode didn't find.

The breakpoints move to the new page without reloading the editor, and your selection is cleared.

## The page tree

Routes are shown as a tree by their path: `/work/process` sits inside `/work`. Home comes first. A row with a folder icon is a path that has pages inside it; a row with a database icon is a dynamic route (`/work/[slug]`), with the number of pages found for it. Point at a row to see its file.

Right-click a page for its menu:

| Item | Does |
| --- | --- |
| Open | Goes to the page |
| Find its pages again | On a dynamic route: looks for its pages again |
| Copy path | Copies `/work/process` |
| Open code | Opens the page's file in the [code view](https://midcode.app/docs/editor/code.md) |
| Page settings… | Its title, description and social image, in Next.js projects and, from the next release, in a folder of plain HTML (see [Site settings](https://midcode.app/docs/editor/site-settings.md)) |
| New page inside | Starts a new page under this one, where midcode can [create pages](#create-a-page) |
| Remove | Moves the page's file to the Trash, where midcode can [remove pages](#remove-a-page) |

### Reorder

Drag a page above or below its siblings; a blue line shows where it lands. Pages only reorder among the pages of the same parent, and Home stays first.

The order is yours, not your framework's, so midcode keeps it in a small file that travels with the project:

```json title=".midcode/pages.json"
{
  "version": 1,
  "order": [
    "/work",
    "/work/[slug]",
    "/about",
    "/contact"
  ]
}
```

Pages that aren't in the list come after, in alphabetical order. The file only affects midcode's tree. See [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

## Create a page

In a Next.js project with the App Router:

1. Click the plus beside "Pages" in the menu ("New page"), or right-click a page → "New page inside".
2. Type its path, like `/about` or `/work/process`.
3. Click "Create page".

midcode writes a `page.tsx` for it in your app folder. It goes next to its closest parent that already has a page, so route groups are respected: with `/work` at `app/(site)/work/page.tsx`, the page `/work/process` is `app/(site)/work/process/page.tsx`. With no parent, it goes beside the home page.

```tsx title="app/about/page.tsx"
export default function Page() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h1 className="text-4xl font-semibold">About</h1>
      <p className="mt-4">A new page, made in midcode.</p>
    </main>
  )
}
```

The path is cleaned as you'd expect (lowercase, dashes for anything that isn't a letter, a number, `_` or `-`), and the heading is its last part in words. The canvas goes to the new page as soon as your dev server answers for it.

Creating a page is not a step in the undo history. To take it back, remove the page.

### Other frameworks (next release)

The next release creates and removes pages in more kinds of project, each the way its framework keeps them. A new page at `/about` is:

| Project | What's written |
| --- | --- |
| Astro | `src/pages/about.astro`, inside the layout the home page uses, or as a whole document with the home page's stylesheets |
| SvelteKit | `src/routes/about/+page.svelte` |
| Nuxt | `pages/about.vue` (or `app/pages/`), when the project has a pages folder |
| Plain HTML | `about.html` at the top of the site, with a copy of the home page's `<head>` |
| Remix | `app/routes/about.tsx` |
| React Router | `app/routes/about.tsx`, and its `route("about", "routes/about.tsx")` line in `app/routes.ts` |
| TanStack Router | `src/routes/about.tsx`, with its `createFileRoute('/about')` |
| Qwik City | `src/routes/about/index.tsx` |
| Hugo | `content/about.md` |
| Jekyll | `about.md`, with the home page's layout and a permalink |
| Eleventy | `about.njk` (or the home page's own extension), with its layout |
| Laravel | `resources/views/about.blade.php`, and `Route::view('/about', 'about');` at the end of `routes/web.php` |

The page gets utility classes only when the project has Tailwind in its `package.json`. In a folder of plain HTML, new pages go at the top of the site, not in subfolders. Remix needs its `app/routes` folder and React Router its `app/routes.ts`.

In any other kind of project the plus isn't shown: a Vite app without file routes, Angular, Django, Rails, Flask. Pages there are written in code, by you or your agent.

## Remove a page

Right-click a page → "Remove". midcode asks first, then moves the page's file to the Trash, so you can put it back from there or from git. If the page was the only file in its folder, the folder goes with it. Pages inside it stay. Home can't be removed.

If the canvas was on that page, it goes back to Home.

In the released version this is for Next.js projects. In the next release it also works in the projects listed above, and takes out the line that names the page in `app/routes.ts` or `routes/web.php`.

## Dynamic routes

A route like `/work/[slug]` is many pages. The canvas shows one of them, the last one you looked at, and the top bar names it: `/work / Oak House`, with the number of pages found. Open the menu to switch: the section "Pages of /work/[slug]" lists them.

midcode finds those pages on your running site, whatever your data source is:

- the site's `/sitemap.xml`;
- the links on the route's parent page (`/work`), then on the home page, then on the other pages;
- the page's own `generateStaticParams`, for pages nothing links to: the values written there, or the field it maps from an imported list (`projects.map((p) => ({ slug: p.slug }))`). Only the ones your dev server answers are kept.

Each page is named by its `<title>`, without the part every title shares, or by its `<h1>`. Up to 200 pages are listed per route. If none are found, midcode says so: link to one from your site, or type its path in the field. "Find its pages again" looks again after you add content.

A dynamic route is one file, so a change to its layout or its styles shows on every one of its pages. Text that comes from your data is changed where the data is written: see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md) and the [CMS](https://midcode.app/docs/data/cms.md).

## Where pages come from

| Project | The tree lists |
| --- | --- |
| [Next.js](https://midcode.app/docs/frameworks/nextjs.md) | Every `page` file under `app/` and every file under `pages/` (also inside `src/`). Route groups like `(site)` don't show in the path; folders starting with `_` or `@`, and `api`, are skipped. |
| [React Router and Remix](https://midcode.app/docs/frameworks/react-router.md) | The routes of `app/routes.ts`, or the files of `app/routes/` |
| [Astro](https://midcode.app/docs/frameworks/astro.md) | The files of `src/pages/` |
| [SvelteKit](https://midcode.app/docs/frameworks/svelte.md) | Every `+page` under `src/routes/` |
| [Nuxt](https://midcode.app/docs/frameworks/nuxt.md) | The `.vue` files of `pages/` |
| [Plain HTML](https://midcode.app/docs/frameworks/html.md) | Every `.html` file, at the path it's served from |

A project whose routes are only in code (a Vite app with its own router, for instance) lists only Home. Type a path to go anywhere else.

### More stacks (next release)

The next release also reads the file routes of [TanStack Start](https://midcode.app/docs/frameworks/tanstack-start.md) and Qwik City, the routes of [Angular](https://midcode.app/docs/frameworks/angular.md), [Laravel](https://midcode.app/docs/frameworks/laravel.md), [Rails](https://midcode.app/docs/frameworks/rails.md), [Django and Flask](https://midcode.app/docs/frameworks/python.md), the pages of [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md) and Gatsby (see [Create React App, Vue CLI, Gatsby, Docusaurus](https://midcode.app/docs/frameworks/webpack.md)), and the templates of a [Shopify theme](https://midcode.app/docs/shopify/themes.md).

## The Assets tab

The Assets tab of the left panel lists what the project is built from, read from the code. Its search field filters all three groups.

- **Templates**: the layouts every page sits in (the App Router's `layout` and `template` files). The root one is "Site layout". Click one to open its code.
- **Components**: your components, grouped by folder. In `.tsx` and `.jsx` files these are the exported components (a function or a constant whose name starts with a capital letter); a `.svelte` file is one component. From the next release, `.vue` files and `.astro` files outside your pages and layouts are listed too. Click a component to [edit it on its own canvas](https://midcode.app/docs/editor/components.md). Drag it onto the canvas to add an instance: midcode writes `<Card />` and its import. The number beside it is how many are on the page you're looking at. Right-click for "Select on page", "Open code" and "Copy reference for your agent".
- **Styles**: your colors, fonts, text styles and link styles. See [Theme and design tokens](https://midcode.app/docs/styling/theme.md).

## Limits

- A new Next.js page is always an App Router `page.tsx`, with the starting markup above. In a project that only has the Pages Router (`pages/`), midcode still writes it under `app/`: add pages to `pages/` in the code instead.
- A page can't be renamed or moved from the tree. Rename its file or folder in [Code mode](https://midcode.app/docs/editor/code.md), or ask your agent.
- A dynamic route's pages are found on the running site, so they need the dev server, and a page that no sitemap, link or `generateStaticParams` leads to isn't listed. You can still type its path.
- React Router routes nested under `prefix()` show without the prefix.

---

# Site settings

> Title, description, language, favicon and social image for the site and for each page. In a Next.js project they're written as metadata in your code.

- Page: https://midcode.app/docs/editor/site-settings
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Site settings is where the things a search engine or a shared link shows are set: the title, the description, the favicon, the social image. There's one form for the site and one for each page, and everything you type is written as Next.js metadata in your own files.

In the released version it's for Next.js projects, and it needs the App Router: `metadata` is written in the root layout. In a project that isn't Next.js the button isn't there. The next release brings it to [other kinds of project](#other-projects), where the same settings are tags in the site's `<head>`. Everything up to that section is about Next.js.

## Open it

Click the globe in the top bar ("Site settings"). The settings take the canvas's place, with a list on the left: "General" under Site settings, then every page under Page settings. To go straight to a page's form, right-click the page in the [page menu](https://midcode.app/docs/editor/pages.md) → "Page settings…".

`Esc` goes back to the canvas. A field is saved when you leave it, or on `Enter`.

## The site

| Field | What it is |
| --- | --- |
| Title | The title of Home, and of every page that has none of its own |
| Title template | How a page's title is completed, with `%s` where the page's title goes: `%s · Oak Studio` |
| Description | The site's description |
| Language | The language of the site, like `en` or `es` |
| Site URL | The address the site is published at. Next.js uses it to make the addresses in share links absolute (the social image's, for instance). |
| Search engines | Off asks search engines not to index the site |
| Favicon | A square image, 64 × 64 pixels or more |
| Social preview | The image a shared link shows, 1200 × 630 pixels |

Beside the fields, a preview shows the title and description the way a search result would.

## A page

Each page has a Title, a Description, the Search engines switch and its own Social preview. The page's title goes into the site's template, and the preview shows the result. A page without a social image uses the site's.

### Dynamic pages

A route like `/work/[slug]` is one form for all its pages, so its title and description can take values from the item each page shows. Under the fields, midcode lists the variables it found: the fields the page reads from its item, and the keys of the data it comes from. Click one to put it at the cursor, or type it yourself in double braces:

```text
{{name}} · Work
```

The preview fills the variables with the first item's values. The social preview can come from a field too: choose it in the list, next to "Upload an image…".

### Client components

`metadata` can't be exported from a file that starts with `'use client'`. For such a page midcode writes the metadata in a `layout.tsx` beside it, and the form says so.

## What midcode writes

Each text field is one edit that changes one value (or adds one property) and goes through the history: `⌘Z` takes it back, and it shows in [Publish](https://midcode.app/docs/publish/publish.md).

### The site

The site's fields go in `export const metadata` of the root layout. Here are several edits at once (title, template, description, site URL, and Search engines turned off):

```diff title="app/layout.tsx"
 export const metadata: Metadata = {
-  title: 'Create Next App',
-  description: 'Generated by create next app',
+  title: { default: 'Oak Studio', template: '%s · Oak Studio' },
+  description: 'Furniture made to last.',
+  metadataBase: new URL('https://oak.studio'),
+  robots: { index: false },
 }
```

Language is the `lang` of the layout's `<html>`:

```diff title="app/layout.tsx"
-    <html lang="en">
+    <html lang="es">
```

If the layout has no `metadata` yet, midcode adds `export const metadata: Metadata = { title: 'Oak Studio' }` after the imports, and the `import type { Metadata } from 'next'` it needs in a TypeScript file. Turning Search engines back on removes `robots` again. Other keys you wrote in the object are never touched.

### A page

A page's fields go in the `metadata` its own file exports:

```diff title="app/about/page.tsx"
 export const metadata: Metadata = {
-  title: 'About',
+  title: 'About us',
+  description: 'Who we are and how we work.',
 }
```

### A dynamic page

Variables need code that runs for each item, so midcode writes `generateMetadata`, reading the same item the page shows. Given this page:

```tsx title="app/work/[slug]/page.tsx"
import { notFound } from 'next/navigation'
import { projects } from '@/content/projects'

export function generateStaticParams() {
  return projects.map((p) => ({ slug: p.slug }))
}

export default async function ProjectPage({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const project = projects.find((p) => p.slug === slug)
  if (!project) notFound()
  return <main>…</main>
}
```

setting the title to `{{name}} · Work` adds:

```diff title="app/work/[slug]/page.tsx"
 import { notFound } from 'next/navigation'
 import { projects } from '@/content/projects'
+import type { Metadata } from 'next'
 
 export function generateStaticParams() {
   return projects.map((p) => ({ slug: p.slug }))
 }
 
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }): Promise<Metadata> {
+  const { slug } = await params
+  const project = projects.find((p) => p.slug === slug)
+  return { title: `${project?.name} · Work` }
+}
+
```

The parameter and the lookup are copied from the page's own component. From then on each field is one more property of the object it returns: a description of `{{summary}}` adds `description: project?.summary`, and a social preview from the `cover` field adds `openGraph: { images: project?.cover }`.

If the page had a static `metadata`, `generateMetadata` replaces it and carries its other keys over.

### Images

Images aren't written in code. They're saved as the files Next.js looks for:

| Image | File |
| --- | --- |
| Favicon | `app/icon.png` (or `.svg`, `.jpg`…; an `.ico` is saved as `app/favicon.ico`) |
| The site's social preview | `app/opengraph-image.png` |
| A page's social preview | `opengraph-image.png` in the page's folder, like `app/about/opengraph-image.png` |

The file keeps its extension. The image it replaces goes to the Trash.

### A client page

```tsx title="app/contact/layout.tsx"
import type { Metadata } from 'next'

export const metadata: Metadata = { title: 'Contact' }

export default function Layout({ children }: { children: React.ReactNode }) {
  return children
}
```

That file is created the first time you set a field on a page that is a client component, next to its `page.tsx`.

## Other projects (next release)

In the next release the globe is also there in projects whose `<head>` is written in a file. The form is the same, and what it writes is HTML tags instead of Next.js metadata.

| Project | Where the site's `<head>` is |
| --- | --- |
| Vite, plain HTML | `index.html` |
| Angular | `src/index.html` |
| SvelteKit | `src/app.html` |
| Create React App, Vue CLI | `public/index.html` |
| Astro | The first layout in `src/layouts/` that has a `<head>`, or `src/pages/index.astro` |
| A site a server renders (Laravel, Django, Rails, Hugo, Jekyll, Eleventy…) | Its layout: the first template that closes a `<head>` |

Setting the title, the description, the language, turning Search engines off and choosing both images in a new Vite project leaves this:

```diff title="index.html"
 <!doctype html>
-<html lang="en">
+<html lang="es">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" href="/favicon.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + React</title>
+    <title>Oak Studio</title>
+    <meta name="description" content="Furniture made to last." />
+    <meta name="robots" content="noindex" />
+    <meta property="og:image" content="/og-image.jpg" />
   </head>
```

- A tag that's already there has its value changed. A new one goes last in the `<head>`, indented like its neighbours and closed the way they are (`>` or `/>`).
- Images are copied into the folder the site serves as it is (`public/`, `static/` in SvelteKit, next to the pages in a folder of HTML) as `favicon.png` and `og-image.jpg`, keeping their extension. Removing an image takes its tag out and leaves the file, since something else may use it. If midcode can't tell which folder that is, it asks you to put the image there and link it in the code.
- Turning Search engines back on removes the `robots` tag.
- There's no Title template and no Site URL: those are Next.js metadata, and a `<head>` has no tag for them.
- Pages have their own form only in a folder of plain HTML, where each page has its own `<head>`. Everywhere else a page takes the site's.
- What a template or a bundler computes is shown as code and left alone: `{{ .Site.Title }}`, `@yield('title')`, `<%= htmlWebpackPlugin.options.title %>`, `%VITE_APP_TITLE%`. Trying to set it answers "This is written in code here: change it in public/index.html."

It has been tried with plain HTML, Vite + Vue, SvelteKit, Astro, Hugo, Jekyll, Laravel and Vue CLI.

### Nuxt and Docusaurus

These two don't write a `<head>`: they say what goes in it in the object their config file exports. midcode reads the settings from that object and writes them into it.

| Setting | Nuxt (`nuxt.config`) | Docusaurus (`docusaurus.config`) |
| --- | --- | --- |
| Title | `app.head.title` | `title` |
| Description | An item of `app.head.meta`: `{ name: 'description', content }` | `tagline` |
| Language | `app.head.htmlAttrs.lang` | `i18n.defaultLocale`, and its place in `i18n.locales` |
| Hidden from search engines | An item of `app.head.meta`: `{ name: 'robots', content: 'noindex' }` | `noIndex: true` |
| Favicon | An item of `app.head.link`: `{ rel: 'icon', href }`, the file in `public/` | `favicon`, the file in `static/img` |
| Social image | An item of `app.head.meta`: `{ property: 'og:image', content }`, the file in `public/` | `themeConfig.image`, the file in `static/img` |

Each edit is one value, or a new property or item written like the ones beside it, and the file has to still parse afterwards. A value the config computes shows as code and isn't written. In a Docusaurus site with several languages, a new default language has to be one of the listed `locales` already. Tried with Nuxt 4 and Docusaurus 3.

### Not covered

React Router and Remix write their `<head>` in a component (`app/root.tsx`), Gatsby keeps these settings in its own config, and WordPress keeps them in its database: midcode doesn't write those yet.

## Analytics (next release)

In the next release, Site settings has an "Analytics" row under "Search engines". Pick a provider, give it the ID it asks for, and midcode writes that provider's script into the site. Pick "None" and the script is taken out. Either one is a single edit you can undo, and it shows in Publish like any other.

| Provider | It asks for | What's written |
| --- | --- | --- |
| Vercel Analytics | Nothing | `<script defer src="/_vercel/insights/script.js">` |
| Plausible | The site's domain | Plausible's script, with `data-domain` |
| Umami | The website ID | Umami's script, with `data-website-id` |
| Google Analytics | The measurement ID (`G-…`) | The `gtag.js` script and the short snippet that starts it |

Nothing is written until the ID is there, and an ID that doesn't look like the provider's is refused. Changing provider replaces the old tags with the new ones. A site that already has one of these scripts shows it here; a self-hosted Plausible or Umami keeps the address its script loads from.

Where the tags go follows the rest of Site settings:

- **Next.js (App Router)**: JSX, last in the `<body>` of `app/layout.tsx`.
- **A `<head>` in markup** (`index.html`, `src/app.html`, an Astro layout, the layout of a site a server renders): last in the `<head>`.
- **Nuxt**: an entry in `app.head.script` in `nuxt.config`. **Docusaurus**: an entry in `scripts` in its config. Google Analytics isn't written there: Docusaurus sets it up with its own plugin.

midcode installs nothing: the tags are your site's. They count visits on the published site, not in the canvas. Vercel Analytics also has to be turned on for the project in Vercel.

### The numbers

"Analytics", under "General" in the list on the left, shows the site's visits for the last 7, 30 or 90 days: visitors, visits, pageviews, bounce rate and visit length, a chart by day, the top pages and where visits come from.

It works for Plausible and Umami, which answer with an API key. The first time, the view asks for one:

- **Plausible**: Account settings → API keys → New API key, of the "Stats API" kind.
- **Umami Cloud**: Settings → API keys → Create key.

midcode tries the key before keeping it, and says so when the provider refuses it or the key isn't for this site. The key is kept encrypted on your Mac, is sent only to that provider (to the server your script is loaded from, when you host it yourself) and is never shown again. "Forget the key" removes it.

Google Analytics and Vercel Analytics don't give their numbers this way: for those the view has a button that opens their own page.

## Limits

- These limits are about Next.js projects. Site settings needs the App Router: without a root layout (`app/layout.tsx` or `src/app/layout.tsx`), the site form answers "This project has no root layout (app/layout.tsx)."
- Metadata that's built in code is shown, not edited. A value that isn't plain text appears as code under "Written in code", and a click opens the file. If `metadata` is a variable or the result of a call, or the root layout uses `generateMetadata`, the form says the metadata is built in code and sends you to the file.
- A page that isn't dynamic and exports no `metadata` yet doesn't get one from the form. The write is refused with "Couldn't tell which item this page shows". Add `export const metadata = {}` to the page's file (or ask your agent) and the fields write into it.
- Variables need midcode to tell which item the page shows: a page component that takes `params` and looks its item up with them, as in the example. When it can't, it asks you to write `generateMetadata` yourself. The same goes for variables on a page that is a client component.
- The fields are the title, the description, indexing, the site URL and the social image. Keywords, Twitter cards, canonical URLs and the rest of Next.js metadata are left as you wrote them.
- Images, and the layout created for a client page, show in Publish but aren't steps in the undo history. A replaced image is in the Trash.

---

# Code view

> Edit your project's code inside midcode: one element's file beside its preview, or the whole project with tabs, a file tree, a terminal and your agent.

- Page: https://midcode.app/docs/editor/code
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Not every change is a visual one. midcode has its own code editor for the moments you want the file itself, so you don't have to leave for another app. There are two ways into it:

- **Open code** shows the file of one element, with the page beside it.
- **Code mode** turns the whole window into your project as code: files, tabs, a terminal, and your agent.

Both are the same editor on the same files, and saving works the same in both: one undoable edit that shows up in [Publish](https://midcode.app/docs/publish/publish.md).

## Open code: one file beside its preview

"Open code" is in several places:

- the right-click menu of an element, on the canvas or in Layers;
- the "Code" section of the right panel: point at a row and click the icon;
- the right-click menu of a page in the [page menu](https://midcode.app/docs/editor/pages.md), and of a component or a layout in Assets.

It opens three columns in place of the canvas:

1. **The file**, with the cursor on the element's line.
2. **A preview**: the page at the breakpoint the element was selected in, the whole page scaled to the column's width, with the element outlined and scrolled into view. Its header says which breakpoint, and "Updates when you save".
3. **The right panel**, the same one as on the canvas, so you can still style what's selected.

Click another element in the preview and the editor goes to its code, in whatever file that is.

The header of the file has four controls: "Reload from disk", "Open in your code editor", "Save" (`⌘S`) and close (`Esc`). If you close with unsaved typing, midcode asks first; the typing is kept as a draft for that file until you quit midcode.

In [component mode](https://midcode.app/docs/editor/components.md), "Open code" on something in the component's file doesn't leave the canvas: the file opens in a pane beside the grid, at that line. The same pane opens with the code button of the component's bar.

## Code mode

Switch from Design to Code in the middle of the top bar. The canvas stays loaded behind, so switching back is instant.

| Where | What |
| --- | --- |
| Left | Your agent (see [Your agent in midcode](https://midcode.app/docs/agents/overview.md)). Its collapse button puts the panel away while the agent keeps running; a thin rail brings it back. |
| Center | The open files as tabs, and the editor |
| Below | The terminal, when it's open |
| Right | The project's files |

### Files

The tree on the right is your project folder. Click a file to open it in a tab. Folders that aren't your own code (`node_modules`, `.next`, `.git`, `dist`, `build` and the like) and dotfiles are dimmed; `.env` files are not.

The buttons above the tree make a new file or a new folder and read the tree again. Right-click a file or a folder for "New file", "New folder", "Rename", "Copy path", "Show in Finder" and "Move to Trash". Files that were created or renamed outside midcode (by your agent, in the terminal) appear when midcode gets the focus back.

### Tabs and the editor

A dot on a tab means unsaved changes. Closing such a tab asks first, and in Code mode closing it drops the changes. A middle click closes a tab.

The editor colors TypeScript, JavaScript and JSX, CSS and SCSS, JSON, Markdown, and HTML (which is also how `.vue`, `.svelte` and `.astro` files are colored). It has line numbers, folding, bracket matching, search and replace (`⌘F`), and indents with `Tab`.

### The preview beside the code

The play button at the end of the tab bar ("Preview beside the code") opens your site next to the editor.

- If the open file is a page's own file, the preview shows that page. Otherwise, and for a dynamic route, it shows the page the canvas is on.
- A list in its header chooses the breakpoint, and the buttons beside it reload and close the preview.
- It updates with every save.
- Click an element in it and the editor opens the file where that element is written, at its line.

### Terminal

Press `` ⌃` `` or click "Terminal" in the bar at the bottom. It's a real terminal in the project's folder: your login shell, with the same `PATH` as your own terminal app.

A terminal keeps running when you close its panel, switch back to Design or look at another project tab, and shows where it was when you open it again. It ends when you close the project's tab or quit midcode.

## Saving

`⌘S` saves the file in front. A save is:

- **one step in the undo history.** Outside the editor, `⌘Z` takes the whole save back, like any other edit. While the editor has the focus, `⌘Z` and `⇧⌘Z` are the editor's own undo and redo, for your typing.
- **one entry in Publish**, named "Code edit in page.tsx".
- **refused if the file changed since you opened it.** midcode never writes over someone else's change: it says "app/page.tsx changed since you opened it. Reload it, then save again."

The editor follows the file while it's open. After an edit on the canvas, an undo, or an edit your agent made through the chat, the text updates by itself. Unsaved typing is never replaced.

The "Open code" editor also checks the disk every few seconds and whenever midcode gets the focus, so changes made outside midcode (the terminal, another editor) show up too. With unsaved typing it shows a "Changed on disk" mark instead, and "Reload from disk" takes the file's version and drops your typing. A Code mode tab doesn't watch for outside changes: if a save is refused there, close the tab and open the file again.

A new file made in the file tree is recorded too, as "New file" with its path. Renaming a file and moving one to the Trash act on the disk directly: they aren't steps in the undo history. A file in the Trash can be put back from there.

## Your own editor

"Open in your code editor" opens the same file, at the same line, in the editor you use. Which one is in Settings (`⌘,`) → "Code editor": Automatic (the first one installed among Cursor, Visual Studio Code, Windsurf and Zed), one of those four, or "Default app for the file".

Nothing stops you from keeping your editor open on the project all the time. midcode reads the files from disk and shows what's there.

## What midcode writes

Exactly what you typed. A save replaces the file's content with the editor's, and `git diff` shows your change and nothing else: midcode doesn't format the file, sort imports or touch other lines.

## Limits

- Files larger than 2 MB aren't opened, and neither are binary files.
- "Open code" opens code, styles and content files: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.css`, `.scss`, `.json`, `.md`, `.mdx`, `.html`, `.svg`, `.txt` and `.yml`. For anything else (a `.svelte`, `.vue` or `.astro` file, a server template) "Open code" answers "midcode can't open this kind of file": use Code mode, which opens any text file.
- The editor doesn't complete code, check types or show errors. For that, open the file in your own editor.
- Unsaved typing in a Code mode tab is lost if you close the tab or quit midcode.
- Renaming or moving a file doesn't update the imports that point to it.

---

# Comments

> Pin a comment to any element on the canvas. Each one is saved in your project with the file and line of its element, so an agent can act on it without midcode.

- Page: https://midcode.app/docs/editor/comments
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A comment is a note pinned to an element: "this heading wraps badly on phones", with a screenshot if you like. What makes it useful is what's saved with it. Each comment records where its element is written, as `file:line:col`, so whoever reads it (you, a teammate, a coding agent) knows which line it's about.

Comments work in every project midcode can open, including the ones it can show but not edit.

## Leave a comment

1. Press `C`, or click "Comment" in the toolbar. The pointer becomes a crosshair and the left panel shows "Comments".
2. Click an element in any frame. A blue pin marks the spot.
3. Write in "New comment", in the right panel. The element and its `file:line` are shown above the text.
4. Press `⌘↵`, or click "Comment".

To attach files, click "Attach", drop them on the panel, or paste an image into the text. A comment can be only files.

You stay in the comment tool, so you can click the next element right away. Press `V` to go back to inspecting. `Esc` gets there too: it first closes the comment that's open, then puts the tool away.

Two other ways in, without changing tool: select an element and click "Comment on this element" at the top of the right panel, or right-click an element and choose "Comment". These pin the comment to the middle of the element.

A comment belongs to the page it was made on, and remembers the breakpoint and its width: `/pricing`, Phone, 390 px. Made while editing a component, it belongs to the page the component is shown on.

## Pins

Each comment has a numbered pin where you clicked. Pins show while the comment tool is on or the "Comments" list is open, and hide otherwise, so the page stays clean while you design.

| Pin | Means |
| --- | --- |
| Orange, with a number | An open comment. |
| Grey | Resolved. |
| Blue | The one that's open in the right panel, or the one you're writing. |

Click a pin to open its comment. A pin follows its element: it's placed by where the element is now, at the same spot inside it, in every breakpoint's frame.

## Read, resolve and delete

The "Comments" list replaces the left panel's tab while it's open. Close it with the ✕, `Esc`, or by leaving the comment tool. The comment button in the toolbar shows how many are open.

- The menu at the top switches between "This page" and "All pages".
- "Resolved" also lists the resolved ones, struck through.
- Click a comment to open it. If it's on another page, the canvas goes there.

The open comment fills the right panel: its text, its attachments, and its element with `file:line`, which opens the code.

| Button | What it does |
| --- | --- |
| "Copy for your agent" | Copies this comment as a brief. See below. |
| "Resolve" | Marks it done. It becomes "Reopen". |
| The trash | "Delete comment": removes it and its attached files. |

Comments aren't part of the undo history: `⌘Z` doesn't bring a deleted comment back.

## Hand comments to an agent

There are three ways, depending on where your agent is.

**In midcode's agent panel.** In the chat, type `@` in the prompt (or use the +) and pick "Open comments". In the terminal view, click "Send the open comments to the agent". Either adds every open comment as one line each, element first, and tells the agent where the full list is:

```text
Address these comments on the site (they're in .midcode/comments.json, with the element each one points at):
- src/components/Pricing.tsx:42:9: This heading wraps badly on phones. Two lines at most.
- src/components/Hero.tsx:18:11: Use the new product shot here.
```

See [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

**Anywhere else, by pasting.** The "Copy open comments for your agent" button at the top of the list puts a Markdown brief of the open comments it lists (this page's, or every page's) on the clipboard. "Copy for your agent" on one comment copies that comment's part of it, from its `###` heading down.

```md
# 1 comment on acme-site

Left in midcode on the live preview. Paths are relative to the project root (`/Users/ana/code/acme-site`); attachments are files in the repo.

## /pricing

### 1. /pricing · Phone 390px · open

- **Element:** `<h2>` · "Simple pricing for teams of every size"
- **Written at:** `src/components/Pricing.tsx:42:9`
- **Inside:** `src/app/pricing/page.tsx:12:7`
- **Where on it:** 42% across, 50% down

> This heading wraps badly on phones. Two lines at most.

- 📎 Screenshot 2026-10-05.png (image/png, 184 KB) → `.midcode/attachments/ab12cd34-Screenshot-2026-10-05.png`
```

**Without midcode at all.** The comments are files in the repository. An agent working there can read `.midcode/comments.json` directly: tell it to, or let [the midcode skill](https://midcode.app/docs/agents/skill.md) do it.

## What midcode writes

Comments live in the project, in `.midcode/`:

```text
.midcode/
  README.md
  comments.json
  attachments/
    ab12cd34-Screenshot-2026-10-05.png
```

`comments.json` is a list, in the order the comments were made. A comment's number is its place in that list.

```json title=".midcode/comments.json"
[
  {
    "id": "5e1f0c2a",
    "createdAt": 1791230400000,
    "resolvedAt": null,
    "page": "/pricing",
    "breakpoint": "phone",
    "viewportWidth": 390,
    "anchor": {
      "ref": {
        "mc": "src/components/Pricing.tsx:42:9",
        "mci": null,
        "i": 0,
        "sel": "body > main > section:nth-of-type(3) > div > h2",
        "mcu": null
      },
      "tag": "h2",
      "component": null,
      "text": "Simple pricing for teams of every size",
      "context": [
        "src/app/pricing/page.tsx:12:7"
      ],
      "fx": 0.42,
      "fy": 0.5
    },
    "body": "This heading wraps badly on phones. Two lines at most.",
    "attachments": [
      {
        "id": "ab12cd34",
        "name": "Screenshot 2026-10-05.png",
        "path": ".midcode/attachments/ab12cd34-Screenshot-2026-10-05.png",
        "type": "image/png",
        "size": 184213
      }
    ]
  }
]
```

| Field | What it is |
| --- | --- |
| `id` | Eight characters, unique in the file. |
| `createdAt` | When it was made, in milliseconds since 1970. |
| `resolvedAt` | When it was resolved. `null` while the comment is open. |
| `page` | The route the comment was made on. |
| `breakpoint` | The id of the breakpoint it was made in. |
| `viewportWidth` | That breakpoint's width in px at that moment. |
| `anchor` | The element. See the next table. |
| `body` | The comment's text. |
| `attachments` | Files copied into `.midcode/attachments/`, each with its original name, its path from the project's root, its type and its size in bytes. |

Inside `anchor`:

| Field | What it is |
| --- | --- |
| `ref.mc` | Where the element is written: `file:line:col`, from the project's root. This is the field an agent needs. |
| `ref.mci` | When a component instance drew the element: `Name\|file:line:col`, where the instance is written. |
| `ref.mcu` | For a component's root: every place the component is used on the way down from the page, each as `Name\|file:line:col`, separated by spaces. |
| `ref.i` | Which one, from 0, when the same line draws several elements (a list). |
| `ref.sel` | A CSS selector for the element. The only locator in projects where midcode can't map elements to code: `mc` and `mci` are `null` there. |
| `tag` | The element's tag. |
| `component` | Its component's name, if it's the root of one. |
| `text` | Its first 120 characters of text. |
| `context` | Where its nearest ancestors written in other files are, nearest first. |
| `fx`, `fy` | Where on the element the pin sits, from 0 to 1 across and down. |

`README.md` is a few lines that explain the folder to whoever opens it, agents included. midcode writes it when it isn't there and never changes one that is.

### In git

`.midcode/` is ordinary files. Commit them and the comments travel with the repository: a teammate who opens the project in midcode sees the same pins. Or add `.midcode/comments.json` and `.midcode/attachments/` to `.gitignore` to keep them to yourself. To git they are changed files like any other: when you [publish](https://midcode.app/docs/publish/publish.md), include them or leave them out.

[What midcode adds to your project](https://midcode.app/docs/start/project-files.md) covers the rest of the folder.

## Limits

- `anchor.ref.mc` is the line the element was on when the comment was made. It isn't updated when the code above it changes, so after edits the pin can point at a neighbour, or disappear until its line holds an element again. The comment's `tag` and `text` say what it was about.
- A comment has one text. There are no replies and no authors: the file doesn't record who wrote what.
- Pins show in the breakpoints' frames, not on what floats on the free canvas.
- A deleted comment is gone, with its attachments.

---

# Tailwind CSS

> How midcode edits a Tailwind CSS 4 project: the classes it swaps, how breakpoints, states and variants are written, and which class expressions it can change.

- Page: https://midcode.app/docs/styling/tailwind
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

In a project that uses Tailwind CSS 4, midcode's right panel never writes CSS. It changes the utility classes on the element you selected, the way you would by hand: one class out, one class in, in the file where the element is written. Your `@theme` tokens fill the controls. Nothing is added to your config or to `package.json`.

A Tailwind 3 project, or one with no Tailwind at all, is styled another way: see [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## How midcode tells which Tailwind you have

When a project opens, midcode reads its CSS files: up to six folders deep, leaving out `node_modules`, `public`, `dist`, `build`, `out` and folders whose name starts with a dot.

| Styles are written as | When midcode finds |
| --- | --- |
| Tailwind 4 classes | A CSS file with `@import "tailwindcss"` or an `@theme` block. This page. |
| `mid:` classes, beside Tailwind 3 | No such file, and a `tailwind.config.js`, `.ts`, `.mjs` or `.cjs` at the root of the project. |
| `mid:` classes | Neither. |

## What midcode writes

One class out, one class in. Each control of the [style panel](https://midcode.app/docs/editor/styles.md) owns one property: text color, font size, horizontal padding, gap, radius. Setting it removes the class that held that property at the breakpoint you're on and puts the new one in its place.

```diff title="app/page.tsx"
-<section className="px-6 py-16">
+<section className="px-6 py-24">
```

The rest of the attribute stays as you wrote it. midcode doesn't sort classes, reformat the line or touch a class it has no reason to change.

What the new class looks like depends on the value:

| midcode writes | When you set |
| --- | --- |
| `p-6`, `gap-6`, `w-6` | A length on your spacing scale: 24 px. |
| `p-4.5` | A half step: 18 px. |
| `p-[17px]`, `w-[413px]` | Any other length. |
| `w-[50%]`, `h-[80vh]` | A percentage or another unit. |
| `text-xl`, `text-hero` | A font size from the list. `text-hero` is your `--text-hero`. |
| `text-[18px]` | A font size you type. A formula keeps its shape: `text-[clamp(2rem,_5vw,_4rem)]`. |
| `text-brand`, `bg-brand` | A color of your theme. |
| `text-[#ff5b2e]` | A color from the picker. |
| `rounded-lg` | A radius on the scale: 8 px. |
| `rounded-[10px]` | Any other radius. |

The spacing scale is your theme's `--spacing` (Tailwind's default is `0.25rem`, 4 px a step). Dragging a resize handle on the canvas writes the same classes as typing the number.

## Breakpoints

Tailwind is mobile first: `text-sm md:text-lg` is `sm` everywhere and `lg` from 768 px up. midcode reads an element's classes as a table, one value per breakpoint, changes the cell you edited, and writes the table back as the fewest classes that say the same.

With the default breakpoints (Desktop 1440 as the primary, Tablet 768, Phone 390), Phone writes with no prefix, Tablet with `md:` and Desktop with `lg:`. Follow one property:

1. A vertical padding set on Desktop, the primary: `py-24`.
2. On Phone, set it to 40: `py-10 md:py-24`.
3. On Tablet, set it to 64: `py-10 md:py-16 lg:py-24`.
4. On Tablet, right-click the property's blue label and choose "Remove override": `py-10 md:py-24`.
5. The same on Phone: `py-24` again.

The rules behind it:

- A change on the primary breakpoint is the rule: it applies wherever nothing overrides it.
- A change on another breakpoint is an override there. It also carries on to the breakpoints beyond it, away from the primary, that were showing the same value. Set a font size on Tablet and Phone gets it too: `text-5xl` becomes `text-4xl lg:text-5xl`.
- Neighbours with the same value share one class.
- Mobile-first CSS can't make a value stop at a larger screen. So a value that exists only on a smaller breakpoint gets a reset at the next one: a background set on Phone alone is `bg-black md:bg-transparent`. Other resets are `text-inherit`, `shadow-none`, `rounded-none` and `[font-size:inherit]`.

### Which screen a breakpoint uses

A breakpoint's screen has to start above the next smaller breakpoint's width and no later than its own, so that an override never leaks into a neighbour. midcode picks Tailwind's named screen that fits (`sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536) and, when none does, an exact one in rem.

| Your breakpoints | Screens |
| --- | --- |
| 1440, 768, 390 | `lg:`, `md:`, none |
| 1440, 1100, 810, 390 | `xl:`, `lg:`, `md:`, none |
| 1440, 1000, 768, 390 | `lg:`, `min-[62.5rem]:`, `md:`, none |

The breakpoints themselves are yours to add, rename and resize: see [The canvas and breakpoints](https://midcode.app/docs/editor/canvas.md).

## States and variants

In [component mode](https://midcode.app/docs/editor/components.md) a cell is also a state and a variant, and the same writes get one more prefix.

| Cell | On the component's root | On an element inside it |
| --- | --- | --- |
| Hover | `hover:` | `group-hover/card:` |
| Pressed | `active:` | `group-active/card:` |
| Focus | `focus-visible:` | `group-focus-visible/card:` |
| Variant `ghost` | `data-[variant=ghost]:` | `group-data-[variant=ghost]/card:` |

`card` is the component's group: its root carries `group/card`, named after the component (`PrimaryButton` gives `group/primary-button`). A variant and a state together are written variant first, and a breakpoint goes before both: `md:data-[variant=ghost]:hover:bg-black`.

Three edits on a card (a background on Hover, a background for the `ghost` variant, a title color on Hover) leave this:

```diff title="components/Card.tsx"
-<article className="group/card rounded-2xl p-6 bg-white" data-variant={variant}>
-  <h3 className="text-lg">{title}</h3>
+<article className="group/card rounded-2xl p-6 bg-white hover:bg-neutral-100 data-[variant=ghost]:bg-transparent" data-variant={variant}>
+  <h3 className="text-lg group-hover/card:text-blue-600">{title}</h3>
```

Choosing "none" for a property in a state or a variant writes a reset, because leaving the class out would still show the value underneath. A shadow taken off on Hover is `hover:shadow-none`.

On a page, outside component mode, an element's `hover:` classes are kept and not edited.

## Where the classes are written

midcode edits the places where class names are written out as text. In JSX that is more than a plain string:

```tsx
<div className="px-6 py-16" />
<div className={cn('px-6 py-16', className)} />
<div className={`px-6 ${wide ? 'max-w-6xl' : 'max-w-3xl'}`} />
<div className={clsx('px-6', { 'opacity-50': disabled })} />
```

- **Plain text** (a string, the string arguments of a call, the fixed parts of a template literal, the strings of an array): classes are swapped in place, and a new one goes at the end of the first plain text.
- **A helper with no plain text** (`cn(className, variants[size])`): the new classes become its first argument. This works for `cn`, `clsx`, `classnames`, `classNames`, `twMerge`, `twJoin`, `cx` and `tw`.
- **No class attribute yet**: midcode adds `className="…"` right after the tag name. From the next release, a file whose JSX writes `class` (Solid, Qwik, Preact) gets `class`.
- **A class inside a condition** (`active && 'bg-black'`, a branch of a ternary, a key of `clsx({ … })`): midcode can find it. When you change that property, it takes the class out of that branch and writes the new one in the plain text, so the value stops depending on the condition. If the condition should stay, edit it in the code.
- **A piece of a computed name** (`text-${size}`): never matched and never changed. midcode only reads whole words.
- **A class an instance passes in** (`<Card className="mt-8" />`): changed where the instance is written. In component mode midcode only writes in the component's own file.

Two things stop an edit. midcode says which and writes nothing:

- The class to replace isn't written out anywhere: it comes from a prop, or from a lookup like `SIZES[size]`. The message names the class and the file, and says it comes from a prop or a condition.
- The whole attribute is a variable (`className={className}`, `className={styles.card}`). The message is "This element's classes come from a variable. Edit them in the code."

In a `.svelte` file (and, from the next release, `.vue`, `.astro`, `.html` and server templates) the same goes for `class="…"`: its written text is edited, a class glued to an expression (`btn-{size}`) is left alone, and `class={expression}` is a variable. Content written in Markdown (Hugo, Jekyll, Eleventy) has no tag to hang a class on: midcode changes its words and says to style it from the template around it.

## Your theme in the controls

midcode reads every `@theme` block of your CSS:

| In `@theme` | Where it shows |
| --- | --- |
| `--color-brand` | "Project colors" in every color control. Written `text-brand`, `bg-brand`. |
| `--font-display` | The Font list, with `sans`, `serif` and `mono`. Written `font-display`. |
| `--text-hero` | The Size list, with Tailwind's `xs` to `9xl`. Written `text-hero`. |
| `--radius-card` | Radius: a corner of that size is written `rounded-card`. |
| `--spacing` | The unit every spacing class is counted in. |

A value that points at another variable (`--color-brand: var(--brand)`) is resolved against `:root`, so its swatch shows the real color. Editing the tokens themselves, and text and link styles, is in [Theme and design tokens](https://midcode.app/docs/styling/theme.md).

## Limits

- midcode models one screen, one state and one variant per class. A class with any other prefix (`dark:`, `max-md:`, `[&>svg]:`, a screen name of your own, two states) is kept exactly as written and is never read or rewritten. The panel doesn't show or edit dark-mode values.
- Screens are Tailwind's defaults. A theme that redefines them (`--breakpoint-md: 900px`) isn't read: midcode still counts `md:` as 768 px.
- A `!` on a class (`!p-4`, `p-4!`) is kept when the class is replaced.
- Text styles and link styles apply to every breakpoint, variant and state. They can't be overridden per cell.
- The panel edits classes on elements. A rule in your CSS (`.hero { padding: 4rem }`, `@apply`) shows on the canvas but isn't rewritten: changing that property adds a class to the element.
- Tailwind 3 classes aren't rewritten. midcode adds [`mid:` classes](https://midcode.app/docs/styling/without-tailwind.md) beside them.

---

# Without Tailwind

> How midcode styles a project that has no Tailwind 4: mid: utility classes on the element, and a midcode.css file in your project with their plain CSS.

- Page: https://midcode.app/docs/styling/without-tailwind
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

You don't need Tailwind to style a project in midcode. In a project with plain CSS, CSS modules, Sass, Bootstrap or Tailwind 3, the right panel works the same, and what it writes is a utility class of midcode's own: `mid:p-6`, `mid:md:flex`, `mid:hover:bg-[#111]`. midcode turns those classes into plain CSS itself, in a file called `midcode.css` that lives in your project.

Nothing is installed in your project and your own classes and stylesheets are never touched. midcode carries the Tailwind 4 compiler inside the app and uses it for the `mid:` classes only. How it decides a project goes this way is in [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

## The syntax

A `mid:` class is a Tailwind 4 utility with the prefix first: `mid:<variant>:<utility>`.

| Class | What it does |
| --- | --- |
| `mid:p-6` | 24 px of padding. |
| `mid:md:p-4` | 16 px of padding from 768 px up. |
| `mid:hover:bg-[#111]` | A background on hover. |
| `mid:text-[80px]` | Any value, in brackets. |
| `mid:bg-brand` | A color of [your theme](https://midcode.app/docs/styling/theme.md). |
| `mid:lead` | A text style of your theme. |
| `mid:group-hover/card:underline` | A state of a component, on an element inside it. |
| `mid:data-[variant=ghost]:bg-transparent` | A variant of a component. |

Everything [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md) says about breakpoints, states, variants and where a class can be written holds here, with `mid:` in front of each class.

## Your first style edit

Nothing is added to a project until you change a style, insert something or edit the theme. The first time, midcode sets the project up and then makes your edit:

1. It creates `midcode.css` next to your app's entry, with the CSS of the `mid:` classes already in the code (none, usually).
2. It adds one import of that file to the entry.
3. It creates `.midcode/theme.css`, an empty theme.
4. It writes your class.

A message tells you what happened: "midcode added midcode.css to the project and imported it in layout.tsx: the styles you make go there."

```diff title="app/layout.tsx"
 import type { Metadata } from 'next'
 import './globals.css'
+import './midcode.css'
```

The import and the theme file are one undoable step, listed in [Publish](https://midcode.app/docs/publish/publish.md) as "Import midcode.css" and "Add .midcode/theme.css". `midcode.css` itself is outside the undo history, because it's rewritten all the time. In Publish, `midcode.css` is ticked and `.midcode/theme.css` is not, like every file under `.midcode/`: tick it if `midcode.css` is ever built somewhere other than your Mac. midcode also adds a "Styles" section to `.midcode/README.md` that explains the classes to an agent working in the project without midcode.

## Where midcode.css goes

| Project | midcode.css | Imported in |
| --- | --- | --- |
| Next.js, App Router | `app/` or `src/app/` | The root `layout`. |
| Next.js, Pages Router | `pages/` or `src/pages/` | `_app`. |
| React Router, Remix | `app/` | `root.tsx`. |
| Vite | Next to the entry | The module `index.html` loads, `src/main.tsx` for instance. |
| SvelteKit | `src/routes/` | `+layout.svelte`. midcode creates it when there is none. |
| Astro | `src/` | The frontmatter of every layout in `src/layouts`, or of every page when there are no layouts. |

In any other project midcode looks for `src/main`, `src/index` or `src/entry-client`. When it finds no entry, it still creates `midcode.css` (in `src/`, or at the root) and tells you to import it yourself: "midcode added src/midcode.css but couldn't tell where to import it. Import it in your app's entry so its styles show."

### Other kinds of project (next release)

From the next release, midcode sets up these projects too. A page or a layout written in HTML gets a `<link>` at the end of its `<head>`, indented like the line above it.

| Project | midcode.css | Linked from |
| --- | --- | --- |
| Plain HTML | The site's root | Every `.html` page, by a relative path: `href="./midcode.css"`. |
| Nuxt | Next to `app.vue` | An import in its `<script setup>`. |
| Shopify theme | `assets/` | `layout/theme.liquid`, with the theme's own stylesheet tag. |
| Rails, Laravel | `public/` | Every layout: `href="/midcode.css"`. |
| Hugo | `static/` | Every layout, the same way. |
| Jekyll, PHP | The folder that's served | Every layout, the same way. |
| Eleventy | `public/`, when the site copies it to its root | Every layout, the same way. |
| Flask | Its `static/` folder | Every layout: `href="/static/midcode.css"`. |
| Django | The first folder of `STATICFILES_DIRS` | Every layout, under your `STATIC_URL`. |
| WordPress theme | The theme's folder | Its header, through `get_theme_file_uri()`. |
| Angular | `public/` | `src/index.html`. |

```html title="layouts/_default/baseof.html"
  <link rel="stylesheet" href="/css/site.css">
  <link rel="stylesheet" href="/midcode.css">
</head>
```

```liquid title="layout/theme.liquid"
  {{ 'midcode.css' | asset_url | stylesheet_tag }}
</head>
```

A "layout" here is any template that closes a `<head>`. Two cases are left to you:

- Where midcode can't tell which folder a stack serves as it is (a whole WordPress install, a Django project with no `STATICFILES_DIRS`), it creates the file and you link it.
- A Laravel or Rails app with Vite in its `package.json` is treated as a Vite project. midcode looks for a JavaScript entry there, and when it finds none it creates `midcode.css` at the project's root and leaves bringing it into the site to you.

How these sites are edited at all is in [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md).

## What midcode writes

Take a heading with a size, another size from 768 px up, and a color on hover. In your markup that is three classes, next to the one it had:

```diff title="app/page.tsx"
-<h1 className="title">Hello</h1>
+<h1 className="title mid:text-[80px] mid:md:text-[56px] mid:hover:text-[#ff5b2e]">Hello</h1>
```

And `midcode.css` gets their rules. This is the file, up to the reset that closes it (described below):

```css title="app/midcode.css"
/*
 * midcode.css: written by midcode (https://midcode.app) from the "mid:" classes in this project's code.
 * Don't edit it by hand: it's rewritten whenever those classes change. The theme is in .midcode/theme.css.
 */
/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
@layer mid-theme, mid-base, mid-components, mid-utilities;
@layer mid-utilities {
  .mid\:text-\[80px\] {
    font-size: 80px !important;
  }
  @media (hover: hover) {
    .mid\:hover\:text-\[\#ff5b2e\]:hover {
      color: #ff5b2e !important;
    }
  }
  @media (width >= 48rem) {
    .mid\:md\:text-\[56px\] {
      font-size: 56px !important;
    }
  }
}
```

A class that uses the scale or the theme brings its variable, in a layer of its own. `mid:p-6` adds:

```css
@layer mid-theme {
  :root, :host {
    --mid-spacing: 0.25rem;
  }
}
@layer mid-utilities {
  .mid\:p-6 {
    padding: calc(var(--mid-spacing) * 6) !important;
  }
}
```

The file holds exactly the rules of the `mid:` classes found in your code. Take the last use of a class out and its rule goes with it.

## Your own CSS stays yours

- **Only `mid:` classes are read.** A class of yours called `.flex`, `.container` or Bootstrap's `.p-3` is never compiled, changed or removed. To the panel, your classes are opaque: a value that comes from your stylesheet shows on the canvas, and changing it in the panel adds a `mid:` class over it.
- **Every declaration is `!important`.** An edit made in midcode has to win over the rule your CSS already has for that element.
- **The layers have their own names.** `mid-theme` and `mid-utilities` can't mix with layers of yours called `base` or `utilities`, or with Tailwind 3's `@layer` directives.
- **Your site isn't reset.** `midcode.css` brings no global reset: your headings, links and margins look as they did.

### What you insert

Tailwind's utilities assume a reset. Since your site doesn't get one, what midcode itself inserts (anything from [Insert](https://midcode.app/docs/editor/insert.md), and its own components) carries the class `mid-base` on its root, and `midcode.css` ends with a small reset scoped to that class: no default margins, unstyled links, lists and buttons, `box-sizing: border-box`. Those rules are not `!important`, so every utility still wins over them.

A section from the Insert panel is written like this:

```tsx
<section className="mid-base mid:py-24 mid:px-6">
  <h2 className="mid:text-4xl mid:font-semibold">Title</h2>
  <p className="mid:mt-4 mid:text-neutral-600">Text</p>
</section>
```

## How midcode.css stays up to date

While the project is open in midcode, the file follows the code:

- **Before each edit is written**, the new classes' CSS goes into the file first, so the page never shows a class without its style.
- **After each edit and each `⌘Z`**, it's rebuilt from what the code holds now.
- **When anything else changes the code** (your editor, an agent, a branch switch), a watcher rebuilds it a moment later. It also rebuilds when `.midcode/theme.css` changes.
- **When the project opens**, it's brought up to date.

midcode looks for `mid:` classes in `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.svelte`, `.astro`, `.vue`, `.html`, `.md` and `.mdx` files, and from the next release also in templates (`.liquid`, `.php`, `.erb`, `.ejs`, `.twig`, `.njk`, `.hbs` and the like). It skips `node_modules`, `.git` and build folders such as `.next`, `dist`, `build` and `out`.

`midcode.css` shows in Publish as one entry, "Styles written by midcode (midcode.css)", however many times it was rewritten. Publish it with your site: the site needs it.

When the project isn't open in midcode (your production build, CI, an agent writing `mid:` classes by hand), [the midcode package](https://midcode.app/docs/styling/package.md) builds the same file.

## Tailwind 3

A Tailwind 3 project goes this way too. midcode doesn't rewrite Tailwind 3's classes and the panel doesn't read them. It writes `mid:` classes beside them, and since those are `!important`, what you set on the canvas wins:

```diff title="src/components/Hero.jsx"
-<section className="py-16 bg-white">
+<section className="py-16 bg-white mid:py-24">
```

## Limits

- Because the rules are `!important`, your own CSS can't override a `mid:` class. Remove the class, or change it in midcode.
- Hover styles sit inside `@media (hover: hover)`, as in Tailwind 4: they don't apply on touch screens.
- A class name put together at runtime (`'mid:p-' + size`) isn't found, so it gets no CSS. Write classes out whole.
- Files over 2 MB aren't read.
- A theme that doesn't compile (a typo while you're editing it) keeps the last `midcode.css` until it's fixed.
- Tried with Next.js, Vite, Vite with Tailwind 3 and Astro 7 (a layout with no frontmatter gets one for the import).

## Troubleshooting

**A style I changed doesn't show.** Check that `midcode.css` is imported in your app's entry, or linked from the page. midcode adds the import when it sets the project up and looks again at every style edit, so a page or a layout you added later gets its link with your next edit. An entry midcode couldn't find needs the import by hand.

**I moved midcode.css.** midcode looks for it next to the entry, then in `src/app/`, `app/`, `src/`, `src/routes/` and the project's root. Anywhere else it won't find it: the next style edit creates a second file next to the entry, while your import still points at the one you moved. Keep the file in one of those places.

**I deleted midcode.css.** The next style edit creates it again from the classes in the code.

**A class I wrote by hand has no effect.** With the project open in midcode it's picked up within a moment. Otherwise run `npx midcode`: see [The midcode package](https://midcode.app/docs/styling/package.md).

**git reports a conflict in midcode.css.** The file is generated: keep either side, then let midcode or `npx midcode` rewrite it.

---

# Theme and design tokens

> Edit your project's colors, fonts, text styles and link styles in midcode, and see the CSS each one writes, with Tailwind 4 and without it.

- Page: https://midcode.app/docs/styling/theme
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A project's theme is the short list of things its pages share: its colors, its fonts, a few named text styles, the way its links look. In midcode they're in the Assets tab of the left panel, under "Styles", in four groups: Colors, Fonts, Text styles and Link styles. The search field at the top of Assets filters them by name. Nothing in the interface is called "Design panel": that name only appears in the comment midcode writes at the top of `.midcode/theme.css`, and it means this list.

Changing one there changes it everywhere it's used, because it is the same variable or class your code uses. Each change is one edit: `⌘Z` undoes it, and [Publish](https://midcode.app/docs/publish/publish.md) lists it (`--color-brand → #e0481f`, "New text style .lead").

## Where the theme lives

| Project | The file |
| --- | --- |
| Tailwind 4 | Your own CSS: the file with the `@theme` block, `app/globals.css` for instance. A token is edited in the file it's declared in. |
| No Tailwind, or Tailwind 3 | `.midcode/theme.css`, which midcode creates with [your first style edit](https://midcode.app/docs/styling/without-tailwind.md). |

Both are read the same way: variables inside `@theme`, and style rules beside it. `.midcode/theme.css` starts out like this:

```css title=".midcode/theme.css"
/*
 * This project's theme in midcode: the colors, fonts, sizes and text styles made in the Design panel.
 * midcode builds midcode.css from this file and from the mid: classes in the code.
 *
 *   --color-brand: #ff5b2e;   →  mid:bg-brand, mid:text-brand
 *   --font-display: "Inter";  →  mid:font-display
 */
@theme {
}
```

It's a file like any other: you or an agent can edit it by hand, and midcode rebuilds `midcode.css` when it changes.

## Colors

Every `--color-*` in `@theme` is a color of the project.

1. Open the Colors group and click the plus, "Add color".
2. Type a name. midcode shows the classes it gives you as you type: `bg-brand · text-brand`.
3. Pick the color and click "Add color".

The variable goes after the last color of the block:

```diff title="app/globals.css"
 @theme {
   --color-linen: #f7f2e7;
   --color-ink: #1a1a1a;
+  --color-brand: #ff5b2e;
   --font-display: "Fraunces", serif;
 }
```

Without Tailwind the same line goes in `.midcode/theme.css`:

```diff title=".midcode/theme.css"
 @theme {
+  --color-brand: #ff5b2e;
 }
```

To change a color, click it and use the picker. Only the value changes:

```diff
-  --color-brand: #ff5b2e;
+  --color-brand: #e0481f;
```

Right-click a color for "Copy name", "Copy value" and "Remove".

To use it, open any color control in the right panel: your colors are under "Project colors", and choosing one writes `text-brand` or `bg-brand` (`mid:text-brand` without Tailwind). The "Custom" tab writes the value itself, `text-[#e0481f]`.

## Fonts

Every `--font-*` in `@theme` shows in the Fonts group with its stack in a field. Edit the field and midcode rewrites the value of the variable. Right-click a font for "Copy name" and "Remove".

There's no button to add a font. Write it in `@theme` yourself and it appears, both here and in the Font list of the right panel, where choosing it writes `font-display`:

```css
@theme {
  --font-display: "Fraunces", serif;
}
```

midcode edits the name of the stack, not the font files. Loading the font (`next/font`, an `@font-face` rule, a `<link>`) stays in your code.

## Text styles

A text style is a named bundle of type settings used across the site: a class, or an `@utility`, with at least two of `font-size`, `font-family`, `font-weight`, `line-height`, `letter-spacing`, `text-transform` and `font-style`. midcode finds the ones your CSS already has.

1. Open Text styles and click the plus, "New text style".
2. Type a name and click "Add style".
3. Set its Font, Size, Weight, Line, Tracking and Case. Each field writes one declaration, and an emptied field removes it.

In a Tailwind 4 project the style is a class, written right after the last text style of your CSS (same file, same layer) or at the end of the theme's file:

```css title="app/globals.css"
.lead {
  font-size: 16px;
  line-height: 1.5;
  font-weight: 400;
}
```

Without Tailwind it's a utility, because a plain `.lead` could be a class your site already has:

```css title=".midcode/theme.css"
@utility lead {
  font-size: 16px;
  line-height: 1.5;
  font-weight: 400;
}
```

To apply one, select a text and choose it in the Style row of the Typography section. midcode adds the class to the element: `lead`, or `mid:lead` without Tailwind. The button beside the row, "Edit this style (changes it everywhere)", opens the same fields without leaving the element.

```diff title="app/page.tsx"
-<p className="mt-4 max-w-xl">We make furniture that lasts.</p>
+<p className="mt-4 max-w-xl lead">We make furniture that lasts.</p>
```

## Link styles

A link style is a color, a hover color and an underline, for links across the site. In CSS it's a class with a `:hover` rule that sets a color or an underline. midcode finds those too.

1. Open Link styles and click the plus, "New link style".
2. Type a name, then choose Color, Hover and Underline. A color is "Same as text" or one of your colors. Underline is "Never", "On hover" or "Always".
3. Click "Add style".

With Tailwind 4:

```css title="app/globals.css"
.link-quiet {
  color: var(--color-ink);
  text-decoration: none;
  text-underline-offset: 0.2em;
  transition: color 0.15s;
}
.link-quiet:hover {
  color: var(--color-brand);
  text-decoration: underline;
}
```

Without Tailwind, the hover is nested in the utility:

```css title=".midcode/theme.css"
@utility link-quiet {
  color: currentColor;
  text-decoration: none;
  text-underline-offset: 0.2em;
  transition: color 0.15s;
  &:hover {
    color: currentColor;
    text-decoration: underline;
  }
}
```

To apply one, select a link and choose it in the Style row of the Link section of the right panel.

## Sizes, radii and spacing

midcode reads three more kinds of token and uses them in the right panel. They have no group in Styles: edit them in the CSS.

| In `@theme` | What it's for |
| --- | --- |
| `--text-hero: 72px` | A size called `hero` in the Size list, beside Tailwind's `xs` to `9xl`. Written `text-hero`. |
| `--radius-card: 12px` | A radius called `card`. A corner of 12 px is written `rounded-card`. |
| `--spacing: 0.25rem` | The step every spacing class counts in. A value in `px` or `rem`. |

## Removing a token or a style

"Remove" first counts where the name is still used in your code and asks: "It's used 4 times in the code. Those places will fall back to the default until you change them." Confirm, and midcode deletes the variable's line, or the style's whole rule (a link style's `:hover` rule goes with it). It doesn't touch the places that used it.

## What midcode writes

Every edit changes only its own characters: a value, one declaration, or one new rule placed beside the others of its kind. The rest of the file, comments and formatting included, stays as it was.

| You do | With Tailwind 4 | Without Tailwind |
| --- | --- | --- |
| Add or change a color | `--color-brand: …;` in the `@theme` of your CSS | The same line in `.midcode/theme.css` |
| Change a font's stack | The value of `--font-display` | The same |
| New text style | `.lead { … }` | `@utility lead { … }` |
| New link style | `.link-quiet { … }` and `.link-quiet:hover { … }` | `@utility link-quiet { … &:hover { … } }` |
| Apply a style to an element | The class `lead` | The class `mid:lead` |
| Use a color on an element | `text-brand`, `bg-brand` | `mid:text-brand`, `mid:bg-brand` |

Without Tailwind, a change to `.midcode/theme.css` also rewrites `midcode.css`. There, a color that some class uses becomes the variable `--mid-color-brand`, and a style that some element carries becomes the rule `.mid\:lead`. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- In a Tailwind 4 project the plus buttons show once your CSS has an `@theme` block. If it has none, add an empty `@theme { }`.
- The picker writes a hex value. A color you wrote as `oklch(…)`, or as a `var(…)` pointing at another variable, becomes a hex once you change it here.
- Text sizes, radii and the spacing step are read, not edited, in this list.
- A text style or a link style can't be different per breakpoint, variant or state: applying one always writes the plain class.
- A style your CSS defines again inside a media query is read once, and the fields edit its first rule.
- Without Tailwind, the variables of your theme are written to `midcode.css` with the prefix: `--mid-color-brand`, `--mid-font-display`. A link style whose color is one of your colors, or a text style whose font is one of your fonts, is written as `var(--color-brand)` or `var(--font-display)`, which that file doesn't define, so the link or the text keeps its inherited color or font. Until that's fixed, choose "Same as text" in the style's fields, or write the prefixed name in `.midcode/theme.css` by hand: `color: var(--mid-color-brand)`.

---

# The midcode package

> Build midcode.css without the app, in your production build, in CI or beside an agent, with the midcode CLI, its Vite plugin or its Next.js wrapper.

- Page: https://midcode.app/docs/styling/package
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

In a project [without Tailwind 4](https://midcode.app/docs/styling/without-tailwind.md), your styles are `mid:` classes in the code, and `midcode.css` is their CSS. The app rewrites that file while the project is open in it. The `midcode` package does the same job everywhere else: a command line tool, a Vite plugin and a Next.js wrapper that build `midcode.css` from the classes in your code.

A project that uses Tailwind 4 doesn't need it: there, midcode writes Tailwind's own classes and Tailwind compiles them.

## When you need it

`midcode.css` is a plain file in your repository, so a site that was only ever edited in midcode builds and deploys with nothing added. Add the package when the classes can change while the app isn't looking:

- You or an agent write `mid:` classes by hand, in an editor or a terminal.
- You want the file rebuilt in CI or in your production build, so that it can never be out of date.
- You'd rather not commit a generated file, and build it instead. Then always pass `--out`, so that a fresh checkout knows where the file goes.
- A teammate works on the project without midcode.

## Install

```bash
npm install -D midcode
pnpm add -D midcode
yarn add -D midcode
```

It needs Node 20 or later. Its one dependency is `tailwindcss` (version 4), which it uses as the compiler for `mid:` classes. Your own stylesheets don't go through Tailwind and nothing in your build config changes unless you add one of the integrations below.

## Any project: the command

Run it before your build, or leave it watching while you work:

```json title="package.json"
{
  "scripts": {
    "prebuild": "midcode",
    "dev:css": "midcode --watch"
  }
}
```

| Command | What it does |
| --- | --- |
| `midcode` | Builds `midcode.css` once. |
| `midcode --watch` | Builds it, and again whenever your code or your theme changes. `-w` for short. |
| `--root <dir>` | The project's folder. Default: the current one. |
| `--out <file>` | Where `midcode.css` goes when the project has none yet. |
| `--help` | Prints the options. `-h` for short. |

A build prints one line:

```bash
$ npx midcode
midcode: 42 classes → /Users/you/site/app/midcode.css
```

It adds "(up to date)" when the file didn't need to change. On an error it prints `midcode: <message>` and exits with code 1, so a `prebuild` script stops the build.

Where your package manager doesn't run `pre` scripts by itself (Yarn 2 and later), call it in the script: `"build": "midcode && vite build"`.

## Vite, Astro, SvelteKit, React Router, Remix

Add the plugin and `midcode.css` is built when the dev server or a build starts, and again whenever a source file or the theme is added, changed or removed while the dev server runs.

```ts title="vite.config.ts"
import { defineConfig } from 'vite'
import midcode from 'midcode/vite'

export default defineConfig({ plugins: [midcode()] })
```

The project's folder is Vite's own `root`. Pass `midcode({ root, out })` to change it, with the same meaning as the command's options.

## Next.js

Wrap your config. `midcode.css` is built before Next starts, and kept up to date while `next dev` runs.

```ts title="next.config.ts"
import withMidcode from 'midcode/next'

export default withMidcode({
  // your config
})
```

`withMidcode` takes your config as an object or as a function, and options as a second argument: `withMidcode(config, { root, out })`. If the build of `midcode.css` fails, it prints the error and lets Next go on.

## From code

The same two functions the command uses are exported:

```ts
import { build, watch } from 'midcode'

const result = await build({ root: process.cwd() })
// { file: '/abs/path/midcode.css', classes: 42, changed: true }

const stop = await watch({}, (r) => {
  if (r instanceof Error) console.error(r.message)
})
```

## Starting without the app

The package always writes to the `midcode.css` the project already has, wherever it is. In a project that has none, say where it goes and import it in your entry:

```bash
npx midcode --out src/midcode.css
```

```ts title="src/main.tsx"
import './midcode.css'
```

Without `--out`, and with no `midcode.css` in the project, the command stops: "No midcode.css in /Users/you/site. Pass where it goes (--out src/midcode.css) and import it in your app's entry."

From then on, write classes with the prefix first and run the command:

```html
<h1 class="title mid:text-[80px] mid:md:text-[56px] mid:hover:text-[#ff5b2e]">Hello</h1>
```

Tokens go in `.midcode/theme.css`. See [Theme and design tokens](https://midcode.app/docs/styling/theme.md) for the format.

```css title=".midcode/theme.css"
@theme {
  --color-brand: #ff5b2e;        /* mid:bg-brand, mid:text-brand */
  --font-display: "Fraunces";    /* mid:font-display */
}

@utility lead {                  /* mid:lead, mid:md:lead */
  font-size: 20px;
  line-height: 1.5;
}
```

When you open that project in midcode later, it reads the same classes and the same theme and carries on from there. Put the file where the app looks for it: next to your entry, or in `src/`, `app/`, `src/app/`, `src/routes/` or the project's root.

## What it reads

- **Classes**: every `mid:` class in the project's `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.svelte`, `.astro`, `.vue`, `.html`, `.md` and `.mdx` files. It skips `node_modules`, `.git`, `.next`, `.nuxt`, `.svelte-kit`, `.astro`, `.vercel`, `.turbo`, `.cache`, `dist`, `build`, `out` and `coverage`.
- **The theme**: `.midcode/theme.css`, when there is one.
- **The output**: the first `midcode.css` it finds in the project. That file is rewritten whole, and only when its content would change.

What it writes is the same CSS the app writes: one rule per class, every declaration `!important`, in layers named `mid-theme` and `mid-utilities`, followed by the reset scoped to `mid-base`. The full description is in [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

> [!WARNING]
> Commit `.midcode/theme.css` if you build `midcode.css` anywhere but your Mac. The package reads your colors, fonts and text styles from it. Without it, classes like `mid:bg-brand` and `mid:lead` get no CSS. In [Publish](https://midcode.app/docs/publish/publish.md), files under `.midcode/` are listed but not ticked: tick this one.

## Limits

- The command and the integrations build the stylesheet. They don't add the import to your entry and they don't write classes: that's the app, or you.
- A class name put together at runtime (`'mid:p-' + size`) isn't found. Write classes out whole.
- Version 0.1.0 doesn't read server templates (`.php`, `.erb`, `.liquid`, `.twig` and the like). The app reads them from its next release.
- If the project has more than one `midcode.css`, only the first one found is written.

---

# CMS

> How midcode finds the content lists in your code, JSON and Markdown files, shows them as tables, and writes each change back into the file.

- Page: https://midcode.app/docs/data/cms
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Beta: midcode labels this beta.

The CMS shows the content your site already keeps in its files as collections: a table of items, with a form for each one. Nothing is stored in midcode. A collection is a list in your code, a JSON file or a folder of Markdown posts, and every change you make is written into that file, as the edit you would have typed.

Use it for what you write yourself and publish with the site: projects, team members, FAQs, posts. What your visitors create while the site runs (accounts, orders, messages) lives in a database: see [Database](https://midcode.app/docs/data/database.md).

Open it with **CMS** in the top bar: a button at the right in the released version and, from the next release, a tab in the middle beside Design and Code. `Esc` goes back to the canvas.

## What counts as a collection

midcode reads the project's files, up to 7 folders deep, and lists three shapes:

| Shape | What it looks for |
| --- | --- |
| A list in a module | A top-level `const` (exported or not) or an `export default` whose value is an array of object literals, in a `.ts`, `.tsx`, `.js`, `.jsx` or `.mjs` file |
| A JSON file | A `.json` file whose top level is an array of objects |
| A Markdown folder | A folder with two or more `.md` / `.mdx` files that start with front matter, or one file if the folder is called `content`, `posts`, `blog`, `articles`, `news` or `docs` |

Every element of the array has to be an object, and at least one of its properties a plain value. `as const` and `satisfies` around the array are fine.

```ts title="content/projects.ts"
export const projects = [
  {
    title: 'Oak House',
    slug: 'oak-house',
    year: 2024,
    featured: true,
    cover: '/images/oak-house.jpg',
    tags: ['residential', 'timber'],
  },
  {
    title: 'River Studio',
    slug: 'river-studio',
    year: 2023,
    featured: false,
    cover: '/images/river-studio.jpg',
    tags: ['workspace'],
  },
]
```

This file shows up as the collection "Projects" (the variable's name, in words), with two items and six fields. A JSON file or a default export is named after its file; a Markdown folder after the folder.

These are not read: `node_modules`, `public`, build folders (`.next`, `dist`, `out`, `build`), folders that start with a dot, config files (`package.json`, `tsconfig.json`, `*.config.*`, `*.d.ts`), and any file over 400 KB.

## Field types

The type of each field is inferred from the values the items have. The table header shows it beside the field's name.

| Type | When |
| --- | --- |
| Text | A string |
| Long text | A string over 90 characters or with a line break, or a field called `body`, `content`, `description`, `summary`, `text`, `answer`, `excerpt` or `bio` |
| Number | Every value is a number |
| Switch | Every value is `true` or `false` |
| Date | Every string starts with `YYYY-MM-DD` |
| Image | Every string ends in `.png`, `.jpg`, `.jpeg`, `.webp`, `.avif`, `.gif` or `.svg` |
| Link | The field is called `href`, `url`, `link` or `website`, or every string starts with `/`, `http://`, `https://` or `mailto:` |
| List | An array of strings |
| Markdown | The body of a Markdown file |
| Code | Anything that isn't a plain value: an import, a JSX element, a function call, a nested array of objects |

A Code field is shown as it's written, with "Code, not content: edit it in the file." It can't be changed from the CMS.

An object of plain values becomes one field per key. `price: { en: 'Free', es: 'Gratis' }` shows as `price.en` and `price.es`, so a text kept per language is edited like any other. To see every text of the site by language, use [Languages](https://midcode.app/docs/data/languages.md).

## Edit an item

1. Pick a collection on the left. The table lists its items; **Search** filters them.
2. Click a row. The item opens on the right, one control per field.
3. Change a field and leave it (or press `Enter` in a one-line field). The file is written at that moment.

A Switch can be flipped in the table itself. An Image field takes a path, or **Choose image…** copies a file into your public folder (under `/images`) and writes its path. A List adds an entry with `Enter` and, with nothing typed, removes the last one with `⌫`. Emptying a Number removes the property from that item.

The file's path, next to the collection's name, opens it in your code editor. The line under it, "Use it in a page:", is the import to paste where you want the list, written with your `tsconfig` alias when there is one:

```ts
import { projects } from '@/content/projects'
```

## Add, remove and reorder

- **New item** adds one at the end of the list. It is a copy of the last item's text with each plain value emptied (`''`, `0`, `false`, `[]`) and "Untitled" as its title; a Code value is copied as it is. In a Markdown folder it creates a new file named after the title, with the folder's fields in its front matter.
- **Delete item**, at the bottom of the item's panel, removes it from the file. In a Markdown folder, the item's file goes to the Trash.
- Drag the handle at the left of a row to reorder. The commas and comments between items stay where they are. Markdown folders have no order to change, and the handle is hidden while you search.
- **Field** adds a property to every item that doesn't have it, with an empty value of the type you choose: Text, Long text, Number, Switch, Image, Link, Date or List. Field names are letters, numbers and `_`.

## New collection

**New collection**, at the bottom of the list, asks for a name and creates `content/<name>.ts` (`src/content/<name>.ts` when the project has a `src` folder) with one item to start from. "Case studies" gives:

```ts title="content/case-studies.ts"
export const caseStudies = [
  {
    title: 'First item',
    slug: 'first-item',
  },
]
```

midcode doesn't add the page that shows it. Import the list where you need it, or ask [your agent](https://midcode.app/docs/agents/overview.md) to build the page.

## What midcode writes

Only the range that changes. Changing the year of the second project and the title of the first:

```diff title="content/projects.ts"
   {
-    title: 'Oak House',
+    title: 'Oak House, Lisbon',
     slug: 'oak-house',
```

```diff title="content/projects.ts"
     slug: 'river-studio',
-    year: 2023,
+    year: 2022,
     featured: false,
```

A string keeps the quote it had (`'`, `"` or a template literal). A new property or item follows the layout of its neighbours: the same indentation, a trailing comma if the others have one. Adding the field `subtitle`:

```diff title="content/projects.ts"
     tags: ['residential', 'timber'],
+    subtitle: '',
   },
```

In a JSON file the same edits are written as JSON (double quotes, quoted keys). In a Markdown file, a field is its line of the front matter and the body is everything under it:

```diff title="content/blog/hello.md"
 ---
-title: Hello
+title: Hello again
 date: 2026-03-01
 tags: [news, studio]
 ---
```

Front matter lists keep their layout: `[a, b]` stays inline, `- item` lines stay lines. A value that YAML would misread (a colon, a leading space, `true`, a number) is written in double quotes.

Every edit is one step of `⌘Z` and one entry in [Publish](https://midcode.app/docs/publish/publish.md), labelled with the field and its new value. Your dev server shows the change on the canvas like any other edit. A text that comes from one of these lists can also be changed by double-clicking it on the canvas: see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).

## If the file changed meanwhile

The table is a reading of the file at one moment. Before midcode edits or deletes an item of a code or JSON collection, it reads the file again and compares that item with what the table showed. If they differ (you or your agent changed the file), nothing is written, the list is reloaded and midcode says "The file changed outside midcode. The list was reloaded; try again."

**Read the files again**, in the collection's header, reloads everything on demand.

## With your agent

With the crosshair of the [agent's prompt](https://midcode.app/docs/agents/overview.md) on, a click in the CMS hands over what you clicked instead of opening it: a collection (its file, how many items, its fields), an item (which one, in which file), or one field of one item with its current value.

## Limits

- The CMS is in beta.
- A list has to be at the top level of its module. An array inside an object (`export const site = { faqs: [...] }`), inside a function or built with `.map()` is not a collection.
- JSON files whose top level is an object are not listed, even if they hold lists.
- Front matter is read as plain `key: value` lines, `[a, b]` lists and `- item` lists. Nested objects and multi-line strings in front matter are left alone and don't show as fields.
- Modules are `.ts`, `.tsx`, `.js`, `.jsx` and `.mjs`. Lists in the script of a `.vue`, `.svelte` or `.astro` file are not read.
- Fields can be added, not renamed or removed from every item at once. Do that in the file ([Code view](https://midcode.app/docs/editor/code.md)), or with your agent.
- A deleted Markdown item is in the Trash, not in `⌘Z`. Undoing **New collection**, or a new Markdown item, empties the file it created and leaves the empty file in place.
- Items don't have ids: an item is its position in the array. That's why an edit is checked against what the table showed.
- In a Shopify theme (next release), the theme's own JSON in `config/`, `templates/`, `sections/`, `locales/`, `blocks/` and `assets/` is not listed. The store's content is in [Store](https://midcode.app/docs/shopify/store.md).

To write content files that the CMS picks up, see [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Languages

> How midcode finds your site's languages, shows every text per page and per language, writes translations into your own files, and translates what's missing.

- Page: https://midcode.app/docs/data/languages
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode reads the translations your project already has, however it keeps them, and shows every text of the site side by side: the default language on the left, another language on the right. What you type is written into the same file and place the other languages use. Missing texts can be translated on your Mac with Apple Intelligence, or handed to your agent.

A site in one language can be read, edited and translated too. Its translations wait in a file beside the project until the languages are set up in code: see [A site in one language](#a-site-in-one-language).

## What midcode detects

midcode looks for three ways of keeping translations. A project can mix them.

**Catalogs**, one JSON file per language, in a folder called `messages`, `locales`, `locale`, `lang`, `langs`, `i18n`, `translations`, `dictionaries`, `dicts`, `intl` or `content` (and `public/locales`). This is what next-intl, i18next, Paraglide and the Next.js docs' dictionaries use.

```text
messages/en.json
messages/es.json

public/locales/en/common.json
public/locales/es/common.json
```

**A record per text**, in the code: an object whose keys are all language codes and whose values are strings.

```ts
const price = { en: 'Free', es: 'Gratis' }
```

**A dictionary per language**, in the code: the same, with an object of texts under each language.

```ts
const copy = {
  en: { title: 'Design in code', cta: 'Download' },
  es: { title: 'Diseñá en código', cta: 'Descargar' },
}
```

It also reads where the project lists its languages: a type such as `type Lang = 'en' | 'es'`, an array called `locales`, `languages`, `langs` or `supportedLocales`, and a `defaultLocale` property. The default language is that `defaultLocale`, else English if the site has it, else the first one found.

A language code is two letters, with an optional region or script: `en`, `es`, `pt-BR`, `zh-Hant`, `en_US`. One stray `{ en, es }` object is not taken as a setup: without catalogs, midcode needs at least two such objects before it treats the site as multilingual.

Not listed as texts: a link per language (`{ en: '/events', es: '/es/eventos' }`) and values that are only punctuation.

## The language menu

With two or more languages, the top bar shows the current language as a flag and its code. The menu lists the site's languages and **Translations…**.

Picking a language shows the canvas in it, when the site has a URL per language. midcode reads that from the `app` folder:

| The project has | The canvas goes to |
| --- | --- |
| `app/[locale]` or `app/[lang]` | `/es/pricing` for every language, the default included |
| The same, with `localePrefix: 'as-needed'` or `'never'` in its routing file or middleware | `/pricing` for the default, `/es/pricing` for the others |
| A folder per language (`app/es`, `app/(es)/es`) | `/pricing` for the default, `/es/pricing` for the others |
| None of these | The canvas stays in one language |

In the last case the menu says "This site has no URL per language, so the canvas stays in one. The texts are all in Translations."

## The Translations view

Choose **Translations…** in the language menu. The view takes the place of the canvas; `Esc` goes back.

- On the left, the languages; each one but the default shows the share of texts it has. Click one to work on it. Under them, "Where they live" lists the catalogs and how many code files hold translations.
- In the middle, two columns: the default language and the one you picked. Texts are grouped by the page that shows them (Home, `/pricing`…), then **Everywhere** for what many pages or a layout share, **Site settings** for page titles and descriptions (what [Site settings](https://midcode.app/docs/editor/site-settings.md) edits), and **Other** for the rest.
- Inside a group, a block per section: the variable, or the catalog's namespace. Each text shows its key; hover it for the button that opens `file:line` in your code editor.

How a text gets its page: midcode follows the imports from each page file to the file that holds the text. For catalogs, it looks for the files that ask for a namespace (`useTranslations('Hero')`, `getTranslations({ namespace: 'Hero' })`, `useTranslation('common')`). A namespace called `meta`, `metadata`, `seo` or `head` goes to Site settings. A catalog key no file asks for is listed under "Messages".

To change a text, type in its field and leave it, or press `Enter` (`⇧Enter` adds a line). An emptied field is not written. A field marked **Missing** has no text in that language; "Same as English" (with the default language's name) means it still holds the default text. With the default language picked on the left, the single column edits the site's own texts.

**Show** switches between **All** and **To translate** (missing, or the same as the default). **Search** looks in the texts of every language and in the keys.

## Add a language

**Add a language**, under the list on the left, offers 64 languages. Picking one:

- copies each catalog of the default language to the new one (`messages/en.json` → `messages/fr.json`), so it starts with the default texts,
- adds the language's key to every record and dictionary in the code, with the default text for now,
- adds it to the `Lang` type and to the `locales` lists.

A record whose values are the languages' own names (a language switcher's labels) gets the new language's name instead of a copy.

```diff title="lib/i18n.ts"
-export type Lang = 'en' | 'es'
-export const locales = ['en', 'es']
+export type Lang = 'en' | 'es' | 'fr'
+export const locales = ['en', 'es', 'fr']
 
-export const names = { en: 'English', es: 'Español' }
+export const names = { en: 'English', es: 'Español', fr: 'Français' }
```

The new language then shows everything as "Same as English" until it's translated. midcode does not create routes: if the site keeps a folder per language, it says "Its pages (/fr/…) still need routes: ask your agent."

## Translate what's missing

With a language other than the default picked:

- **Translate missing** translates every text that is missing or still the default, on your Mac, with Apple Intelligence. It needs macOS 26 on Apple silicon; without it the button is disabled. Texts go ten at a time, each with a hint of what it is (alt text, page title, its key), and each batch is written as it comes back. The button becomes **Stop**, with the count. Spaces at the edges of the original and a lowercase first letter are kept.
- **Copy for agent** puts a brief on the clipboard: the language, the files the translations live in, the rules (keep placeholders, ICU plurals, tags, URLs and brand names as they are), and one line per text to translate with its `file:line`, key and default text. Paste it to [your agent](https://midcode.app/docs/agents/overview.md).

With the crosshair of the agent's prompt on, clicking a text in this view hands it over: what it says, where it's written, and its translation if it has one.

Read what a model wrote before you publish it.

## What midcode writes

A translation replaces that one string. In a catalog:

```diff title="messages/es.json"
   "hero": {
-    "title": "Design in code"
+    "title": "Diseñá en código"
   }
```

A key the language doesn't have yet is added next to its siblings, with any object it needs on the way:

```diff title="messages/es.json"
   "hero": {
-    "title": "Diseñá en código"
+    "title": "Diseñá en código",
+    "subtitle": "Cada cambio es código"
   }
```

In the code, the string keeps its quotes, and a missing language gets its key at the end of the object:

```diff title="components/Pricing.tsx"
-const price = { en: 'Free', es: 'Gratis' }
+const price = { en: 'Free', es: 'Gratis', fr: 'Gratuit' }
```

Everything written to one file at once is one step of `⌘Z` and one entry in [Publish](https://midcode.app/docs/publish/publish.md), labelled like "Translation (es): 3 in es.json".

## A site in one language

When midcode finds fewer than two languages, the top bar shows a languages button instead of a flag. It says "This site is in one language" and offers:

- **Open the texts**: the Translations view, with the texts as they're written in the markup.
- **Ask your agent to set it up** and **Copy the brief**: a request to move every text into one catalog per language (`messages/<locale>.json`), add a language switcher and `hreflang` alternates, in the way that fits the framework (for Next.js: next-intl, a `[locale]` segment and middleware). Showing another language on the site is a change to its routes and code, so it's the agent's job.

The texts come from your JSX: text between tags, `alt`, `title`, `placeholder`, `aria-label` and similar attributes, and the `title` and `description` of `export const metadata`. The site's language is the `lang` of its `<html>` tag, or English.

Editing a text in the site's own language rewrites it where it's written, as an undoable edit:

```diff title="app/page.tsx"
-<h1>Design in code</h1>
+<h1>Design, in code</h1>
```

**Add a language** works here too, and the new language starts empty. What you translate (by hand, with **Translate missing**, or through **Copy for agent**) is not written into your code. It's kept in `.midcode/translations.json`, by the site's own text:

```json title=".midcode/translations.json"
{
  "source": "en",
  "languages": [
    "es"
  ],
  "texts": {
    "Design in code": {
      "es": "Diseñá en código"
    },
    "Download": {
      "es": "Descargar"
    }
  }
}
```

The same text in several places shares one translation. If you reword the site's text, its translations follow the new wording. The brief for the agent points at this file, so the agent that sets up the languages uses these translations as they are and only translates what's missing. Commit the file if you want them kept with the repository. See [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

## Shopify themes (next release)

In a Shopify theme the catalogs are the theme's `locales/*.json`. The file named `en.default.json` marks the default language, and the `*.schema.json` files (the theme editor's own texts) are left out. See [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## Limits

- Catalogs are read when they're JSON. One file per language written as `.ts`, YAML or `.po` is not found.
- Records and dictionaries are read from `.ts`, `.tsx`, `.js`, `.jsx` and `.mjs` files under 400 KB. Texts in the script of a `.vue`, `.svelte` or `.astro` file are not.
- Language codes have to be ones midcode knows (the 64 of the list, with any region).
- Grouping by page and switching the canvas read [Next.js](https://midcode.app/docs/frameworks/nextjs.md) routes (`app/` and `pages/`). In other frameworks every text is still listed and editable, under Other or Messages, and the canvas stays in one language.
- A missing item of an array in a catalog can't be added from here: add it in the file.
- **Add a language** adds texts, not routes, middleware or a language switcher.
- A one-language site's texts are read from JSX files only (`.tsx`, `.jsx`, `.js`, `.mjs`). Text that comes from a variable, a prop or a data file isn't listed there; edit it on the [canvas](https://midcode.app/docs/editor/text-and-media.md) or in the [CMS](https://midcode.app/docs/data/cms.md).
- `.midcode/translations.json` is written directly, without a step in `⌘Z`. Publish lists it as a changed file, like any other file of the project.
- Undoing **Add a language** takes back the edits to your code file by file. The catalog it created is emptied, not deleted.
- midcode writes texts as you type them. Placeholders (`{name}`, `%s`) and plural forms are yours to keep right.

To write translations in a shape midcode picks up, see [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Database

> How midcode finds your project's Postgres or SQLite database, shows its tables, lets you edit rows safely, and what it never does with your connection string.

- Page: https://midcode.app/docs/data/database
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

Database is the place in midcode for what your site stores while it runs: users, orders, messages. It finds the database your project already points at, shows its tables as tables, lets you change rows, run SQL, change the tables themselves, and see who signs in and which environment variables the site reads.

Three rules hold everywhere in it:

- **Your connection string stays in midcode's main process.** The window you look at only learns where a database is (its host and name, or its file), never how to get in. It isn't put in reports, and it isn't given to your agent. See [Privacy and security](https://midcode.app/docs/reference/privacy.md).
- **A database that isn't on this Mac opens read-only** until you turn on **Allow changes**. Read-only is enforced by the database engine, not by midcode reading your SQL.
- **What you change is changed in the database, for real.** It isn't a file, so there is no `⌘Z` and nothing to publish. That's why rows wait for **Save**, and why what can't be taken back is asked about first.

This page covers finding and connecting a database, the overview, browsing tables and editing rows. The rest is in [SQL, charts and backups](https://midcode.app/docs/data/sql.md), [Changing tables](https://midcode.app/docs/data/schema.md), [Sign-in and users](https://midcode.app/docs/data/users.md) and [Environment variables](https://midcode.app/docs/data/env.md).

Not sure this is what you need? What you write yourself (posts, FAQs, a team list) is the [CMS](https://midcode.app/docs/data/cms.md), and publishes with the site. What your visitors create is the database.

## Open it

Click **Database** in the middle of the top bar. The view takes the place of the canvas; `Esc` goes back.

The left side is one list of places, with no tabs: **Overview**, **Tables** (each table), **SQL** (the SQL editor and your saved queries), **Sign-in** (People, Ways to sign in, Protected pages) and **Site** (Environment variables). Above the list are the connection, its engine and address, and the **Allow changes** switch. The view opens where you left it, and on Overview the first time.

## Which databases midcode finds

midcode looks where your project's own code looks. It reads these files, in this order: `.env.local`, `.env.development.local`, `.env.development`, `.env`, `.env.production.local`, `.env.production`.

| Found from | Example |
| --- | --- |
| Any variable whose value is a connection string, whatever it's called | `DATABASE_URL=postgresql://…`, `DIRECT_URL`, `POSTGRES_URL` |
| [Laravel](https://midcode.app/docs/frameworks/laravel.md)'s `DB_*` set | `DB_CONNECTION=pgsql` with `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`; or `DB_CONNECTION=sqlite` with `DB_DATABASE` |
| A SQLite path in a variable whose name has `DATABASE`, `DB` or `SQLITE` | `DATABASE_URL="file:./dev.db"` (resolved from `prisma/` first, as Prisma does) |
| SQLite files in the usual folders | `*.db`, `*.sqlite`, `*.sqlite3` in the project's root, `prisma`, `db`, `data`, `database`, `storage`, `drizzle`, `sqlite`, `var`, `instance` |

`${OTHER}` references inside an `.env` file are filled in from the same file. A file only counts as SQLite if it starts with SQLite's own header.

Each one found is a connection in the **Connection** menu, named after its variable or its file. With several, midcode opens the one you picked last, else the first one on this Mac.

### Engines

| Engine | In midcode |
| --- | --- |
| Postgres (Supabase, Neon, Vercel Postgres, Railway, RDS, one on your Mac) | Opens |
| SQLite (a file) | Opens |
| MySQL / MariaDB, Turso / libSQL, MongoDB, SQL Server, `prisma://` URLs | Listed, with "isn't supported yet" |

## Connect one by hand

If the project has no connection string (a Supabase site that only uses its API keys, for example), give midcode one:

1. In Overview, click **Connect one I have**. With a database already open, use the **+** beside the connection menu.
2. Paste the connection string. It starts with `postgres://` or `postgresql://`. **Where do I find it?** says where it is in Supabase (Connect → Session pooler), Neon (Dashboard → Connect) and Vercel (Storage → your database → `.env.local`).
3. Click **Connect**. midcode tries the string before keeping it.

Supabase and Neon show the string with `[YOUR-PASSWORD]` in it: replace that with your database's password, or midcode tells you the password is missing.

The string is kept encrypted on your Mac, in midcode's own data, never in your project. It is never shown again: the field is a password field, and the window gets back only the host and database name. **Remove connection…**, in the **⋯** menu beside the connection, makes midcode forget it; the database isn't touched.

`sslmode` in the string is read the way Postgres' own tools read it: `disable` uses no TLS, `require` encrypts without checking the certificate, `verify-ca` and `verify-full` check it. Without it, a remote host is tried with TLS first and a local one without. Prisma's `?schema=` picks the schema that opens.

Only Postgres is connected this way. A SQLite file is found when it's in one of the folders above.

## Create a database

In a project with no database, Overview offers **Create a database**. It makes an empty SQLite file at `data/database.db` in your project and opens it. Nothing to install or start. Asking again gives you the same file.

It's right for building and trying things. A file database works on your Mac and on a server with a disk; a site published on Vercel or Netlify needs a hosted database (Supabase, Neon).

## Overview

Overview answers "is this connected to my site, and what's next?". It lists six things in order, each with a check when it's there and the next step when it isn't. Everything it says about your site comes from reading your code, not from running it.

| Step | What it reads | What it offers |
| --- | --- | --- |
| A database | The connections found | **Connect one I have**, **Create a database** |
| Your site reads it | The package your code talks to a database with (Prisma, Drizzle, Supabase's client, a driver, or Laravel / Django / Rails) and the files that import it | **Connect the site…**, **Give it to the site** |
| Tables | The database | **New table** (see [Changing tables](https://midcode.app/docs/data/schema.md)), **Open** |
| Forms | Every `<form>` in your code and templates, with the `name` of its fields | **Save to a table…** |
| Sign-in | The sign-in library in your code | **Add sign-in**, **Open** |
| Rows on your pages | The tables | **Show a table on a page…** |

### Give it to the site

A connection you typed is known only to midcode: your site's code doesn't have it. **Give it to the site** writes it as `DATABASE_URL` into the project's local env file (`.env.local` in Next.js, Vite, Astro, SvelteKit, Nuxt, Remix and React Router projects, `.env` otherwise):

```text title=".env.local"
DATABASE_URL=postgresql://app:secret@db.example.com:5432/shop
```

The string goes from the main process to that file and nowhere else. midcode reads the file back the way your site will, and removes the line again if it doesn't give the same string. It refuses if `DATABASE_URL` already has a value, and if the file isn't ignored by git (see [Environment variables](https://midcode.app/docs/data/env.md)). From then on the connection is the project's, and midcode's own copy is deleted.

### What the agent writes

midcode does not write the code that reads a database: it depends on how each project is built. Four buttons put the request in words for [your agent](https://midcode.app/docs/agents/overview.md) instead, with what midcode already knows. Each shows the exact text before anything is sent, with **Copy** and **Send to the agent**.

- **Connect the site…** asks for one module that opens the database (`lib/db.ts` or wherever the project keeps such things), with the client the project already has, server only.
- **Save to a table…**, in Overview's list of forms and in a form's [settings on the canvas](https://midcode.app/docs/editor/components.md), sends where the form is written, its field names, and the table you chose (with its columns) or the name of a new one. With no form yet, add one from [Insert](https://midcode.app/docs/editor/insert.md).
- **Show a table on a page…**, here and as **Show on a page…** in a table's **⋯** menu, asks you for the page, the shape (Cards, List or Table) and the columns, and sends the table's columns and types.
- **Add sign-in** is described in [Sign-in and users](https://midcode.app/docs/data/users.md).

The briefs say where the connection comes from (the variable's name and the file it's in, or the SQLite file's path), never the string itself. What the agent changes from the Chat view is undoable and listed in [Publish](https://midcode.app/docs/publish/publish.md) like any other edit. An agent in the Terminal view writes files by itself: they show in Publish as changed files, outside `⌘Z`.

## Read-only and Allow changes

Under the connection, midcode says **Read-only** or **Changes allowed**.

- A database on this Mac starts with changes allowed. "On this Mac" means a SQLite file, or a Postgres host that is `localhost`, `127.0.0.1`, `::1`, a `*.localhost` name, `host.docker.internal` or a Unix socket.
- Any other database starts read-only. Turning on **Allow changes** asks first: "This database isn't on this Mac: it may be the one your site runs on. What you change here is changed for real, with no undo and nothing to publish."
- The choice lasts until you close midcode. Next time, a remote database is read-only again.
- Without a [license or a running trial](https://midcode.app/docs/start/install.md), nothing can be changed, as with every other edit in midcode.

Read-only is the engine's own. On Postgres every statement runs inside a `READ ONLY` transaction, so Postgres refuses an `UPDATE`, and also a function that writes. A SQLite file is opened read-only. Statements that would leave that transaction (`COMMIT`, `BEGIN`, `SET TRANSACTION…`) are refused before they run.

## Browse a table

Click a table in the list. A view is listed too, with its own icon. The number beside each table is how many rows it has: counted in SQLite, Postgres' own estimate in Postgres.

- **Rows** shows 200 rows at a time, with the arrows for the previous and next 200. The count reads like "1–200 of 12,480"; a "≈" means counting took too long and the number is the engine's estimate.
- Click a column's header to sort: ascending, descending, then back. Sorting and filtering are done by the database, over the whole table.
- **Filter** adds a condition on a column: `=`, `≠`, `>`, `≥`, `<`, `≤`, contains, is null, is not null. Several filters all have to hold. "contains" ignores case.
- A value that points at another table has an arrow: it opens that table on the row it points at.
- A long value, or JSON, is read whole in the strip under the grid when you select its cell. `⌘C` copies the selected cell, and the arrow keys move between cells. Every key is in [Keyboard shortcuts](https://midcode.app/docs/reference/shortcuts.md).
- **Structure** lists the columns: type, whether empty is allowed, default, and keys. A foreign key is a link to its table.
- **Open as SQL** puts a `select *` of the table, with `limit 100`, in the [SQL editor](https://midcode.app/docs/data/sql.md), to go on from there.

With several schemas in a Postgres database, a **Schema** menu chooses whose tables are listed. Past 8 tables there is a search field.

## Edit rows

Rows can be changed in a table (not a view), on a connection that allows changes.

- Double-click a cell, press `Enter`, or start typing. A column that only takes some values (a boolean, an enum) opens a list. A long value or JSON is edited in the strip below, with **Set to NULL**, **Cancel** and **Done**.
- **New row** adds a row at the top. A cell you leave alone shows "default" and takes the table's default.
- Click a row's number to pick it (`⇧` for a range), then **Duplicate** or **Delete** (`⌫`). A duplicate leaves out the key the database gives by itself.
- Right-click a cell for **Copy**, **Set to NULL**, **Use the default**, **Put back what it was**, **Duplicate row**, **Delete row** and, on a row marked for deletion, **Keep this row**.

Nothing touches the database while you do this. Changes are staged: changed cells are tinted, new rows green, deleted rows red, and the table shows a dot in the list. A bar at the bottom says how many changes are unsaved, with **Discard** and **Save** (`⌘S`). Staged changes are kept per table while midcode is open, also if you leave the view.

### What Save does

Save sends every change of that table as one transaction: deletes, then updates, then new rows. One statement per change:

```sql
update "public"."orders" set "status" = $1
where "id" = $2 and "status" is not distinct from $3
```

- A row is found by its whole primary key.
- An update also checks that each cell it changes still holds what the grid showed (`$3` above).
- Each statement must change exactly one row.

If any of that fails, it's a conflict: someone else changed or removed the row since you read it. The whole transaction is rolled back, nothing is saved, and midcode says "A row isn't what it was when you read it". Read the table again and redo the change.

On a database that isn't on this Mac, Save asks once more before it runs: "Once saved, there's no undo."

### Tables you can't fully edit

| Table | What you can do |
| --- | --- |
| No primary key | Add rows. Existing rows can't be changed or deleted: they can't be told apart |
| A view | Nothing: change the tables it reads from |
| Binary columns (`bytea`, `blob`) | Read only |

A lock beside the table's name says which of these applies.

## With your agent

The agent doesn't see your database. With the crosshair of the [agent's prompt](https://midcode.app/docs/agents/overview.md) on, a click hands over exactly what you clicked: a table in the list gives its name, columns, types and keys (never its rows); a row in the grid gives that row's values. Nothing else leaves the view.

## Limits

- Database is in beta and not in the released version yet.
- Postgres and SQLite only. MySQL, Turso and MongoDB are recognised and not opened.
- Table pages are 200 rows. Counting a table stops after 4 seconds and falls back to the estimate. A SQLite file over 200 MB isn't counted table by table when it opens.
- A statement may take 30 seconds; then it's stopped.
- Row changes have no undo, and conflicts are all or nothing: one conflicting row holds back the whole Save.
- midcode doesn't add `data/database.db` to `.gitignore`. A SQLite file inside your project is a file git sees, so Publish lists it when it changes. Decide whether it belongs in the repository.
- Tried with Postgres 17 and SQLite, against databases made for testing. Not tried: a real Supabase project (its `auth` and `storage` schemas, its roles), partitioned tables, large databases.

## Troubleshooting

**"This connection is read-only. Turn on "Allow changes" first."** The database isn't on this Mac, or changes were turned off. Turn the switch on, above the list.

**"Nothing answers at that address (connection refused)."** The database isn't running, or the port is wrong. For a local Postgres, start it; for a hosted one, check the string.

**A table of the site is missing.** It may be in another schema: check the **Schema** menu. **Read the tables again**, beside the switch, reloads the list after something changed outside midcode.

**The site and midcode show different data.** They may point at different databases. Your site reads the env file of the mode it runs in; midcode lists every connection it finds in all of them and opens one. Check the name and the file of the connection in the menu.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

---

# SQL, charts and backups

> Run SQL against your project's database in midcode, save queries with the project, read a result as a chart, and export, import or delete a whole database.

- Page: https://midcode.app/docs/data/sql
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

The SQL editor runs what you write against the database open in [Database](https://midcode.app/docs/data/database.md), Postgres or SQLite. A script runs as one transaction, anything that can't be taken back is asked about before it runs, and a query you name is saved as a file in your project. The same view exports a whole database to a file, loads one from a file, and deletes one.

Whatever SQL changes is changed in the database itself. There is no `⌘Z` for it and nothing to publish. To change tables through a dialog that also records a migration, see [Changing tables](https://midcode.app/docs/data/schema.md).

## The SQL editor

Open **Database** in the top bar, then **SQL editor** in the list on the left.

- The editor completes the real tables and columns of the open database. Once a statement names a table (`from`, `join`, `update`, `into`), that table's columns are offered wherever a name can go. `Tab` accepts.
- **Run** (`⌘↵`) runs what's selected, or everything when nothing is. While it runs the button is **Stop**, which cancels the statement in the database.
- **Explain** asks how the database would run the first statement, without running it (`explain` in Postgres, `explain query plan` in SQLite).
- Drag the line between the editor and the result to resize them.
- `⌘Z` and `⇧⌘Z` undo and redo what you typed in the editor, not what a statement did.

Each statement gives its own result. With several, a row of tabs names them ("1 · SELECT", "2 · UPDATE") and the last one that returned rows is shown. A statement with no rows says what it did: "3 rows changed", or "done".

Under a result: the number of rows, how long it took, and **Table** / **Chart**. Values are shown as the database prints them. In Postgres nothing is converted on the way, so a `bigint`, a `numeric` or a timestamp reads exactly as it is stored.

When a statement fails, the error is shown in the database's own words and the cursor goes to the place it points at.

What you type in the unnamed editor is kept between sessions, so it's a safe place to try things.

## How a script runs

midcode splits the script into statements and runs them in order, in one transaction: all of it, or none. If the third statement fails, what the first two changed is undone, and the result says "Nothing was kept: what the statements before it changed was undone with it."

Two kinds of script are not wrapped in a transaction:

- one that has its own (`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`…): it keeps to those,
- one with a statement a database refuses inside a transaction: `VACUUM`, `PRAGMA`, `ATTACH`, `REINDEX`, `CREATE DATABASE`, anything `CONCURRENTLY`.

When one of those fails, the result says "The statements before it stay as they ran."

On a read-only connection the script runs under the engine's own read-only mode (see [Read-only and Allow changes](https://midcode.app/docs/data/database.md)). A statement that changes something is refused by the database, and midcode says "This connection is read-only. Turn on "Allow changes" first."

Two limits apply to every statement:

| Limit | What happens |
| --- | --- |
| 1,000 rows | The first 1,000 are shown, with "add a LIMIT, or a WHERE, to see others". Postgres reads them through a cursor, so a table of millions costs only the rows shown |
| 30 seconds | The statement is stopped: "It took more than 30 seconds and was stopped." |

## What's asked first

On a connection that allows changes, midcode looks at each statement before running the script. These are asked about, all in one dialog:

| Statement | What the dialog says |
| --- | --- |
| `DROP …`, or `ALTER … DROP …` | removes it, with what's in it |
| `TRUNCATE` | empties the table |
| `DELETE` with no `WHERE` | has no WHERE: it deletes every row |
| `UPDATE` with no `WHERE` | has no WHERE: it changes every row |

The dialog is titled "Run this?" (or "Run these?"), quotes each statement, ends with "There's no undo for it.", and runs the script only if you click **Run**. Nothing runs while it's open. A `DELETE` inside a `WITH` is caught too; an `INSERT … ON CONFLICT DO UPDATE` is not asked about.

## Saved queries

**Save with a name** (`⌘S`) asks for a name and writes the query to your project:

```sql title=".midcode/queries/Signups this week.sql"
select date_trunc('day', created_at) as day, count(*) as signups
from users
where created_at > now() - interval '7 days'
group by 1
order by 1;
```

The file is the SQL as you wrote it, nothing added. Its name is the name you gave, without the characters a file name can't have, up to 80 characters. Saved queries are listed under **SQL** on the left; `⌘S` in one saves it again, and a dot marks unsaved changes. **Delete this query**, on a query's row, sends its file to the Trash.

Because they are files in the project, queries travel with the repository and your agent can read them. Commit `.midcode/queries/` if you want to share them. See [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

## Results as CSV

A result with rows has two buttons at the right of its footer: **Copy as CSV** and **Export as CSV**, which asks where to save. The first line is the column names. `NULL` is an empty field, and a value with a comma, a quote or a line break is quoted. It holds the rows on screen, so at most 1,000.

## Charts

Click **Chart** under a result to draw it instead of listing it.

- **Value** is the number that's plotted; it lists the result's numeric columns.
- **Along** is the column the values are set against. Any column works.
- **Drawn as** is **Bars** or **Line**. midcode starts with a line when the column along is a date, or a number with more than 12 rows, and with bars otherwise.

```sql
select date_trunc('month', created_at)::date as month, count(*) as orders
from orders
group by 1
order by 1;
```

Run this and switch to Chart: `orders` by `month`, as a line. Hover a point or a bar for its value. With more points than fit, the chart scrolls sideways. A result with no numeric column says "Nothing to chart: this result has no column of numbers."

A chart is one measure against one column: one series, one axis. It's a way to read a result, and isn't saved with the query.

## Export a database

The **⋯** beside the connection has **Export…**. It writes the whole database to a file you choose:

- **SQL script**: a `.sql` file that makes the tables again and fills them. Untick **With the rows** for the tables alone.
- **Database file** (SQLite only): a copy of the file itself, made with SQLite's `VACUUM INTO`, so it is consistent even if your site is writing at that moment.

A Postgres export is one schema; with several, the dialog asks which. The file is written beside its destination as `<name>.part` and renamed when it's complete, so a failed export never replaces a good backup.

### What a Postgres script contains

Everything is read in one read-only snapshot, and every name is written with its schema. In this order: enum types, sequences, functions, tables, their rows, where each sequence left off, primary keys and other constraints, indexes, views and materialized views, triggers, row-level security and its policies. A function that takes or returns a table's row is written after the tables.

```sql title="shop-2026-10-05.sql"
-- db.example.com:5432/shop, schema "public" · Postgres · exported by midcode on 2026-10-05
-- What makes the tables, then their rows.
-- Not in this file: roles and what they may do, extensions, comments.
-- Load it in one transaction (midcode’s Import does; psql: --single-transaction), into a database that doesn’t have these tables yet.

SET LOCAL check_function_bodies = false;
CREATE SCHEMA IF NOT EXISTS "public";
CREATE TABLE "public"."orders" (
  "id" bigint GENERATED BY DEFAULT AS IDENTITY NOT NULL,
  "email" text NOT NULL,
  "created_at" timestamp with time zone DEFAULT now() NOT NULL
);
INSERT INTO "public"."orders" ("id", "email", "created_at") VALUES
  ('1', 'ana@example.com', '2026-09-30 14:02:11.52+00');
SELECT pg_catalog.setval(pg_catalog.pg_get_serial_sequence('"public"."orders"', 'id'), 1, true);
ALTER TABLE ONLY "public"."orders" ADD CONSTRAINT "orders_pkey" PRIMARY KEY (id);
```

Not in the file:

- roles and grants,
- extensions (the ones the database has are named in a comment; the database you load into needs the ones it uses),
- comments on tables and columns,
- partitioned and foreign tables (named in a comment),
- anything that belongs to an extension,
- other schemas: each schema is its own export.

The file's first lines say the first three, so whoever loads it knows.

### What a SQLite script contains

Each table's `CREATE TABLE` exactly as SQLite keeps it, an `INSERT` per row with every value written by SQLite's own `quote()`, where each `AUTOINCREMENT` left off, then indexes, views and triggers. It is wrapped the way `sqlite3 .dump` wraps it:

```sql title="database-2026-10-05.sql"
-- database.db · SQLite · exported by midcode on 2026-10-05
-- What makes the tables, then their rows.
PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE "messages" (
  "id" integer primary key,
  "name" text not null,
  "body" text
);
INSERT INTO "messages" ("id", "name", "body") VALUES (1, 'Ana', 'Hello');
COMMIT;
```

Generated columns are left out of the `INSERT`s, and a virtual table is written without its shadow tables.

## Import a SQL file

**Import a SQL file…**, in the same menu, loads a `.sql` script into the open database. The connection has to allow changes.

1. Choose the file. midcode reads it and counts its statements. Nothing has run yet.
2. A dialog says what's in it: how many statements of each kind ("CREATE × 4, INSERT × 120") and how many of them delete something that's there now.
3. **Load it** runs the file.

The file runs as one transaction: all of it or none. A script with its own `BEGIN` and `COMMIT` keeps to those, and one with a statement that can't run inside a transaction runs statement by statement. If a statement fails, midcode shows its line, the statement and the error, and says whether anything was kept: "It wasn't loaded: nothing was changed", or "It stopped partway".

A script exported by midcode expects a database that doesn't have those tables yet. A `.db` file is not a script: put it in your project's `data` folder and midcode finds it.

## Delete a database

**Delete database…** only deletes a database that is a file inside your project.

- The dialog says what goes: how many tables and rows, and which variable points at the file, so you know your site fails wherever it reads it.
- You type the file's name to confirm. Pasting is blocked, so it can't be done by a slip.
- The file goes to the Trash, with SQLite's `-wal`, `-shm` and `-journal` files. It can be put back until the Trash is emptied.
- **Export a copy first** opens the export dialog from there.

A database on a server isn't deleted from midcode. The dialog says where to delete it (Supabase, Neon, or the tool that runs it on your Mac) and, for a connection you typed, offers **Remove connection…**, which only makes midcode forget the string. A SQLite file outside your project isn't deleted either: delete it in Finder.

## Limits

- SQL in midcode is in beta and not in the released version yet.
- What's asked first is found by scanning the statement, not by parsing it. A `WHERE` anywhere in the statement, in a subquery too, counts as having one. Don't lean on the dialog: read what you run.
- One statement may return 1,000 rows and take 30 seconds. An export or an import may take 10 minutes. An import file may be 150 MB; load a bigger one with `psql` or `sqlite3`.
- Explain covers the first statement only.
- Charts are one series, bars or a line. No stacked or grouped series, no second axis, no export as an image.
- A saved query can't be renamed from the editor: rename its file.
- Tried: a Postgres 17 database with an enum, serial and identity columns, a generated column, foreign keys, a check, a partial index, a view, functions (one returning rows of a table), a trigger and policies, exported, imported into another database and compared equal, with new ids continuing where they were. The same with SQLite, against `sqlite3 .dump`.
- Not tried: a real Supabase project (its `auth` and `storage` schemas, its roles), partitioned tables (they are skipped), large databases.

---

# Changing tables

> Create, rename and delete tables and columns from midcode, see the exact SQL before it runs, and where the change is recorded in your project, Prisma included.

- Page: https://midcode.app/docs/data/schema
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

In [Database](https://midcode.app/docs/data/database.md) you can change the tables themselves: make a new one, add a column, rename or delete either. Every change goes through the same two steps. First you say what you want, in words (a name, the columns, their types). Then midcode shows the exact SQL it will run and the file where the change will be kept in your project. Nothing runs before you click **Apply**.

Where the change ends up depends on how your project defines its tables:

| The project | What midcode does |
| --- | --- |
| Has no tool for its tables | Runs the SQL and writes it as a migration file |
| Uses Prisma | Edits `prisma/schema.prisma`, runs the SQL Prisma writes for that edit, and records it as a Prisma migration |
| Uses Drizzle, or Laravel, Django or Rails migrations | Doesn't run it: hands the change to your agent with what to do in that tool |

The connection has to allow changes: see [Read-only and Allow changes](https://midcode.app/docs/data/database.md). A change to the tables has no `⌘Z`.

## What you can change

| Change | Postgres | SQLite |
| --- | --- | --- |
| Create a table | Yes | Yes |
| Rename or delete a table | Yes | Yes |
| Add, rename or delete a column | Yes | Yes |
| Make a column required or optional | Yes | No |
| Change a column's default | Yes | No |

SQLite can't alter a column that exists, so those two aren't offered there.

## Make a change

**A new table.** Click the **+** beside **Tables** in the list (or **New table** in Overview). Give it a name, choose what each row's id is, and list its columns:

- **Each row's id**: "A number that counts up" (1, 2, 3…) or "A random id" (a UUID). The column is always called `id`.
- Each column has a name, a type, a default and **Required**. The form starts with one empty column and a `created_at` that fills itself with the moment the row is made. Rows left without a name are ignored.

**A column.** Open the table, then **⋯** → **Add column…**, or **Add column** in the **Structure** tab. Besides name, type and default, a new column can be **Required** and **No two rows the same** (unique). If the table already has rows, a required column needs a default: midcode says so.

**Everything else.** In **Structure**, the **⋯** at the end of a column's row has **Rename…**, **Make it required** or **Let it be empty**, **Change the default…** and **Delete column…**. The table's own **⋯** has **Rename table…** and **Delete table…**. A primary key column can be renamed, not deleted or altered.

Then **Continue** shows the review: the SQL, the file it will be kept in, and, on a database that isn't on this Mac, "the change is real as soon as it's applied". **Back** returns to the form. **Apply** runs it. A change with nothing to fill in (required or optional, a deletion) goes straight to the review. A deletion says what is lost ("Its rows go with it, and there's no undo.") and its button is a red **Delete**.

### Column types

The dialog offers types in words. Each engine gets its own:

| In the dialog | Postgres | SQLite |
| --- | --- | --- |
| Text | `text` | `text` |
| Number | `integer` | `integer` |
| Decimal number | `numeric` | `real` |
| Yes / No | `boolean` | `boolean` |
| Date | `date` | `date` |
| Date and time | `timestamptz` | `datetime` |
| JSON | `jsonb` | `json` |
| → another table | The type of that table's key, with `references` | The same |

A link ("→ orders") is offered for every table in the same schema that has a one-column primary key. It makes a foreign key to that key.

Defaults are asked the way the type is answered: **Today** or **Now** for dates, **Yes** or **No**, or a value you type, which midcode checks (a number has to be a number, JSON has to parse) and quotes. Table and column names are always written in quotes, so a table called `Order` or a column called `user` is fine. A name can be up to 63 characters.

## The SQL it runs

A table called `messages`, with the id that counts up, on Postgres:

```sql
create table "public"."messages" (
  "id" bigint generated by default as identity primary key,
  "name" text not null,
  "email" text not null,
  "body" text,
  "created_at" timestamptz not null default now()
);
```

The same on SQLite:

```sql
create table "messages" (
  "id" integer primary key,
  "name" text not null,
  "email" text not null,
  "body" text,
  "created_at" datetime not null default current_timestamp
);
```

With "A random id", the key is `"id" uuid primary key default gen_random_uuid()` on Postgres and `"id" text primary key default (lower(hex(randomblob(16))))` on SQLite.

The other changes are one statement each:

```sql
alter table "public"."messages" add column "read" boolean not null default false;
alter table "public"."orders" add column "customer_id" bigint not null references "public"."customers" ("id");
alter table "public"."messages" rename column "body" to "text";
alter table "public"."messages" alter column "body" set not null;
alter table "public"."messages" drop column "body";
alter table "public"."messages" rename to "inbox";
drop table "public"."messages";
```

On SQLite a unique column added to an existing table is two statements, because SQLite takes `unique` only when a table is made:

```sql
alter table "messages" add column "slug" text;
create unique index "messages_slug_key" on "messages" ("slug");
```

The statements of one change run as one transaction.

## The migration file

After the SQL runs, midcode writes it into your project, so the code says what the database is and another copy of it can be brought to the same state.

```sql title="db/migrations/20261005183000_create_messages.sql"
-- Create the table “messages” with an “id” key (a number that counts up) and the columns “name” (text, required), “email” (text, required), “body” (text, optional), “created_at” (datetime, required, default now)

create table "public"."messages" (
  "id" bigint generated by default as identity primary key,
  "name" text not null,
  "email" text not null,
  "body" text,
  "created_at" timestamptz not null default now()
);
```

Where it goes:

| The project has | The folder |
| --- | --- |
| `supabase/migrations` or `supabase/config.toml` | `supabase/migrations/` |
| A SQLite database | `migrations/` beside the file: `data/database.db` → `data/migrations/` |
| `.sql` files in `migrations/`, `db/migrations/`, `sql/migrations/` or `database/migrations/` | That folder |
| None of these | `db/migrations/` |

The name follows the files already there. If they are numbered (`0004_add_orders.sql`), the new one is the next number with the same width (`0005_create_messages.sql`). Otherwise it's the time, in UTC, as Supabase's CLI and most tools write it: `20261005183000_create_messages.sql`. The second part says what the change is: `create_messages`, `add_messages_read`, `rename_messages_body_to_text`, `drop_messages`.

In a Supabase project, if the database has Supabase's own `supabase_migrations.schema_migrations` table, midcode adds the migration to it in the same transaction, so a later `supabase db push` doesn't run it again.

The file shows in [Publish](https://midcode.app/docs/publish/publish.md), as "Database:" and its name. It is not in `⌘Z` on purpose: taking the file back would not take the change out of the database. midcode never overwrites a migration file that exists.

## Projects with Prisma

If the project has `prisma/schema.prisma`, the change is made the way Prisma means it to be made.

1. midcode edits `prisma/schema.prisma`: only the lines that change, lined up with their neighbours.
2. It asks the project's own Prisma CLI for the SQL between the schema as it was and as it is now (`prisma migrate diff`, from file to file). No database is asked anything.
3. The review shows that SQL and, under "And in `prisma/schema.prisma`", the lines that go and the lines that come.
4. **Apply** runs the SQL in one transaction, on the connection that's open. If the project has a `prisma/migrations` folder, midcode also writes `prisma/migrations/<time>_<name>/migration.sql` and, in the same transaction, adds it to `_prisma_migrations` with the checksum Prisma checks. To Prisma it's a migration like any other, already applied.
5. `prisma generate` runs, so your code knows the new shape.

Adding an optional text column `subtitle` to `Post`:

```diff title="prisma/schema.prisma"
 model Post {
   id        Int      @id @default(autoincrement())
   title     String
   createdAt DateTime @default(now())
+  subtitle  String?
 }
```

```sql title="prisma/migrations/20261005183000_add_post_subtitle/migration.sql"
-- AlterTable
ALTER TABLE "Post" ADD COLUMN     "subtitle" TEXT;
```

The SQL is Prisma's own, in Prisma's own style. midcode never runs `prisma db push`, `prisma migrate dev` or `prisma migrate deploy`: those compare the whole database with the whole schema, or apply every pending migration, not this one change.

Three things are worth knowing:

- **Renaming a column** adds `@map("new_name")` to the field and runs midcode's own `rename column`, because Prisma would write it as a column dropped and another added. Your code keeps calling the field what it did.
- **A link** to another table is three lines: the column, the relation, and the other model's side of it. Deleting that column, or that table, takes all three.
- **Without a `prisma/migrations` folder** (a project that uses `db push`), only the schema and the database change.

The files are written before the SQL runs and put back as they were if the database refuses it. If the client can't be generated, midcode says: "Run: npx prisma generate".

### What Prisma changes are handed to the agent

When a change isn't one clean edit of the schema, midcode doesn't make it. The review says why and shows the text for your agent instead. That happens for:

- renaming a table (Prisma names its key and indexes after it),
- renaming or deleting a column that is the table's key, part of a key or an index, or that another table links to,
- renaming a column that has a unique index, or one that is a link,
- making a link column required or optional,
- a table or a column that isn't in the Prisma schema (it was made another way),
- a second link between the same two models, or a table that links to itself (both need named relations),
- deleting a table another model still points at,
- a schema split in several files, or anywhere other than `prisma/schema.prisma`,
- a project with Prisma migrations on SQLite,
- a database whose migration history isn't where the project's is: a migration not applied yet (midcode names it and says to run `npx prisma migrate deploy` first), one that failed halfway, or no `_prisma_migrations` table at all,
- a change for which Prisma would drop something you didn't ask to drop,
- Prisma not installed in the project yet.

## Projects with another tool

midcode recognises these by their files:

| Tool | Recognised by | What the brief tells the agent to run |
| --- | --- | --- |
| Drizzle | `drizzle.config.ts` (`.js`, `.mjs`) | Change the Drizzle schema, then `npx drizzle-kit generate && npx drizzle-kit migrate` |
| Laravel | `artisan` | `php artisan make:migration …`, write the change, `php artisan migrate` |
| Django | `manage.py` | Change `models.py`, then `makemigrations` and `migrate` |
| Rails | `bin/rails` | `bin/rails generate migration …`, write the change, `bin/rails db:migrate` |

In these projects the tool's files are the truth. SQL run behind its back would leave the tool and the database disagreeing, so midcode refuses to run the change even if asked. The review step shows the brief, with **Copy** and **Send to the agent**:

```text
Change this project's database: Add the column “subtitle” (text, optional) to the table “posts”.

The project defines its tables with Drizzle, so don't run SQL against the database directly: Drizzle and the database would stop agreeing.
Make the change in the Drizzle schema (the file drizzle.config points at), then run: npx drizzle-kit generate && npx drizzle-kit migrate (or npx drizzle-kit push, if the project has no migrations folder)

For reference, the change as SQL (Postgres):
alter table "public"."posts" add column "subtitle" text;
```

One exception: the database midcode created for you (`data/database.db`) is always changed directly, whatever else the project has.

Changing rows, and running your own SQL in the [SQL editor](https://midcode.app/docs/data/sql.md), work the same in every project. Only changes made through these dialogs are held back.

## Limits

- Changing tables is in beta and not in the released version yet.
- Not possible yet from these dialogs: changing a column's type, creating or dropping indexes, a key of more than one column. Use the [SQL editor](https://midcode.app/docs/data/sql.md) or your agent.
- SQLite can't change whether an existing column is required, or its default, and can't add a column that defaults to the current time to a table that exists.
- Drizzle is recognised and handed to the agent; midcode doesn't edit a Drizzle schema.
- Rows you changed in a table and hadn't saved are discarded when that table's columns change.
- If the migration file can't be written after the SQL ran, the database still has the change: midcode says "Done." without a file.
- The Prisma path was checked with Prisma 5.22 and 7.6 (`migrate status`, `migrate diff` against the database and `migrate dev` all agree afterwards). Other versions follow the same commands and weren't each tried.

---

# Sign-in and users

> How midcode reads your site's sign-in from its code, lists the people in your database without ever reading a password, and what it asks your agent to build.

- Page: https://midcode.app/docs/data/users
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

The **Sign-in** group of [Database](https://midcode.app/docs/data/database.md) shows who signs in to your site and how: the people, the ways to sign in the site offers, and which pages ask for a signed-in visitor.

Two things to know first. midcode reads all of this from your project's code and never guesses it from the database alone. And midcode **does not write sign-in code**: adding sign-in, another way to sign in, or a check on a page is put in words for your agent, with what midcode already knows about the project.

## Where it is

Open **Database** in the top bar. Under **Sign-in** in the list on the left there are three places: **People**, **Ways to sign in** and **Protected pages**. The last two show a count once a sign-in library is found.

With no sign-in in the project, People says "No sign-in yet" and offers **Add sign-in**.

## What's read from your code

### The library or service

midcode looks at your `package.json` (and, for three frameworks, at their files). The first that matches, in this order:

| Sign-in | Recognised by |
| --- | --- |
| Auth.js | `next-auth`, `@auth/core`, `@auth/sveltekit`, `@auth/nextjs` or `@auth/express` |
| Better Auth | `better-auth` |
| Clerk | Any `@clerk/…` package |
| Supabase Auth | A Supabase package, and code that calls its auth (`.auth.signInWithPassword(`, `.auth.getUser(`, `.auth.signOut(`…) |
| Firebase Auth | `firebase`, and an import from `firebase/auth` |
| Auth0 | `@auth0/nextjs-auth0` or `@auth0/auth0-react` |
| Kinde | Any `@kinde-oss/…` package |
| WorkOS | `@workos-inc/authkit-nextjs` or `@workos-inc/node` |
| Lucia | `lucia` |
| Laravel | An `artisan` file |
| Django | A `manage.py` file |
| Devise | `devise` in the `Gemfile` |

Supabase is often only the database, so its package alone doesn't count: the code has to call its auth.

### Ways to sign in

Read from the library's own setup, for three of them:

| Library | What midcode reads |
| --- | --- |
| Auth.js | The providers imported from `next-auth/providers/…` or `@auth/…/providers/…` |
| Supabase Auth | `signInWithOAuth({ provider: '…' })`, `signInWithPassword` / `signUp` (email and password), `signInWithOtp` (email link) |
| Better Auth | The keys of `socialProviders`, `emailAndPassword: { enabled: true }`, `magicLink()`, `passkey()` |

Each way shows the file it's set up in; click it to open the file. When the users are in your database, each also shows how many people use it, and a way people use that the code doesn't show (one set up in the service's dashboard) is listed too.

For the other libraries nothing is read from the code. With a hosted service the list says so: "They're set up in Clerk, not in your code."

### Protected pages

Every [page of the site](https://midcode.app/docs/editor/pages.md), with a lock when a check for a signed-in visitor was found. There are two kinds:

- **"Checked before the page, in `proxy.ts`"**: Next.js runs one file before pages (`proxy.ts` since Next 16, `middleware.ts` before; also under `src/`). midcode reads its `matcher` and whether the file asks for a session at all. A page counts when a matcher covers its route, or when the file has no matcher.
- **"Checked in `app/account/page.tsx`"**: the page's own file, or in the App Router any layout above it, both asks who is signed in (`auth()`, `getServerSession()`, `currentUser()`, `getUser()`, `getSession()`, `requireUser()`…) and turns the visitor away (`redirect()`, `notFound()`, `unauthorized()`, `forbidden()`, `redirectToSignIn()`, `auth.protect()`).

Anything else says **No check found**.

> [!WARNING]
> This is reading code, not running it. A lock means a check is there, not that it holds; "No check found" means exactly that, not that the page is open. Try the page signed out to be sure. The view says so too.

## People

People lists the rows of the table your sign-in keeps users in.

- With Supabase Auth, that's `auth.users`.
- Otherwise it's the first of `User`, `user`, `users`, `Users`, `auth_user`, `accounts_user` or `profiles`, in the default schema, that has an email column and a primary key.

Columns are recognised by name: email, name, picture (`image`, `avatar`, `avatar_url`, `picture`…), whether the email is confirmed, when the person joined, when they were last seen, and a role (`role`, `tier`, `plan`, `is_admin`…). Only those columns are asked for. A page of people is one query:

```sql
select "id", "email", "name", "created_at", "password_hash" is not null
from "public"."users"
order by "created_at" desc nulls last, "id"
limit 50 offset 0
```

**midcode never reads a password's hash or a token.** For a password column it asks only whether it's set (`is not null`), to show that the person signs in with a password. The other ways each person uses come from the accounts table beside the users (`account`, `accounts` or `identities`, with a user id and a provider).

Each row shows the person's picture or initial, name and email, a check if the email is confirmed, the role, an icon per way to sign in, and "Joined" and "Seen" dates. Search by name or email; the list is 50 people at a time, newest first.

Click a person to open their row in its table, filtered to that row. There it's a row like any other: see [Edit rows](https://midcode.app/docs/data/database.md).

Reading people needs no permission to change the database, so it works on a read-only connection.

### When the users aren't in your database

Clerk, Firebase Auth, Auth0, Kinde and WorkOS keep your users for you. People then says "Your users are in" that service, with a button that opens its dashboard. If the database has no table of users, it says "No table of users here" and asks whether it's the right connection.

## What the agent is asked

Three buttons open a dialog that ends in a text for [your agent](https://midcode.app/docs/agents/overview.md). Each has two steps: you choose, then you read exactly what will be asked, and **Copy** it or **Send to the agent**. The files the agent changes from the Chat view are undoable and show in [Publish](https://midcode.app/docs/publish/publish.md).

| Button | Where | You choose |
| --- | --- | --- |
| **Add sign-in** | Overview, and People when there's none | The library, the ways to sign in, and (optional) the pages only signed-in people see |
| **Add a way to sign in** | Ways to sign in | Which of email and password, Google, GitHub and email link to add (the ones the site doesn't have) |
| **Protect pages** | Protected pages; **Protect…** on a page's row | The pages, from those with no check found |

For **Add sign-in**, midcode offers Supabase Auth, Better Auth, Auth.js and Clerk, and marks one "Suggested": Supabase Auth if the project already uses Supabase, Better Auth if a database is connected, Clerk if there's none.

Every brief starts from what midcode read, so the agent doesn't have to find it again: the framework and its version, the router, TypeScript or JavaScript, the package manager, Tailwind, the ORM, the database's engine, the sign-in already there with its config file, and how the site protects other pages already. A brief for a Next.js project with Prisma:

```text
Add sign-in to this site with Better Auth.

The project: Next.js 16.0.1, app router, TypeScript, pnpm, Tailwind, Prisma for the database. Its database is Postgres.

What to build:
- Ways to sign in: Email and password, Google.
- A sign-in page at /sign-in and a sign-up page at /sign-up, looking like the rest of the site: reuse its components and styles, no new UI library.
- A way to sign out, and who is signed in shown in the site’s header or nav if it has one.
- Require sign-in for these pages, sending signed-out visitors to /sign-in and back where they were going afterwards:
    /account (app/account/page.tsx)

How:
- Use Better Auth, keeping users in the project's own database. Its tables (user, session, account, verification) are added through Prisma: with the Prisma adapter, add the models to prisma/schema.prisma and apply them the way this project applies schema changes.
- In Next 16 the file that runs before pages is proxy.ts (middleware.ts before 16): use the one this project's version (16.0.1) expects.
- Keys and secrets go in .env.local as placeholders, and their names in .env.example. Never make up a real key, and never commit one.
- When you’re done, list what’s left to do by hand: each key to create, where to create it, and the variable it goes in.
```

The keys the agent leaves as placeholders show up afterwards in [Environment variables](https://midcode.app/docs/data/env.md) as missing, ready to be given a value.

A "protect" brief also names the file that runs before pages and its matchers, and points at a page that's already protected: "Do it the way the site already does".

## Limits

- Sign-in and users is in beta and not in the released version yet.
- midcode writes no sign-in code, and has no actions on users: no invite, no password reset, no block. A person's row can be edited as a row, nothing more.
- Ways to sign in are read for Auth.js, Supabase Auth and Better Auth only.
- The file that runs before pages is read for [Next.js](https://midcode.app/docs/frameworks/nextjs.md). Checks made elsewhere (SvelteKit hooks, Nuxt or Laravel route middleware, a Django decorator, a wrapper component) aren't recognised: those pages say "No check found".
- A matcher is read when it's written as strings. With one built in code, or a file that decides by its own `if`s instead of a matcher, midcode takes the file to run on every page, so every page shows as checked.
- Users kept by a hosted service (Clerk, Firebase Auth, Auth0, Kinde, WorkOS) aren't listed; midcode links to the service.
- The users table is found by its name. A table called something else isn't found: open it from **Tables**.
- A picture is shown only when it's a full `http(s)` address.
- What was checked: the reading of code against `package.json` files and source files of each kind, and the People list against users seeded in a test Postgres. Not tried against live projects of each service.

---

# Environment variables

> How midcode lists the variables your site reads from its .env files, shows which are missing without ever showing a value, and the rules it follows when it writes one.

- Page: https://midcode.app/docs/data/env
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

Environment variables are the keys and addresses your site reads without having them written in its code: a database's connection string, an API key, the site's own URL. midcode lists the ones your project has, the ones it asks for and doesn't have, and lets you give one a value.

One rule shapes the whole view: **a value goes in and never comes back out.** midcode tells you whether a variable is set, never what it holds.

## Open it

Open **Database** in the top bar and choose **Environment variables**, under **Site** in the list on the left. It works with or without a database connected.

## What the list shows

midcode reads every file in the project's root called `.env` or `.env.<something>`: `.env`, `.env.local`, `.env.production`, `.env.development.local`. A file whose name ends in `.example`, `.sample`, `.template`, `.dist` or `.defaults` is an example: what it lists is asked for, never set.

It also reads your code for the variables it uses: `process.env.NAME`, `process.env['NAME']` and `import.meta.env.NAME`, in JavaScript and TypeScript, Vue, Svelte and Astro files.

Each variable is one row:

| Part | What it says |
| --- | --- |
| The mark | A green check: it has a value in some file. An amber warning: no value yet |
| **public** | Its name starts with `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, `NUXT_PUBLIC_`, `REACT_APP_`, `EXPO_PUBLIC_` or `GATSBY_`: it's sent to the browser with the page, so never put a secret in it |
| The line under the name | The files where it has a value (`.env.local · .env`), or why it's listed without one: "Asked for in .env.example", "Read in the code", or "Empty" |
| The file beside it | The code file that reads it, or how many do |

A variable counts as missing when no file gives it a value and something wants it: an example file lists it, the code reads it, or a file has it with nothing after the `=`. Missing variables come first, and the header counts them ("2 without a value").

Variables your platform or your tools set by themselves are not listed only because the code reads them: `NODE_ENV`, `PORT`, `HOST`, `CI`, `MODE`, `DEV`, `PROD`, `BASE_URL`, `VERCEL_*`, `NETLIFY_*`, `RAILWAY_*`, `RENDER_*`, `FLY_*` and a few more.

## Values are never shown

The files are read in midcode's main process, which tells the window only which variables are set, where, and where they're read. The value field is a password field. What you type is sent to be written, and the window keeps no copy: after **Save** the field is empty again. Nothing in this view puts a value in a report or in front of your agent. See [Privacy and security](https://midcode.app/docs/reference/privacy.md).

The view says it at the bottom: "midcode shows which are set, never what they hold. A value you type is written to the file and not kept here."

## Writing a value

1. Click **Set** on a variable without a value, **Change** on one that has it, or **New variable**.
2. Type the value. For a new variable, type its name too: it's upper-cased as you type, and anything but letters, digits and `_` becomes `_`.
3. Choose the **File**. It starts on the file the variable is already in, or on the project's local file: `.env.local` in Next.js, Vite, Astro, SvelteKit, Nuxt, Remix and React Router projects (and wherever one exists), `.env` otherwise. Example files aren't offered.
4. Click **Save**, or press `Enter`. midcode says "Written to" and the file.

### The rules

- **A secret is not written to a file git would publish.** midcode asks git whether the file is ignored (`git check-ignore`). If it isn't, nothing is written and midcode says: "`.env` isn't ignored by git: a value put there would be published with your code. Use .env.local."
- **A public variable is the exception.** One with a public prefix can be written to any file: it reaches the browser anyway.
- A project with no git repository has nothing to publish to, so the value is written.
- A name is letters, digits and `_`, and doesn't start with a digit.
- Like every edit in midcode, it needs a [license or a running trial](https://midcode.app/docs/start/install.md).

### What gets written

The variable's line is replaced where it is. Every other line of the file, comments included, stays as it was:

```diff title=".env.local"
 NEXT_PUBLIC_SITE_URL=http://localhost:3000
-RESEND_API_KEY=
+RESEND_API_KEY=re_123abc
```

A variable the file doesn't have is added at the end:

```diff title=".env.local"
 RESEND_API_KEY=re_123abc
+STRIPE_SECRET_KEY=sk_test_abc
```

A value made only of letters, digits and `_ @ % + = : , . / -` is written bare. Anything else is written in double quotes, with quotes and line breaks escaped:

```text title=".env.local"
MAIL_FROM="Akila Studio <hello@example.com>"
```

If the file doesn't exist, midcode creates it, readable only by your user.

## Removing a variable

Hover a variable that's in a file and click **Remove**. midcode asks first: its line is taken out of every file that has it (not the example files), and "There's no undo: keep the value somewhere if you'll need it."

## Warnings

A banner appears above the list for each file that holds a value of a non-public variable and isn't ignored by git: "`.env` isn't ignored by git: what's in it is published with your code." Add the file to `.gitignore`, or move its secrets to `.env.local`.

## Where else midcode writes a variable

**Give it to the site**, in the Database overview, writes one variable through the same rules: `DATABASE_URL`, with the connection string of a database you connected by hand. See [Give it to the site](https://midcode.app/docs/data/database.md).

When your agent adds sign-in or a service, it's asked to leave keys as placeholders in `.env.local` and their names in `.env.example`. They show up here as missing: see [Sign-in and users](https://midcode.app/docs/data/users.md).

## Limits

- Environment variables is in beta and not in the released version yet.
- Writing or removing a variable has no `⌘Z`: these edits don't go through midcode's history.
- Only `.env` files in the project's root are read, and only `NAME=value` lines. A value that spans several lines isn't understood.
- A line written as `export NAME=…` is read, and comes back as `NAME=…` when midcode writes it.
- Reads in the code are found by pattern. `const { API_KEY } = process.env`, a computed `process.env[name]`, and other languages' ways (`os.environ` in Python, `ENV[]` in Ruby, `env()` in PHP files) aren't found.
- midcode doesn't send variables to [Vercel](https://midcode.app/docs/publish/vercel.md) or any other host. A value you set here is on your Mac; set it again where the site is deployed.
- midcode writes the file and doesn't restart your dev server. Whether a new value is picked up without a restart is up to your framework: see [Open a project](https://midcode.app/docs/start/open-a-project.md).

---

# Your agent in midcode

> Run Claude Code, Codex, Gemini CLI, OpenCode or Cursor beside the canvas, hand it what you click, and undo or publish what it changes.

- Page: https://midcode.app/docs/agents/overview
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode has no AI of its own and sells no model usage. The Agent panel runs the coding agent you already use, in your project's folder, with your own account. What midcode adds is the canvas: you point at an element instead of describing it, the agent's changes show on every breakpoint as they land, and each one is an edit you can undo and publish like your own.

The small things (a color, a line of copy, a padding) you still change by hand on the canvas. The agent is for what's faster to ask for.

## Chat or Terminal

The panel shows the agent in one of two ways. The button in the panel's header switches between them ("Show as a terminal" / "Show as a chat"), and midcode remembers which one you left.

- **Chat**, the default, is midcode's own conversation with the agent, over the [Agent Client Protocol](https://agentclientprotocol.com). midcode starts the agent as a process in your project's folder, shows its replies, plans, tool calls and diffs, and records every file it changes.
- **Terminal** is the agent's own command-line program in a real terminal, exactly as you'd run it yourself. midcode only pastes context into it.

| Agent | Chat | Terminal | Page |
| --- | --- | --- | --- |
| Claude Code | Yes | Yes | [Claude Code](https://midcode.app/docs/agents/claude-code.md) |
| Codex | Yes | Yes | [Codex](https://midcode.app/docs/agents/codex.md) |
| Gemini CLI | Yes | Yes | [Gemini CLI](https://midcode.app/docs/agents/gemini-cli.md) |
| OpenCode | Yes | Yes | [OpenCode](https://midcode.app/docs/agents/opencode.md) |
| Cursor | No | Yes | [Cursor](https://midcode.app/docs/agents/cursor.md) |

Pick the agent in the "Agent" menu at the top left of the panel. One that's missing says what to install, with a button to check again. Each agent's page says what has to be installed and signed in first.

## Where the panel is

In the Design view the agent is the "Agent" tab of the left panel, next to "Layers" and "Assets". The panel gets wider while that tab is open, and you can drag its edge.

The agent also stays beside everything that takes the canvas's place: the Code view, an element's code, the CMS, Translations and Site settings (and, in the next release, the Database and Store views). Beside the Code view it starts open. Beside the others it starts put away, as a thin rail with one button, "Show the agent". The collapse button in the header puts it away again, and the agent keeps running meanwhile.

## The prompt

Write what you want and press `Enter`. `⇧Enter` adds a line. `Esc` stops a turn that's running, and so does the "Stop" button.

- **Files.** The "+" button, then "Photos & files", or drop files on the prompt. An image goes to the agent as an image when the agent accepts them, a small file can go in whole, and anything else goes as a link to the file.
- **Context.** Type `@`, or use "+": "Selected element" (its reference, see below), "Open comments" (every open comment with the element it points at) and "This page" (the file and route open on the canvas). Each becomes a chip above the text that you can remove before sending.
- **The crosshair.** Click it, then click what you mean. The next thing you click goes into the prompt as a chip: an element on the canvas or in a code preview, a collection, item or field in the [CMS](https://midcode.app/docs/data/cms.md), a text in [Translations](https://midcode.app/docs/data/languages.md). `Esc` cancels.
- **Commands.** Type `/` as the first character to list the agent's own commands, as the agent reports them.
- **Mode, model and effort.** The pickers under the text are the agent's own session options. midcode shows what the agent offers and adds none. It remembers the model and effort you chose for each agent.

"New chat" in the header starts over with the same agent. There is one conversation per project and agent.

## The thread

The agent's replies are rendered as Markdown. Its thinking folds away ("Thought for 12s"). Tool calls are grouped, and each one opens to show what it did: the command it ran, the output, or the diff of the file it edited. A plan the agent makes shows as a "Plan" card that ticks off as it goes.

When a turn ends, the files it changed are listed under the reply with their added and removed lines. Click one to open it in the [Code view](https://midcode.app/docs/editor/code.md).

## Permission cards

When the agent asks before it does something (run a command, write a file), the thread shows a card, "Allow this?", with the command or the diff and the agent's own choices as buttons: usually allow once, always allow, or reject. Which actions need asking is decided by the agent and the mode you put it in, not by midcode. Stopping the turn cancels any card still waiting.

## Teaching the agent midcode (next release)

The button with the graduation cap, in the panel's header in both views, adds [the midcode skill](https://midcode.app/docs/agents/skill.md) to the selected agent: what midcode's files are, how to write styles, components and content that stay editable on the canvas, where your comments are. It goes into the agent's own skills folder on your Mac (`~/.claude/skills/midcode` for Claude Code), not into your project.

## How the agent's edits are recorded

In the Chat view, every file the agent edits inside your project goes into midcode's history and into [Publish](https://midcode.app/docs/publish/publish.md):

- One `⌘Z` takes back one tool call, whether it touched one file or several. A file the agent created is deleted by undoing it.
- The Publish list names each change after the agent, for example "Claude Code: edit Hero.tsx".
- The canvas shows the change as soon as your dev server reloads it, on every breakpoint.

Undo only writes when the file is still as that edit left it. If you or the agent changed it again since, midcode says "The file changed outside midcode, so that edit can't be undone" and leaves the file alone.

Your own edits on the canvas and the agent's are in the same history, in the order they happened.

## What the agent can reach

The agent runs in your project's folder with your user's permissions and your login shell's `PATH`. When it reads or writes a file through midcode, midcode answers only for paths inside the project and refuses anything outside it. What the agent's own tools can reach (its shell, its network access) is the agent's business: its permission mode and the cards above are the control.

The conversation goes from the agent to its provider, not through midcode. See [Privacy and security](https://midcode.app/docs/reference/privacy.md).

## The Terminal view

The Terminal view opens a login shell in the project's folder and types the agent's command into it, so your `PATH`, your shell setup and the agent's own sign-in are what they are in your terminal. If the agent exits, the shell is still there. The header has three buttons of its own:

- "Send the selection to the agent" pastes the selected element's reference into the agent's prompt, without sending it.
- "Send the open comments to the agent" pastes every open comment.
- "Restart the agent" closes the session and starts a new one.

What the agent changes shows on the canvas and in Publish's list of changed files. It is not in midcode's `⌘Z`, and not in Publish's "Done in midcode" list: in a terminal the agent writes files by itself, so use its own undo, or git. A file it creates is listed in Publish without a tick.

## Handing things to the agent

The same reference travels everywhere: what the element is, what it says, and where it's written.

```text
<h1> "Built to outlast"
written at src/components/Hero.tsx:14:7
inside src/app/page.tsx:9:5 › src/app/layout.tsx:21:7
page / · Desktop 1440px
```

The first line has the layer's name if you gave it one, the tag, the component and the text. `file:line:col` is where the element's opening tag is ([How midcode works](https://midcode.app/docs/start/how-it-works.md) says how it knows). "inside" lists the nearest ancestors written in other files. An element drawn by a component that passes its props on adds `rendered by <Card> at …`, an item of a list adds `item 3 of a list`, and in component mode there is a line for the component, variant and state.

| Where | Control | What the agent gets |
| --- | --- | --- |
| Right panel | "Ask your agent about this" | The selection's reference, as a chip in the chat or pasted into the terminal |
| Right panel | "Copy reference for your agent" (`⌘C`) | The reference, on the clipboard. midcode keeps the element itself for `⌘V` |
| An element, right-click | "Copy reference for your agent" (`⇧⌘C`, "Copy Reference" in the Element menu) | The reference, on the clipboard |
| Several elements, right-click | "Copy references for your agent" | One reference, then a line per element |
| Assets, right-click a component | "Copy reference for your agent" | `<Card> (components/Card.tsx:3)` |
| Component bar | "Send to agent" | The component's file, props, variants, states, where it's used, and the cell you're editing |
| A comment | "Copy for your agent" | That comment as a brief: page, element, file and line, your words, attachments |
| Comments list | "Copy open comments for your agent" | All open comments, as one Markdown brief |
| Translations | "Copy for agent" | What's missing in that language, with each text's file and line |
| Language menu | "Ask your agent to set it up" | A brief to give a one-language site its languages |

Comments are also files: `.midcode/comments.json` in your project, which any agent can read without midcode. See [Comments](https://midcode.app/docs/editor/comments.md).

### From the database (next release)

The crosshair also takes a table (its columns, never its rows) or one row from the [Database](https://midcode.app/docs/data/database.md) view. And where a change is code that has to fit your project, midcode writes the request instead of the code, with "Send to the agent" and "Copy": "Show on a page…" and "Save to a table…" ([Database](https://midcode.app/docs/data/database.md)), a table change in a project that uses Drizzle or a framework's migrations ([Changing tables](https://midcode.app/docs/data/schema.md)), and "Add sign-in", "Add a way to sign in" and "Protect pages" ([Sign-in and users](https://midcode.app/docs/data/users.md)).

"Send to the agent" puts the brief in the chat's prompt. With the Terminal view, use "Copy" and paste it.

## Limits

- Cursor has no Chat view: it runs in the Terminal view, or in its own window beside midcode.
- Closing the project's tab or quitting midcode stops the agent. Conversations aren't saved: the next chat is a new session, and the agent doesn't remember the last one.
- In the Chat view, a file the agent deletes, or changes by running a shell command instead of an edit, isn't an undo step. It still shows as a changed file in Publish.
- The crosshair and the `@` menu are the Chat view's. The Terminal view has its two send buttons.
- midcode doesn't choose or limit models: the pickers are what your agent and account offer.

## Troubleshooting

**The agent doesn't start.** The panel shows why, often with the agent's own last line. Signed out is the usual reason: run the agent once in a terminal and sign in. The first start can take a minute, because Claude Code's and Codex's adapters are downloaded then. After four minutes midcode stops waiting.

**"The agent hasn't answered in a while."** It may be retrying. Check your connection, and the agent's key or sign-in.

**It was installed but midcode says it isn't.** midcode looks for the command on your login shell's `PATH`, which it reads when it first needs it. Open a new terminal and check that the command runs there, then press "Check again". If installing it added a new folder to your `PATH`, quit midcode and open it again.

To write code that stays editable on the canvas, give your agent [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md), or install [the midcode skill](https://midcode.app/docs/agents/skill.md).

---

# Claude Code

> How midcode runs Claude Code, which accounts work in the chat, the optional API key, and the Terminal view for a Claude plan.

- Page: https://midcode.app/docs/agents/claude-code
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Claude Code runs in midcode's Agent panel in both views. The Chat view talks to Claude Code's engine through an adapter and records every edit. The Terminal view is the `claude` command itself. Which one you use depends on how you pay for Claude: the chat needs an API account, and a Claude plan runs in the Terminal view.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `npx -y @agentclientprotocol/claude-agent-acp@0.84.0 --hide-claude-auth` | `claude`, typed into a login shell |
| Needs on your Mac | Node.js (for `npx`) | Claude Code: `npm install -g @anthropic-ai/claude-code` |
| Account | An Anthropic Console account, or an API key | Whatever Claude Code is signed in with, a Claude plan included |
| Claude's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with Claude Code or git |

## The chat

The first time you open the chat, `npx` downloads the adapter, and the panel says "Getting Claude Code ready" for about a minute. The adapter's version is fixed by each midcode release, so it changes when midcode updates, not on its own.

The pickers under the prompt (mode, model, effort) are the options Claude Code's engine offers for the session with your account. midcode adds none, and remembers the model and effort you chose.

### Which accounts work

- **Claude Code's own sign-in, when it's an Anthropic Console account or an API key.** Nothing to set up: the chat uses the sign-in Claude Code already has on your Mac, and usage is billed to that account. If you haven't signed in yet, run `claude` in a terminal and `/login` once.
- **An API key saved in midcode.** With one, the chat needs nothing but Node.js.

A Claude subscription plan (Pro or Max) does not work in the chat. midcode starts the adapter with `--hide-claude-auth`, which keeps it from using a claude.ai subscription sign-in: Anthropic doesn't allow apps other than its own to bill a Claude plan. If your Claude Code is signed in with a plan, the chat says so:

```text
Your Claude Code is signed in with a Claude plan, which apps like midcode can't use. Add an API key, or use the Terminal view.
```

### The API key

The key is optional. To add one:

1. With Claude Code chosen in the chat, click "API key" (the key icon in the panel's header).
2. Paste the key. "Get a key" opens the Anthropic Console's keys page.
3. Click "Save key".

Before saving, midcode asks Anthropic's API whether it accepts the key, and tells you if it doesn't. A saved key wins over Claude Code's own sign-in: the chat bills that key's account. The key is kept encrypted on your Mac, outside your project, and is handed only to the agent's process when it starts (as `ANTHROPIC_API_KEY`). More in [Privacy and security](https://midcode.app/docs/reference/privacy.md).

"Remove the saved key", in the same place, deletes it. Saving or removing a key stops the running agent and starts a new chat.

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `claude`. It's Claude Code exactly as in your own terminal: the same sign-in (a Claude plan works here), the same settings, your `CLAUDE.md`, your commands. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view Claude Code writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat doesn't read an `ANTHROPIC_API_KEY` that your shell exports: variables like that are left out when midcode starts the agent. Save the key in midcode instead. The Terminal view is your shell, so there it applies.
- What the chat picks up from your Claude Code setup (settings, hooks, MCP servers) is up to the adapter. If something you rely on is missing, use the Terminal view.

## Troubleshooting

**"Claude Code needs Node.js".** The chat is started with `npx`. Install Node.js, then press "Check again".

**"Claude Code isn't signed in with an API key or a Console account."** Run `claude` and `/login` once in a terminal, or add an API key.

**The key isn't accepted.** It has to start with `sk-ant-` and be active in the Console.

To have Claude write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Codex

> How midcode runs OpenAI's Codex in the chat and in a terminal, what has to be installed and signed in first, and where its settings come from.

- Page: https://midcode.app/docs/agents/codex
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Codex runs in midcode's Agent panel in both views, with the Codex sign-in already on your Mac. midcode has no OpenAI account of its own and never sees your credentials: it starts Codex in your project's folder and shows what it does.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `npx -y @agentclientprotocol/codex-acp@2.0.1` | `codex`, typed into a login shell |
| Needs on your Mac | The Codex CLI, signed in, and Node.js (for `npx`) | The Codex CLI, signed in |
| Account | Codex's own sign-in | Codex's own sign-in |
| Codex's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with Codex or git |

## Set it up

1. Install the Codex CLI, if you don't have it:

   ```bash
   npm install -g @openai/codex
   ```

2. Run `codex` once in a terminal and sign in the way you normally do.
3. In midcode, open the Agent panel and choose Codex in the "Agent" menu.

If the panel says "Codex isn't installed", it shows the same install command with a button to copy it. Press "Check again" once it's installed.

## The chat

midcode looks for `codex` on your login shell's `PATH`, then starts the adapter that speaks the Agent Client Protocol for Codex. The first time, `npx` downloads it, and the panel says "Getting Codex ready" for about a minute. The adapter's version is fixed by each midcode release.

From there it's the same chat as with any agent:

- Codex's plan shows as a "Plan" card, and its tool calls open to the command, the output or the diff.
- When Codex asks before running something, you answer on a card in the thread.
- Each edit Codex makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("Codex: …").
- The pickers under the prompt are the options Codex offers for the session with your account. midcode adds none, and remembers the model and effort you chose for Codex separately from the other agents.

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `codex`. It's the CLI as you know it, with its own interface and settings. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view Codex writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get the `OPENAI_…` or `CODEX_…` variables your shell exports: they're left out when midcode starts it. If your Codex depends on one (an API key in your shell profile, for example), use the Terminal view, which is your shell, or sign in with `codex` so the CLI keeps the sign-in itself.
- midcode can't sign you in to Codex or switch its account. That's done in the CLI.

## Troubleshooting

**"Sign in to Codex first: run codex once in a terminal."** The adapter started but Codex has no sign-in it can use. Do that, then press "Try again".

**"Codex isn't installed", and it is.** Check that `codex` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

**"Codex couldn't start".** The panel shows the reason it was given, often the last line the agent printed. One cause is Node.js missing: the adapter is run with `npx` even when the Codex CLI was installed another way.

To have Codex write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Gemini CLI

> How midcode runs Google's Gemini CLI in the chat and in a terminal, what has to be installed and signed in first, and what to check when it won't start.

- Page: https://midcode.app/docs/agents/gemini-cli
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Gemini CLI runs in midcode's Agent panel in both views, with the account the CLI is signed in with on your Mac. midcode never handles your Google credentials: it starts the CLI in your project's folder and talks to it.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `gemini --acp` | `gemini`, typed into a login shell |
| Needs on your Mac | Gemini CLI, signed in | Gemini CLI, signed in |
| Account | Gemini CLI's own sign-in | Gemini CLI's own sign-in |
| Gemini's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with the CLI or git |

## Set it up

1. Install Gemini CLI, if you don't have it:

   ```bash
   npm install -g @google/gemini-cli
   ```

2. Run `gemini` once in a terminal and sign in.
3. In midcode, open the Agent panel and choose Gemini CLI in the "Agent" menu.

If the panel says "Gemini CLI isn't installed", it shows the same command with a button to copy it. Press "Check again" once it's installed.

## The chat

Gemini CLI speaks the Agent Client Protocol by itself, so there is no adapter in between and nothing extra is downloaded: midcode runs the `gemini` on your login shell's `PATH` with `--acp`, in your project's folder. If the CLI takes more than a few seconds to answer, the panel says "Getting Gemini CLI ready" while it waits.

The version is the one you installed. midcode doesn't update Gemini CLI, and what the chat can do follows it:

- The pickers under the prompt (mode, model, effort) are the options your Gemini CLI reports for the session. If it reports none, there are no pickers.
- Typing `/` at the start of the prompt lists the commands it reports.
- Images you attach go to Gemini as images when the CLI says it accepts them, and as file links otherwise.

Each edit Gemini makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("Gemini CLI: …"). The canvas shows the result at every breakpoint as your dev server reloads, so a layout that works on Desktop and breaks on Phone is in front of you while the agent is still working.

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `gemini`. It's the CLI as you know it. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view Gemini writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get the `GEMINI_…` variables your shell exports: they're left out when midcode starts it. If you use Gemini CLI with a `GEMINI_API_KEY` from your shell profile, the chat won't see that key. Use the Terminal view, which is your shell, or a sign-in the CLI keeps itself.
- midcode can't sign you in to Gemini CLI or switch its account. That's done in the CLI.

## Troubleshooting

**"Sign in to Gemini CLI first: run gemini once in a terminal."** The CLI started but has no sign-in it can use. Do that, then press "Try again".

**"Gemini CLI couldn't start".** The panel shows the reason it was given, often the last line the CLI printed. A Gemini CLI too old to know the `--acp` option is one cause: update it with the install command above.

**"Gemini CLI isn't installed", and it is.** Check that `gemini` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

To have Gemini write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# OpenCode

> How midcode runs OpenCode in the chat and in a terminal, with the providers and models you set up in it, and what to check when it won't start.

- Page: https://midcode.app/docs/agents/opencode
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

OpenCode runs in midcode's Agent panel in both views, with whichever providers and models you configured in it. midcode needs no key of its own for the model: it starts OpenCode in your project's folder and shows what it does.

What the panel does for every agent (the prompt, the crosshair, permission cards, undo) is in [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

## At a glance

| What | Chat | Terminal |
| --- | --- | --- |
| midcode starts | `opencode acp` | `opencode`, typed into a login shell |
| Needs on your Mac | OpenCode, with a provider set up | OpenCode, with a provider set up |
| Account | The providers and keys in your OpenCode | The providers and keys in your OpenCode |
| OpenCode's edits | Each one is a `⌘Z` step and a line in Publish | On the canvas and in Publish; undone with OpenCode or git |

## Set it up

1. Install OpenCode, if you don't have it:

   ```bash
   npm install -g opencode-ai
   ```

2. Run `opencode` once in a terminal and connect the provider you want to use.
3. In midcode, open the Agent panel and choose OpenCode in the "Agent" menu.

If the panel says "OpenCode isn't installed", it shows the same command with a button to copy it. Press "Check again" once it's installed.

## The chat

OpenCode speaks the Agent Client Protocol by itself, so there is no adapter in between and nothing extra is downloaded: midcode runs the `opencode` on your login shell's `PATH` with `acp`, in your project's folder. The version is the one you installed. If it takes more than a few seconds to answer, the panel says "Getting OpenCode ready" while it waits.

- **Your models.** The pickers under the prompt are whatever OpenCode reports for the session (its mode, model and effort options, when it has them), so the models are the ones of the providers you connected. midcode adds none, and remembers the model you chose for OpenCode separately from the other agents.
- **Its commands.** Typing `/` at the start of the prompt lists the commands OpenCode reports.
- **Its permissions.** When OpenCode asks before it does something, the card in the thread has OpenCode's own choices. Which actions it asks about is set in OpenCode.

Each edit OpenCode makes is one `⌘Z` step and a line in [Publish](https://midcode.app/docs/publish/publish.md), named after it ("OpenCode: …").

## The Terminal view

Switch the panel to the Terminal view ("Show as a terminal") and midcode opens a login shell in your project's folder and types `opencode`. It's OpenCode's own interface, as in your terminal. The two buttons in the header paste the selected element's reference, or your open comments, into its prompt.

In this view OpenCode writes files by itself: they show on the canvas and in Publish's list of changed files, but they are not steps in midcode's `⌘Z`.

## Limits

- The chat's agent doesn't get provider keys from your shell's variables. When midcode starts an agent it leaves out the variables that start with `ANTHROPIC_`, `OPENAI_`, `GEMINI_` and `CODEX_`, so an `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` exported in your shell profile doesn't reach OpenCode there. Connect the provider inside OpenCode so it keeps the credential itself, or use the Terminal view, which is your shell.
- midcode doesn't configure OpenCode: providers, models, agents and permissions are set in OpenCode.

## Troubleshooting

**"Sign in to OpenCode first: run opencode once in a terminal."** OpenCode started but has no provider it can use. Connect one, then press "Try again".

**"OpenCode couldn't start".** The panel shows the reason it was given, often the last line OpenCode printed. An OpenCode too old to have the `acp` command is one cause: update it with the install command above.

**"OpenCode isn't installed", and it is.** Check that `opencode` runs in a new terminal window. midcode looks on your login shell's `PATH`; if installing it added a folder to your `PATH`, quit midcode and open it again.

To have OpenCode write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Cursor

> Use midcode beside Cursor on the same project, run Cursor's CLI agent in midcode's terminal view, and copy references and briefs Cursor can act on.

- Page: https://midcode.app/docs/agents/cursor
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Cursor works with midcode in two ways. Its CLI agent runs inside midcode's Agent panel, in the Terminal view. And the Cursor app runs beside midcode on the same folder: you copy from the canvas what Cursor needs to know, and the canvas shows what Cursor saves.

Cursor does not run in midcode's Chat view. That view is for [Claude Code](https://midcode.app/docs/agents/claude-code.md), [Codex](https://midcode.app/docs/agents/codex.md), [Gemini CLI](https://midcode.app/docs/agents/gemini-cli.md) and [OpenCode](https://midcode.app/docs/agents/opencode.md).

## At a glance

| What | How |
| --- | --- |
| In the Agent panel | Terminal view only, as "Cursor Agent" |
| midcode starts | `cursor-agent`, typed into a login shell |
| Needs on your Mac | Cursor's CLI, signed in with your Cursor account |
| Cursor's edits | On the canvas and in Publish's changed files; undone in Cursor or with git, not with midcode's `⌘Z` |

## Cursor's CLI in the Terminal view

1. Install Cursor's CLI, if you don't have it. This is the command midcode shows when it can't find it (see [cursor.com/cli](https://cursor.com/cli)):

   ```bash
   curl https://cursor.com/install -fsS | bash
   ```

2. In midcode, open the Agent panel and switch it to the Terminal view ("Show as a terminal").
3. Choose "Cursor Agent" in the "Agent" menu. midcode opens a login shell in your project's folder and starts it. Sign in there if it asks.

Cursor's CLI installs under two names, so midcode finds it as either and types this:

```bash
cursor-agent || agent
```

With an element selected, "Send the selection to the agent" in the panel's header pastes its reference into the agent's prompt, and "Send the open comments to the agent" pastes your open comments. Nothing is sent until you press `Enter`.

## The Cursor app beside midcode

Open the same project folder in both. There's nothing to connect: midcode runs your real dev server, so whatever Cursor saves shows on the canvas at every breakpoint, and Publish lists the files it changed next to yours.

### Copy a reference

Select an element and press `⌘C` (or "Copy reference for your agent" in the right panel). midcode keeps the element for pasting on the canvas and puts this on the clipboard, ready for Cursor's chat:

```text
<h1> "Built to outlast"
written at src/components/Hero.tsx:14:7
inside src/app/page.tsx:9:5
page / · Desktop 1440px
```

It says what the element is, its text, where its opening tag is written (`file:line:col`), the files it sits inside, and the page and breakpoint you were looking at. With several elements selected, right-click and choose "Copy references for your agent".

### Copy your comments

Comments you pin on the canvas are saved in your project, in `.midcode/comments.json`, where Cursor can read them. "Copy open comments for your agent", in the Comments list, puts them on the clipboard as one Markdown brief. It's grouped by page, and each comment has a heading with its number, page, breakpoint and whether it's open, then this:

```md
- **Element:** `<h1>` · "Built to outlast"
- **Written at:** `src/components/Hero.tsx:14:7`
- **Inside:** `src/app/page.tsx:9:5`
- **Where on it:** 50% across, 50% down

> Make this one line on desktop
```

Files attached to a comment are listed with their path inside the repository. More in [Comments](https://midcode.app/docs/editor/comments.md).

### Open the file in Cursor

In Settings (`⌘,`), set "Code editor" to Cursor. "Automatic" already picks Cursor when it's in your Applications folder. Then "Open in your code editor", in midcode's code pane, opens the file in Cursor at the line you were on. To get to the pane from the canvas, right-click an element and choose "Open code".

## Editing at the same time

midcode and Cursor write the same files:

- midcode reads the file again for every edit and changes only the characters of that edit. It never writes back an older copy.
- `⌘Z` in midcode only undoes an edit while the file is still as that edit left it. If Cursor changed it since, midcode says so and leaves it alone.
- If you edit on the canvas right after Cursor saved, before the page reloaded, midcode may say it couldn't find the element. Wait for the canvas to reload and do it again.

## Limits

- No Chat view for Cursor, so no crosshair, no diffs in a thread and no undo of its edits in midcode.
- midcode doesn't talk to the Cursor app: the clipboard and the files are what passes between them.

To have Cursor write code that stays editable on the canvas, install [the midcode skill](https://midcode.app/docs/agents/skill.md) or point it at [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

---

# Code that midcode can edit

> How to write markup, classes, components and content, by hand or with an agent, so every part of it stays editable on midcode's canvas.

- Page: https://midcode.app/docs/agents/editable-code
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode edits a site by changing the characters where a thing is written: the words between two tags, one class in a `className`, one value in an array. So what's written as plain text in the code can be changed on the canvas, and what's computed when the page renders can't.

This page is for whoever writes that code, a person or an AI agent. Each rule gives the form midcode can edit, the form it can't, and why. None of it is needed for a site to open in midcode: it decides how much of the site you can change by clicking. The examples are React; [other languages](#other-languages) are further down.

## Where an element is written

While your dev server runs under midcode, every element knows where its opening tag is written: `src/components/Hero.tsx:14:7` is the file, the line and the column. Every edit is made there, and it's the reference midcode gives an agent.

- Write JSX in `.tsx` or `.jsx` files. In Next.js and Vite projects those are the files midcode marks.
- Elements from a package, or from HTML put in as a string (`dangerouslySetInnerHTML`, rendered Markdown), aren't written in your code: they show on the canvas and can't be edited there.
- Never write `data-mc`, `data-mci` or `data-mcu` yourself. midcode adds them while the dev server runs, and one written by hand points at the wrong place.

## Text

```tsx
// Do: the words are written, in the markup or in data
<h1>Built to outlast</h1>
<h3>{project.title}</h3>   {/* title: 'Oak House', in content/projects.ts */}

// Don't: the words are put together when the page renders
<h1>{`Built to ${verb}`}</h1>
<p>{count} projects</p>
<h3>{project.title.toUpperCase()}</h3>
```

Double-clicking a text edits it in place when everything inside the element is literal text. Otherwise midcode looks through the project for the exact text as one whole string and edits it there: an array in a data file, a prop where the component is used, a JSON catalog. A text assembled from pieces never exists as one string, so it's never found.

- If the same string is written in several places, midcode takes the one in the element's file or in a file it imports. If it still can't tell, it lists the places and changes nothing.
- For capitals use a class (`uppercase`), not `.toUpperCase()`.
- Keep a text in one element. In `<p>Made <em>to order</em></p>` only the `<em>` can be edited in place.

More in [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).

## Classes

```tsx
// Do: class names written out, in the attribute
<section className="px-6 py-16">
<div className={cn('rounded-2xl p-6', featured && 'ring-1', className)}>

// Don't: classes kept somewhere else, or built
const box = 'rounded-2xl p-6'
<div className={box}>
<div className={`p-${size}`}>
<div className={button({ size })}>   {/* cva */}
```

The style panel swaps one class for another inside the text of `className`, so each diff is one word. It reads plain strings, template literals, arrays, `+`, and the arguments of `cn()`, `clsx()`, `classnames()`, `twMerge()` and `cx()`. A class held in a constant, glued to an expression (`p-${size}`) or returned by a function isn't written there: midcode says it comes from a prop or a condition, and leaves it.

- When `className` is only a variable (`className={styles.card}`), there's nowhere to add a class. Wrap it, `className={cn(styles.card)}`, and midcode adds its classes as a first argument.
- A class inside a condition (`featured && '…'`, a ternary, a `clsx({ … })` key) can be taken out, but midcode never writes into a branch: the new class goes in the unconditional text. Put what a person will tune there.

More in [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

## Breakpoints

```tsx
// Do: mobile first, with min-width screens
<h1 className="text-4xl md:text-6xl lg:text-8xl">

// Don't: max-width screens, or screens with a name of your own
<h1 className="text-8xl max-lg:text-6xl max-md:text-4xl">
```

Each breakpoint on the canvas writes at one min-width screen, and the smallest writes with no prefix. midcode reads `sm:`, `md:`, `lg:`, `xl:`, `2xl:`, `min-[810px]:` and `min-[50rem]:`. A class with any other prefix (`max-md:`, `dark:`, `[&>svg]:`, your own screen name, two states at once) is kept exactly as written and never read. The panel doesn't show or change it, so it can silently win over what the panel writes. A project's breakpoints, and the screen each one writes at, are in `.midcode/breakpoints.json`. Without that file they are the defaults: Phone with no prefix, Tablet at `md:`, Desktop at `lg:`. More in [The canvas and breakpoints](https://midcode.app/docs/editor/canvas.md).

## Projects without Tailwind 4

```tsx
// Do: midcode's utilities, with mid: first
<h1 className="title mid:text-[40px] mid:md:text-[80px] mid:hover:text-[#ff5b2e]">

// Don't: bare utilities, the prefix in the wrong place, a built name
<h1 className="title text-[40px] md:mid:text-[80px]">
<div className={`mid:p-${n}`}>
```

A project is a Tailwind 4 project when one of its stylesheets has `@import "tailwindcss"` or an `@theme` block: write Tailwind's classes there. In any other project (plain CSS, CSS modules, Bootstrap, Tailwind 3) the utilities are Tailwind 4's with `mid:` in front, and midcode reads only those: the site's own classes are left alone, even one called `flex`.

Their CSS is `midcode.css`, rebuilt from the `mid:` classes that appear whole in the code: by the app while the project is open in it, and anywhere else by the midcode package (`npx midcode`, once it's installed). Never edit `midcode.css` by hand, and put tokens in `.midcode/theme.css` ([Theme and design tokens](https://midcode.app/docs/styling/theme.md)). See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) and [The midcode package](https://midcode.app/docs/styling/package.md).

## Images and attributes

```tsx
// Do: the value is one whole string, here or in data, or an imported file
<img src="/images/oak.jpg" alt="Oak House" />
<img src={studio.photo} alt={studio.name} />

// Don't: the value is computed
<img src={`/images/${slug}.jpg`} alt={alt(slug)} />
```

Replacing an image, or changing an `alt` or a link's `href`, rewrites the attribute where its value is written as one string: on the element, on the component's use, or in the data. In a Next.js project, an image you `import` is replaced in place, by a file of the same type. In other projects, reference the image by its path in the public folder.

## Components

```tsx
// Do: one root element, and the rest of the props passed on to it
export function Button({ className, children, ...rest }: ButtonProps) {
  return <button className={cn('rounded-full px-5 py-2', className)} {...rest}>{children}</button>
}

// Don't: nothing passed on, or no element of its own
export function Button({ children }: ButtonProps) {
  return <><button className="rounded-full px-5 py-2">{children}</button></>
}
```

With `{...rest}` on the root, each button on the page carries where its `<Button>` is written, so the label and the classes given at that use (`<Button className="mt-8">Buy</Button>`) are edited there. Without it, a text passed as children can't be found. Variants need a function component that returns an element of its own, not a fragment.

### Props

```tsx
// Do: a type, literal defaults, hints where the type isn't enough
type TickerProps = {
  /** @label Speed @min 10 @max 120 @step 5 @unit s */
  speed?: number
  align?: 'left' | 'center'
  /** @control color */
  tint?: string
  heroImage?: string
}
export function Ticker({ speed = 40, align = 'left', tint = '#111111', heroImage }: TickerProps) {

// Don't: nothing to read
export function Ticker(props: any) {
```

Props show in the right panel as controls: a switch for `boolean`, a number field for `number` (a slider with `@min` and `@max`), a choice for a union of strings, a text field for `string`. A string becomes an image, color or link control by the last word of its name (`heroImage`, `textColor`, `ctaHref`) or with `@control image|color|link|textarea`. Defaults are read from the destructuring when they're literals. A `ReactNode` or a function shows as code. Without types, midcode reads the destructuring, its defaults and a JSDoc `@type {'a' | 'b'}`.

Where the component is used, write values midcode can write back: `title="Oak"`, `speed={60}`, `featured`. An expression (`speed={fast ? 20 : 60}`, `{...config}`) shows as code. A prop made on the canvas is a [variable](https://midcode.app/docs/editor/variables.md).

### Variants and states

```tsx
// Do: a variant prop, data-variant and a named group on the root
type CardProps = { title: string; variant?: 'primary' | 'ghost' }

export function Card({ title, variant = 'primary', ...rest }: CardProps) {
  return (
    <article data-variant={variant} className="group/card rounded-2xl bg-white p-6 hover:shadow-lg data-[variant=ghost]:bg-transparent" {...rest}>
      <h3 className="text-lg group-hover/card:underline group-data-[variant=ghost]/card:text-neutral-500">{title}</h3>
    </article>
  )
}

// Don't: variants decided in code
<article className={variant === 'ghost' ? 'bg-transparent' : 'bg-white'}>
<article className={card({ variant })}>   {/* cva */}
```

midcode writes variants this way itself, and needs them this way to show a component as a grid of variants and states:

- The prop is called `variant`, typed as a union of kebab-case names, with a default.
- The root has `data-variant={variant}` and `group/<name>`, the component's name in kebab-case (`ProductCard` is `group/product-card`).
- On the root, a variant's classes start with `data-[variant=x]:` and a state's with `hover:`, `active:` or `focus-visible:`. Inside it, `group-data-[variant=x]/<name>:` and `group-hover/<name>:`, `group-active/<name>:`, `group-focus-visible/<name>:`. The default variant has no prefix.

Variants written with cva, or with conditions on the prop, are recognized and left alone: the canvas says they're written in code. Use `focus-visible:`, not `focus:`, which midcode doesn't read as a state. In a project without Tailwind 4 all of it carries the prefix: `mid:group/card`, `mid:data-[variant=ghost]:bg-transparent`. More in [Components](https://midcode.app/docs/editor/components.md).

## Lists of content

```ts
// Do: an array of plain objects, at the top of a module
export const projects = [
  { title: 'Oak House', year: 2024, cover: '/images/oak.jpg', featured: true },
  { title: 'Pine Studio', year: 2023, cover: '/images/pine.jpg', featured: false },
]

// Don't: a list that's assembled
export const projects = [...houses, ...studios].map(toProject)
export const site = { projects: [/* … */] }
```

The [CMS](https://midcode.app/docs/data/cms.md) shows as a collection any array whose items are all object literals, declared at the top level of a `.ts`, `.tsx`, `.js`, `.jsx` or `.mjs` file (exported or not, or the default export), a JSON file that is an array of objects, and a folder of `.md` or `.mdx` files with front matter. A value is editable when it's a string, a number, a boolean, `null` or a list of strings; anything else (an import, JSX, a call) shows as code. An object of plain values such as `{ en: 'Free', es: 'Gratis' }` is one field per key.

## Languages

```ts
// Do: one catalog per language, or a text per language under language codes
// messages/en.json, messages/es.json
const price = { en: 'Free', es: 'Gratis' }
export const locales = ['en', 'es']
export type Lang = 'en' | 'es'

// Don't: languages decided in code
const price = lang === 'es' ? 'Gratis' : 'Free'
const price = { english: 'Free', spanish: 'Gratis' }
```

[Languages](https://midcode.app/docs/data/languages.md) finds JSON catalogs named by language (`messages/es.json`, `locales/es/common.json`, in a folder called `messages`, `locales`, `lang`, `i18n`, `translations` or `dictionaries`), objects whose keys are all language codes, the `Lang` type and the `locales` list. A single `{ en, es }` object in a project with no catalogs isn't taken as a setup.

## What midcode leaves in the project

`.midcode/comments.json` is the list of comments left on the canvas, readable without midcode. `anchor.ref.mc` is where the element is written, `anchor.ref.mci` the component use that drew it, if any. `resolvedAt` is `null` while a comment is open, and attachments are paths inside `.midcode/attachments/`.

```json title=".midcode/comments.json"
[
  {
    "id": "3f9a1c2e",
    "createdAt": 1759676400000,
    "resolvedAt": null,
    "page": "/",
    "breakpoint": "desktop",
    "viewportWidth": 1440,
    "anchor": {
      "ref": { "mc": "src/components/Hero.tsx:14:7", "mci": null, "i": 0, "sel": "body > main > section > h1", "mcu": null },
      "tag": "h1",
      "component": null,
      "text": "Built to outlast",
      "context": ["src/app/page.tsx:9:5"],
      "fx": 0.5,
      "fy": 0.5
    },
    "body": "Make this one line on desktop",
    "attachments": []
  }
]
```

`.midcode/README.md` says what the folder holds and, in a project without Tailwind 4, how its styles are written. `app/midcode-scratch/` is midcode's [free canvas](https://midcode.app/docs/editor/free-canvas.md): leave it as it is. The rest is in [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

## Other languages

In `.svelte` files the same rules hold with Svelte's syntax: text and `class="…"` written out are editable, `{expression}` and `class={…}` aren't, and props come from `$props()`. A Svelte component gets variants and states the same way as a React one (that code is shared, but no Svelte project is on record as tried with them); variables are for React components only.

In the next release the same goes for Vue, Astro, plain HTML and the templates a server renders, where whatever the language computes (`{{ title }}`) can't be edited in place. For a component's props to show as controls, declare them: `defineProps` in a `.vue` file, `interface Props` in the frontmatter of an `.astro` file. Vue and Astro components get variants and states too, written through that same declaration (a `variant` member with its default, `data-variant` and `group/<name>` on each root); variables are for React components only.

Also in the next release, where pages are built from Markdown (Hugo, Jekyll, Eleventy), a heading, a paragraph or a one-line list item is edited on the canvas when it's only words. One with emphasis, code, a link or a shortcode in it is changed in the file. Markdown content takes no classes or attributes: style it from the template around it.

## Limits

- An element moves only within its file and its function: an item drawn by a `.map()` stays in its list.
- midcode finds a text by its exact words, at least two characters long. It doesn't follow a value through functions.
- The style panel reads the classes it has controls for (size, spacing, layout, type, fill, border, radius, shadow). Any other class stays as written.

---

# The midcode skill

> A skill that teaches Claude Code, Codex, Cursor, Gemini CLI or OpenCode how midcode works, so the code they write stays editable on the canvas.

- Page: https://midcode.app/docs/agents/skill
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

A project edited with midcode is a normal repository, so any coding agent can work in it. What an agent doesn't know by itself is what midcode put there and what midcode needs: that `midcode.css` is generated, what `mid:p-6` means, where your comments are kept, how a component has to be written for its variants to show on the canvas.

The midcode skill is that knowledge, packaged the way agents take it: a folder with a `SKILL.md` and reference files. The agent reads the skill's one-line description at the start of every session, and opens the rest only when the task has to do with midcode.

## Install it

There are two ways: from midcode, for you and every project on your Mac, or with the open installer, for a repository and everyone who works on it.

### From midcode's Agent panel (next release)

In the [Agent panel](https://midcode.app/docs/agents/overview.md), the button with the graduation cap opens the skill's panel. Its tooltip names the agent you have selected: "Teach Codex how midcode works". An empty chat shows the same words under its suggestions while the agent doesn't have the skill.

Click "Add to Codex" (or whichever agent it is). midcode copies the skill it carries into that agent's own skills folder on your Mac, the folder in the last column of the table below, and the panel shows where: `~/.codex/skills/midcode`. Nothing is written in your project and nothing is downloaded: it's the skill that matches the midcode you have.

- The agent reads it from its next session: start a new chat, or restart the agent.
- It's added to one agent at a time. Pick another agent in the panel to add it there too.
- "Update the skill" shows when the folder holds another version, an older midcode's or one installed from this site. It replaces the skill's files and leaves anything else you keep in that folder.
- "Remove the skill" moves the folder to the Trash.

### With the installer

In your project's folder:

```bash
npx skills add https://midcode.app
```

[`skills`](https://github.com/vercel-labs/skills) is the open-source installer for agent skills. It reads the skill from this site, checks it against the digest the site publishes, asks which agents to install it for, and puts it in each one's skills folder:

| Agent | In the project | For every project (`-g`) |
| --- | --- | --- |
| Claude Code | `.claude/skills/midcode/` | `~/.claude/skills/midcode/` |
| Codex | `.agents/skills/midcode/` | `~/.codex/skills/midcode/` |
| Cursor | `.agents/skills/midcode/` | `~/.cursor/skills/midcode/` |
| Gemini CLI | `.agents/skills/midcode/` | `~/.gemini/skills/midcode/` |
| OpenCode | `.agents/skills/midcode/` | `~/.config/opencode/skills/midcode/` |

With several agents, the files are kept once in `.agents/skills/midcode/` and the other folders link to it. The installer also writes a `skills-lock.json` that records where the skill came from, which is what lets it update later.

Installed in the project, the skill is a folder you can commit: everyone who works on the repository, and every agent they use, gets it. Installed with `-g`, it's there for every project on your Mac.

To skip the questions:

```bash
npx skills add https://midcode.app -g -a claude-code -y
```

### Without the installer

The skill is one archive. Unpack it where your agent looks for skills:

```bash
mkdir -p .claude/skills/midcode
curl -fsSL https://midcode.app/.well-known/agent-skills/midcode.tar.gz | tar -xz -C .claude/skills/midcode
```

## What's in it

- `SKILL.md`: the short version. How to recognise a midcode project, which files midcode owns, the rules for writing markup, styles, components and content that stay editable, and how to read what you send from the canvas (an element's reference, your comments).
- `references/`: every page of these docs as Markdown, one file each (`editor-components.md`, `styling-without-tailwind.md`, `frameworks-nextjs.md`…). `SKILL.md` ends with the list, so the agent opens the one page a task needs and nothing else.

## What changes with it

With the skill installed, an agent working in your project:

- Writes text, classes and attributes in the forms midcode can edit afterwards, and says so when it has to use one it can't ([Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md)).
- Styles with Tailwind's classes in a Tailwind 4 project and with `mid:` classes everywhere else, and never edits `midcode.css` by hand ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)).
- Writes a component's variants and states the way the canvas shows them: a typed `variant` prop, `data-variant`, a named group ([Components](https://midcode.app/docs/editor/components.md)).
- Reads `.midcode/comments.json` when you ask it to go through your comments, and finds each one's element by its file and line ([Comments](https://midcode.app/docs/editor/comments.md)).
- Leaves alone what's midcode's: the `.midcode/` folder's files, the canvas page, the generated stylesheet ([What midcode adds to your project](https://midcode.app/docs/start/project-files.md)).

## Keep it current

The skill is built from these docs, so it changes when they do. Added from midcode, it's updated from the same panel: "Update the skill" shows after you update midcode. Added with the installer:

```bash
npx skills update midcode
```

## Without a skill

Every page of the docs is one click from a chat:

- **Copy for AI**, on top of each page, copies it as Markdown.
- Add `.md` to a page's address for the same text: `https://midcode.app/docs/editor/components.md`.
- [`/llms.txt`](https://midcode.app/llms.txt) lists every page with one line each, and [`/llms-full.txt`](https://midcode.app/llms-full.txt) is the whole documentation in one file.

---

# Publish

> What the Publish panel lists, how to choose the files that go out, the exact git commands midcode runs, and what happens when a push fails.

- Page: https://midcode.app/docs/publish/publish
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Publish is the button at the right end of the top bar. It puts the files you choose into one commit and pushes the branch. If your repository deploys on push (Vercel, Netlify, Cloudflare Pages), that push is the deploy.

midcode runs your own git, in your project's folder. It never force-pushes, never rewrites history and never commits a file you didn't tick. The number on the button is how many files have changed.

## What the panel shows

Click Publish. The panel is headed "Publish changes", with your branch and where it pushes (`main → origin/main`).

- **Done in midcode**: the edits made in midcode since the last publish, in words, newest first. Each has its file and how long ago it was made: `Text “Built to outlast” → “Built to endure”`, `Vertical padding → 96px`, `Text color → brand`. What your agent changed from the Chat view is here too, under the agent's name.
- **Files**: every file git sees as changed in the project, whoever changed it: you in midcode, you in your editor, an agent in a terminal. Each has a checkbox, a letter (N new, M modified, D deleted) and the lines it gained and lost.
- **The commit message**, already written.

The list refreshes every few seconds while midcode is in front, and when you come back to it.

## Choose what goes

A file is ticked unless there's a reason for it not to be:

| Not ticked by default | Why |
| --- | --- |
| Files under `.midcode/` | Comments, layer names, your breakpoints, the theme. Yours to commit or not: see [What midcode adds to your project](https://midcode.app/docs/start/project-files.md). They don't count in the number on the button. |
| `.env` files | They usually hold secrets. The row is marked "secrets?". |
| A new file with no entry in "Done in midcode" | It may be a scratch file, or something an agent is still writing in a terminal. A page you just made from the [page menu](https://midcode.app/docs/editor/pages.md) is one too, until you edit it: tick it. |

Tick or untick any row. The line under the list says how many will go: "3 of 5 files". What you leave out stays in your working tree exactly as it is, and is listed again next time.

## The commit message

midcode writes the message from the edits whose files are ticked, and rewrites it as you tick and untick. Once you type in the field, it's yours.

```text
Edits from midcode: 3 changes

- Text “Built to outlast” → “Built to endure”
- Vertical padding → 96px
- Text color → brand
```

With one edit, the message is that edit. With files changed outside midcode only, it's `Update from midcode (2 files)`.

## What midcode runs

Clicking Publish comes down to three commands, with the paths you ticked:

```bash
git add -A -- app/page.tsx components/Hero.tsx
git commit -m "<your message>" -- app/page.tsx components/Hero.tsx
git push
```

- `git add -A -- <files>` stages those paths and nothing else, including a deletion.
- `git commit -- <files>` commits only those paths, even if you had something else staged. That stays staged.
- `git push` pushes the branch to its upstream. The first time a branch is pushed it's `git push -u origin HEAD`.

Because it's your git, the commit carries your name and email, and your hooks and signing settings apply. The one difference from a terminal is that git can't stop to ask for a password: missing credentials, or an ssh key that needs its passphrase typed, make the push fail with git's own message.

If the repository has no remote called `origin`, the button reads "Commit" and midcode stops after the commit.

## After a publish

The panel says "Published", with the commit, the branch and, on GitHub, the account that pushed. "View commit" opens it on GitHub, GitLab or Bitbucket. With a [Vercel account connected](https://midcode.app/docs/publish/vercel.md), the deploy that push started shows right there, until it's live.

The edits that went out leave the "Done in midcode" list.

## When the push fails

The commit is never lost. The panel says "Committed" instead of "Published", shows the last lines of what git answered, and offers "Try the push again".

If you close it, Publish remembers: with nothing left to commit it shows "1 commit(s) not pushed yet." and a "Push" button.

The usual reasons:

- **The wrong GitHub account.** midcode tries to push as the account that has access, and tells you when none of yours does. See [GitHub](https://midcode.app/docs/publish/github.md).
- **The remote has commits you don't.** midcode doesn't pull and never forces. Pull or rebase in a terminal, then press "Push".
- **No network, or no credentials.** Fix it, then press "Push".

## Undo and the list

`⌘Z` takes an edit out of your files and out of "Done in midcode" at the same time, so the list is always what's really there to publish. Undo works while the file is as midcode left it: if it changed outside midcode since, the edit stays and midcode says so.

The list itself is kept in the app's data, not in your repository. An edit whose file was committed some other way, from a terminal for instance, drops out of it.

## Branches

The pill beside the project's name shows the current branch. Click it for the branches of the repository, newest first, and beside them what the selected branch changed compared with the main one (the remote's default branch, else `main`, else `master`).

- **New branch**: the plus, "New branch from here". Type a name. It runs `git switch -c`, and changes you haven't committed come along.
- **Switch**: select a branch and click "Switch to …", or double-click it. If you have uncommitted changes, midcode asks: "Commit them to" the branch you're leaving, or "Bring them to" the one you're going to. If they'd clash with the other branch, git refuses and nothing moves.
- **Merge**: "Merge to main" commits what's pending on the branch, switches to the main branch and merges with a merge commit (`git merge --no-ff`). If both changed the same lines, the merge is aborted, you're back where you were, and midcode tells you to resolve it in your editor. After a clean merge the branch is deleted. The merge is local: open Publish and press "Push" to send it. With uncommitted changes on some other branch, midcode asks you to commit or undo them first.
- **Delete**: the trash icon, for a branch that is neither the current one nor the main one. It asks first, because commits that aren't merged anywhere are lost with it.

Your dev server follows the files, so the canvas shows whichever branch you're on.

## What never shows

- `app/midcode-scratch/`, the page behind [the free canvas](https://midcode.app/docs/editor/free-canvas.md). It's left out of the list, of the files and of every commit midcode makes.
- Files git ignores.
- Files outside the project's folder, when the project is part of a bigger repository.

## A project inside a bigger repository

When the folder you opened is one part of a repository (`site/` beside `api/`, an app of a monorepo), Publish only sees the files under that folder, with paths relative to it, and only commits those. The push still pushes the branch, which is the whole repository's.

## Shopify themes (next release)

For a theme, git keeps the code and the store has to be sent the theme itself. So in a theme's Publish panel there's one more row at the top, "Send the theme to your store", which opens the store's themes. Publishing below it only saves the code. See [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## Without git

Everything else in midcode works without git: edits are written to your files either way.

- If the project isn't a repository, the panel says "This project doesn't use git". Run `git init` and add a remote, and it works from then on.
- If the Mac has no git at all, it says so and gives the command that installs Apple's command line tools: `xcode-select --install`.

## Limits

- midcode commits and pushes. It doesn't pull, fetch, rebase or open pull requests.
- It pushes to the remote called `origin`.
- The panel shows how many lines each file gained and lost, not the lines. Read a diff in [Code](https://midcode.app/docs/editor/code.md) or in your git tool.
- Up to 300 changed files are listed.
- A commit and a push each get two minutes: a hook that runs longer makes the publish fail.

---

# GitHub

> How midcode publishes to GitHub: which account pushes when your Mac has several, how to connect one, and where its token is kept.

- Page: https://midcode.app/docs/publish/github
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

You don't have to connect anything to publish to GitHub. [Publish](https://midcode.app/docs/publish/publish.md) is `git push`, and git uses whatever your Mac already has: an ssh key, a credential helper, the GitHub CLI.

What midcode adds for a repository on GitHub is the choice of account. Many people have more than one (their own, a client's), and git pushes as whichever one the Mac answers with, usually the wrong one for half the repositories. midcode asks GitHub which of your accounts can push to this repository and pushes as that one. Connecting an account in Settings gives it one more account to try, and lets it push over https on a Mac with no git credentials set up at all.

## Which account pushes

Before a push to a `github.com` remote, https or ssh, midcode does three things:

1. It gathers the accounts it can use: the one connected in midcode, then every account logged in to the GitHub CLI (`gh auth status`). The CLI's accounts count even if you never connected anything in midcode.
2. It asks GitHub about each one, in that order: can this account push to this repository?
3. It pushes as the first one that can. The Publish panel says who, after the commit and the branch: "as your-login".

The answer is remembered for that repository until you quit midcode.

If none of them can push, git goes on with the Mac's own setup, as if midcode had done nothing. If that fails too, midcode names the accounts it tried: "None of your GitHub accounts (studio, personal) can push to client/site. Log in with the account that has access (in Terminal: gh auth login; it adds the account, yours stays), then try again." Do that, then press "Push" in Publish.

## How the push is made

When midcode has found the account, the push is this:

```bash
git -c credential.helper= -c credential.https://github.com.helper= push
```

- The two `-c` settings turn your credential helpers off for this one command. Otherwise a helper would answer first, as another account. Your git config isn't changed.
- The account's token reaches git through `GIT_ASKPASS`: a small script of midcode's that answers git's question from an environment variable set for that command only. The token is never written into the remote's URL, into your git config or into the script.

### A remote over ssh

An ssh remote (`git@github.com:client/site.git`) pushes with your ssh key, and that key belongs to one account. If that push fails and midcode has an account that can push, it sends the same commits over https instead:

```bash
git push https://github.com/client/site.git HEAD:refs/heads/main
```

Then it records what a push to `origin` would have recorded (the remote branch, and the upstream if the branch had none), so `git status` agrees. Your remote's URL stays as it was.

## Connect an account

Open Settings with `⌘,`. Under "Connections" ("Optional. midcode works without them."), click "Connect" beside GitHub. There are three ways in.

### Sign in with GitHub

1. Click "Sign in with GitHub".
2. midcode shows a one-time code and opens GitHub's device page in your browser. Click the code to copy it.
3. Type the code on that page and approve.
4. midcode says "Connected to GitHub as your-login".

This is the GitHub CLI's own browser sign-in (`gh auth login --web`), which midcode runs for you, asking for the `repo` and `read:user` scopes. So it needs the GitHub CLI: without it, midcode says "Signing in with GitHub needs the GitHub CLI for now (brew install gh), or paste a token." It also means the account is signed in to the GitHub CLI on your Mac, not only in midcode.

### Use my GitHub CLI login

This button shows when the GitHub CLI is already logged in. midcode takes the token of the CLI's active account (`gh auth token`). The row then reads "via CLI" beside the account.

### Use a token instead

1. Click "Use a token instead".
2. Paste a fine-grained personal access token with "Contents: read and write" on the repositories you publish to. "Create one" opens GitHub's page for it.
3. Click "Connect".

Whichever way you choose, midcode checks the token with GitHub before it keeps it. A token that doesn't work gets "That token didn't work. Check it and its permissions."

"Disconnect" makes midcode forget the account. It doesn't revoke the token on GitHub and it doesn't log the GitHub CLI out.

## Where the token is kept

- It's encrypted with the macOS Keychain and stored in midcode's own data folder, not in your project. On a Mac that can't encrypt it, midcode refuses to store it.
- It lives in the app's main process. The window that draws the interface gets the account's name, login and picture, never the token.
- It goes to two places only: `api.github.com`, to check the account and ask about a repository, and the `git push` of your project's own GitHub remote. Never to midcode's servers or to any other host.

More in [Privacy and security](https://midcode.app/docs/reference/privacy.md).

## What midcode does with GitHub

It does three things:

- It reads who the account is.
- It asks whether the account can push to the repository you're publishing.
- It pushes the commits you made in Publish, and links to them with "View commit".

It never does these:

- Force-push, or rewrite history.
- Open, review or merge pull requests.
- Create repositories, or change a repository's settings.
- Read your issues, your organizations or your other repositories.

## Other git hosts

Publishing is plain git, so any remote your Mac can push to works: GitLab, Bitbucket, a server of your own. "View commit" also links to `gitlab.com` and `bitbucket.org`. Choosing the account is for repositories on `github.com`. A GitHub Enterprise host goes the plain git way.

## Troubleshooting

**"Repository not found", or a 403.** The account that pushed can't see the repository. In a terminal, run `gh auth login` with the account that has access (it's added beside the one you have), then press "Push" in Publish.

**The sign-in never finishes.** "Sign-in didn't finish. Try again, or paste a token." Use "Open the page again" if the browser tab was lost, or "Cancel" and paste a token.

**A push worked before and now fails.** A token can expire or be revoked. Disconnect and connect again. Meanwhile git falls back to the Mac's own credentials.

**The commit went out under the wrong name.** The account that pushes isn't the commit's author. The author is the name and email in your git config (`git config user.name`, `git config user.email`).

---

# Vercel

> How a publish from midcode becomes a Vercel deploy through your git push, and what connecting your Vercel account adds to the Publish panel.

- Page: https://midcode.app/docs/publish/vercel
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

If your repository is connected to a Vercel project, publishing from midcode is a deploy. midcode commits the files you chose and pushes them, and Vercel builds from that push as it does from any other. midcode needs no access to Vercel for this, and adds nothing to your build.

Connecting your Vercel account in midcode is optional and does one thing: after a publish, the panel shows the deploy that push started, until it's live.

## Publish is the deploy

Nothing changes in how your project deploys:

- A push to your production branch is a production deploy.
- A push to any other branch is a preview deploy, with its own address to share. [Branches](https://midcode.app/docs/publish/publish.md) in midcode are a quick way to get one.

After a push, [Publish](https://midcode.app/docs/publish/publish.md) says so whether or not an account is connected: "pushed. If the project is connected to Vercel, the deploy has started."

## Follow the deploy

With an account connected, one more line appears under the published commit:

| The line | What it means |
| --- | --- |
| "Deploying on Vercel…" | Vercel is building the commit you pushed, or hasn't picked it up yet. |
| "Live on Vercel" | The production deploy is ready. "Open" opens it. |
| "Preview ready on Vercel" | A preview deploy is ready. "Open" opens its address. |
| "The Vercel deploy failed" | The build failed. "See logs" opens the deploy on Vercel. |

midcode checks every 4 seconds while that panel is open, for up to 15 minutes.

## Connect your account

Open Settings with `⌘,`. Under "Connections", click "Connect" beside Vercel. There are three ways in.

### Sign in with Vercel

1. Click "Sign in with Vercel".
2. midcode shows a code and opens Vercel's device page in your browser.
3. Type or confirm the code on that page.
4. midcode says "Connected to Vercel as your-username".

This is the Vercel CLI's own sign-in (`vercel login`), which midcode runs for you. If the CLI isn't installed, midcode runs the latest one through `npx`, which needs Node on your Mac. When it finishes, midcode takes the token the CLI saved. So the account is signed in to the Vercel CLI on your Mac too.

### Use my Vercel CLI login

This button shows when the Vercel CLI is already logged in. midcode uses the token it has.

### Use a token instead

1. Click "Use a token instead".
2. Paste a token from your Vercel account settings. "Create one" opens that page.
3. Click "Connect".

midcode checks the token with Vercel before it keeps it. "Disconnect" makes midcode forget it. It doesn't revoke the token on Vercel and it doesn't log the CLI out.

## How midcode finds your deploy

midcode has to work out which Vercel project is this folder, then which deploy is this commit.

1. If the folder was linked with `vercel link`, it reads the project from `.vercel/project.json`.
2. Otherwise it looks for the Vercel project whose git repository is your `origin`, first in your own account and then in each of your teams.
3. It reads that project's ten latest deploys and takes the one built from the commit you pushed.

```json title=".vercel/project.json"
{
  "projectId": "prj_…",
  "orgId": "team_…"
}
```

That file is written by the Vercel CLI, not by midcode. midcode only reads it.

## What midcode does with Vercel

It reads four things, and every request is a read:

- Who the account is.
- Your teams, to find the project.
- The project connected to your repository.
- That project's latest deploys and their state.

It never does these:

- Start, cancel or promote a deploy.
- Change a project's settings, domains or environment variables.
- Add a build step, a config file or a dependency to your project.
- Read your other projects' deploys.

The token is kept the same way as [GitHub's](https://midcode.app/docs/publish/github.md): encrypted with the macOS Keychain, in the app's main process only, and sent to `api.vercel.com` and nowhere else.

## Other hosts

Netlify, Cloudflare Pages and any other host that builds from a git push deploy when you publish, in the same way. Following the deploy inside midcode is for Vercel.

## Limits

- midcode matches a deploy to your commit through the GitHub commit Vercel records for it. Following a deploy was built for repositories on GitHub. With a repository on GitLab or Bitbucket the deploy still happens, but following it wasn't tried.
- The deploy shows after a publish made in midcode, in that panel. There's no list of past deploys.
- midcode looks at your account and your first 20 teams, and at a project's ten latest deploys.

## Troubleshooting

**No deploy line after publishing.** Either no Vercel account is connected, or midcode found no Vercel project for this repository in your account and teams. Run `vercel link` in the project's folder, then quit and reopen midcode: the project it found, or didn't, is remembered until you quit.

**It follows the wrong project.** When several Vercel projects build from the same repository (a monorepo), midcode takes the first one Vercel returns. Run `vercel link` in the folder you open in midcode, so `.vercel/project.json` names the right one.

**"Deploying on Vercel…" never changes.** Vercel hasn't made a deploy for that commit. Check on Vercel whether the branch is one it builds and whether the repository is still connected.

**The site deployed but the styles are missing.** In a project without Tailwind, `midcode.css` has to be in the commit. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) and, to build the file on Vercel instead, [The midcode package](https://midcode.app/docs/styling/package.md).

---

# Next.js

> How midcode runs a Next.js project, how each element learns where it's written, and what you can edit, including pages, site settings and the free canvas.

- Page: https://midcode.app/docs/frameworks/nextjs
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Next.js is the stack midcode edits most completely. Text, styles, images, layout, components with their variants and states, new pages, site settings and the free canvas outside the breakpoints: each one is written into your `.tsx` and `.jsx` files. Nothing is installed in the project and `next.config` is never touched.

The full set needs the App Router. A project that only has the Pages Router is edited on the canvas the same way and its pages are listed, but new pages and Site settings are written for the App Router. The free canvas comes to the Pages Router in the next release.

## At a glance

| | Next.js |
| --- | --- |
| Detected by | `next` in the `dependencies` or `devDependencies` of `package.json` |
| Runs with | `next dev`, started by midcode with one `--require` in front |
| Elements are marked by | A loader added in memory to Turbopack (or webpack) when the dev server starts |
| Editing | Full, in `.tsx` and `.jsx` files |
| Components | Yes: instances, props, variants and states, variables |
| Pages | `app/**/page.*` and `pages/**`. New pages and removing them in the App Router |
| Styles | Tailwind 4 classes, or `mid:` classes with `midcode.css` imported in the root layout |
| Tried with | Next.js 16 on Turbopack (16.3 among them), with Tailwind 4 and without Tailwind |

## How midcode runs it

When you [open a folder](https://midcode.app/docs/start/open-a-project.md), midcode reads its `package.json`. If `next` is in `dependencies` or `devDependencies`, the project is Next.js. That check comes before Vite, Astro and the others, so a Next.js project that also has `vite` installed is still Next.js.

If the dependencies aren't installed, the canvas says "Dependencies are missing" and offers "Install with pnpm" (or npm, yarn, bun: the one your lockfile belongs to).

Then midcode starts the dev server itself. It doesn't run your `dev` script:

```bash
node --require /Applications/midcode.app/Contents/Resources/injected/next-hook.cjs \
  node_modules/next/dist/bin/next dev --port 4310 --hostname localhost
```

- `node` is the one on your login shell's PATH: midcode asks your shell, so a version manager's Node is found. If the Mac has no Node at all, midcode's own stands in.
- `next` is your project's own, found the way Node resolves it (so a hoisted install works).
- The port is the first free one from 4310 up.

The dev server log (the button with the status dot, on the right of the top bar) starts with that command and the Node that runs it: `$ next dev --port 4310  (/opt/homebrew/bin/node)`.

The `--require` is all midcode adds. It preloads a hook into `next dev` and into the processes Next forks. The hook waits for Next to load your config and, on the object Next hands back, in memory, adds three things:

- a Turbopack rule for `*.tsx` and `*.jsx` that runs midcode's loader first. Rules you already have for those files still run after it.
- the same loader as a webpack rule, when Next runs on webpack (its default up to Next 15). Your own `webpack()` function runs first.
- `devIndicators: false`, so Next's dev badge doesn't sit on top of the canvas.

Nothing is written to disk: not `next.config`, not `package.json`, not the lockfile. The marks exist only in the dev server midcode started. `next build`, a `next dev` you run in a terminal and your deployed site have none. Telemetry is also off for that one process (`NEXT_TELEMETRY_DISABLED=1`). What midcode does add to a project, and when, is listed in [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

If midcode quits or crashes, the dev server notices within a few seconds and stops itself, so the port and Next's lock are free again.

### What the loader adds

The loader runs on every `.tsx` and `.jsx` file outside `node_modules`. It adds attributes to the compiled output and leaves everything else byte for byte where it was, so line numbers stay true.

```tsx title="app/page.tsx"
import { Card } from '@/components/Card'

export default function Page() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h1 className="text-5xl font-semibold">Selected work</h1>
      <Card title="Oak table" />
    </main>
  )
}
```

```tsx title="components/Card.tsx"
export function Card({ title }: { title: string }) {
  return (
    <article className="rounded-2xl p-6">
      <h3>{title}</h3>
    </article>
  )
}
```

This is what reaches the page:

```html
<main data-mc="app/page.tsx:5:5" class="mx-auto max-w-3xl px-6 py-24">
  <h1 data-mc="app/page.tsx:6:7" class="text-5xl font-semibold">Selected work</h1>
  <article data-mc="components/Card.tsx:3:5" data-mcu="Card|app/page.tsx:7:7" class="rounded-2xl p-6">
    <h3 data-mc="components/Card.tsx:4:7">Oak table</h3>
  </article>
</main>
```

- `data-mc` goes on every element written in your JSX: the file (relative to the project), the line and the column of its `<`. A wrapped element like `<motion.div>` counts as an element.
- `data-mci` is handed to every component instance as a prop: `Card|app/page.tsx:7:7`, the name and where it's used. It only shows in the page when the component passes its props on to an element.
- `data-mcu` goes on the element a component returns, and says where that component is used. Nested components make a chain, outermost first, separated by spaces: `Hero|app/page.tsx:9:7 Section|components/Hero.tsx:4:5`. This is how [Layers](https://midcode.app/docs/editor/layers.md) names components and how the root of a component is moved where it's used.

Fragments, `Suspense`, `StrictMode`, `Profiler`, providers and consumers get no mark: they draw no element of their own.

Server and client components are marked alike: the loader works on the source file, and so do the edits.

## What you can edit

Click the `<h1>` and the right panel shows where it's written under Code. Change its size and one class is swapped in that file:

```diff title="app/page.tsx"
-      <h1 className="text-5xl font-semibold">Selected work</h1>
+      <h1 className="text-6xl font-semibold">Selected work</h1>
```

Everything in the editor works in a Next.js project:

- Text, edited in place, including text that lives in an array or a content file: see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).
- Position, size, layout, type, fill and effects, per breakpoint: see [The style panel](https://midcode.app/docs/editor/styles.md).
- Images and video. The new file is copied into `public/` and the reference rewritten. An image your code imports (`import hero from './hero.jpg'`) is replaced in place, with a file of the same type.
- Structure: [Insert](https://midcode.app/docs/editor/insert.md), and [moving, duplicating and deleting](https://midcode.app/docs/editor/select-move-resize.md). Interactive components from Insert are written once to `components/midcode/` (`src/components/midcode/` when your app lives in `src`).
- [Components](https://midcode.app/docs/editor/components.md) with variants, states and typed props, and [Variables](https://midcode.app/docs/editor/variables.md).
- [CMS](https://midcode.app/docs/data/cms.md), [Languages](https://midcode.app/docs/data/languages.md), [Code view](https://midcode.app/docs/editor/code.md) and [Publish](https://midcode.app/docs/publish/publish.md).

Every edit is one step of `⌘Z`. What makes an element editable, and what doesn't, is in [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md).

## Pages

The page menu in the top bar lists what midcode finds in `src/app`, `app`, `src/pages` and `pages`.

| File | Page |
| --- | --- |
| `app/page.tsx` | `/` |
| `app/(marketing)/pricing/page.tsx` | `/pricing` |
| `app/work/[slug]/page.tsx` | `/work/[slug]`, a dynamic route |
| `pages/about.tsx` | `/about` |
| `pages/blog/index.tsx` | `/blog` |

Pages can be `.tsx`, `.ts`, `.jsx`, `.js` or `.mdx`. Left out: `api` folders, folders that start with `_` or `@`, and in `pages/` the files that start with `_` (`_app`, `_document`). A dynamic route is one entry, and its pages are found in the running site (its sitemap and the links on its pages), then in the page's own `generateStaticParams`.

In an App Router project you can also make and remove pages. "New page" writes a `page.tsx` in a new folder, next to the closest parent page that exists:

```tsx title="app/about/page.tsx"
export default function Page() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h1 className="text-4xl font-semibold">About</h1>
      <p className="mt-4">A new page, made in midcode.</p>
    </main>
  )
}
```

"Remove page" moves the file to the Trash, and its folder too when the page was the only thing in it. Reordering, dynamic routes and the Assets tab are in [Pages and navigation](https://midcode.app/docs/editor/pages.md).

## Site settings

The globe in the top bar opens Site settings. In the released version it only shows in Next.js projects. Title, description, search engines, favicon and social image are written the way Next.js reads them: `export const metadata` in the root layout or in the page, `generateMetadata` when a dynamic page's title uses its item's fields, and image files by convention (`app/icon.*`, `app/opengraph-image.*`). A change replaces only the value:

```diff title="app/layout.tsx"
 export const metadata: Metadata = {
-  title: 'Create Next App',
+  title: 'Oak & Iron',
   description: 'Furniture made to order.',
 }
```

It needs a root layout (`app/layout.tsx`). The details are in [Site settings](https://midcode.app/docs/editor/site-settings.md). In the next release other kinds of project get the same form, written as tags of their `<head>`: Next.js keeps writing `metadata`.

## The free canvas

In an App Router project, anything you draw (`F`), drop or paste on the empty canvas floats there. It lives in one real page, `app/midcode-scratch/page.tsx` (under `src/app` if that's where your app is), that answers 404 in production, stays out of the page list and is never offered in Publish. See [The free canvas](https://midcode.app/docs/editor/free-canvas.md).

## Styles

A project counts as Tailwind 4 when one of its CSS files has `@import "tailwindcss"` or an `@theme` block. There, midcode writes Tailwind's own classes and reads your `@theme` tokens: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

In any other Next.js project (plain CSS, CSS Modules, Tailwind 3) midcode writes its own prefixed utilities, like `mid:p-6`, and compiles them to `midcode.css`. On your first style edit that file is created next to the root layout and imported there, as one undoable edit:

```diff title="app/layout.tsx"
 import type { Metadata } from 'next'
 import './globals.css'
+import './midcode.css'
```

Without a root layout the import goes in `pages/_app.*`. If midcode finds neither, it still writes `midcode.css` and tells you to import it yourself. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- Only `.tsx` and `.jsx` files are marked. JSX written in a `.js` file, common in Next.js projects without TypeScript, gets no marks: its elements show, but midcode can't tell where they're written until the file is renamed to `.jsx`. The content of `.mdx` pages isn't marked either.
- midcode runs `next dev` itself. Flags in your `dev` script (`--turbopack`, `--webpack`, `--experimental-https`, a port) aren't read, and a custom server (`node server.js`) isn't used. In the next release you can give midcode your own command (see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md)); the site then shows without marks.
- There is no fallback to your own script, as there is for Vite projects. If `next dev` doesn't start, the canvas shows the error.
- On Next 15 and older, a dev server started this way runs on webpack. The loader is written for it, but only Next 16 on Turbopack is on record as tried.
- With the Pages Router only: no Site settings, which needs a root layout in `app/`, and in the released version no free canvas (the next release keeps it in `pages/midcode-scratch.tsx`). New page is still offered, and writes `app/<path>/page.tsx`: an App Router page beside your `pages/` folder.
- A new page starts with Tailwind class names. In a project without Tailwind 4 they do nothing until you restyle it.
- An element drawn by a package (a UI library in `node_modules`) has no mark. The right panel says a library draws it: edit its parent, or the component that uses it.
- An element moves within its file and its function. Text and classes that are computed are edited in code.

## Troubleshooting

**"A Next server is already running for this project".** Next allows one dev server per project folder, and midcode needs its own. Click "Stop it and use midcode", or stop yours in the terminal and press Restart in the dev server log.

**"Next.js is not in node_modules. Install the dependencies."** Use the "Install with…" button on the same card.

**An element has no file and line in the right panel.** It has no mark. Check that its file is `.tsx` or `.jsx`, and that it isn't drawn by a package. If nothing in the project has one, the hook couldn't attach to this version of Next: the dev server then runs as it always would, without marks. Send the report from the dev server log ("Send report").

**A style doesn't show.** In a project without Tailwind 4, check that `midcode.css` is imported in the root layout.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md) and [How midcode works](https://midcode.app/docs/start/how-it-works.md).

---

# React with Vite

> How midcode starts a Vite project with your own config plus one plugin, what it marks in your JSX and what you can edit, with Preact, Solid and Qwik.

- Page: https://midcode.app/docs/frameworks/react-vite
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode edits a React app built with Vite in full: text, styles, images, structure, components with variants and states, and variables, all written into your `.tsx` and `.jsx` files. It starts Vite with your own config and one extra plugin, so the canvas shows your real app.

Compared with [Next.js](https://midcode.app/docs/frameworks/nextjs.md), three things are missing in the released version: making pages, Site settings and the free canvas. The next release brings Site settings, written into your `index.html`, new pages where the routes are files, and [the free canvas](https://midcode.app/docs/editor/free-canvas.md), kept in `src/midcode-scratch.tsx`. A Vite app whose router is written in code has no list of pages to read.

## At a glance

| | React with Vite |
| --- | --- |
| Detected by | `vite` in `package.json`, together with `react` (or `preact`, `solid-js`) |
| Runs with | `vite dev`, with a config of midcode's that loads yours and adds one plugin |
| Elements are marked by | That plugin, as Vite transforms each `.tsx` and `.jsx` file |
| Editing | Full, in `.tsx` and `.jsx` files |
| Components | Yes: instances, props, variants and states, variables |
| Pages | None listed, unless the routes are files (TanStack Router, Qwik City: next release). New pages only there |
| Styles | Tailwind 4 classes, or `mid:` classes with `midcode.css` imported in the module `index.html` loads |
| Tried with | Vite + React with Tailwind 4, without Tailwind and with Tailwind 3 |

## How midcode runs it

midcode reads `package.json`. `next`, `@react-router/dev`, `@remix-run/dev`, `astro`, `@sveltejs/kit` and `nuxt` are checked first, each with its own page in these docs. If none is there and `vite` is, the project is a Vite project. It's editable when `react`, `preact` or `solid-js` is a dependency too. (With `svelte` or `vue` instead, see [Svelte and SvelteKit](https://midcode.app/docs/frameworks/svelte.md) and [Vue](https://midcode.app/docs/frameworks/vue.md).)

midcode then starts Vite itself, with your project's own `vite` and the `node` of your login shell (midcode's own Node if the Mac has none):

```bash
vite dev /Users/you/sites/dashboard \
  --config "/Users/you/Library/Application Support/midcode/injected/vite.config.mjs" \
  --port 4310 --strictPort --host localhost
```

The port is the first free one from 4310 up. The dev server log (the button with the status dot in the top bar) shows the command and the Node that runs it.

The `--config` is what makes the canvas editable. It points at a file in midcode's own data folder, outside your project. This is the part of it that matters (`root` is your project's folder, `entry('vite')` finds the Vite in your `node_modules`, and the two variables hold the path of your config and of midcode's plugin):

```js title="~/Library/Application Support/midcode/injected/vite.config.mjs"
// Written by midcode: the project's Vite config, plus the midcode plugin.
export default async (env) => {
  const vite = await import(entry('vite'))
  const user = await vite.loadConfigFromFile(env, process.env.MIDCODE_USER_CONFIG || undefined, root)
  const { midcode } = await import(pathToFileURL(process.env.MIDCODE_VITE_PLUGIN).href)
  const config = user?.config ?? {}
  return { ...config, root: config.root ?? root, plugins: [midcode(root), ...(config.plugins ?? [])] }
}
```

Your `vite.config` (`.ts`, `.mts`, `.js`, `.mjs`, `.cjs` or `.cts`, at the project root) is loaded by your own Vite and returned as it is, with one more plugin at the front. Your file is never modified and nothing is added to `package.json`. The plugin only applies while serving, so it can't take part in a build, and it only exists in the dev server midcode started.

If your config serves over HTTPS (a certificate plugin), midcode reads the address from Vite's `Local:` line and accepts a self-signed certificate for localhost.

### Options from your dev script (next release)

What your `dev` script asks of Vite is kept. With `"dev": "vite --mode staging --base /app/"`, midcode starts `vite dev … --mode staging --base /app/`. The port, the host, the config and opening a browser stay midcode's to say, so `--port`, `--host`, `--config`, `--open` and `--strictPort` are dropped. The script is only read when it does nothing but call Vite: `a && vite`, or `FOO=1 vite`, isn't.

### What the plugin adds

The plugin runs on `.tsx` and `.jsx` files outside `node_modules` and adds attributes to what Vite serves. The rest of each file stays where it was, so line numbers stay true.

```tsx title="src/App.tsx"
import { Hero } from './components/Hero'

export default function App() {
  return (
    <main className="mx-auto max-w-5xl px-6">
      <Hero title="Ship the dashboard" />
    </main>
  )
}
```

```tsx title="src/components/Hero.tsx"
export function Hero({ title }: { title: string }) {
  return (
    <section className="py-24">
      <h1 className="text-5xl font-semibold">{title}</h1>
    </section>
  )
}
```

The `<section>` reaches the page like this:

```html
<section data-mc="src/components/Hero.tsx:3:5" data-mcu="Hero|src/App.tsx:6:7" class="py-24">
  <h1 data-mc="src/components/Hero.tsx:4:7" class="text-5xl font-semibold">Ship the dashboard</h1>
</section>
```

- `data-mc`: where the element is written, as file, line and column of its `<`.
- `data-mcu`: on the element a component returns, where that component is used. Nested components make a chain, outermost first.
- `data-mci`: the same `Hero|src/App.tsx:6:7`, handed to the component as a prop. It shows in the page only if the component passes its props on to an element.

### When midcode's way doesn't start

Some projects need what only their own script sets up: an env file loaded by a wrapper, another process, a toolchain that wraps Vite. If Vite started this way exits, or doesn't answer in 45 seconds, midcode stops it and runs your `dev` script instead (`npm run dev`, or the same with your package manager, in your shell), reading the address from its output.

The site then shows, but without marks, so nothing on the canvas can be edited. You notice in three places:

- a message when the canvas appears: "midcode couldn't start this project its own way, so it runs your dev script: the site shows, but editing on the canvas needs midcode's plugin. The log says why." It has a "Send report" button.
- the dev server log, which says what happened ("it stopped", or "no answer in 45 s") before the second start.
- the right panel: under Code, a selected element has no file and line.

The same happens from the start when midcode can't find `vite` among the project's installed packages but there's a `dev` script (a toolchain that wraps Vite).

## What you can edit

Select the `<h1>` above and change its size. One class is swapped:

```diff title="src/components/Hero.tsx"
-      <h1 className="text-5xl font-semibold">{title}</h1>
+      <h1 className="text-6xl font-semibold">{title}</h1>
```

Double-click it and type. The words aren't in `Hero.tsx`, so midcode looks for the exact text in the project and edits it where it's written:

```diff title="src/App.tsx"
-      <Hero title="Ship the dashboard" />
+      <Hero title="Ship the new dashboard" />
```

The rest of the editor works as it does everywhere JSX is edited:

- [Text, images and video](https://midcode.app/docs/editor/text-and-media.md). New media is copied into `public/`.
- [The style panel](https://midcode.app/docs/editor/styles.md), per breakpoint.
- [Insert](https://midcode.app/docs/editor/insert.md), and [moving, duplicating and deleting](https://midcode.app/docs/editor/select-move-resize.md). Interactive components are written once to `src/components/midcode/`.
- [Components](https://midcode.app/docs/editor/components.md) and [Variables](https://midcode.app/docs/editor/variables.md).
- [CMS](https://midcode.app/docs/data/cms.md), [Languages](https://midcode.app/docs/data/languages.md), [Code view](https://midcode.app/docs/editor/code.md), [Publish](https://midcode.app/docs/publish/publish.md).

## Pages

A Vite app has no convention for pages, and a router written in code (`createBrowserRouter`, `<Routes>`) isn't read. The page menu lists Home only. To see another page, open the menu, type its path (`/pricing`) and press `Enter`.

Routes kept as files are read in the next release: see [TanStack Start](https://midcode.app/docs/frameworks/tanstack-start.md), and Qwik City below. Those are also the Vite apps where midcode adds and removes pages, because a page there is a file. With a router written in code, a new page is yours or your agent's to write.

## Site settings (next release)

In the next release the globe in the top bar opens Site settings in a Vite project too. The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of the `index.html` at the project's root:

```diff title="index.html"
-    <title>Vite + React</title>
+    <title>Oak Studio</title>
+    <meta name="description" content="Furniture made to last." />
   </head>
```

A tag that's there has its value changed, and a new one goes last in the `<head>`. Images are copied into `public/` as `favicon` and `og-image`, with the extension of the file you picked (`favicon.png`, `og-image.jpg`). A value Vite fills in when it builds (`%VITE_APP_TITLE%`) shows as code and isn't written. There's one form for the whole app: a page has no `<head>` of its own. It was tried on a Vite project with Vue, which has the same `index.html`. See [Site settings](https://midcode.app/docs/editor/site-settings.md).

## Styles

With Tailwind 4 (a CSS file with `@import "tailwindcss"` or an `@theme` block), midcode writes Tailwind's classes: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes `mid:` utilities and compiles them to `midcode.css`. On your first style edit the file is created next to the module your `index.html` loads, and imported there after its last import:

```diff title="src/main.tsx"
 import { createRoot } from 'react-dom/client'
 import './index.css'
 import App from './App.tsx'
+import './midcode.css'
```

If `index.html` loads no module, midcode looks for `src/main.*`, `src/index.*` or `src/entry-client.*`. If it finds none, it writes `midcode.css` anyway and tells you to import it. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Preact, Solid and Qwik (next release)

A Vite project with `preact`, `solid-js`, `@builder.io/qwik` or `@qwik.dev/core` in place of `react` is started and marked the same way: it's the same JSX and the same plugin. The released version already edits Preact and Solid projects this way. What the next release adds:

- These libraries write `class`, not `className`. A new attribute follows the file it goes into: when the file says `class=` and never `className=`, midcode writes `class`, and what you drag in from Insert is converted (`className` to `class`, `htmlFor` to `for`).
- midcode's own interactive components (Carousel, Tabs, Slideshow, Ticker and the others) are React. Without `react` in the project they're refused with "This component needs a React page".
- Qwik City only starts with `vite --mode ssr`, which is why the options of your `dev` script are kept. Its pages are listed: each folder of `src/routes` that has an `index.tsx`, `.jsx`, `.mdx` or `.md`. "New page" in the page menu makes such a folder with an `index.tsx` in it.

One thing to know: in a file that has no class attribute yet, midcode has nothing to follow and writes `className`.

Tried with a Vite + Solid and a Vite + Preact project made by `create-vite`, and with a Qwik City project. SolidStart has never been tried.

## Limits

- No free canvas in the released version: `F` inserts a frame in the page instead of drawing one on the empty canvas. The next release [brings it](https://midcode.app/docs/editor/free-canvas.md) to a Vite app with an `index.html` at its root.
- No new pages and no Site settings in the released version. In the next release Site settings needs an `index.html` at the project's root, and pages are added only where routes are files.
- In the next release, a `.midcode/server.json` in the project replaces midcode's own start with your command or address. The site then shows without marks, to view and comment: see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).
- Only `.tsx` and `.jsx` files are marked.
- Your `vite.config` has to be at the project root. A `--config` in your `dev` script isn't followed.
- The dev server listens on midcode's port, not the one in your config or script. An app that only works on one fixed port (an OAuth callback, an API that allows a single origin) won't get it.
- An image your code imports (`import logo from './logo.svg'`) isn't swapped from the canvas: replacing imported images in place is Next.js only. An image referenced by its path is replaced and copied into `public/`.
- An element drawn by a package has no mark, and one that's moved stays in its file and its function.
- A Laravel app that uses Vite is a different case: the canvas shows what PHP serves. See [Laravel](https://midcode.app/docs/frameworks/laravel.md).

## Troubleshooting

**The site shows but nothing can be edited.** midcode fell back to your `dev` script. Open the dev server log: the line before the second start says why. Usual causes are a config that reads something only your script sets, or a version of Vite midcode's config can't load. "Send report" sends the log and how the project is set up.

**"Vite is not in node_modules. Install the dependencies."** The project has no `dev` script either. Install with the button on the card.

**A style doesn't show.** Check that `midcode.css` is imported in your entry file.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md). In a workspace, see [Monorepos](https://midcode.app/docs/frameworks/monorepos.md).

---

# React Router and Remix

> How midcode runs React Router in framework mode and Remix on Vite, how your routes become its pages, and what you can edit in their JSX.

- Page: https://midcode.app/docs/frameworks/react-router
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode edits React Router apps (framework mode) and Remix apps that run on Vite the way it edits any React project: text, styles, images, structure, components and variables, written into your route and component files. On top of that it reads your routes, so each one is a page you can go to from the top bar.

In the released version routes are made in code. The next release adds and removes them from the page menu. Editing `meta` from the app isn't there: these apps write their `<head>` in JSX, which Site settings doesn't write. A Remix app on the classic compiler, before Vite, opens to look at and comment on, without editing.

## At a glance

| | React Router and Remix |
| --- | --- |
| Detected by | `@react-router/dev` (React Router) or `@remix-run/dev` (Remix) in `package.json` |
| Runs with | `react-router dev` or `remix vite:dev`, with a Vite config of midcode's that loads yours and adds one plugin |
| Elements are marked by | That plugin, as Vite transforms each `.tsx` and `.jsx` file |
| Editing | Full, in `.tsx` and `.jsx` files |
| Components | Yes: instances, props, variants and states, variables |
| Pages | `app/routes.ts`, or the files of `app/routes/`. New routes and removing them in the next release |
| Styles | Tailwind 4 classes, or `mid:` classes with `midcode.css` imported in `app/root.tsx` |
| Tried with | A React Router project made by `create-react-router`, with Tailwind 4 |

React Router used as a library inside a plain Vite app (`react-router` or `react-router-dom`, without `@react-router/dev`) is a Vite project: see [React with Vite](https://midcode.app/docs/frameworks/react-vite.md).

## How midcode runs it

midcode reads `package.json`. `@react-router/dev` makes the project React Router, `@remix-run/dev` makes it Remix. Both are checked before plain Vite.

It then starts the framework's own dev command, from your `node_modules`, with the `node` of your login shell (midcode's own Node if the Mac has none):

```bash
react-router dev /Users/you/apps/store \
  --config "/Users/you/Library/Application Support/midcode/injected/vite.config.mjs" \
  --port 4310 --strictPort --host localhost
```

For Remix the command is `remix vite:dev`, with the same options. The port is the first free one from 4310 up.

The `--config` points at a file in midcode's own data folder, outside your project. It loads your `vite.config` with your project's own Vite and returns it with one more plugin at the front. Your config, with its `reactRouter()` or `remix()` plugin, runs as it always does. Nothing is written in the project, and the plugin only exists in the dev server midcode started. The file itself is shown in [React with Vite](https://midcode.app/docs/frameworks/react-vite.md).

Loaders and actions run as usual: the canvas shows your real app from your real dev server.

### What the plugin adds

```tsx title="app/routes/home.tsx"
import { Welcome } from '../welcome/welcome'

export default function Home() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h2>Our work</h2>
      <Welcome />
    </main>
  )
}
```

In the page, the heading arrives with the file, line and column it's written at:

```html
<h2 data-mc="app/routes/home.tsx:6:7">Our work</h2>
```

`data-mc` goes on every element of your JSX. A component instance gets `data-mci` as a prop (`Welcome|app/routes/home.tsx:7:7`), and the element that component returns carries the same value in `data-mcu`, which is how midcode knows where a component is used.

Double-click the heading, type, and that string is the only thing that changes:

```diff title="app/routes/home.tsx"
-      <h2>Our work</h2>
+      <h2>Selected work</h2>
```

### When midcode's way doesn't start

If the dev command started this way exits, or doesn't answer in 45 seconds, midcode stops it and runs your own `dev` script instead. The site shows, without marks: nothing can be edited on the canvas. A message says so when the canvas appears, with a "Send report" button, and the dev server log says why.

This is what happens with a Remix app on the classic compiler: `remix vite:dev` has no Vite to start.

## What you can edit

Everything the editor does with JSX:

- [Text, images and video](https://midcode.app/docs/editor/text-and-media.md). New media goes to `public/`.
- [The style panel](https://midcode.app/docs/editor/styles.md), per breakpoint.
- [Insert](https://midcode.app/docs/editor/insert.md), and [moving, duplicating and deleting](https://midcode.app/docs/editor/select-move-resize.md). Interactive components are written once to `app/components/midcode/`.
- [Components](https://midcode.app/docs/editor/components.md) and [Variables](https://midcode.app/docs/editor/variables.md).
- [CMS](https://midcode.app/docs/data/cms.md), [Languages](https://midcode.app/docs/data/languages.md), [Code view](https://midcode.app/docs/editor/code.md), [Publish](https://midcode.app/docs/publish/publish.md).

## Pages

midcode reads routes from the source, without running anything. It looks in `app/` (or `src/app/`).

If there's a `routes.ts` (or `.js`, `.tsx`), each `index(…)` and `route(…)` in it is a page:

```ts title="app/routes.ts"
import { type RouteConfig, index, route } from '@react-router/dev/routes'

export default [
  index('routes/home.tsx'),
  route('about', 'routes/about.tsx'),
  route('work/:slug', 'routes/project.tsx'),
  route('files/*', 'routes/files.tsx'),
] satisfies RouteConfig
```

That gives `/`, `/about`, `/work/[slug]` and `/files/[...]`. The last two are dynamic routes: one entry each, whose pages midcode finds in the running site (its sitemap and the links on its pages).

Without a `routes.ts` (Remix), or when it only calls `flatRoutes()`, the files of `app/routes/` are the pages:

| File | Page |
| --- | --- |
| `_index.tsx` | `/` |
| `about.tsx` | `/about` |
| `work._index.tsx` | `/work` |
| `work.$slug.tsx` | `/work/[slug]` |
| `docs/route.tsx` | `/docs` |
| `$.tsx` | `/[...]` |

A page that isn't listed can still be opened: type its path in the page menu and press `Enter`. More in [Pages and navigation](https://midcode.app/docs/editor/pages.md).

### New routes (next release)

In the next release, "New page" in the page menu makes a route, and "Remove" takes one out.

In React Router, a new page at `/about` is a file in `app/routes/` and its line in `app/routes.ts`. `route` is added to the import when it isn't there:

```tsx title="app/routes/about.tsx"
export default function About() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h1 className="text-4xl font-semibold">About</h1>
      <p className="mt-4">A new page, made in midcode.</p>
    </main>
  )
}
```

```diff title="app/routes.ts"
-import { type RouteConfig, index } from "@react-router/dev/routes";
+import { type RouteConfig, index, route } from "@react-router/dev/routes";
 
-export default [index("routes/home.tsx")] satisfies RouteConfig;
+export default [index("routes/home.tsx"), route("about", "routes/about.tsx")] satisfies RouteConfig;
```

The new line goes right after the last route of the list, on the same line as it. A deeper path uses dots in the file's name: `/blog/first` is `app/routes/blog.first.tsx`. The class names are written when Tailwind is in your `package.json`; without it the tags come bare.

In Remix the file is the route, so only `app/routes/about.tsx` is written.

"Remove" moves the route's file to the Trash and, in React Router, takes its `route(…)` line out of `app/routes.ts` (and `route` out of the import, when that was its last use).

Creating and removing was tried on both. The new page was looked at on the canvas in React Router, not in a running Remix app.

## Styles

With Tailwind 4, midcode writes Tailwind's classes: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes `mid:` utilities and compiles them to `midcode.css`, created next to `root.tsx` on your first style edit and imported there:

```diff title="app/root.tsx"
 import type { Route } from "./+types/root";
 import "./app.css";
+import './midcode.css'
```

See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- No Site settings and no free canvas. The `<head>` of these apps is JSX in `app/root.tsx`, and each route's `meta`: write them in code, or ask your agent.
- In the released version, routes are made in code. In the next release a new route needs an `app/routes.ts` (React Router) or an `app/routes/` folder (Remix): without it the plus isn't in the page menu. When `app/routes.ts` builds its list another way than `[…] satisfies RouteConfig` (with `flatRoutes()`, say), midcode answers "midcode can't add a page to this project by itself yet: its pages are made in code. Ask the agent for it."
- In the next release, a `.midcode/server.json` in the project replaces midcode's own start: the site shows without marks ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).
- Nesting isn't followed in `routes.ts`. A route inside `prefix('blog', […])`, or nested under another `route(…)`, is listed without its parent's path. `layout(…)` adds nothing, which is right.
- In `app/routes/`, a file that starts with an underscore other than `_index` is skipped. That leaves out pathless layouts, as it should, but also the routes named under them (`_auth.login.tsx`). Routes with a trailing underscore segment (`blog_.$slug.tsx`) are skipped too.
- Only `.tsx` and `.jsx` files are marked.
- An image your code imports isn't swapped from the canvas. An image referenced by its path is.
- The dev server listens on midcode's port, not the one in your config.
- Remix hasn't been tried with a real project, and styling without Tailwind hasn't been tried on React Router or Remix. Both run on the same code as Vite + React, where it has.

## Troubleshooting

**The site shows but nothing can be edited.** midcode fell back to your `dev` script. The dev server log (the button with the status dot in the top bar) says why on the line before the second start.

**"React Router is not in node_modules. Install the dependencies."** (or "Remix"). Install with the button on the card.

**A route is missing from the page menu.** It's one of the cases under Limits. Type its path in the menu.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

---

# TanStack Start

> A TanStack Start or TanStack Router app is edited like any Vite + React project, and midcode reads its file routes as pages.

- Page: https://midcode.app/docs/frameworks/tanstack-start
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode treats a TanStack Start app as what it is: a Vite project written in React. It's started, marked and edited exactly as described in [React with Vite](https://midcode.app/docs/frameworks/react-vite.md). What this page adds is the one thing specific to TanStack: its routes are files, so midcode can list them as pages.

The same goes for a plain Vite app that uses TanStack Router with file routes.

## At a glance

| | TanStack Start |
| --- | --- |
| Detected by | `vite` and `react` in `package.json`. The routes are found by the folder that holds `__root.tsx` |
| Runs with | `vite dev`, with a config of midcode's that loads yours and adds one plugin |
| Elements are marked by | That plugin, as Vite transforms each `.tsx` and `.jsx` file |
| Editing | Full, in `.tsx` and `.jsx` files |
| Components | Yes: instances, props, variants and states, variables |
| Pages | The route files of `src/routes`. New pages and removing them |
| Styles | Tailwind 4 classes, or `mid:` classes with `midcode.css` |

## How midcode runs it

There is no check for TanStack itself. midcode sees `vite` in `package.json`, with `react`, and starts Vite with its own config in front of yours:

```bash
vite dev /Users/you/apps/start-app \
  --config "/Users/you/Library/Application Support/midcode/injected/vite.config.mjs" \
  --port 4310 --strictPort --host localhost
```

That config loads your `vite.config`, with its `tanstackStart()` plugin and everything else, and adds the plugin that marks each JSX element with its file, line and column. Nothing is written in your project. Options in your `dev` script, such as `--mode`, are kept. The port in it isn't: midcode picks its own. The details, and what happens when Vite doesn't start this way, are in [React with Vite](https://midcode.app/docs/frameworks/react-vite.md).

A route file is marked like any other component:

```tsx title="src/routes/index.tsx"
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({ component: Home })

function Home() {
  return (
    <main className="p-8">
      <h1 className="text-4xl font-bold">Welcome</h1>
    </main>
  )
}
```

```html
<h1 data-mc="src/routes/index.tsx:8:7" class="text-4xl font-bold">Welcome</h1>
```

## Pages

midcode looks for `__root.tsx` (or `.jsx`, `.ts`, `.js`) in `src/routes`, `app/routes` and `src/app/routes`. The folder that has it is the routes folder, and each `.tsx` or `.jsx` file in it or in its subfolders is a page. The address comes from the file's name, read the way TanStack Router reads it:

| File | Page |
| --- | --- |
| `index.tsx` | `/` |
| `about.tsx` | `/about` |
| `posts.index.tsx` or `posts/index.tsx` | `/posts` |
| `posts.$postId.tsx` | `/posts/[postId]`, a dynamic route |
| `posts_.$postId.edit.tsx` | `/posts/[postId]/edit` |
| `_app.settings.tsx` | `/settings` |
| `(marketing)/pricing.tsx` | `/pricing` |
| `files.$.tsx` | `/files/[...]` |

Dots nest like folders. Parts that only group or wrap add nothing to the address: a name that starts with `_`, a `(group)` folder, `route.tsx`, `.lazy`. Not listed: `__root`, anything whose name starts with `-`, and an `api` folder at the top.

A dynamic route is one entry. midcode finds its pages in the running site, from its sitemap and the links on its pages. See [Pages and navigation](https://midcode.app/docs/editor/pages.md).

"New page" in the page menu writes a route file with its `createFileRoute`, and "Remove" moves a route's file to the Trash:

```tsx title="src/routes/about.tsx"
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({ component: About })

function About() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-24">
      <h1 className="text-4xl font-semibold">About</h1>
      <p className="mt-4">A new page, made in midcode.</p>
    </main>
  )
}
```

A deeper path uses dots: `/posts/first` is `posts.first.tsx`. The class names are written when Tailwind is in your `package.json`. Both are offered when `__root.tsx` (or `.jsx`) is in `src/routes`, or `__root.tsx` in `app/routes`.

## Styles

With Tailwind 4, midcode writes Tailwind's classes: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes `mid:` utilities and compiles them to `midcode.css`. It imports that file in the module `index.html` loads, or in `src/main.*`, `src/index.*` or `src/entry-client.*`. A TanStack Start app usually has none of those. In that case midcode writes `src/midcode.css` and tells you it couldn't tell where to import it: load it in `src/routes/__root.tsx`, the way your app loads its other stylesheet. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- Only the file names are read. Routes built in code, virtual file routes and a custom routes folder set in the plugin's options aren't followed. Any page can still be opened by typing its path in the page menu.
- An older TanStack Start project that has no `vite` in its `package.json` isn't recognised as a Vite project: it runs with its own `dev` script and shows without marks.
- No free canvas: it's for Next.js projects on the App Router.
- [Site settings](https://midcode.app/docs/editor/site-settings.md) writes the `<head>` of an `index.html` at the project's root. A Vite app that uses TanStack Router has one. A TanStack Start app usually doesn't (its `<head>` is built in its root route), and then the globe isn't in the top bar: set the title and the rest in code.
- No TanStack Start version is on record as tried end to end. The route reader follows TanStack Router's file naming, and everything else is the Vite + React path, which is tried.
- The other limits of [React with Vite](https://midcode.app/docs/frameworks/react-vite.md) apply.

---

# Svelte and SvelteKit

> How midcode runs SvelteKit and Vite + Svelte, how it reads .svelte files with your own compiler, and which edits it writes into them.

- Page: https://midcode.app/docs/frameworks/svelte
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode edits SvelteKit and Vite + Svelte projects in their `.svelte` files: text, static classes, attributes and tags, plus inserting, moving, duplicating and removing elements. It reads each file with the Svelte compiler your project already has, so what midcode sees is what Svelte sees.

Components are recognised, their props show as controls, and a component opens on its own canvas with variants and states. The free canvas comes with the next release, for plain elements. [variables](https://midcode.app/docs/editor/variables.md), new pages (SvelteKit) and Site settings come with the next release.

## At a glance

| | Svelte and SvelteKit |
| --- | --- |
| Detected by | `@sveltejs/kit` in `package.json` (SvelteKit), or `vite` together with `svelte` (Vite + Svelte) |
| Runs with | `vite dev`, with a config of midcode's that loads yours and puts one plugin first |
| Elements are marked by | That plugin, before Svelte compiles each `.svelte` file, using your project's `svelte/compiler` |
| Editing | Text, static classes, attributes, tags; insert, move, duplicate, remove |
| Components | Instances, props, variants and states. Variables in the next release |
| Pages | SvelteKit: every `+page` under `src/routes`, and new ones in the next release. Vite + Svelte: none listed |
| Styles | Tailwind 4 classes, or `mid:` classes with `midcode.css` imported in `src/routes/+layout.svelte` |
| Tried with | A SvelteKit project made by `sv create`, with Tailwind 4 |

## How midcode runs it

midcode reads `package.json`. `@sveltejs/kit` makes the project SvelteKit. Without it, `vite` with `svelte` is a Vite + Svelte project.

SvelteKit is a Vite plugin, so both are started the same way: your project's own `vite`, run by the `node` of your login shell (midcode's own Node if the Mac has none), with a config of midcode's in front of yours.

```bash
vite dev /Users/you/sites/docs \
  --config "/Users/you/Library/Application Support/midcode/injected/vite.config.mjs" \
  --port 4310 --strictPort --host localhost
```

That config lives in midcode's own data folder. It loads your `vite.config` with your own Vite and returns it with one more plugin, placed first so it reads each `.svelte` file before Svelte's plugin compiles it. Neither `vite.config` nor `svelte.config.js` is touched, nothing is installed, and the plugin only exists in the dev server midcode started. The file itself, and what happens when Vite doesn't start this way (midcode runs your own `dev` script, and the site shows without marks), are in [React with Vite](https://midcode.app/docs/frameworks/react-vite.md).

### What the plugin adds

The plugin parses each `.svelte` file with your project's `svelte/compiler` and adds attributes to what Svelte is given. The file on disk is not changed, and lines stay where they are.

```svelte title="src/routes/+page.svelte"
<script>
  import Faq from '$lib/Faq.svelte'
</script>

<main class="mx-auto max-w-3xl px-6 py-24">
  <h1 class="text-5xl font-semibold">Selected work</h1>
  <Faq title="Questions" />
</main>
```

```svelte title="src/lib/Faq.svelte"
<script>
  let { title } = $props()
</script>

<section class="rounded-2xl p-6">
  <h2>{title}</h2>
</section>
```

In the page:

```html
<main data-mc="src/routes/+page.svelte:5:1" class="mx-auto max-w-3xl px-6 py-24">
  <h1 data-mc="src/routes/+page.svelte:6:3" class="text-5xl font-semibold">Selected work</h1>
  <section data-mc="src/lib/Faq.svelte:5:1" data-mcu="Faq|src/routes/+page.svelte:7:3" class="rounded-2xl p-6">
    <h2 data-mc="src/lib/Faq.svelte:6:3">Questions</h2>
  </section>
</main>
```

- `data-mc` goes on every element: the file, the line and the column of its `<`.
- `data-mci` (`Faq|src/routes/+page.svelte:7:3`) is handed to each component instance as a prop.
- `data-mcu` goes on the elements at the top of a component, and says where the component is used. midcode reads it from the component's `$props()` (or `$$props` in a component that uses `export let`). That's how [Layers](https://midcode.app/docs/editor/layers.md) names components and how a section that is a component moves where it's used.

`<svelte:head>`, `<svelte:window>`, `<svelte:body>`, `<svelte:document>` and `<svelte:options>` are left alone. While a file doesn't parse (you're halfway through typing), it gets no marks: Svelte shows its error and midcode steps aside.

## What you can edit

Select the `<h1>`, change its size, and one class is swapped:

```diff title="src/routes/+page.svelte"
-  <h1 class="text-5xl font-semibold">Selected work</h1>
+  <h1 class="text-6xl font-semibold">Selected work</h1>
```

- **Text.** Double-click an element that holds only text and type. A `{`, `}` or `<` you type is written as an entity, so it can't start an expression or a tag. When the text is an expression (`{title}`), midcode looks for the exact words in the project and edits them where they're written, here the `title="Questions"` in `+page.svelte`. See [Text, images and video](https://midcode.app/docs/editor/text-and-media.md).
- **Classes.** The written part of `class="…"`. With an expression inside (`class="card {active ? 'on' : ''}"`), midcode edits the text around it and leaves the expression alone.
- **Attributes and tags.** `src`, `alt`, `href` and the rest when they're written as text, and changing one HTML tag for another. New images go to `static/` in SvelteKit, `public/` in Vite + Svelte.
- **Insert.** What you drag in from [Insert](https://midcode.app/docs/editor/insert.md) is converted to Svelte markup before it's written: `class`, `for`, no self-closing `<div />`. An import it needs goes into the component's `<script>` (one is added at the end of the file when there's none), as `$lib/…` for files in `src/lib`. The result is parsed with your compiler first. If it wouldn't parse, nothing is written.
- **Move, duplicate, remove.** An element moves within its file, and the comment above it travels with it. See [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md).
- **Props.** Select an instance and the right panel shows what the component declares, from `let { title, count = 3 }: Props = $props()` or from `export let`, as typed controls. Setting one writes the attribute on the instance.
- **Components.** A `.svelte` file with a capitalised name is listed in Assets, and opens on its own canvas. A variant is written as a `variant` prop with its default, `data-variant={variant}` and a `group/<name>` class on each top-level element. States are `hover:`, `active:` and `focus-visible:` classes. See [Components](https://midcode.app/docs/editor/components.md).

[CMS](https://midcode.app/docs/data/cms.md), [Languages](https://midcode.app/docs/data/languages.md), [Code view](https://midcode.app/docs/editor/code.md) and [Publish](https://midcode.app/docs/publish/publish.md) work as in any project.

### Several elements at once (next release)

Removing several selected elements at once, wrapping elements in a stack (`⇧A`) and moving several together work in `.svelte` files in the next release. In the released version those three are JSX only: in a `.svelte` file you remove and move one element at a time. They were tried in `.vue` files, which go through the same code as `.svelte` files.

`⌥`-drag comes to `.svelte` files in the same release: the element stays where it is, and a copy goes beside or inside the element you drop it on, in the same file. The released version answers "Copies made by dragging aren't available in Svelte files yet." A copy can't float on the empty canvas: that's the free canvas, which is Next.js only.

## Pages

In SvelteKit, every folder of `src/routes` with a `+page.svelte` (or `+page.ts`, `.js`, `.md`) is a page. `(group)` folders add nothing to the address, and a folder like `[slug]` is a dynamic route: one entry, whose pages midcode finds in the running site.

| File | Page |
| --- | --- |
| `src/routes/+page.svelte` | `/` |
| `src/routes/(site)/about/+page.svelte` | `/about` |
| `src/routes/blog/[slug]/+page.svelte` | `/blog/[slug]` |

A Vite + Svelte app has no page list. Type a path in the page menu and press `Enter` to see another page. More in [Pages and navigation](https://midcode.app/docs/editor/pages.md).

### New pages (next release)

In the next release, "New page" in the page menu makes a SvelteKit page: a folder under `src/routes` with a `+page.svelte` in it.

```svelte title="src/routes/about/+page.svelte"
<main class="mx-auto max-w-3xl px-6 py-24">
  <h1 class="text-4xl font-semibold">About</h1>
  <p class="mt-4">A new page, made in midcode.</p>
</main>
```

The class names are written when Tailwind is in your `package.json`; without it the tags come bare. "Remove" moves the `+page.svelte` to the Trash, with its folder when it was the only file in it. A Vite + Svelte app keeps its pages in code, so neither is offered there.

## Site settings (next release)

In the next release the globe in the top bar opens Site settings. The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of `src/app.html` in SvelteKit, and of `index.html` in Vite + Svelte:

```diff title="src/app.html"
 		%sveltekit.head%
+		<title>Oak Studio</title>
+		<meta name="description" content="Furniture made to last." />
 	</head>
```

A new tag goes last in the `<head>`, indented and closed like the tags around it. Images are copied into `static/` in SvelteKit and `public/` in Vite + Svelte. There's one form for the whole site: a title a page sets in its own `<svelte:head>` isn't read or written. Tried with SvelteKit. See [Site settings](https://midcode.app/docs/editor/site-settings.md).

## Styles

A `<style>` block keeps working: midcode doesn't read or change it. The style panel writes utility classes on the element.

With Tailwind 4 they're Tailwind's own: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md). Without it, midcode writes `mid:` utilities and compiles them to `midcode.css`, which it imports on your first style edit:

```diff title="src/routes/+layout.svelte"
 <script>
+  import './midcode.css'
   import favicon from '$lib/assets/favicon.svg'
```

If the project has no `src/routes/+layout.svelte`, midcode makes one that imports the stylesheet and renders the page (`{@render children()}`, or `<slot />` before Svelte 5). In Vite + Svelte the import goes in the module `index.html` loads, such as `src/main.ts`. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).

## Limits

- [the free canvas](https://midcode.app/docs/editor/free-canvas.md) comes with the next release, for plain elements: a component or an element with an expression in it can't float. [variables](https://midcode.app/docs/editor/variables.md), new pages and Site settings aren't in the released version.
- A class that's computed is left alone: `class={…}`, a `class:name` directive, or a name glued to an expression (`btn-{size}`). midcode says the classes come from a variable and writes nothing.
- Text is edited in an element that holds only text. A paragraph with a link or a `<strong>` inside is edited in code. The link and the `<strong>` themselves can be edited.
- An element inside `{#each}` that uses the loop's values can't be moved out of its list, and nothing can be dropped inside a component instance.
- Elements move within one file.
- A component with no `<script>`, or one whose script declares no props and uses no runes, doesn't report where it's used: its elements are selected as plain elements of its file.
- Variants need a root midcode can write to. When the top of the file is a block (`{#if}`), when the root's `class` is an expression, or when props are taken as `let props = $props()` without a type, midcode says why it can't add one.
- Interactive components from Insert (Carousel, Tabs and the others) are React and can't go into a `.svelte` file: their tiles say "Needs a React page". Icons go in as inline SVG.
- midcode asks your compiler for Svelte 5's syntax tree. A project on Svelte 4 or older has not been tried.
- Styling without Tailwind has not been tried on a real SvelteKit project. Variants and states in `.svelte` components share their code with JSX components, but no Svelte project is on record as tried with them.

## Troubleshooting

**The site shows but nothing can be edited.** midcode fell back to your `dev` script. The dev server log (the button with the status dot in the top bar) says why.

**"Couldn't insert it: the code wouldn't parse".** The new markup wouldn't be valid where you dropped it. Nothing was written. Drop it somewhere else, or add it in code.

**"The text in the code doesn't match the preview."** The page hadn't reloaded after an earlier change. Wait for it and try again.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

---

# Vue

> How midcode runs a Vite + Vue app, marks the elements of every template, and what you can edit in a .vue file, from text and classes to the props of each component.

- Page: https://midcode.app/docs/frameworks/vue
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode edits a Vue app built with Vite in the `<template>` of its single-file components: text, classes, attributes, new elements, their order, and the props a component is given where it's used. Your `<script>`, your `<style>` and everything the template computes (`{{ }}`, `:bound` values, `v-if`) stay exactly as you wrote them. midcode adds to a `<script setup>` in two cases only: the import of a component you drag in from the Assets tab, and the `variant` prop of a component you give [variants](#variants-and-states). midcode 1.1.2 and earlier open a Vue project to check every breakpoint and leave comments, without editing.

A Vue app built with Vue CLI runs another way: see [Create React App, Vue CLI, Gatsby, Docusaurus](https://midcode.app/docs/frameworks/webpack.md). Nuxt has [its own page](https://midcode.app/docs/frameworks/nuxt.md), and so does Vue inside [Laravel](https://midcode.app/docs/frameworks/laravel.md).

## At a glance

| | Vue with Vite |
| --- | --- |
| Detected by | `vite` and `vue` in the dependencies of `package.json` |
| Runs with | Your project's own Vite, with your config and one plugin added |
| Elements are marked by | That plugin, in memory, while the dev server runs |
| Editing | Text, classes, attributes, tag; insert, move, duplicate, delete, wrap in a stack |
| Components | Instances and typed props. A component opens on its own canvas, with variants, states and variables |
| Pages | The home page is listed; any other route opens by typing its path |
| Styles | Your Tailwind 4 classes, or `mid:` utilities compiled to `midcode.css` |
| Tried with | Vite + Vue + Tailwind 4 |

## How midcode runs it

midcode takes a project for Vue with Vite when its `package.json` lists `vite` and `vue` and none of the frameworks it checks first (Next.js, React Router, Remix, Astro, SvelteKit, Nuxt). It then starts the Vite that's in your `node_modules`:

```bash
vite dev <your project> --config <midcode's config> --port 4310 --strictPort --host localhost
```

The port is the first free one from 4310. It runs with the Node your shell has, or with midcode's own when there is none. If your `dev` script gives Vite other options (`vite --mode staging`), midcode passes them along; the port, the host and the config are midcode's to say.

That config is a small file in midcode's own data folder (`~/Library/Application Support/midcode/injected/vite.config.mjs`), not in your project. It loads your `vite.config` with your project's Vite and puts one plugin first in the list. Your `vite.config`, your `package.json` and your lockfile aren't changed, and the plugin only applies to the dev server, never to a build.

As Vite loads each `.vue` file, the plugin adds a mark to every element of its `<template>` before Vue compiles it. This file:

```vue title="src/components/Hero.vue"
<template>
  <section class="hero">
    <h1 class="title">Build calmly</h1>
    <Card title="Oak" :count="3" />
  </section>
</template>
```

reaches Vue's compiler like this (the root's `data-mcu` left out):

```vue
<template>
  <section data-mc="src/components/Hero.vue:2:3" class="hero">
    <h1 data-mc="src/components/Hero.vue:3:5" class="title">Build calmly</h1>
    <Card data-mci="Card|src/components/Hero.vue:4:5" title="Oak" :count="3" />
  </section>
</template>
```

- `data-mc` is the file, line and column where the element is written. It's what the canvas edits by.
- `data-mci` goes on a component used in a template. Vue hands it to the component's root element, like any attribute the component doesn't declare.
- `data-mcu` goes on the elements at the top of each template, read from `$attrs`. It says where this component is used, also when the component has several roots.

Tags that draw nothing of their own get no instance mark: `<template>`, `<slot>`, `<component>`, `<transition>`, `<transition-group>`, `<keep-alive>`, `<teleport>`, `<suspense>`, `<router-view>`.

None of this is written to disk. Hot reload keeps working: when a file changes, Vue's plugin receives the marked version again.

If midcode's way of starting Vite doesn't come up (the process stops, or nothing answers in 45 seconds), midcode runs your own `dev` script instead and says so. The site shows, but without marks, so you can only view and comment. [Open a project](https://midcode.app/docs/start/open-a-project.md) covers that case.

## What you can edit

Click an element and the right panel shows where it's written, as `file:line`. The editor's own pages describe each tool: [select, move and resize](https://midcode.app/docs/editor/select-move-resize.md), [text and media](https://midcode.app/docs/editor/text-and-media.md), [the style panel](https://midcode.app/docs/editor/styles.md), [Insert](https://midcode.app/docs/editor/insert.md), [Layers](https://midcode.app/docs/editor/layers.md). What follows is how each one lands in a `.vue` file.

### Text

Double-click a text and type. The new words replace the old ones in the template:

```diff title="src/components/Hero.vue"
-    <h1 class="title">Build calmly</h1>
+    <h1 class="title">Build slowly</h1>
```

A text is edited there when everything inside its element is written text. If you type `{{`, it's written as an entity (`&#123;&#123;`), so Vue doesn't read it as an expression.

Text that comes from `{{ title }}` isn't in the template. midcode then looks for the exact string in the project's `.ts`, `.js`, `.json` and `.md` files (a data file, a locale) and edits it there when it can tell which one it is. `.vue` files aren't searched: a value written in the component's own `<script>` is edited in the code, and one given as a prop where the component is used is changed there, in the code or from the instance's **Props**. [Text, images and video](https://midcode.app/docs/editor/text-and-media.md) explains the search.

### Classes and attributes

The style panel writes into the static `class` attribute, and creates it when the element has none. A `:class` binding is an expression and is left alone:

```diff title="src/components/Hero.vue"
-    <h1 class="title" :class="{ dark }">Build calmly</h1>
+    <h1 class="title text-6xl" :class="{ dark }">Build calmly</h1>
```

If a class you're replacing isn't written in the template, midcode says it comes from a prop or a condition and writes nothing.

Attributes (a link's `href`, an image's `src` and `alt`, an input's settings, a `<select>` and its options) are read as written, including the ones Vue binds to code. A value is written the way Vue writes it:

| Value | Written as |
| --- | --- |
| A text | `href="/pricing"` |
| On | `disabled` |
| A number or other code | `:maxlength="40"` |

### Structure

Insert adds plain markup (what the panel holds is converted from JSX: `class`, not `className`). A component dragged from the Assets tab is written with its import, in the file's `<script setup>` (one is added at the top of the file when it has none), as a relative path with its extension: `import Card from './Card.vue'`. Dragging moves an element before, after or inside another one in the same file, and the comment right above it travels with it. Several elements can be deleted, moved or wrapped in a stack (`⇧A`) at once. `⌥`-drag leaves the element where it is and puts a copy beside or inside the one you drop it on, in the same file.

### Components and props

A component used in a template shows in Layers with its name and is selected as an instance. Its **Props** in the right panel are typed controls, read from what the component declares:

- `defineProps<Props>()`, with the defaults from `withDefaults(…, { … })` or from a destructuring.
- `defineProps({ title: String, count: { type: Number, default: 0 } })`. `String`, `Number` and `Boolean` choose the control, and `required: true` is respected.
- `defineProps(['title', 'image'])`: the names alone.
- The `props` of the object a plain `<script>` exports.

```vue title="src/components/Card.vue"
<script setup lang="ts">
interface Props {
  title: string
  count?: number
  featured?: boolean
}
const props = withDefaults(defineProps<Props>(), { count: 0, featured: false })
</script>
```

Changing a prop writes it where the component is used:

```diff title="src/components/Hero.vue"
-    <Card title="Oak" :count="3" />
+    <Card title="Walnut" :count="5" featured />
```

A value equal to the declared default removes the attribute. A new one goes after the last attribute, or before a `v-bind="…"` when there is one. `<card-item>` is read as `CardItem`, and `my-title` as the prop `myTitle`. A component used without an import (unplugin-vue-components) is looked for by name under `components/`, `app/components/`, `src/components/` and `layers/`.

### Variants and states

A `.vue` file is a component. The Assets tab lists it (pages, layouts and `App.vue` aside), and it opens on its own canvas, where you add variants and states: see [Components](https://midcode.app/docs/editor/components.md).

A state is written as classes (`hover:`, `active:`, `focus-visible:`), as in any component. A variant is a `variant` prop, declared the way the component already declares its props, with `:data-variant="variant"` and a `group/<name>` class on each root of the template:

| The component has | The prop is written as |
| --- | --- |
| `defineProps<Props>()` | A `variant?: 'primary' \| 'ghost'` member in the type, and its default in `withDefaults(…)` (put around `defineProps` when it isn't there) or in the destructuring |
| `defineProps({ … })` | `variant: { type: String, default: 'primary' }`, with the list of variants in a JSDoc `@type` above it |
| No props yet | One line: `withDefaults(defineProps<{ variant?: 'primary' \| 'ghost' }>(), { variant: 'primary' })` in TypeScript, the `defineProps({ … })` form in JavaScript. A `<script setup>` is added when the file has none |

Renaming or removing a variant follows the instances that set it (`variant="ghost"`, `:variant="'ghost'"`).

## Pages

midcode doesn't read Vue Router's routes, so the page menu in the top bar lists only the home page. To open another one, type its path there ("Search, or type a path and press Enter"). [Pages and navigation](https://midcode.app/docs/editor/pages.md) has the rest. midcode doesn't add pages to a Vue app: its routes are code, yours or your agent's to write.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of your `index.html`:

```diff title="index.html"
-    <title>Vite + Vue</title>
+    <title>Oak Studio</title>
+    <meta name="description" content="Furniture made to last." />
   </head>
```

Images are copied into `public/`. A value Vite fills in when it builds (`%VITE_APP_TITLE%`) shows as code and isn't written. There's one form for the whole app: a page has no `<head>` of its own.

## Styles

With Tailwind 4 (a stylesheet with `@import "tailwindcss"` or an `@theme` block), the panel writes your own utilities: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes its own prefixed utilities (`class="title mid:text-[56px]"`) and keeps their plain CSS in `midcode.css`, next to the module your `index.html` loads. The first style edit creates the file and imports it there, as one undoable step:

```diff title="src/main.ts"
 import { createApp } from 'vue'
 import App from './App.vue'
+import './midcode.css'
```

Your `<style scoped>` blocks keep working and aren't edited. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) has the details.

## Limits

- A `<template lang="pug">` isn't read: its elements get no marks.
- Elements move within one file. midcode doesn't follow what a `v-for` gives its contents: an element that reads the loop's item can be dragged out of the loop, where that name no longer exists. `⌘Z` puts it back.
- An insert that needs an import is refused in a component written with the Options API (a plain `<script>` and no `<script setup>`), where an import alone wouldn't be enough: "This needs an import, which midcode can't add to Hero.vue yet. Add it in the code." Insert's interactive components are React and answer "Needs a React page"; icons go in as inline SVG.
- [variables](https://midcode.app/docs/editor/variables.md) are written as `{{ title }}`, `:src="image"` and a `:style="{ … }"` object. A prop the template or the script also reads in its own code isn't renamed or removed from the canvas.
- Variants aren't written for a component on the Options API or one that lists its props as `defineProps([...])` ("Variants for a component that declares its props this way are coming"), nor for one whose template or script already reads `variant` ("This component's variants are written in code: edit them there or ask your agent").
- In the released version there's no free canvas. The next release brings [the free canvas](https://midcode.app/docs/editor/free-canvas.md) to a Vite + Vue app, for plain elements: a component or an element with a binding in it can't float.
- Tried: text, classes, attributes and structure in a Vite + Vue + Tailwind 4 app; props typed by an interface and by `defineProps({ … })`, read and written; a component with two roots. Removing, wrapping and moving several elements, and Site settings, were tried on Vite + Vue projects too. So was component mode, in TypeScript and in JavaScript: variants read, added, renamed and removed, and a style written in one variant's cell of the grid. A Vue app without Tailwind follows the same path as any Vite project, but wasn't tried with Vue itself.

---

# Nuxt

> How midcode starts a Nuxt dev server with a layer of its own, which files are pages, how auto-imported components get their props, and where midcode.css goes.

- Page: https://midcode.app/docs/frameworks/nuxt
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode edits a Nuxt project in the templates of its pages, layouts and components: text, classes, attributes, new elements, their order, and the props a component is given where it's used. It starts Nuxt's own dev server with one extra layer, so your `nuxt.config` is never changed. midcode 1.1.2 and earlier open a Nuxt project to check every breakpoint and leave comments, without editing.

Nuxt's files are Vue single-file components, and midcode edits them the same way as in any Vue app. This page covers what's particular to Nuxt; [Vue](https://midcode.app/docs/frameworks/vue.md) shows each kind of edit with the code it writes.

## At a glance

| | Nuxt |
| --- | --- |
| Detected by | `nuxt` in the dependencies of `package.json` |
| Runs with | `nuxi dev`, extended with a layer of midcode's |
| Elements are marked by | A Vite plugin that layer adds, while the dev server runs |
| Editing | Text, classes, attributes, tag; insert, move, duplicate, delete, wrap in a stack |
| Components | Instances and their props, auto-imported components included. A component opens on its own canvas, with variants, states and variables |
| Pages | The `.vue` files of `pages/` or `app/pages/`. New pages and removing them, when that folder exists |
| Styles | Your Tailwind 4 classes, or `mid:` utilities with `midcode.css` imported from `app.vue` |
| Tried with | Nuxt 4 |

## How midcode runs it

A project is Nuxt when `nuxt` is in its dependencies. midcode looks in your `node_modules` for Nuxt's command line (the `nuxi` package, then `@nuxt/cli`, then `nuxt` itself) and runs it:

```bash
nuxi dev --port 4310 --host localhost --extends <midcode's layer>
```

The port is the first free one from 4310, and the process runs with the Node your shell has, or with midcode's own when there is none.

The layer is a folder in midcode's own data folder (`~/Library/Application Support/midcode/injected/nuxt-layer/`), with one file in it:

```js title="nuxt.config.mjs (midcode's layer, outside your project)"
// Written by midcode: a Nuxt layer that adds the midcode plugin to Vite.
import { midcode } from 'file:///…/vite-plugin.mjs'
export default { vite: { plugins: [midcode(process.env.MIDCODE_ROOT)] } }
```

Nuxt merges a layer under your own config, so your `nuxt.config`, your modules and your `package.json` stay as they are. The plugin only applies to the dev server.

As each `.vue` file is loaded, the plugin marks the elements of its `<template>` before Vue compiles it: `data-mc="app/pages/index.vue:3:5"` (file, line and column) on every element, and `data-mci="Card|app/pages/index.vue:8:5"` on every component used there. Nothing is written to disk. [Vue](https://midcode.app/docs/frameworks/vue.md) shows a template before and after.

Nuxt's own pass-through components get no instance mark, because an attribute on them would land on a whole page: `<NuxtPage>`, `<NuxtLayout>`, `<NuxtLoadingIndicator>`, `<NuxtRouteAnnouncer>`, `<ClientOnly>`, `<DevOnly>` and `<ServerOnly>`.

If the server doesn't come up this way (the process stops, or nothing answers in 45 seconds), midcode runs your own `dev` script instead and says so: the site shows, without marks, and you can only view and comment. The same happens when Nuxt's command line isn't found in `node_modules`.

## What you can edit

Everything on the canvas works on the template of the file the element is written in: a page, a layout, `app.vue` or a component.

- **Text**: double-click and type. Text that's written in the template is replaced there. Text that comes from `{{ }}` is looked for as an exact string in the project's `.ts`, `.js`, `.json` and `.md` files and edited there when midcode can tell which one it is ([Text, images and video](https://midcode.app/docs/editor/text-and-media.md)).
- **Styles**: the [style panel](https://midcode.app/docs/editor/styles.md) writes into the static `class` attribute. A `:class` binding is left alone.
- **Attributes**: links, images, inputs, a `<select>` and its options. A value that's code is written the way Vue binds it (`:maxlength="40"`).
- **Structure**: [Insert](https://midcode.app/docs/editor/insert.md), drag to move within the same file (`⌥`-drag to leave a copy there instead), duplicate, delete, and wrap several elements in a stack with `⇧A`.

A style edit on a page looks like this:

```diff title="app/pages/index.vue"
 <template>
-  <h1 class="text-4xl font-medium">Studio</h1>
+  <h1 class="text-5xl font-medium">Studio</h1>
 </template>
```

### Auto-imported components

Nuxt lets a template use a component without importing it. When midcode finds no import for `<BaseButton>` in the file, it looks for a `.vue` file by that name under `components/`, `app/components/`, `src/components/` and `layers/`, up to five folders deep. It follows Nuxt's naming: `components/base/Button.vue` is `<BaseButton>`, and so is `components/base/BaseButton.vue`.

Once the file is found, the instance's **Props** are typed controls, read from the component's `defineProps` (a type argument with `withDefaults` or a destructuring, an object of constructors, or an array of names). A change is written on the instance:

```diff title="app/pages/index.vue"
-    <BaseButton label="Start" />
+    <BaseButton label="Start now" :size="2" outline />
```

A text is written as `label="…"`, a number or other code as `:size="…"`, a switch that's on as the bare name. A value equal to the declared default removes the attribute.

A component Nuxt or a module provides (`<NuxtLink>`) has no file in your project, so midcode lists what the instance is given, without the component's own types.

A component of your own is in the Assets tab under the name Nuxt gives it (`components/base/Button.vue` is `BaseButton`), and opens on its own canvas, where you add variants and states. They're written as in any Vue component: see [Variants and states](https://midcode.app/docs/frameworks/vue.md). Pages, layouts, `app.vue` and `error.vue` aren't listed as components.

## Pages

Pages are the `.vue` files of `pages/` and `app/pages/`, whichever your project has:

| File | Page |
| --- | --- |
| `app/pages/index.vue` | The home page |
| `app/pages/about.vue` | `/about` |
| `app/pages/blog/index.vue` | `/blog` |
| `app/pages/blog/[slug].vue` | `/blog/[slug]`, a dynamic route |

For a dynamic route, the page menu in the top bar lists its real pages, found in the running site's sitemap and links ([Pages and navigation](https://midcode.app/docs/editor/pages.md)). Folders whose name starts with `_` or a dot aren't listed, and a folder in parentheses doesn't count in the path. A project with no pages folder shows the home page alone.

When the project has a pages folder, "New page" in the page menu writes a page in it, and "Remove" moves a page's file to the Trash:

```vue title="app/pages/about.vue"
<template>
  <main class="mx-auto max-w-3xl px-6 py-24">
    <h1 class="text-4xl font-semibold">About</h1>
    <p class="mt-4">A new page, made in midcode.</p>
  </main>
</template>
```

The class names are written when Tailwind is in your `package.json`; without it the tags come bare. Without a pages folder the plus isn't in the menu: Nuxt only draws pages once there is one and `app.vue` has a `<NuxtPage />`, so the first page is yours or your agent's to set up.

Nuxt keeps the site's `<head>` in its config, so that's where [Site settings](https://midcode.app/docs/editor/site-settings.md) reads and writes: `app.head.title`, `app.head.htmlAttrs.lang`, the `description`, `robots` and `og:image` items of `app.head.meta` and the `rel: 'icon'` item of `app.head.link` in `nuxt.config`, with the favicon and the social image copied to `public/`. Each edit is one value, or a new property or item written like its neighbours. A value the config computes shows as code and isn't written. Tried with Nuxt 4.

## Styles

With Tailwind 4 (a stylesheet with `@import "tailwindcss"` or an `@theme` block), the panel writes your own utilities: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes its own prefixed utilities (`mid:p-6`, `mid:md:flex`) and keeps their plain CSS in `midcode.css`, next to your `app.vue` (`app/app.vue`, or `app.vue` at the root). The first style edit creates the file and imports it from that component, as one undoable step:

```diff title="app/app.vue"
+<script setup>
+  import './midcode.css'
+</script>
+
 <template>
   <NuxtLayout>
     <NuxtPage />
   </NuxtLayout>
 </template>
```

When `app.vue` already has a `<script>`, the import goes on its first line. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) explains what's in the file and why every rule is `!important`.

## Limits

- Tried with Nuxt 4, component mode included. Nuxt 3 wasn't tried, and Nuxt 2 isn't covered.
- The marks come from a Vite plugin: a Nuxt app set to build with webpack gets none.
- A project without `app.vue` has nowhere midcode knows to import `midcode.css`. It creates the file and tells you ("midcode added midcode.css but couldn't tell where to import it. Import it in your app's entry so its styles show."). Import it yourself, for example by listing it under `css` in your `nuxt.config`.
- A `<template lang="pug">` isn't read.
- Elements move within one file. midcode doesn't follow what a `v-for` gives its contents, so an element that reads the loop's item can be dragged out of the loop. `⌘Z` puts it back.
- A component dragged in from the Assets tab is written without an import when its file is under `components/`, which Nuxt brings in by itself. One from another folder gets its import in the file's `<script setup>`, and is refused in a component written with the Options API. Insert's interactive components are React ("Needs a React page"), and icons go in as inline SVG.
- Markdown rendered by a content module has no marks on the canvas. A folder of `.md` files with front matter shows up in the [CMS](https://midcode.app/docs/data/cms.md) instead.
- [variables](https://midcode.app/docs/editor/variables.md) are written as in any Vue component. Variants and variables aren't written for a component on the Options API or one that lists its props as `defineProps([...])`.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects on the App Router.

## Troubleshooting

**The site shows, but nothing can be edited.** midcode fell back to your `dev` script. Open the **Dev server log** in the top bar: it has the line that says why midcode's own start didn't come up. A config that needs something only your script sets up (an env file, a second process, a fixed port) is the usual reason.

**"Dependencies are missing".** The project has no `node_modules` yet. The canvas offers to install them with your package manager; see [Open a project](https://midcode.app/docs/start/open-a-project.md).

---

# Astro

> How midcode runs astro dev with one plugin added, what it edits in an .astro file, and how components, islands, pages and styles work.

- Page: https://midcode.app/docs/frameworks/astro
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode edits an Astro site in the markup of its `.astro` files, the part below the frontmatter: text, classes, attributes, new elements, their order, and the props a component is given where it's used. The frontmatter and whatever sits inside `{ }` stay exactly as you wrote them, except for what midcode adds there when you ask for it: the import of a component you drag in from the Assets tab, a stylesheet import in a site without Tailwind, and a `variant` prop when you give a component [variants](#variants-and-states). An island (React, Preact, Solid, Svelte, Vue) is edited in its own file. midcode 1.1.2 and earlier edit only an Astro site's JSX islands, and leave `.astro` files to view and comment.

## At a glance

| | Astro |
| --- | --- |
| Detected by | `astro` in the dependencies of `package.json` |
| Runs with | Your project's own `astro dev`, with your config and one Vite plugin added |
| Elements are marked by | That plugin, in memory, as each `.astro` file is loaded |
| Editing | Text, classes, attributes, tag; insert, move, duplicate, delete, wrap in a stack |
| Components | `.astro` components are recognised where they're used, with their props as typed controls, and open on their own canvas with variants, states and variables |
| Pages | The files of `src/pages`. New pages and removing them |
| Styles | Your Tailwind 4 classes, or `mid:` utilities with `midcode.css` imported in each layout |
| Tried with | Astro 7 |

## How midcode runs it

A project is Astro when `astro` is in its dependencies. midcode starts the Astro that's in your `node_modules`:

```bash
astro dev --root <your project> --config <midcode's config> --port 4310 --host localhost --ignore-lock
```

The port is the first free one from 4310, and the process runs with the Node your shell has, or with midcode's own when there is none. Astro's telemetry is turned off for that process.

The config is a small file in midcode's own data folder (`~/Library/Application Support/midcode/injected/astro.config.mjs`). It imports your `astro.config` and adds one plugin to its `vite.plugins`. Your config, your `package.json` and your lockfile aren't changed, and the plugin only applies to the dev server, never to a build.

Astro compiles an `.astro` file before any plugin gets to transform it, so midcode hands the file over already marked, as it's loaded. Take this component:

```astro title="src/components/Hero.astro"
---
import Card from './Card.astro'
const { title } = Astro.props
const woods = ['Oak', 'Walnut']
---
<section class="hero">
  <h1 class="title">{title}</h1>
  <p class="lead">Furniture made to order.</p>
  <ul>
    {woods.map((wood) => <li class="wood">{wood}</li>)}
  </ul>
  <Card title="Oak" price={9} />
</section>
```

What Astro compiles while midcode runs it has a mark on every element: `data-mc="src/components/Hero.astro:6:1"` on the `<section>` (the file, line and column where it's written), and `data-mci="Card|src/components/Hero.astro:12:3"` on the `<Card>`. The elements at the top of each `.astro` file also get a `data-mcu`, read from `Astro.props`, which says where that component is used. Nothing is written to disk.

`<html>`, `<head>` and what's inside it, `<script>` and `<style>` are never marked.

If the server doesn't come up this way (the process stops, or nothing answers in 45 seconds), midcode runs your own `dev` script instead and says so: the site shows, without marks, and you can only view and comment.

## What you can edit

The tools are the editor's own: [select, move and resize](https://midcode.app/docs/editor/select-move-resize.md), [text and media](https://midcode.app/docs/editor/text-and-media.md), [the style panel](https://midcode.app/docs/editor/styles.md), [Insert](https://midcode.app/docs/editor/insert.md). In the component above:

| Element | On the canvas |
| --- | --- |
| `<p class="lead">` | Everything: its text, its classes, its place |
| `<h1 class="title">` | Classes and attributes. Its text is `{title}`, which isn't written there |
| `<li class="wood">` | Classes and attributes. An expression draws it, so it can't be moved or removed |
| `<Card … />` | Its props, where it's used |

Several elements can be removed, moved or wrapped in a stack (`⇧A`) at once, and `⌥`-drag leaves the element where it is and puts a copy where you drop it. All of it stays within one file.

### Text, classes and attributes

A text is replaced in the markup when everything inside its element is written text:

```diff title="src/components/Hero.astro"
-  <p class="lead">Furniture made to order.</p>
+  <p class="lead">Furniture made to last.</p>
```

A `{` or `}` you type is written as an entity, so Astro doesn't read it as an expression. Text that comes from an expression is looked for as an exact string in the project's `.ts`, `.js`, `.json` and `.md` files and edited there when midcode can tell which one it is; otherwise it's edited in the code.

The style panel writes into a written `class="…"` attribute and creates it when there's none. A `class:list` directive is an expression and is left alone. An attribute's value is written as text (`href="/about"`), as a bare name when it's a switch (`disabled`), or in braces when it's a number or other code (`width={640}`).

### Elements an expression draws

An element written inside `{ }` (the `<li>` in the `.map` above, or what a condition returns) is one piece of that expression. You can restyle it, and every copy it draws changes with it. Moving or removing it would break the expression, so midcode refuses: "An expression draws this element ({…}). Move or remove it in the code."

### Components and props

An `.astro` component used in a page shows in Layers with its name and is selected as an instance. Its **Props** are typed controls, read from the `interface Props` (or `type Props`) in its frontmatter, with the defaults its `Astro.props` destructuring gives:

```astro title="src/components/Card.astro"
---
interface Props {
  title: string
  price?: number
  featured?: boolean
}
const { title, price = 0, featured = false } = Astro.props
---
```

A change is written where the component is used:

```diff title="src/components/Hero.astro"
-  <Card title="Oak" price={9} />
+  <Card title="Walnut" price={12} featured />
```

A value equal to the declared default removes the attribute. Astro's own pass-through components get no instance mark: `Fragment`, `ViewTransitions`, `ClientRouter`, `Content`, `Debug`, `Code`, `Prism`.

Drag a component from the Assets tab onto the page and midcode writes the instance with its import, in the frontmatter (one is added at the top of the file when it has none), as a relative path with its extension: `import Card from '../components/Card.astro'`.

### Variants and states

An `.astro` file outside your `pages` and `layouts` folders is a component. The Assets tab lists it, and it opens on its own canvas, where you add variants and states: see [Components](https://midcode.app/docs/editor/components.md).

A state is written as classes (`hover:`, `active:`, `focus-visible:`). A variant is a `variant` prop: a `variant?: 'primary' | 'ghost'` member in `interface Props`, its default in the frontmatter's destructuring (`const { variant = 'primary' } = Astro.props`), and `data-variant={variant}` with a `group/<name>` class on each element at the top of the markup. A component with no props yet gets the interface and the destructuring. Renaming or removing a variant follows the instances that set it (`variant="ghost"`).

### Islands

The same plugin marks the JSX of `.tsx` and `.jsx` files, `.svelte` files (read with your project's Svelte compiler) and `.vue` templates. An island is edited in its own file, like in a project of that framework: see [React with Vite](https://midcode.app/docs/frameworks/react-vite.md), [Svelte](https://midcode.app/docs/frameworks/svelte.md) and [Vue](https://midcode.app/docs/frameworks/vue.md).

## Pages

Pages are the files of `src/pages`: `.astro`, `.md`, `.mdx`, `.html`, `.tsx` and `.jsx`.

| File | Page |
| --- | --- |
| `src/pages/index.astro` | The home page |
| `src/pages/about.astro` | `/about` |
| `src/pages/blog/[slug].astro` | `/blog/[slug]`, a dynamic route |

For a dynamic route, the page menu in the top bar lists its real pages, found in the running site's sitemap and links ([Pages and navigation](https://midcode.app/docs/editor/pages.md)). Folders whose name starts with `_` or a dot aren't listed.

"New page" in the page menu writes `src/pages/<path>.astro` the way your home page is written, and "Remove" moves a page's file to the Trash. When the home page imports a layout from a `layouts` folder and wraps its content in it, the new page does the same:

```astro title="src/pages/about.astro"
---
import Layout from '../layouts/Layout.astro'
---

<Layout>
	<main class="mx-auto max-w-3xl px-6 py-24">
	  <h1 class="text-4xl font-semibold">About</h1>
	  <p class="mt-4">A new page, made in midcode.</p>
	</main>
</Layout>
```

If the home page gives its layout a `title`, the new page gets `title="About"`. Without a layout, the new page is a whole document that imports the stylesheets the home page imports in its frontmatter. The class names are written when Tailwind is in your `package.json`.

A page written in Markdown shows on the canvas, but Markdown carries no marks. Edit that content in the [CMS](https://midcode.app/docs/data/cms.md): a folder of `.md` or `.mdx` files with front matter is a collection there.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). In an Astro site the title, the description, the language, search engines, the favicon and the social image are tags in the `<head>` of a layout: the first file of `src/layouts`, by name, that closes a `<head>`, or `src/pages/index.astro` when no layout does. Images are copied into `public/`.

What the layout takes from its props (`<title>{title}</title>`) shows as code and is left to your code. There's one form for the whole site: pages have none of their own.

## Styles

With Tailwind 4 (a stylesheet with `@import "tailwindcss"` or an `@theme` block), the panel writes your own utilities: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes its own prefixed utilities (`mid:p-6`, `mid:md:flex`) and keeps their plain CSS in `src/midcode.css`. Astro has no single entry file, so the first style edit imports the stylesheet in the frontmatter of every layout in `src/layouts` (or of every page in `src/pages`, when the site has no layouts), as one undoable step:

```diff title="src/layouts/Layout.astro"
 ---
+import '../midcode.css'
 import Header from '../components/Header.astro'
 ---
```

A layout with no frontmatter gets one with that single line. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) explains what's in the file.

## Limits

- Insert's interactive components are React ("Needs a React page"), and icons go in as inline SVG.
- An element whose whole class is an expression (`class={classes}`) is styled in the code: the panel works on a written `class="…"`.
- A tag with a dash in its name (a custom element like `<my-widget>`) is read as a component and gets no mark.
- Elements move within one file.
- Pages are looked for in `src/pages`. With another `srcDir`, the list has the home page alone, and any path can be typed in the page menu.
- [variables](https://midcode.app/docs/editor/variables.md) are written as `{title}`, `src={image}` and a `style={{ … }}` object. A prop the frontmatter or the markup also reads in its own code isn't renamed or removed from the canvas.
- Variants aren't written for a component whose root is another component ("Its root is another component that doesn't pass its props on ({...props}), so data-variant wouldn't reach the page"), nor for one whose markup or frontmatter already reads `variant` ("This component's variants are written in code: edit them there or ask your agent").
- In the released version there's no free canvas. The next release brings [the free canvas](https://midcode.app/docs/editor/free-canvas.md), for plain elements: a component or an element with an expression in it can't float.
- Tried with Astro 7: editing `.astro` files, and a component used three times, once inside a `.map`. An Astro 7 site without Tailwind was tried too (a layout with no frontmatter gets one), and so were creating and removing a page, Site settings, and component mode (variants read, added, renamed and removed).

---

# Angular

> How midcode runs ng serve, finds each element of an Angular page in the components' templates after it loads, and edits those templates, external or inline.

- Page: https://midcode.app/docs/frameworks/angular
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode edits an Angular app in its components' templates: text, classes, attributes and structure, in `.html` templates and in the ones written inside a component's `.ts`. Angular's build takes no plugin from outside, so midcode doesn't mark elements while the app compiles. It finds each element in your templates after the page has loaded. What Angular computes (`{{ }}`, `[bound]` values, `@if` and `@for` blocks) is left exactly as written. midcode 1.1.2 and earlier don't edit Angular projects.

## At a glance

| | Angular |
| --- | --- |
| Detected by | `angular.json` at the project's root |
| Runs with | `./node_modules/.bin/ng serve --host 127.0.0.1 --port $PORT` |
| Elements are marked by | Matching each loaded page against the components' templates |
| Editing | Text, classes, attributes, tag; insert, move, duplicate, delete, wrap in a stack |
| Components | No instances or props panel. A component's host element is selected like any element |
| Pages | The routes of `app.routes.ts` or a routing module |
| Styles | Your Tailwind 4 classes, or `mid:` utilities with `public/midcode.css` linked from `src/index.html` |
| Tried with | Angular 22 (standalone components, zoneless) |

## How midcode runs it

A folder with an `angular.json` is an Angular project. midcode runs your project's own CLI, in your login shell, from the project's folder:

```bash
NG_CLI_ANALYTICS=false ./node_modules/.bin/ng serve --host 127.0.0.1 --port $PORT
```

`$PORT` is a free port midcode picks, starting at 4310. `NG_CLI_ANALYTICS=false` keeps the CLI from stopping to ask about analytics, which nobody could answer. Nothing in `angular.json`, your `package.json` or your build changes. To run it another way, see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).

### How elements get their marks

When a page loads in a frame, midcode reads its elements and looks each one up in the project's templates. Where it's sure, it sets `data-mc="file:line:col"` on the element in the page (never in your files), and from there the canvas treats it like any other marked element.

An element of the page is a written element when what's fixed in the template is there in the page: its tag, its `id`, every class that isn't computed, its text when text is all it holds, and attributes like `href`, `src`, `alt`, `type` or `placeholder`. midcode looks first among the children of what its parent turned out to be, then in the whole project, where only an unmistakable match counts. In doubt the element stays unmarked: it can't be edited, and it's never edited by mistake.

An Angular page keeps drawing itself: the router swaps views, an `@if` flips. midcode watches the page, and when elements arrive without a mark it matches the page again. After an edit it reloads nothing: Angular's dev server swaps the template in place. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) describes the matching in full; Angular goes the same way.

### Which files are templates

- A file named `*.component.html` or `*.ng.html`, and, in an Angular project, any other `.html` (`app.html`, `src/index.html`).
- A component's `.ts` with its template inside (`template: '…'`, in backticks or quotes). It's read where it sits, so a mark points into the `.ts` file. A template the code builds with `${…}` isn't read.

Files like `*.spec.ts`, `*.routes.ts`, `*.config.ts`, `*.service.ts` and `*.module.ts` are never read for templates.

## What you can edit

Take this template:

```html title="src/app/home/home.html"
<section class="hero">
  <h1>{{ title() }}</h1>
  <p class="lead">Furniture made to order.</p>
  @for (wood of woods(); track wood.id) {
    <app-card [wood]="wood" class="card" />
  }
</section>
```

| Element | On the canvas |
| --- | --- |
| `<p class="lead">` | Everything: its text, its classes, its place |
| `<h1>` | Classes and attributes. Its text is `{{ title() }}`, which isn't written there |
| `<app-card>` | Its written classes and attributes. `[wood]` shows as code. Written once and drawn for every item, so an edit changes them all |

What the reader takes as computed, and never rewrites:

- `{{ … }}`, and ICU messages (`{count, plural, …}`).
- The blocks: `@if`, `@else`, `@for`, `@empty`, `@switch`, `@case`, `@default`, `@defer` with `@placeholder`, `@loading` and `@error`, a `@let x = …;`, and the `}` that closes a block.
- `[property]`, `(event)`, `[(both)]`, `*structural`, `#reference` and `@animation` on a tag.

`<ng-container>`, `<ng-template>` and `<ng-content>` aren't in the page, though what's inside them is. Any other tag with a dash is a component's host element: it's in the page, and you can select it where it's written.

### Text

```diff title="src/app/home/home.html"
-  <p class="lead">Furniture made to order.</p>
+  <p class="lead">Furniture made to last.</p>
```

In an Angular template a `{` opens a message, a `}` closes a block and an `@` opens one, so midcode writes those three as entities: typing `hello@oak.studio` leaves `hello&#64;oak.studio` in the file, which the page shows as you typed it.

### Classes and attributes

The [style panel](https://midcode.app/docs/editor/styles.md) writes into the static `class` attribute and creates it when there's none. `[class.active]`, `[ngClass]` and `[class]` are bindings and are left alone.

Attributes are read as written, and a value bound to code shows as code under the name it binds. A value is written the way Angular writes it: a text as `placeholder="Your email"`, a switch that's on as `disabled`, a number or other code as `[maxlength]="40"`.

### Inline templates

The same edits work inside a component's `.ts`:

```diff title="src/app/badge/badge.ts"
 @Component({
   selector: 'app-badge',
-  template: `<span class="badge">New</span>`,
+  template: `<span class="badge">Just in</span>`,
 })
```

Quotes, backticks and backslashes you type are written as entities there (`It&#39;s here`), so they can't end the string. Before saving, midcode checks that everything outside the templates is unchanged. If an edit would reach the code around them, nothing is written and it says so: "That can't be written inside this component's code as it is: it would end its template. Edit it in the code."

### Structure

[Insert](https://midcode.app/docs/editor/insert.md) adds plain markup, an element is dragged before, after or inside another one in the same file (`⌥`-drag leaves a copy there instead), and several can be deleted, moved or wrapped in a stack (`⇧A`) at once.

## Pages

The page list comes from the files where the app lists its routes: `*.routes.ts`, `*-routing.module.ts` and `*.routing.ts` under `src/`, the app's own first. Every `path: '…'` is a page, under the paths of the routes it's a child of:

| Route | Page |
| --- | --- |
| `{ path: '', component: Home }` | The home page |
| `{ path: 'work', loadComponent: () => import('./work/work') }` | `/work` |
| `{ path: 'work/:id', component: Project }` | `/work/[id]`, a dynamic route |
| `{ path: '**', component: NotFound }` | Not a page |

When a route's component can be followed through its import, the page knows its template file. A dynamic route has no address of its own: open one of its pages by typing a real path in the page menu in the top bar ("Search, or type a path and press Enter"). [Pages and navigation](https://midcode.app/docs/editor/pages.md) has the rest.

midcode doesn't add pages to an Angular app: a route is a line of code and a component, yours or your agent's to write.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of `src/index.html`, and the images are copied into `public/`. There's one form for the whole app. This wasn't tried on an Angular project.

## Styles

With Tailwind 4 through PostCSS, which is what `ng new --style=tailwind` sets up, the panel writes your own utilities: see [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

Without it, midcode writes its own prefixed utilities (`mid:p-6`, `mid:md:flex`) and keeps their plain CSS in `public/midcode.css`. The first style edit creates the file and links it from the page every route goes through, as one undoable step:

```diff title="src/index.html"
   <link rel="icon" type="image/x-icon" href="favicon.ico">
+  <link rel="stylesheet" href="/midcode.css">
 </head>
```

These are global rules, each one `!important`, so they apply inside every component whatever its view encapsulation. Your components' own styles aren't edited. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) has the details.

## Limits

- On a page with a header, a router outlet, `@for`, `@if` / `@else`, a component with an inline template and projected content, 48 of 49 elements were found. The missing one is the host element the router creates, which isn't written anywhere.
- Tried on that app: text, classes and attributes, in external and inline templates. Not tried: apps built on NgModules, server-side rendering, component libraries such as Angular Material, and one `templateUrl` shared by several components.
- What a library draws has its template in `node_modules`, which midcode doesn't read: those elements stay unmarked.
- midcode reads a block's opening and its closing `}` as markers, not as a container. An element that uses a `@for`'s item can be dragged out of the block, where that name no longer exists. `⌘Z` puts it back.
- Routes of a lazy-loaded routing file show without the prefix they're mounted under.
- Styles without Tailwind need the `public/` folder Angular has served since version 18. An older project, with its assets listed in `angular.json`, wasn't tried. New images are copied into `public/` too, and without that folder Site settings can't place a favicon or a social image: it asks you to put the file where the site serves it and link it in the code.
- An insert that needs an import is refused, and Insert's interactive components are React ("Needs a React page").
- There are no component instances here, so no [props, variants or states](https://midcode.app/docs/editor/components.md). [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects on the App Router.

## Troubleshooting

**An element can be selected but not edited.** midcode didn't find it in a template with certainty. That happens when several written elements could be it and nothing fixed tells them apart: give it a class or an `id` of its own. It also happens when the element isn't written in your templates at all (a library's, or one a script adds).

**The server didn't start.** Open the log with **View log** on the card. "Change how it runs" under it lets you give another command, such as your own `npm start`; midcode keeps it in `.midcode/server.json` ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).

---

# Plain HTML

> How midcode serves a folder of .html files itself, marks each element as it sends the page, edits the files in place and links midcode.css from every page.

- Page: https://midcode.app/docs/frameworks/html
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode edits a folder of `.html` files with no framework and no build step. It serves the folder itself, reloads the page when a file changes, and writes each edit (text, classes, attributes, new elements, their order) into the `.html` file, with the rest of the file left byte for byte as it was. You don't need Node or a `package.json`. midcode 1.1.2 and earlier open a folder of HTML to check every breakpoint and leave comments, without editing.

## At a glance

| | Plain HTML |
| --- | --- |
| Detected by | An `index.html` at the folder's root, and nothing else midcode knows how to run |
| Runs with | midcode's own static server |
| Elements are marked by | That server, as it sends each page |
| Editing | Text, classes, attributes, tag; insert, move, duplicate, delete, wrap in a stack |
| Components | None: every element is written where it shows |
| Pages | Every `.html` file, at the path it's served from. New pages at the top of the folder |
| Styles | `mid:` utilities, with `midcode.css` at the folder's root and a `<link>` in every page |
| Tried with | A plain HTML site, and the one New project creates |

## How midcode runs it

A folder is plain HTML when it has an `index.html` at its root and midcode finds nothing else to run:

- none of the files that give away another stack (`artisan`, `manage.py`, `_config.yml`, `index.php` and the rest of the list in [Any other stack](https://midcode.app/docs/frameworks/custom-server.md));
- and either no `package.json`, or one with none of the frameworks midcode knows and no `dev` script.

midcode then serves the folder on `http://localhost:4310` (the first free port from there) and writes one line in the log: `midcode serves <folder> on http://localhost:4310`. The server is small on purpose:

- A folder's address answers with its `index.html`, and `/about` answers with `about.html`.
- Nothing is cached, so what you see is what's on disk.
- It reloads every frame when a `.html`, `.css`, `.js`, `.json` or image file in the folder changes, whoever changed it: midcode, your editor or an agent.

### How elements get their marks

The marks are added to each page as the server sends it. Your file:

```html title="index.html"
<!doctype html>
<html lang="en">
  <head>
    <title>Oak and Iron</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>Welcome</h1>
      <p class="lead">Handmade furniture.</p>
    </main>
  </body>
</html>
```

What the canvas receives:

```html
  <body data-mc="index.html:7:3">
    <main data-mc="index.html:8:5">
      <h1 data-mc="index.html:9:7">Welcome</h1>
      <p data-mc="index.html:10:7" class="lead">Handmade furniture.</p>
    </main>
  <script>new EventSource('/__midcode/reload').onmessage = () => location.reload()</script></body>
```

`data-mc` is the file, line and column where the element is written. The script at the end is what reloads the page. Both exist only in what's served: the file on disk is never given a mark or a script. `<html>`, `<head>` and everything in it, `<script>`, `<style>` and `<noscript>` aren't marked.

## What you can edit

Click an element and the right panel shows where it's written, as `file:line`. The editor's pages describe each tool: [select, move and resize](https://midcode.app/docs/editor/select-move-resize.md), [text and media](https://midcode.app/docs/editor/text-and-media.md), [the style panel](https://midcode.app/docs/editor/styles.md), [Insert](https://midcode.app/docs/editor/insert.md), [Layers](https://midcode.app/docs/editor/layers.md).

**Text.** Double-click and type:

```diff title="index.html"
-      <h1>Welcome</h1>
+      <h1>Welcome back</h1>
```

A text is edited when everything inside its element is written text. A `<` you type is written as `&lt;`.

**Styles.** The style panel writes classes on the element (see [Styles](#styles) below):

```diff title="index.html"
-      <p class="lead">Handmade furniture.</p>
+      <p class="lead mid:text-[20px] mid:md:text-[18px]">Handmade furniture.</p>
```

**Attributes.** A link's `href`, an image's `alt`, an input's type and placeholder, a `<select>` and its options are read from the tag and written back as plain attributes: a text as `href="/about.html"`, a switch that's on as `disabled`, a number as `maxlength="40"`.

**Structure.** Insert adds plain markup at the selection or at the end of the page. Drag an element before, after or inside another one in the same file, and the comment right above it travels with it. Several elements can be deleted, moved or wrapped in a stack (`⇧A`) at once, and `⌥`-drag leaves the element where it is and puts a copy where you drop it, in the same file.

midcode's reader is tolerant on purpose. An `<li>` or a `<p>` that's never closed, an attribute without quotes or a stray closing tag are read as they are and stay as they are: only the range you edit changes, and nothing is tidied or reformatted. A tag with a dash in its name (a custom element) is an element like any other.

## Pages

Every `.html` file in the folder is a page, at the path the server answers it from:

| File | Page |
| --- | --- |
| `index.html` | The home page |
| `about.html` | `/about.html` |
| `blog/index.html` | `/blog` |
| `blog/first-post.html` | `/blog/first-post.html` |

`node_modules` and folders whose name starts with a dot or `_` aren't listed. Pick a page from the page menu in the top bar ([Pages and navigation](https://midcode.app/docs/editor/pages.md)).

"New page" in that menu writes a new `.html` file at the top of the folder. Type its path without the extension: `/about` makes `about.html`. The file gets a copy of the home page's `<head>`, so it links the same stylesheets, with its own `<title>`:

```html title="about.html"
<!doctype html>
<html lang="en">
  <head>
    <title>About</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>About</h1>
      <p>A new page, made in midcode.</p>
    </main>
  </body>
</html>
```

A path with a folder in it is refused ("In a folder of HTML, a new page goes at the top of the site: /about"), because the copied `<head>` links its files by paths that only hold at the top. Make a page in a subfolder by hand, or with your agent, and it appears in the list. "Remove" moves a page's file to the Trash.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). In a folder of HTML every page has its own `<head>`, so there are two kinds of form: one for the site, written in `index.html`, and one for each page, written in that page's file (right-click a page in the page menu, then "Page settings…"). The title, the description, the language, search engines, the favicon and the social image are tags of that `<head>`:

```diff title="index.html"
   <head>
-    <title>Oak and Iron</title>
+    <title>Oak and Iron, furniture</title>
     <link rel="stylesheet" href="styles.css">
+    <meta name="description" content="Handmade furniture.">
   </head>
```

A tag that's there has its value changed. A new one goes last in the `<head>`, indented and closed like its neighbours. Images are copied to the top of the folder as `favicon` and `og-image`, with the extension of the file you picked, and linked by that name.

## Styles

A folder of HTML has no Tailwind build, so midcode uses its own utilities: Tailwind 4's, written with the prefix `mid:` and turned into plain CSS by midcode itself. Your own stylesheets and classes aren't touched.

The first style edit sets this up, as one undoable step:

- `midcode.css` is created at the folder's root, with the CSS of exactly the `mid:` classes found in your files.
- Every `.html` page gets one `<link>` to it at the end of its `<head>`, indented like the line above. A page in a subfolder gets the relative path (`../midcode.css`).

```diff title="index.html"
     <link rel="stylesheet" href="styles.css">
+    <link rel="stylesheet" href="./midcode.css">
   </head>
```

A page you add later gets its `<link>` with the next style edit. `midcode.css` is rewritten whenever the classes in your files change, and it's part of your site: publish it with the pages. Colors, fonts and text styles you make in the Styles list of the Assets tab go in `.midcode/theme.css`. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) explains the syntax and why every rule is `!important`; [Theme and design tokens](https://midcode.app/docs/styling/theme.md) covers the theme file.

## Limits

- Markup that a script builds in the browser has no marks: it's edited in that script.
- Nothing is shared between pages. A header repeated in ten files is ten elements, and an edit changes the one you clicked.
- A page has to be an `.html` file. The server doesn't send an `.htm` file as a page.
- midcode reads `{{ … }}`, `{% … %}` and `{# … #}` as something a template language computes, because many generators call their templates `.html` too. A text with one of those in it isn't edited on the canvas, and a `{{` you type is written as an entity.
- A new image is copied to `public/images/` and referenced as `/images/<file>`, the way frameworks with a `public/` folder serve it. midcode's static server serves the folder itself, so after swapping an image check that its `src` points at where the file is.
- Insert's interactive components (carousel, tabs and the like) are React and answer "Needs a React page". Icons go in as inline SVG.
- [Components](https://midcode.app/docs/editor/components.md) don't apply here. [the free canvas](https://midcode.app/docs/editor/free-canvas.md) comes with the next release, kept in `midcode-scratch.html` beside your pages.
- A page's form in Site settings has a title, a description, the search engines switch and a social image. The language and the favicon are in the site's form, which writes `index.html` only: another page keeps the `lang` and the icon its own file says.

## Troubleshooting

**The canvas asks "How does this site run?"** There's no `index.html` at the root of the folder you opened, so midcode didn't take it for a plain site. Open the folder that holds `index.html`, or tell midcode how to serve it: see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).

**It opens as something else.** A `package.json` with a `dev` script, or a file like `index.php` or `_config.yml`, makes midcode run that instead of serving the folder. The **Dev server log** in the top bar shows what it ran.

**A style shows on one page and not on another.** The other page has no `<link>` to `midcode.css`. Make any style edit and midcode adds the missing ones.

---

# Create React App, Vue CLI, Gatsby, Docusaurus

> How midcode edits sites built with webpack or Rspack, which take no plugin from outside, by riding along in their own dev script.

- Page: https://midcode.app/docs/frameworks/webpack
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

Sites built with webpack or Rspack are edited on the canvas too: Create React App, Vue CLI, Gatsby, Docusaurus, Rsbuild, or a webpack config you wrote yourself. None of these tools takes a plugin from outside the way Vite and Next.js do, so midcode goes in another way. It runs the project's own script and preloads a hook into it. The hook adds midcode's loaders to whatever config webpack is called with.

What you can edit is the code you wrote: the JSX and the Vue components in the project's own folders. What a theme or a generated folder draws has no marks.

## At a glance

| | webpack and Rspack sites |
| --- | --- |
| Detected by | A tool that runs webpack or Rspack, together with `react`, `preact`, `vue` or `solid-js`, in `package.json` |
| Runs with | Your own script (`dev`, `start`, `serve`, `develop` or `docs:dev`), in your shell, on a port midcode picks, with one `--require` added through `NODE_OPTIONS` |
| Elements are marked by | Two loaders the hook puts first in the config webpack or Rspack is given |
| Editing | Text, classes, attributes and structure, in the project's `.js`, `.jsx`, `.tsx` and `.vue` files |
| Components | Instances and props are recognised, as in any JSX or Vue project |
| Pages | Gatsby: the files of `src/pages`. The others: none listed |
| Styles | `mid:` classes, with `midcode.css` imported in `src/index.js` or `src/main.js` |
| Tried with | Create React App 5, Vue CLI 5, Gatsby 5, Docusaurus 3, Rsbuild 2 with React, a webpack 5 config written by hand |

## How midcode runs it

midcode reads `package.json`. The project is one of these when it has no `next`, `vite`, `astro`, `@sveltejs/kit`, `nuxt`, `@react-router/dev` or `@remix-run/dev` (those have their own pages), and its dependencies hold both:

- something that runs webpack or Rspack: `react-scripts`, `@craco/craco`, `react-app-rewired`, `@vue/cli-service`, `gatsby`, `@docusaurus/core`, `webpack-dev-server`, `webpack-cli`, `@webpack-cli/serve`, `@rsbuild/core`, `@rspack/cli` or `@rspack/core`;
- something that draws its pages: `react`, `preact`, `vue` or `solid-js`.

The script it runs is the first one your `package.json` has among `dev`, `start`, `serve`, `develop` and `docs:dev`. That's `start` in Create React App and Docusaurus, `serve` in Vue CLI, `start` or `develop` in Gatsby. It runs in your login shell, with your package manager and your Node, as if you had typed:

```bash
NODE_OPTIONS='--require "/Applications/midcode.app/Contents/Resources/injected/webpack-hook.cjs"' \
PORT=4310 BROWSER=none \
npm run start
```

`PORT` is a free port, the first from 4310 up, for the tools that honour it (Create React App does). `BROWSER=none` keeps the script from opening a browser tab. midcode also passes the hook the project's folder and where its loaders are, in variables named `MIDCODE_…`. The address the site answers at is read from what the script prints.

Some of these tools don't read `PORT`. Left alone they'd take their usual port (3000, 8000, 8080), which may belong to a server of your own. So when your script is only a call to one of them and names no port, midcode adds `--port` with its own: `npm run serve -- --port 4310` in a Vue CLI project (`pnpm run serve --port 4310` with pnpm, yarn or bun). The tools it does this for are `rsbuild`, `rspack`, `vue-cli-service`, `webpack`, `webpack-dev-server`, `docusaurus`, `gatsby`, `parcel`, `vitepress`, `vuepress` and `eleventy`. A script that does more than call the tool (`a && webpack serve`), or that already has `--port` or `-p`, runs as it is.

The dev server log (the button with the status dot in the top bar) says so:

```text
Built with webpack: midcode adds its stamps as the site builds.
$ npm run start  (your shell)
```

The hook is loaded into every Node process the script starts. It does nothing until one of them requires `webpack` or `@rspack/core`. Rspack 2 is an ES module, which Rsbuild 2 imports instead of requiring: there the hook answers the import with a module that hands out the same wrapped `rspack()`. That part needs a Node that can hook into imports (22.15 or later). Then, each time that tool is called with a config, the config gains two rules, ahead of its own:

- one for `.jsx`, `.tsx`, `.js` and `.mjs` files, with the loader that marks JSX. `.js` is included because that's where Create React App writes JSX.
- one for `.vue` files, with the loader that marks Vue templates.

Both skip anything outside the project folder, anything in `node_modules`, and any folder whose name starts with a dot (Gatsby's `.cache`, Docusaurus's `.docusaurus`). A config that builds for Node (`target: 'node'`, a server-side build) is left as it is. Nothing is written to disk, and nothing in your webpack config, `craco.config.js`, `vue.config.js`, `gatsby-config.js` or `docusaurus.config.js` changes.

### What the loaders add

```jsx title="src/App.js"
function App() {
  return (
    <div className="App">
      <h1>Hello</h1>
    </div>
  );
}

export default App;
```

In the page, the heading carries the file, line and column it's written at:

```html
<h1 data-mc="src/App.js:4:7">Hello</h1>
```

Component instances get `data-mci` as a prop (`App|src/index.js:10:5`), and the element a component returns carries where it's used in `data-mcu`. They are the same three marks midcode leaves in [Next.js](https://midcode.app/docs/frameworks/nextjs.md) and Vite projects, and the same in `.vue` files as in [Vue](https://midcode.app/docs/frameworks/vue.md) with Vite.

## What you can edit

Double-click the heading and type. The string in the file is the only thing that changes:

```diff title="src/App.js"
-      <h1>Hello</h1>
+      <h1>Hello again</h1>
```

Text, classes, attributes, images, inserting, moving, duplicating and removing work as in any JSX or Vue project: see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md), [The style panel](https://midcode.app/docs/editor/styles.md), [Insert](https://midcode.app/docs/editor/insert.md) and [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md). For what's editable inside a `.vue` file, see [Vue](https://midcode.app/docs/frameworks/vue.md).

A text that isn't in the markup is found where it's written. In Docusaurus the tagline on the home page comes from the config, and that's where the edit lands:

```diff title="docusaurus.config.js"
-  tagline: 'Dinosaurs are cool',
+  tagline: 'Docs that stay current',
```

## Pages

In Gatsby, each file of `src/pages` (`.js`, `.jsx`, `.tsx`, `.mdx`) is a page, except `404` and `500`. The other tools have no list midcode reads: the page menu shows Home. To see another page, type its path in the menu and press `Enter`.

## Site settings

In Create React App and Vue CLI the site's `<head>` is a file, `public/index.html`, and [Site settings](https://midcode.app/docs/editor/site-settings.md) writes its tags there: the title, the description, the language, search engines, the favicon and the social image. Images are copied into `public/`.

What the bundler fills in when it builds is shown as code and left alone. Vue CLI's `<title><%= htmlWebpackPlugin.options.title %></title>` is one of those: the form shows it, and the title stays your code's to set. Tried with Vue CLI.

Gatsby keeps these settings in its own config, and midcode doesn't write them yet.

Docusaurus keeps these settings in `docusaurus.config`, and Site settings reads and writes them there: `title`, `tagline` (the description), `i18n.defaultLocale`, `noIndex`, `favicon` and `themeConfig.image`, with images copied to `static/img`. Tried with Docusaurus 3. See [Nuxt and Docusaurus](https://midcode.app/docs/editor/site-settings.md).

## Styles

These projects rarely have Tailwind 4, so midcode writes its own `mid:` utilities and compiles them to `midcode.css` (see [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)). On your first style edit it creates `src/midcode.css` and imports it in the entry it finds: `src/index.js` in Create React App, `src/main.js` in Vue CLI.

```diff title="src/index.js"
 import './index.css';
 import App from './App';
 import reportWebVitals from './reportWebVitals';
+import './midcode.css'
```

Gatsby and Docusaurus have no such entry file. There midcode still writes `src/midcode.css` and tells you it couldn't tell where to import it. Load it where the site takes its global CSS: `gatsby-browser.js` in Gatsby, `customCss` in `docusaurus.config.js`. Styles were not tried on those two.

## What was tried

Each number is the elements of one page that carried a mark, out of all the elements on it.

| Stack | Marked | Notes |
| --- | --- | --- |
| Create React App 5 | 13 of 15 | The other two are written in `public/index.html`. Text, classes and `mid:` styles show through hot reload |
| Vue CLI 5 | 36 of 39 | Text, classes and `mid:` styles show through hot reload |
| Gatsby 5 | 35 of 41 | All of them from `src/pages/index.js`. Its pages are listed |
| Docusaurus 3 | 21 | The project's own JSX in `src/pages` and `src/components`. Docusaurus 3 builds with Rspack |

Rsbuild 2 with React and a webpack 5 config written by hand (babel-loader and webpack-dev-server) were tried too, with no count on record.

## Limits

- Only your own source is marked. In Docusaurus most of a page is the theme, which comes from `node_modules`, and the docs are MDX: neither can be selected by its code. The same goes for what's written in `public/index.html`.
- Rsbuild 2 imports Rspack as an ES module, and the hook can only answer an import on Node 22.15 or later. On an older Node the site runs and nothing is marked.
- Parcel and Nuxt 2 are not covered.
- The hook travels in `NODE_OPTIONS`, so the script has to run with a Node from your shell's PATH, and neither the script nor your shell profile may set that variable to something else.
- A project with an `index.html` at its root and no script called `dev` is taken for plain HTML, and midcode serves its files itself. Name the script `dev`, or say how the site runs: see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).
- Component mode, variants and variables were not tried on these stacks. What was tried is text, classes and styles.
- midcode's own interactive components (Carousel, Tabs and the others) are React. A Vue CLI project can't take them.
- No new pages: midcode doesn't write them in these projects, Gatsby's `src/pages` included. No free canvas: it's for Next.js projects on the App Router.
- Site settings doesn't write Gatsby's config, which is where Gatsby keeps the site's title and the rest.
- A Laravel or Rails app that builds its assets with webpack is served as Laravel or Rails: see [Laravel](https://midcode.app/docs/frameworks/laravel.md) and [Ruby on Rails](https://midcode.app/docs/frameworks/rails.md).

## Troubleshooting

**The site shows but nothing can be selected by its code.** The hook didn't reach webpack. Check your script: if it sets `NODE_OPTIONS` itself (`NODE_OPTIONS=--openssl-legacy-provider react-scripts start`), that replaces midcode's. Keep what's already there instead: `NODE_OPTIONS="$NODE_OPTIONS --openssl-legacy-provider" react-scripts start`. An `export NODE_OPTIONS=…` in your shell profile does the same and needs the same change.

**The server never answers.** midcode waits two minutes for the address the script prints, or for an answer on the port it passed. A script that listens somewhere else without printing a `localhost` address can't be found: say where it runs in [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).

**A style doesn't show.** In Gatsby and Docusaurus, check that you imported `src/midcode.css` yourself.

More in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

---

# Laravel

> How midcode runs a Laravel app, edits its Blade views on the canvas, and handles the React, Vue and Livewire starter kits, without changing a file to do it.

- Page: https://midcode.app/docs/frameworks/laravel
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a Laravel app and edits its Blade views on the canvas: text, classes, attributes, new elements and their order, written into the `.blade.php` file. Pages made with Inertia (React or Vue) and with Livewire are edited too. What PHP prints (`{{ $title }}`) is changed where the value is written, not on the canvas.

There are three layers, and they don't ship at the same time:

| Layer | What you get | Status |
| --- | --- | --- |
| The app on the canvas | A Laravel app that uses Vite, shown at its `APP_URL` when that's a `localhost` or `127.0.0.1` address: every breakpoint, Preview, comments. Nothing is editable | In 1.1.2 |
| Blade | Blade views edited on the canvas, with or without Vite | Next release |
| Starter kits | Inertia pages in React or Vue, and Livewire and Volt pages | Next release |

## At a glance

| | Laravel |
| --- | --- |
| Detected by | An `artisan` file at the top of the folder |
| Runs with | PHP's built-in server on a port midcode picks, with one file of midcode's loaded first. Vite runs beside it when the app uses Vite |
| Elements are marked by | Blade, as it compiles each view. Inertia pages by midcode's Vite plugin |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove |
| Components | `<x-…>` and Livewire components are edited in their own view. An instance isn't selectable |
| Pages | The GET routes of `routes/web.php`. A new page is a Blade view and a `Route::view` line |
| Styles | Tailwind 4 classes, or `mid:` utilities with `public/midcode.css` |
| Tried with | Laravel 13 on PHP 8.5, and the React, Vue and Livewire starter kits of Laravel 12 |

## In the version you can download today

midcode 1.1.2 opens a Laravel app whose `package.json` has Vite. It starts Vite and shows the site at the `APP_URL` of your `.env` (`http://localhost:8000` when there's none).

- If nothing answers there five seconds after Vite is up, and `APP_URL` is a plain `http` address on this Mac, midcode runs `php artisan serve` on that host and port in your shell.
- You can check every breakpoint, use the site in Preview and leave comments. Blade views can't be edited.
- A site on a host name of its own, like the `https://shop.test` that Herd or Valet give it, stays blank in 1.1.2: that version only lets `localhost` addresses into the canvas. The next release shows any host.
- A Laravel app without Vite isn't recognised in 1.1.2.
- This layer was tried with a stand-in server answering at `APP_URL`, not with Herd or Valet themselves.

Everything below is the next release.

## How midcode runs it

When it can, midcode serves the app itself instead of running `php artisan serve`. It starts PHP's built-in server, the same one `artisan serve` runs, from your app's `public/` folder:

```bash
php -d auto_prepend_file=<midcode's data folder>/injected/blade-prepend.php \
    -S 127.0.0.1:<port> server.php
```

`php` is the first one on your login shell's PATH. `server.php` is your project's own if it has one, else the one inside `vendor/laravel/framework`. The port is a free one midcode picks. Two more things are set for that process only: `VIEW_COMPILED_PATH` points at a folder in midcode's data folder, and PHP's deprecation notices aren't printed into the page (they still go to the log).

The file loaded first is what gets the marks in:

1. It loads Composer's autoloader. When Laravel first asks for its Blade compiler, it defines that class from Laravel's own source with one line added at the top of `compileString()`.
2. That line hands each view of your project (never one under `vendor/`) to a small server midcode runs on `127.0.0.1`. It answers with the same source, with a `data-mc="file:line:col"` attribute on every element. Blade compiles that.
3. The compiled views land in midcode's folder, which is emptied at every start. `storage/framework/views` isn't used, so what Herd or `artisan serve` show later has no marks in it.
4. If anything looks unfamiliar (another Blade compiler, no answer in three seconds), Blade compiles the view as it is.

The same file adds one script to the HTML it serves, so the page reloads when a `.php`, `.css` or `.js` file under `resources/` changes.

midcode adds no file to your project and changes none to do this. Your app still writes its own logs, sessions and cache to `storage/`, as it does under any server.

### With Vite

When `package.json` has Vite, midcode starts it with your own Vite config plus its plugin, on a port it picks. Laravel's Vite plugin chooses the host, as it does for you. The canvas shows midcode's PHP server once Vite is up and the site answers.

### Without Vite

Only the PHP server runs.

### When midcode can't serve it

If there's no `php` on your PATH, no `server.php`, or no `public/` folder, midcode falls back to how the app is usually served: it shows `APP_URL` if something already answers there (Herd, Valet), and otherwise runs `php artisan serve`. Those pages arrive without Blade's marks. midcode then looks each element up in your views after the page loads, the way it does for [any site a server renders](https://midcode.app/docs/frameworks/server-templates.md). That path hasn't been tried with Herd.

### What you need

- PHP on your Mac, on your shell's PATH.
- The app in a state where it runs: `composer install` done, a `.env` with its key, its database reachable. midcode doesn't run Composer or migrations on a project it opens.
- For an app with Vite, its `node_modules`. midcode offers to install them when they're missing.

## What you can edit

Click any element of a view: the right panel shows its file and line under **Code**. Double-click a text to change it.

```diff title="resources/views/welcome.blade.php"
 <section class="px-6 py-16">
-    <h1 class="text-4xl font-semibold">Fresh bread, every morning</h1>
+    <h1 class="text-5xl font-semibold">Bread, pastries and coffee</h1>
     <p class="mt-4 text-neutral-600">{{ $tagline }}</p>
```

What Blade computes is read as "not written here" and never touched:

- `{{ $x }}`, `{!! $x !!}`, `@if(…)`, `@foreach(…)`, `@csrf` and every other directive, `@php … @endphp`, `<?php ?>`. `{{-- … --}}` is a comment.
- In an attribute, the written part and the PHP part are told apart: in `class="card {{ $active ? 'on' : '' }}"` the panel changes `card` and leaves the rest.
- `:name`, `@click`, `x-…`, `wire:…` and `@class([…])` on a tag are left as they are.

An element drawn inside `@foreach` is one line of the view, shown many times: editing its classes changes all of them. A tag opened in one branch of an `@if` and closed in another can't be moved or removed from the canvas.

### Blade components

`<x-card>` and `<livewire:counter />` aren't selectable as instances, and they have no props panel. What a component draws is marked in its own view (`resources/views/components/card.blade.php`), so you edit it there by clicking it. What you write between a component's tags is marked where you wrote it.

## Starter kits

Laravel's own kits were tried, on Laravel 12.

### React and Vue, through Inertia

The pages are components in `resources/js/pages`. midcode's Vite plugin marks them as Vite builds them, exactly as in a [Vite + React](https://midcode.app/docs/frameworks/react-vite.md) or [Vue](https://midcode.app/docs/frameworks/vue.md) project, and Blade marks `resources/views/app.blade.php`. On the page that was measured, 161 of 164 elements had a mark. A text or class edit shows through Vite's hot reload, without the page loading again.

### Livewire and Volt

Livewire's views are Blade, so they're marked like any view: 162 of 162 elements on the kit's home page. The marks survive a Livewire round trip, because the Blade it sends back is already marked. On a Volt page, what isn't marked are Flux's components: they come from `vendor/`.

New project in the hub makes any of them (PHP, then Laravel, Laravel + React, Laravel + Vue or Laravel + Livewire) with `composer create-project`. See [New project](https://midcode.app/docs/start/new-project.md).

## Pages

**Pages** in the top bar lists the GET routes written out in `routes/web.php`, and in the route files it brings in with `require __DIR__.'/auth.php'`.

| Route | Page | File it opens |
| --- | --- | --- |
| `Route::view('/about', 'about')` | `/about` | `resources/views/about.blade.php` |
| `Route::get('/', fn () => view('welcome'))` | Home | `resources/views/welcome.blade.php` |
| `Route::get('/', fn () => Inertia::render('welcome'))` | Home | `resources/js/pages/welcome.tsx` (or `.jsx`, `.vue`) |
| `Volt::route('/profile', 'settings.profile')` | `/profile` | `resources/views/livewire/settings/profile.blade.php` |
| `Route::get('/posts/{post}', [PostController::class, 'show'])` | `/posts/[post]` | None: the view isn't named in the route |

A route with a parameter is a dynamic page: midcode finds its real addresses from the running site's sitemap and links ([Pages and navigation](https://midcode.app/docs/editor/pages.md)). You can always type a path such as `/pricing` in **Pages** and press `Enter`.

"New page" in that menu writes a Blade view and the route that shows it, at the end of `routes/web.php`:

```php title="resources/views/about.blade.php"
@extends('layouts.app')

@section('content')
    <main class="mx-auto max-w-3xl px-6 py-24">
      <h1 class="text-4xl font-semibold">About</h1>
      <p class="mt-4">A new page, made in midcode.</p>
    </main>
@endsection
```

```diff title="routes/web.php"
 Route::get('/', fn () => view('welcome'));
+
+Route::view('/about', 'about');
```

The view is written like the home page's: under the same `@extends` and `@section` when the home view extends a layout, otherwise as a whole document with a copy of the home view's `<head>`. `/blog/first` is `resources/views/blog/first.blade.php`, shown by `Route::view('/blog/first', 'blog.first')`. The class names are written when Tailwind is in your `package.json`. A new page is a Blade view in an Inertia app too.

"Remove" moves a page's view to the Trash and takes its `Route::view` line out with it. Making a page, seeing it on the canvas and removing it were tried on a Laravel app.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). In a Laravel app the title, the description, the language, search engines, the favicon and the social image are tags in the `<head>` of a view: the first one that closes a `<head>`, in alphabetical order of its path. Images are copied into `public/`.

What Blade computes there is shown as code and isn't written: a `<title>{{ config('app.name', 'Laravel') }}</title>` shows in the form as that code, and stays your code's to set. There's one form for the whole app. Tried on a Laravel app.

## Styles

- **Tailwind 4** (what Laravel sets up through Vite): midcode writes Tailwind's classes and Vite compiles them. See [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).
- **No Tailwind, no Vite**: midcode writes `mid:` utilities, keeps their CSS in `public/midcode.css`, and adds `<link rel="stylesheet" href="/midcode.css">` before `</head>` in every layout view. See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md).
- **Vite without Tailwind 4**: midcode writes `midcode.css` at the top of the project and says it couldn't tell where to import it. Import it from `resources/js/app.js`.

## Limits

- Text that PHP prints is edited where the value is written: the controller, a language file, the database. midcode's own search for a text reads `.json`, `.js`, `.ts` and `.md` files, never `.php` or `.blade.php`.
- Views that come from `vendor/` (a package's, Flux's) are never marked.
- Elements move inside one view. Moving one from a partial into the view that includes it is done in the code.
- Routes inside a group with a prefix are listed without the prefix, and `Route::resource` isn't read.
- The canvas shows the app at `http://127.0.0.1:<port>`, not at its `APP_URL`. Anything tied to the host name (a session domain, an OAuth callback) behaves as it would at that address.
- Not tried: Herd, Valet, Sail, Inertia with Svelte.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.
- "Remove" only knows the `Route::view` line midcode writes. For a page whose route is written another way (`Route::get` with a closure or a controller), the view goes to the Trash and the route stays: take that line out yourself.
- With several views that close a `<head>` (a layout for the site and one for sign-in pages), Site settings writes the first by path, which may not be the one your pages use. The note under the form's images names the file it writes.
- A MySQL or MariaDB database can't be opened yet. midcode's [Database](https://midcode.app/docs/data/database.md) finds the connection from the `DB_*` values of `.env`, and opens Postgres and SQLite.

## Troubleshooting

**"Vite is running, but the site isn't answering at … (APP_URL in .env)."** midcode's PHP server didn't come up and nothing else serves the app. Run `php -v` in a terminal: if it isn't found, PHP isn't on your PATH. If it is, open the **Dev server log** in the top bar to read what PHP said.

**Some elements of a Blade view have no file and line.** midcode is probably showing the app from another server and finding elements after the page loads, which finds fewer. When midcode serves the app itself, the log has a line starting with `$ php -S 127.0.0.1:`. If it's missing, check that `php` is on your PATH.

**A Laravel error page.** That's your app answering: a missing `.env`, no `APP_KEY`, a database that isn't running. Fix it as you would in a browser, then press **Reload breakpoints**.

**To serve it your own way**, use **Change how it runs** on the error card: a command, an address, or both ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)). Your command then replaces midcode's start altogether: Vite isn't started for you.

---

# WordPress

> How midcode runs a WordPress site from its root or from a theme's folder, what it can edit in a classic theme, and why a block theme is mostly out of reach.

- Page: https://midcode.app/docs/frameworks/wordpress
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a WordPress site and edits the markup written in its theme: the header, the footer, the templates and their parts. A classic theme is mostly editable. A block theme mostly isn't, because its pages are drawn by blocks and kept in the database, not written in files. Post and page content is never editable from the canvas: it lives in the database.

WordPress pages reach the canvas without saying where each element is written, so midcode finds each one in the theme's files after the page loads. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains how, and what that means for editing.

## At a glance

| | WordPress |
| --- | --- |
| Detected by | `wp-load.php` at the top of the folder, or a theme's `style.css` inside `wp-content/themes/<theme>` |
| Runs with | `php -S 127.0.0.1:$PORT`, with one file of midcode's loaded first |
| Elements are marked by | midcode, after each page loads, by matching it against the theme's `.php` files |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove. Only what the theme writes as HTML |
| Pages | Not listed. Type the path |
| Styles | Tailwind 4 classes, or `mid:` utilities with `midcode.css` in the theme's folder, linked from `header.php` |
| Tried with | WordPress 7.1 on SQLite: a classic theme (21 of 23 elements found) and Twenty Twenty-Five (6 of 94) |

## How midcode runs it

You can open either of two folders.

**The whole install**: the folder with `wp-load.php` and `wp-config.php` or `wp-includes/`. midcode runs this in it:

```bash
php -d auto_prepend_file=<midcode's data folder>/injected/wordpress-prepend.php -S 127.0.0.1:$PORT
```

**A theme's folder**: usually the theme is the repository and WordPress is around it. midcode recognises a folder whose `style.css` starts with a `Theme Name:` header and that sits three levels inside an install (`wp-content/themes/<theme>`). It serves that install with the same command plus `-t <path to the install>`.

`$PORT` is a free port midcode picks. The command runs in your login shell, so `php` is the one your terminal would use. What it prints is in the **Dev server log** in the top bar.

### The site's address

WordPress keeps its own address in its database and sends every request there. Served on a new port, it would redirect to a site that isn't running.

The file loaded first fixes that for this one process. It's a few lines of PHP in midcode's data folder that define `WP_HOME` and `WP_SITEURL` as the address the request came to, which WordPress takes over what the database says:

```php title="wordpress-prepend.php (in midcode's data folder)"
if (PHP_SAPI === 'cli-server' && !empty($_SERVER['HTTP_HOST'])) {
    if (!defined('WP_HOME')) {
        define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);
    }
    if (!defined('WP_SITEURL')) {
        define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
    }
}
```

Nothing in your `wp-config.php`, your theme or your database changes, and the site answers as before everywhere else.

### A site that already runs

If `wp-config.php` sets `WP_HOME` to an address, as some local setups do, midcode asks that address first. When it answers, the log says "Already running at …: midcode shows it." and nothing is started.

### What you need

- PHP on your Mac, on your shell's PATH.
- A working install: `wp-config.php` in place and its database running. midcode starts PHP, not MySQL.

## What you can edit

In a classic theme, what's written as HTML in the theme's files can be edited where it's written:

```php title="template-parts/content.php"
<article id="post-<?php the_ID(); ?>" <?php post_class( 'entry' ); ?>>
	<h2 class="entry-title"><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
	<div class="entry-content"><?php the_content(); ?></div>
	<p class="entry-more">Keep reading</p>
</article>
```

- The `<article>`, the `<h2>`, the link, the `<div>` and the `<p>` are written here, so midcode can find them and change their classes, attributes and tag. The file is one post of the loop: a change shows on every post.
- "Keep reading" is written in the file, so a double-click edits it.
- The title is `the_title()`: it isn't in the file. Neither is the HTML that `the_content()` prints inside the `<div>`.

A text and a style change in the footer:

```diff title="footer.php"
-	<p class="site-info">Made with care in Rosario</p>
+	<p class="site-info mid:text-[14px]">Made with care in Buenos Aires</p>
```

On the classic theme that was tried (a header, a footer, an index, template parts and the loop), 21 of the 23 elements of the page were found. The two that weren't are the posts' content.

When you open the whole install, only the themes the page is drawn with count: midcode reads their names from the `wp-theme-…` and `wp-child-theme-…` classes of `<body>` and from where the page's assets come from. Other installed themes are ignored, and `wp-admin` and `wp-includes` are never read.

### Block themes

A block theme's templates are block markup, and most of what you see is drawn by dynamic blocks that have no HTML in the theme. What the Site Editor changes is saved in the database. With Twenty Twenty-Five, 6 of the page's 94 elements were found. For a block theme, midcode is a way to see every breakpoint and leave comments, not to edit.

## Pages

midcode doesn't read WordPress's pages: **Pages** in the top bar shows the home page. To open another one, type its path there (for example `/sample-page`) and press `Enter`.

## Styles

Unless the theme has Tailwind 4, midcode writes its own `mid:` utilities and keeps their CSS in `midcode.css` ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)).

Opened from the theme's folder, `midcode.css` goes in that folder and the theme's `header.php` gets one line, on your first style edit:

```diff title="header.php"
 	<?php wp_head(); ?>
+	<link rel="stylesheet" href="<?php echo esc_url( get_theme_file_uri( 'midcode.css' ) ); ?>">
 </head>
```

The file ships with the theme, like any of its assets.

Opened from the whole install, or with a block theme (which has no `header.php`), midcode can't tell where the link goes. It writes `midcode.css` at the top of the folder, says it couldn't tell where to import it, and leaves the link to you. To style a classic theme, open the theme's folder.

## Limits

- Text printed by PHP isn't editable on the canvas. That includes strings passed through translation functions, like `<?php esc_html_e( 'Read more', 'mytheme' ); ?>`: edit those in the file.
- Menus, widgets, the post content, anything set in the Customizer or the Site Editor: they come from the database.
- What a plugin draws is the plugin's. Opened from the whole install, a plugin's files are read like any other file of the folder, so an element may point into `wp-content/plugins`. An edit there is lost when the plugin updates.
- A theme opened on its own, outside an install, isn't recognised as WordPress.
- The install that was tried keeps its database in SQLite. One on MySQL wasn't tried, and neither were child themes or multisite.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.
- midcode doesn't add pages to a WordPress site, and [Site settings](https://midcode.app/docs/editor/site-settings.md) isn't offered: WordPress keeps its title, description and icon in its database and prints them with `wp_head()`.

## Troubleshooting

**The canvas jumps to another address, or stays blank.** `wp-config.php` fixes `WP_HOME` and nothing answers there, so WordPress redirects to a site that's down. Start it (Local, MAMP, Herd) and press **Restart** in the dev server log, or remove the constant.

**"Error establishing a database connection".** WordPress is answering, its database isn't. Start it.

**"php" isn't installed on this Mac.** midcode runs the `php` your shell finds. Install it, or point midcode at a site that already runs with **Change how it runs** on the error card ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).

**A theme you opened by itself doesn't run.** Open it from inside the install, at `wp-content/themes/<theme>`. A theme folder that isn't inside a WordPress isn't recognised as one.

---

# PHP and Twig

> How midcode runs a PHP site with PHP's built-in server and edits the HTML written in its .php and .twig templates, leaving what PHP prints alone.

- Page: https://midcode.app/docs/frameworks/php
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a PHP site that isn't Laravel or WordPress (plain PHP pages, or a framework with a front controller and Twig templates) and edits the HTML written in its templates: text, classes, attributes, new elements and their order. What PHP or Twig prints (`<?= $title ?>`, `{{ title }}`) is edited where the value is written, not on the canvas.

PHP renders the page, so midcode finds each element in your template files after the page loads. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains how. [Laravel](https://midcode.app/docs/frameworks/laravel.md) and [WordPress](https://midcode.app/docs/frameworks/wordpress.md) have their own pages.

## At a glance

| | PHP and Twig |
| --- | --- |
| Detected by | `index.php` at the top of the folder, or in `public/`, `web/` or `webroot/` |
| Runs with | `php -S 127.0.0.1:$PORT`, with `-t <folder>` when `index.php` is in one of those folders |
| Elements are marked by | midcode, after each page loads, by matching it against the project's `.php`, `.phtml` and `.twig` files |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove |
| Pages | Not listed. Type the path |
| Styles | Tailwind 4 classes, or `mid:` utilities with `midcode.css` next to `index.php` |
| Tried with | Plain PHP with includes and a loop, and PHP with Twig. Every element written in the templates was found |

## How midcode runs it

midcode looks for `index.php` and starts PHP's built-in server where it is:

| Where `index.php` is | Command |
| --- | --- |
| The top of the folder | `php -S 127.0.0.1:$PORT` |
| `public/` | `php -S 127.0.0.1:$PORT -t public` |
| `web/` | `php -S 127.0.0.1:$PORT -t web` |
| `webroot/` | `php -S 127.0.0.1:$PORT -t webroot` |

`$PORT` is a free port midcode picks. The command runs in your login shell, in the project's folder, so `php` is the one your terminal would use. Its output is in the **Dev server log** in the top bar.

`public/`, `web/` and `webroot/` are where frameworks like Symfony, Slim, CodeIgniter, Craft, Drupal and CakePHP keep their front controller. midcode recognises them by that folder only. None of those frameworks was tried.

A folder is checked for Laravel (`artisan`) and WordPress (`wp-load.php`) first. Nothing in your project is changed to run it, and nothing is installed.

You need PHP on your Mac, on your shell's PATH, and whatever the site itself needs to answer: its Composer packages installed, its database running.

## What you can edit

Anything written as HTML in a `.php`, `.phtml` or `.twig` file. Code between `<?php` and `?>` (and `<?= ?>`) is never touched. In Twig, neither are `{{ }}` and `{% %}`; `{# #}` is a comment.

```php title="index.php"
<?php include 'partials/header.php'; ?>
<main class="page">
  <h1>Our menu</h1>
  <ul class="menu">
    <?php foreach ($dishes as $dish): ?>
      <li class="dish"><?= htmlspecialchars($dish['name']) ?></li>
    <?php endforeach; ?>
  </ul>
</main>
<?php include 'partials/footer.php'; ?>
```

- "Our menu" is written in the file: double-click it on the canvas to change it.
- The `<li>` is one line shown once per dish. Its classes can be edited, and the change applies to every dish. Its text is PHP's.
- What `partials/header.php` writes is edited in that file. Click an element of the header and the right panel shows `partials/header.php` and the line under **Code**.

Changing the heading and giving the list more room, in a site without Tailwind:

```diff title="index.php"
-  <h1>Our menu</h1>
-  <ul class="menu">
+  <h1>Today's menu</h1>
+  <ul class="menu mid:p-6">
```

In an attribute, the written part and the computed part are told apart. Here the panel can add a class next to `button` and can't change the `href`:

```html title="templates/home.html.twig"
<a class="button" href="{{ path('menu') }}">See the menu</a>
```

After each edit midcode reloads the page in every breakpoint: PHP has no live reload of its own. A change you make in your editor shows when you press **Reload breakpoints**.

## Pages

midcode doesn't read a PHP site's routes. **Pages** in the top bar shows the home page; type a path there (for example `/about.php`) and press `Enter` to open another one. It doesn't add pages either: a new one is a file, or a route, that you or your agent write.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of your site: the first file that closes a `<head>`, in alphabetical order of its path (a header partial, usually). Images are copied to the folder PHP serves, next to `index.php`.

What PHP or Twig prints there (`<title><?= $title ?></title>`) shows as code and isn't written. This wasn't tried on a PHP site.

## Styles

With Tailwind 4 in the project, midcode writes Tailwind's classes. It starts only the PHP server: if a separate command compiles your CSS, keep it running yourself.

Without Tailwind, midcode writes `mid:` utilities and keeps their CSS in `midcode.css`, in the folder PHP serves (next to `index.php`). On your first style edit it adds one line to every file that closes a `<head>`:

```diff title="partials/header.php"
   <link rel="stylesheet" href="/css/site.css">
+  <link rel="stylesheet" href="/midcode.css">
 </head>
```

See [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) for what's in that file.

## Limits

- `.htaccess` rules don't apply: PHP's built-in server doesn't read them. If your site depends on them, serve it your usual way and give midcode its address ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).
- Text that PHP or Twig prints is edited where the value is written. midcode's own search for a text reads `.json`, `.js`, `.ts` and `.md` files, never `.php` or `.twig`.
- HTML built inside a PHP string (`echo '<div class="card">'`) isn't written as a tag in a template, so it isn't found.
- A tag opened in one branch of an `if` and closed in another can't be moved or removed from the canvas.
- Templates inside `vendor/` are never read.
- If the project's `package.json` lists Vite, midcode opens it as a Vite project and starts Vite, not PHP. Laravel is the only PHP stack where it runs both. You can still see such a site by giving midcode its command or address in `.midcode/server.json`, but its templates aren't matched.
- Smarty (`.tpl`) and Latte (`.latte`) files aren't read. Blade outside Laravel wasn't tried.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.

## Troubleshooting

**"php" isn't installed on this Mac (or not on your shell's PATH).** midcode runs the `php` your login shell finds. Install it, then press **Restart** in the dev server log.

**Links that work on your own server don't work here.** The site expects rewrite rules. See the first limit above.

**The site needs another command.** Use **Change how it runs** on the error card to set the command and the address. `$PORT` in the command is the port midcode picked. It's saved in `.midcode/server.json`:

```json title=".midcode/server.json"
{
  "command": "php -S 127.0.0.1:$PORT -t public router.php",
  "url": "http://127.0.0.1:$PORT"
}
```

---

# Django, Flask and FastAPI

> How midcode starts a Django, Flask or FastAPI site with the project's own Python, edits its templates on the canvas, and where pages and styles come from.

- Page: https://midcode.app/docs/frameworks/python
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a Django, Flask or FastAPI project, starts it with the project's own Python, and edits the HTML written in its templates: text, classes, attributes, new elements and their order. What the template language works out (`{{ post.title }}`, `{% for %}`, a form Django renders) is left to your code.

Python renders the page, so midcode finds each element in your templates after the page loads. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains how that works and what it means for editing.

## At a glance

| | Django, Flask and FastAPI |
| --- | --- |
| Detected by | `manage.py` (Django); a `Flask(…)` or `FastAPI(…)` app in a project that depends on that package |
| Runs with | `manage.py runserver`, `flask run --debug` or `uvicorn --reload`, with the project's own Python |
| Elements are marked by | midcode, after each page loads, by matching it against the project's templates |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove |
| Pages | Django's `urls.py`, Flask's `@app.route`. FastAPI: type the path |
| Styles | Tailwind 4 classes, or `mid:` utilities with `midcode.css` in the static folder (Django, Flask) |
| Tried with | Django with its `.venv`, Flask, and FastAPI with Jinja. Every element written in the templates was found |

## How midcode runs it

| Stack | Recognised by | Command |
| --- | --- | --- |
| Django | `manage.py` at the top of the folder | `<python> manage.py runserver 127.0.0.1:$PORT` |
| Flask | The project depends on `flask`, and a file makes the app: `app = Flask(__name__)` | `<python> -m flask --app <module> run --debug --host 127.0.0.1 --port $PORT` |
| FastAPI | The project depends on `fastapi`, and a file makes the app: `app = FastAPI()` | `<python> -m uvicorn <module>:<name> --reload --host 127.0.0.1 --port $PORT` |

`$PORT` is a free port midcode picks. The command runs in your login shell, in the project's folder, and what it prints is in the **Dev server log** in the top bar. Nothing in the project is changed to run it.

"Depends on" means the package is named in `requirements.txt`, `requirements/base.txt`, `requirements/dev.txt`, `pyproject.toml`, `Pipfile` or `setup.py`. For Flask, an `app.py` that imports it is enough.

The app is looked for in the `.py` files at the top of the project (`app.py`, `main.py`, `wsgi.py`, `asgi.py`, `application.py`, `run.py` and `server.py` first) and one folder in (`<folder>/__init__.py`, `app.py`, `main.py`). For Flask, a `create_app()` or `make_app()` factory counts too. For FastAPI the app has to be assigned to a name.

`--debug` makes Flask read your templates and code again when they change. `--reload` restarts Uvicorn when your code changes.

### Which Python

midcode uses the first of these it finds:

1. The project's virtual environment: `.venv/bin/python`, `venv/bin/python` or `env/bin/python`.
2. `uv run python`, when there's a `uv.lock`.
3. `poetry run python`, when there's a `poetry.lock`.
4. `pipenv run python`, when there's a `Pipfile`.
5. `python3` from your shell.

So a Django project with a `.venv` runs as `.venv/bin/python manage.py runserver 127.0.0.1:$PORT`.

### What you need

Python and the project's packages installed, and the site in a state where it runs (its database migrated, its settings in place). midcode doesn't run `pip install` or `migrate` on a project it opens.

[New project](https://midcode.app/docs/start/new-project.md) makes a Django or a Flask site with its own `.venv`, a `templates/` and a `static/` folder.

## What you can edit

Anything written as HTML in a template. In Django's and Jinja's templates, `{{ }}` and `{% %}` are never touched, and `{# #}` is a comment.

```html title="templates/home.html"
{% extends "base.html" %}
{% block content %}
<section class="hero">
  <h1>Fresh bread, every morning</h1>
  {% include "partials/hours.html" %}
  {% for loaf in loaves %}
  <article class="loaf"><h2>{{ loaf.name }}</h2></article>
  {% endfor %}
</section>
{% endblock %}
```

- The heading is written here: double-click it on the canvas to change it.
- What `base.html` and `partials/hours.html` write is edited in those files. The right panel shows which file and line an element comes from, under **Code**.
- The `<article>` is one line shown once per loaf: a class you add applies to all of them. The loaf's name is the template's to print.

```diff title="templates/home.html"
-<section class="hero">
-  <h1>Fresh bread, every morning</h1>
+<section class="hero mid:p-6">
+  <h1>Bread, pastries and coffee</h1>
```

After an edit midcode reloads the page in every breakpoint.

## Pages

**Pages** in the top bar is filled from your routes, read as text (nothing is run):

- **Django**: the `ROOT_URLCONF` of the settings module that `manage.py` names. Every `path("about/", …)` is a page. `include("blog.urls")` is followed, under its prefix, up to three levels. The admin and Django's own includes are left out. `<int:id>` makes a dynamic page, shown as `[id]`.
- **Flask**: every `@app.route("/about")` or `@bp.route(…)` in the project's `.py` files, up to three folders deep. A route that only takes `POST` isn't a page. `<name>` and `<int:id>` are dynamic.
- **FastAPI**: not read. Type a path in **Pages** and press `Enter`.

Where it can, midcode also knows the template behind a page: `TemplateView.as_view(template_name="home.html")` or the `render(request, "home.html")` of the view a Django route names, and the `render_template("home.html")` of a Flask view. Templates are looked for in `templates/` and in `<app>/templates/`.

A dynamic page finds its real addresses from the running site's sitemap and links ([Pages and navigation](https://midcode.app/docs/editor/pages.md)).

midcode doesn't add pages here: in Django, Flask and FastAPI a page is a route and a view written in Python, yours or your agent's to write.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of a template: the first one that closes a `<head>`, in alphabetical order of its path (often `templates/base.html`).

What the template computes there (`<title>{% block title %}Bakery{% endblock %}</title>`) shows as code and isn't written. Images are copied to the same folder as `midcode.css` (the table below). In a FastAPI project, or a Django one without `STATICFILES_DIRS`, midcode has no such folder (unless the project has a `public/` one) and asks you to put the image where the site serves it and link it in the code. This wasn't tried on a Django, Flask or FastAPI site.

## Styles

With Tailwind 4 in the project, midcode writes Tailwind's classes. It starts only the web server: if a separate command compiles your CSS, keep it running yourself.

Without Tailwind, midcode writes `mid:` utilities and keeps their CSS in `midcode.css` ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)). Where the file goes depends on the stack:

| Stack | `midcode.css` goes in | Linked as |
| --- | --- | --- |
| Flask | `static/` beside the app, or `<package>/static/` when the app is a package | `/static/midcode.css` |
| Django | The folder that `STATICFILES_DIRS` names in the settings file | Under `STATIC_URL`, for example `/static/midcode.css` |
| FastAPI | The top of the project, or `src/` when there is one | Not linked: add the `<link>` yourself |

On your first style edit, every template that closes a `<head>` gets the link, as one undoable step:

```diff title="templates/base.html"
     <link rel="stylesheet" href="{% static 'style.css' %}">
+    <link rel="stylesheet" href="/static/midcode.css">
   </head>
```

The link is a plain path, not `{% static %}`. If your production site serves static files from another address, change that line to `{% static 'midcode.css' %}`.

In Django, midcode reads `STATICFILES_DIRS` and `STATIC_URL` from the settings file that `manage.py` names. If that file doesn't set `STATICFILES_DIRS`, or the folder doesn't exist, midcode writes `midcode.css` at the top of the project and says it couldn't tell where to import it.

## Limits

- Text the template prints, including `{% translate "…" %}`, isn't editable on the canvas.
- HTML that Python builds (`{{ form.as_p }}`, a widget, the Django admin) isn't written in your templates, so it isn't found.
- Templates inside the virtual environment are never read.
- Django's `re_path()` and routes built in code aren't listed. A Flask blueprint's `url_prefix` isn't added to its routes.
- If the project's `package.json` lists Vite or another framework midcode knows, the folder opens as that kind of project and its templates aren't matched.
- A virtual environment is the path that was tried. `uv`, Poetry and Pipenv are chosen by their lockfile and weren't tried. Neither were settings split across several files.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.

## Troubleshooting

**"No module named django" (or flask, uvicorn) in the log.** midcode picked a Python that doesn't have the project's packages. Put the environment in `.venv` at the top of the project, or set the command yourself.

**midcode asks "How does this site run?".** It didn't find where the Flask or FastAPI app is made, for example because it's deeper than one folder in. Type the command and the address. `$PORT` is the port midcode picked. They're saved in `.midcode/server.json`:

```json title=".midcode/server.json"
{
  "command": "uv run uvicorn src.shop.main:app --reload --host 127.0.0.1 --port $PORT",
  "url": "http://127.0.0.1:$PORT"
}
```

**A Django error page about the database.** The site is running and needs its migrations. Run them in a terminal, then press **Reload breakpoints**.

**The site runs in Docker.** Leave the command empty and give midcode the address where it answers. The templates on your Mac are matched the same way ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).

---

# Ruby on Rails

> How midcode starts a Rails app, edits the HTML written in its ERB views on the canvas, reads its routes as pages, and what helpers like link_to leave out of reach.

- Page: https://midcode.app/docs/frameworks/rails
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a Rails app, starts its server, and edits the HTML written in its ERB views, layouts and partials: text, classes, attributes, new elements and their order. What ERB works out (`<%= post.title %>`) and the tags that helpers build (`link_to`, `image_tag`, `form_with`) aren't editable on the canvas.

Rails renders the page, so midcode finds each element in your views after the page loads. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains how that works and what it means for editing.

## At a glance

| | Ruby on Rails |
| --- | --- |
| Detected by | `bin/rails` or `config/application.rb` |
| Runs with | `bin/rails server -b 127.0.0.1 -p $PORT` |
| Elements are marked by | midcode, after each page loads, by matching it against the app's `.erb` files |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove |
| Components | A partial is edited in its own file |
| Pages | `config/routes.rb`: `root`, `get` and `resources` |
| Styles | Tailwind 4 classes, or `mid:` utilities with `public/midcode.css` |
| Tried with | Rails 8: 15 of 16 elements found on a page with a layout, a view, a partial in a loop and an `if` / `else` |

## How midcode runs it

When the folder has `bin/rails` or `config/application.rb`, midcode runs this in your login shell, in the project's folder:

```bash
bin/rails server -b 127.0.0.1 -p $PORT
```

`$PORT` is a free port midcode picks. The command finds Ruby the way your terminal does, so a version manager set up in your shell applies. What Rails prints is in the **Dev server log** in the top bar. Nothing in the app is changed to run it.

You need Ruby, the app's gems installed (`bundle install`) and its database prepared. midcode doesn't run either on a project it opens.

midcode runs the server, not `bin/dev`. If your app counts on `Procfile.dev` to build its CSS or JavaScript, run those watchers in a terminal, or set the command yourself with **Change how it runs** (below).

## What you can edit

Anything written as HTML in an `.erb` file. Code between `<%` and `%>` is never touched.

```erb title="app/views/posts/index.html.erb"
<section class="posts">
  <h1>Latest posts</h1>
  <% @posts.each do |post| %>
    <article class="post <%= 'featured' if post.featured? %>">
      <h2><%= post.title %></h2>
      <%= link_to "Read more", post, class: "more" %>
    </article>
  <% end %>
</section>
```

- "Latest posts" is written here: double-click it on the canvas.
- The `<article>` is one line shown once per post. The panel changes `post` and what you add next to it, and leaves the ERB inside the attribute alone. A change applies to every post.
- The `<h2>` is found. Its text is `post.title`, which isn't in the file.
- The link has no mark: `link_to` builds the `<a>`, and no file writes that tag. On the page that was tried, the one element of 16 that wasn't found was a `link_to`.

To make that link editable, write the tag yourself. Its class and its words can then be changed on the canvas, and the address stays computed:

```diff title="app/views/posts/index.html.erb"
-      <%= link_to "Read more", post, class: "more" %>
+      <a class="more" href="<%= post_path(post) %>">Read more</a>
```

A partial rendered in a loop (`_post.html.erb`) works like the `<article>` above: every copy on the page points at the same line of the partial.

Pages that Turbo swaps in without a full load are matched again as they arrive.

After an edit midcode reloads the page in every breakpoint.

## Pages

**Pages** in the top bar is filled from `config/routes.rb`, read as text:

| In `routes.rb` | Page | View it opens |
| --- | --- | --- |
| `root "pages#home"` | Home | `app/views/pages/home.html.erb` |
| `get "about", to: "pages#about"` | `/about` | `app/views/pages/about.html.erb` |
| `get "posts/:id", to: "posts#show"` | `/posts/[id]` | `app/views/posts/show.html.erb` |
| `resources :posts` | `/posts` and `/posts/[id]` | `app/views/posts/index.html.erb` and `show.html.erb` |

`only:` on a `resources` line is respected. A dynamic page finds its real addresses from the running site's sitemap and links ([Pages and navigation](https://midcode.app/docs/editor/pages.md)). For any page that isn't listed, type its path in **Pages** and press `Enter`.

midcode doesn't add pages to a Rails app: a page is a route, a controller action and a view, yours or your agent's to write.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of a layout: the first template that closes a `<head>`, in alphabetical order of its path, which is `app/views/layouts/application.html.erb` in a new app. Images are copied into `public/`.

What ERB computes there (`<title><%= content_for(:title) || "Bakery" %></title>`) shows as code and isn't written. This wasn't tried on a Rails app.

## Styles

With Tailwind 4 in the app, midcode writes Tailwind's classes ([Tailwind CSS](https://midcode.app/docs/styling/tailwind.md)). Something has to compile them: see the note about `bin/dev` above.

Without it, midcode writes `mid:` utilities and keeps their CSS in `public/midcode.css`, which Rails serves as it is. On your first style edit, each layout that closes a `<head>` gets one line:

```diff title="app/views/layouts/application.html.erb"
     <%= stylesheet_link_tag "application" %>
+    <link rel="stylesheet" href="/midcode.css">
   </head>
```

It's one undoable step. [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) explains what's in the file.

## Limits

- What helpers build isn't written as HTML, so it has no mark: `link_to`, `image_tag`, `button_to`, `form_with` and its fields, `content_tag`.
- Haml and Slim views aren't read. Their pages are listed, and nothing in them can be edited.
- Routes inside a `namespace` or a `scope` are listed without its prefix. Routes made by an engine or in a loop aren't listed.
- `public/` is never searched for templates: its error pages have a `<body>` of their own.
- If the app's `package.json` lists Vite (Vite Ruby), midcode opens the folder as a Vite project and its views aren't matched.
- A table change made in midcode's Database isn't run on a Rails app: midcode hands your agent the steps for a Rails migration ([Changing tables](https://midcode.app/docs/data/schema.md)).
- The Rails that was tried ran with a Ruby that isn't on the PATH, so its command was set in `.midcode/server.json`. The automatic start runs the same command.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.

## Troubleshooting

**The server didn't start, and the log says `ruby` or `bundle` wasn't found.** Your login shell doesn't have the Ruby the app needs. Use **Change how it runs** on the error card and put it in the command. It's saved in `.midcode/server.json`:

```json title=".midcode/server.json"
{
  "command": "PATH=\"/opt/homebrew/opt/ruby/bin:$PATH\" bin/rails server -b 127.0.0.1 -p $PORT",
  "url": "http://127.0.0.1:$PORT"
}
```

**"A server is already running".** That's Rails: it keeps one `tmp/pids/server.pid` per app, so a server you started in a terminal blocks midcode's. Stop the other one, or give midcode's its own pid file by adding `-P tmp/pids/midcode.pid` to the command.

**Classes you add from the panel have no effect.** The app uses Tailwind and nothing is compiling it. Start your CSS watcher, or use a command that starts everything: midcode also sets `PORT` in the command's environment.

**A Rails error page.** The app is running and something in it failed: pending migrations, a missing credential. Fix it as you would in a browser, then press **Reload breakpoints**.

---

# Hugo, Jekyll and Eleventy

> How midcode runs a Hugo, Jekyll or Eleventy site, edits its layouts and the words of its Markdown content on the canvas, and where pages and styles come from.

- Page: https://midcode.app/docs/frameworks/static-generators
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a Hugo, Jekyll or Eleventy site, starts the generator's own server, and edits two things on the canvas: the HTML written in your layouts and includes, and the words of your Markdown content. What the template language works out (`{{ .Title }}`, `{% for post in site.posts %}`) is left to your code.

The generator builds the page, so midcode finds each element in your files after the page loads. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains how that works and what it means for editing.

## At a glance

| | Hugo, Jekyll and Eleventy |
| --- | --- |
| Detected by | Hugo and Jekyll by their config file. Eleventy by its config file and a script in `package.json` |
| Runs with | `hugo server`, `jekyll serve`, or the Eleventy site's own `dev` script |
| Elements are marked by | midcode, after each page loads, by matching it against the layouts, includes and Markdown files |
| Editing | In templates: text, classes, attributes and tag; insert, move, duplicate and remove. In Markdown: the words, and a heading's level |
| Pages | The files of `content/` (Hugo), the files with front matter (Jekyll), the templates (Eleventy). New pages and removing them |
| Styles | Tailwind 4 classes, or `mid:` utilities with `midcode.css` in the folder the generator copies as it is |
| Tried with | Hugo (a base layout, a partial, a `range`), Eleventy (a Nunjucks layout) and Jekyll 4 (a layout, an include, a loop of posts: 17 of 17 elements found) |

## How midcode runs it

| Generator | Recognised by | Command |
| --- | --- | --- |
| Hugo | `hugo.toml`, `hugo.yaml`, `hugo.yml` or `hugo.json`. Or `config.toml` / `config.yaml` beside `content/` and `layouts/` or `themes/` | `hugo server --bind 127.0.0.1 --port $PORT` |
| Jekyll | `_config.yml` or `_config.toml` | `bundle exec jekyll serve --host 127.0.0.1 --port $PORT`. Without a `Gemfile`, the same without `bundle exec` |
| Eleventy | `eleventy.config.js` (or `.mjs`, `.cjs`, `.eleventy.js`) and a `dev` script in `package.json` | `npm run dev` (or `pnpm`, `yarn`, `bun`: the one the project uses) |

`$PORT` is a free port midcode picks. Commands run in your login shell, in the project's folder, and what they print is in the **Dev server log** in the top bar. Nothing in the project is changed to run it.

Eleventy is a Node project, so it starts like any project with a dev script: midcode runs the script and reads the address from what Eleventy prints. If there's no `dev` script, it uses `start` or `serve`. When the script is only a call to `eleventy` (`eleventy --serve`) and names no port, midcode adds `--port` with its own, so the site doesn't land on Eleventy's usual 8080, which may be a server of yours: `npm run dev -- --port 4310`.

You need the generator itself: `hugo` on your PATH, Ruby with Jekyll (and Bundler, for a site with a `Gemfile`), or the site's `node_modules` for Eleventy. midcode offers to install `node_modules` when they're missing; it doesn't install Hugo or gems.

[New project](https://midcode.app/docs/start/new-project.md) makes an Eleventy or a Hugo site.

## What you can edit

### Layouts and includes

Anything written as HTML in a template: Hugo's `layouts/`, Jekyll's `_layouts/` and `_includes/`, Eleventy's `_includes/` and pages. `{{ }}` and `{% %}` are never touched.

```html title="layouts/index.html"
{{ define "main" }}
<main class="hero">
  <h1>Fresh bread, every morning</h1>
  <p class="lead">{{ .Site.Params.tagline }}</p>
  {{ range .Site.RegularPages }}
  <a class="post" href="{{ .RelPermalink }}">{{ .Title }}</a>
  {{ end }}
</main>
{{ end }}
```

- The heading is written here: double-click it on the canvas.
- The paragraph's classes can be edited. Its text comes from the site's config.
- The link is one line shown once per page of the `range`. A class you add applies to all of them.
- What `baseof.html` or a partial writes is edited in that file. The right panel shows the file and line under **Code**.

```diff title="layouts/index.html"
-<main class="hero">
-  <h1>Fresh bread, every morning</h1>
+<main class="hero mid:p-6">
+  <h1>Bread, pastries and coffee</h1>
```

### Markdown content

On these sites, a page's content is a Markdown file. midcode finds each heading, paragraph and one-line list item of the page in your `.md` files by its words, and lets you change them:

```diff title="content/posts/sourdough.md"
 ---
 title: "Sourdough, day by day"
 ---
-## What you'll need
+## What you need
 
-Flour, water, salt and a week of patience.
+Flour, water, salt and one week.
```

- **Words**: double-click a heading, a paragraph or a list item. What Markdown would read as its own (asterisks, underscores, backticks, square brackets, a `#` at the start of a line) is escaped when it's written. A paragraph written over several lines is written back as one.
- **Level**: change the **Tag** under Typography in the right panel to make an `##` an `###`, or a heading a paragraph.
- **Remove** it with `⌫`.

That's all Markdown takes. It has no tag to hang a class or an attribute on, so a style edit is refused: "This is written in Markdown: its words can be changed here, not its classes or attributes. Style it from the template around it." Moving and inserting are refused the same way.

What is and isn't found:

- A block has to be only words. A paragraph with emphasis, a link, code, an image or a shortcode in it gets no mark.
- Front matter, code blocks, tables, quotes and raw HTML are skipped. So are list items that run over several lines and task-list items.
- Generators curl quotes and join dashes. midcode compares the words without that, so `"day by day"` in the file matches the curled quotes on the page.
- When two files write the same words (a subtitle every post has), the file where most of the page's words were found wins.
- `README.md`, `CHANGELOG.md`, `LICENSE.md` and the like are never read as content.

A post's title usually comes from its front matter (`{{ .Title }}`), not from a heading in the body, so it's a text the template prints: see the first limit below. A folder of Markdown files with YAML front matter also shows as a collection in the [CMS](https://midcode.app/docs/data/cms.md), where those fields are edited.

### After an edit

Hugo and Eleventy reload the page themselves. Jekyll rebuilds the site first: midcode reloads the page a moment after the edit and, if it comes back unchanged, again a little later, up to two more times.

## Pages

**Pages** in the top bar is filled from the site's files:

- **Hugo**: every `.md` or `.html` file of `content/`, up to four folders deep. `content/about.md` is `/about`, and `content/posts/_index.md` is `/posts`. A `url:` in YAML front matter wins. If no file gives the home page and there's a `layouts/index.html`, Home opens that layout.
- **Jekyll**: every `.html`, `.md` or `.markdown` file that starts with front matter, at its `permalink:` or at its own path. Folders that start with an underscore aren't looked in, so posts aren't listed one by one.
- **Eleventy**: every template outside `_includes` and `_data`, at its `permalink:` or at its own path. A template whose permalink is computed makes one page per item and isn't listed.

For a page that isn't listed, type its path in **Pages** and press `Enter`.

"New page" in that menu writes a page the way each generator keeps them, and "Remove" moves a page's file to the Trash. A new page at `/about` is:

| Generator | What's written |
| --- | --- |
| Hugo | `content/about.md`, with its `title` in front matter |
| Jekyll | `about.md` at the top of the site, with the home page's `layout` (`default` when it names none), a `title` and `permalink: /about/` |
| Eleventy | `about.njk` beside the home page (`.liquid` or `.html` when that's what the home page is), with the home page's `layout` and a `title` |

```md title="content/about.md"
---
title: "About"
---

A new page, made in midcode.
```

In Hugo and Jekyll the page is Markdown. In Eleventy it's a template with a `<main>`, a heading and a paragraph, and its class names are written when Tailwind is in your `package.json`. Creating and removing a page was tried on the three.

## Site settings

The globe in the top bar opens [Site settings](https://midcode.app/docs/editor/site-settings.md). The title, the description, the language, search engines, the favicon and the social image are written as tags in the `<head>` of a layout: the first template that closes a `<head>`, in alphabetical order of its path. Images are copied to the same folder as `midcode.css` (the table below).

What the template computes there (`<title>{{ .Site.Title }}</title>`, `<title>{{ page.title }}</title>`) shows as code and isn't written: it's still changed where the value is written. There's one form for the whole site. Tried with Hugo and Jekyll.

## Styles

With Tailwind 4 in the project, midcode writes Tailwind's classes ([Tailwind CSS](https://midcode.app/docs/styling/tailwind.md)). Without it, midcode writes `mid:` utilities and keeps their CSS in `midcode.css` ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)), in the folder the generator copies to the site as it is:

| Generator | `midcode.css` goes in |
| --- | --- |
| Hugo | `static/` |
| Jekyll | The project's top folder |
| Eleventy | `public/`, when the config has `addPassthroughCopy({ public: '/' })` |

On your first style edit, every layout that closes a `<head>` gets one line, as one undoable step:

```diff title="_layouts/default.html"
     <link rel="stylesheet" href="{{ '/assets/site.css' | relative_url }}">
+    <link rel="stylesheet" href="/midcode.css">
   </head>
```

The link is the plain path `/midcode.css`. If the site is published under a sub-path (Jekyll's `baseurl`, a Hugo `baseURL` with a folder), change that line to the form your other stylesheets use.

An Eleventy site that doesn't copy `public/` to its root gets `midcode.css` written at the top of the project (in `src/` when there is one), and midcode says it couldn't tell where to import it. Add the passthrough copy and the `<link>` yourself.

## Limits

- Text the template prints is edited where the value is written: front matter, a data file, the site's config. Double-click one and midcode looks for those exact words in the project's `.md`, `.json`, `.js` and `.ts` files, and changes them there when they're written in one place ([Text, images and video](https://midcode.app/docs/editor/text-and-media.md)). So a title in a post's front matter or a string in a JSON data file can be found, and a value in a `.yml`, `.yaml` or `.toml` file (the site's config, most data files) can't. That search wasn't tried on these generators.
- Hugo's `public/` is never read: it's the built site. Neither are `_site`, `dist`, `build` and `out`. If your generator writes its pages to a folder with another name, those built files are read as if they were templates, and an element may point at one of them. Check the file under **Code** before you edit.
- A theme's layouts inside the project (`themes/<name>/layouts`) are matched like your own. Editing a theme you update from elsewhere is a change you'd lose.
- Markdown was tried with Hugo (Goldmark) and Jekyll (kramdown), not with Eleventy.
- The Jekyll that was tried ran with a Ruby that isn't on the PATH, so its command was set in `.midcode/server.json`. The automatic start runs the same command.
- Zola (`config.toml` beside `templates/` and `content/`, run with `zola serve --interface 127.0.0.1 --port $PORT`) and MkDocs (`mkdocs.yml`, run with `<python> -m mkdocs serve -a 127.0.0.1:$PORT` and [the project's Python](https://midcode.app/docs/frameworks/python.md)) are recognised and weren't tried. Their Markdown content is read the same way as Hugo's, and midcode doesn't add pages to them.
- A `url` in TOML front matter (`+++`) isn't read for Hugo's page list.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects.

## Troubleshooting

**"hugo" (or "bundle", "jekyll") isn't installed on this Mac.** midcode runs the command your login shell finds. Install it, or set the command with its full path in **Change how it runs** on the error card. It's saved in `.midcode/server.json` ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)).

**An Eleventy site opens as plain HTML, with `{{ }}` showing on the page.** Its `package.json` has no `dev` script and there's an `index.html` at the top, so midcode took the folder for a static site. Name the script that serves it `dev`: `"dev": "eleventy --serve"`.

**A Markdown paragraph can't be edited.** It has a link, emphasis or a shortcode in it, so its words aren't plain in the file. Edit it in the file: switch to **Code** in the top bar ([Code view](https://midcode.app/docs/editor/code.md)) or use your editor.

**An edit doesn't show in Jekyll.** The rebuild took longer than midcode waited. Press **Reload breakpoints** in the top bar.

---

# Sites a server renders

> How midcode edits a site whose HTML a server builds from templates (PHP, Django, Rails, Hugo and others) by finding each element of the page in your template files.

- Page: https://midcode.app/docs/frameworks/server-templates
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

A PHP, Django, Rails, Hugo, Jekyll or Eleventy site can be edited on the canvas: text, classes, attributes, the tag, new elements, their order. The edit is written into the template file. What midcode can't edit is what the server works out while it renders: a value printed from a variable, content that comes from a database, HTML a helper builds.

This page explains how that works, because it's different from a React or Vue project, and it decides what is and isn't editable. Each stack has its own page with the command midcode runs and what was tried: [Laravel](https://midcode.app/docs/frameworks/laravel.md), [WordPress](https://midcode.app/docs/frameworks/wordpress.md), [PHP and Twig](https://midcode.app/docs/frameworks/php.md), [Django, Flask and FastAPI](https://midcode.app/docs/frameworks/python.md), [Ruby on Rails](https://midcode.app/docs/frameworks/rails.md), [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md).

## At a glance

| | Sites a server renders |
| --- | --- |
| Runs with | The stack's own command on a port midcode picks, or the command and address you give it |
| Elements are marked by | midcode, after each page loads, by matching the page against the project's template files |
| Editing | Text, classes, attributes and tag; insert, move, duplicate and remove. Only what is written in a template |
| Components | Not recognised. A partial or an include is edited in its own file |
| Pages | Read from the stack's routes or files where midcode knows how; otherwise you type the path. New pages in Hugo, Jekyll, Eleventy and Laravel |
| Styles | Tailwind 4 classes, or `mid:` utilities with a `midcode.css` linked from your layouts |
| Tried with | Plain PHP, Twig, Django, Flask, FastAPI, Rails 8, Hugo, Jekyll 4, Eleventy, Express with EJS, WordPress |

## Why these pages arrive without marks

In a Next.js or Vite project, midcode adds a step to the dev server that marks every element with the file, line and column where it's written. That's how a click on the canvas knows which line to change ([How midcode works](https://midcode.app/docs/start/how-it-works.md)).

A site that a server renders has no such step. PHP, Python, Ruby or a site generator turns templates into finished HTML, and midcode has no place to hook into that. The page reaches the canvas with nothing that says where each element came from.

So midcode puts the marks on afterwards. Each time a page loads on the canvas, it looks up every element of that page in the project's templates and, where it finds it, gives it the same mark (`file:line:col`). From then on the canvas treats it like any marked element. Nothing is added to your project to do this: the marks exist only in the page shown inside midcode.

This is how midcode edits every stack it starts with the stack's own command, and any project with a `dev` script whose pages come from templates, such as Express with EJS ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)). An [Angular](https://midcode.app/docs/frameworks/angular.md) app is matched the same way, against its components' templates. Two stacks get real marks instead: Laravel's Blade views, marked as Blade compiles them, and [Shopify themes](https://midcode.app/docs/shopify/themes.md), where midcode uploads a marked copy of the theme.

## How midcode finds an element

When a page loads, midcode notes for each element its tag, classes, id, its own text, a few attributes and what it sits inside. Then it reads every template in the project and lists the elements written there, each with what is fixed and what is computed.

Take this template:

```html title="templates/home.html"
{% extends "base.html" %}
{% block content %}
<section class="hero">
  <h1>Fresh bread, every morning</h1>
  <p class="lead">{{ tagline }}</p>
  <ul class="menu">
    {% for item in menu %}
    <li class="menu-item">{{ item.name }}</li>
    {% endfor %}
  </ul>
</section>
{% endblock %}
```

- The `<h1>` holds only words, and no other template has an `<h1>` with those words. It's found at once, and its text can be edited.
- The `<section class="hero">` isn't written inside the layout's `<main>`, where the page shows it. midcode looks for it across the project: it's the `<section>` with that class that contains the `<h1>` already found.
- The `<p class="lead">` and the `<ul class="menu">` are found among the children written inside that `<section>`. The paragraph's classes can be edited. Its text can't: it's `{{ tagline }}`.
- Every `<li>` the loop draws points at the same line. Select the second one and the right panel says "Item 2 of a list: editing the code changes all of them."

### What has to match

A written element can be an element of the page only if everything fixed about it is there:

- **The tag** is the same.
- **The id**, when the template writes one plainly.
- **Every class** written plainly. Extra classes on the page are fine (a script or the server added them). A class glued to something computed, like `btn-{{ size }}`, is ignored.
- **Telling attributes** written plainly: `alt`, `title`, `name`, `type`, `placeholder`, `for`, `role`, `aria-label`, `value`, `method`, `rel` and `target` have to be equal. `href`, `src` and `action` count in favour when they're equal and don't rule the element out when they differ, because servers rewrite addresses.
- **The text**, when the element holds nothing but written text. Whitespace doesn't matter, and curled quotes and joined dashes compare equal to straight ones. When the text is mixed with computed parts or with other elements, each written run of four characters or more has to appear.

### Where it looks

1. First, the elements that can't be anything else: one place in the whole project fits, and by more than the tag (an id, the text, a couple of classes).
2. Then top-down. An element inside a parent that was found is looked for among the children written inside that parent in the template. Several alike, one after another, are taken in order: the first `<div class="card">` of the page is the first one written, the second is the second. When the one before has something computed in it, midcode takes it for a loop and assigns the same written element again.
3. An element written in another file than its parent (the page a layout wraps, an include, a partial) is looked for in the whole project. It counts only if exactly one place fits, or if it's the one that holds the elements already found inside it. A bare `<body>`, `<main>`, `<header>`, `<footer>`, `<nav>` or `<aside>` is matched when the project writes that tag once.

### When it gives up

When two places fit equally and nothing settles it, the element gets no mark. midcode never guesses: an unmarked element can't be edited by mistake. You can still select it and leave a [comment](https://midcode.app/docs/editor/comments.md) on it; the **Code** section of the right panel says it isn't in your project's files. Its parent usually is.

## Which templates are read

| Files | Read as | Computed, never edited |
| --- | --- | --- |
| `.blade.php` | Blade | `{{ }}`, `{!! !!}`, `@directives`, `@php … @endphp`, `<?php ?>` |
| `.twig` `.njk` `.nunjucks` `.jinja` `.jinja2` `.j2` `.liquid` `.hbs` `.handlebars` `.mustache` `.gohtml` `.tmpl` | Braces: Twig, Nunjucks, Jinja, Liquid, Handlebars, Go templates | `{{ }}` and `{% %}`. `{# #}` is a comment |
| `.html` `.htm` | HTML that may hold the same braces (Django, Jinja, Hugo and Eleventy name theirs so) | `{{ }}` and `{% %}` |
| `.erb` `.ejs` `.eex` `.heex` `.leex` | ERB, EJS | `<% %>` and `<%= %>` |
| `.php` `.phtml` | PHP | `<?php ?>` and `<?= ?>` |
| `.md` `.markdown` | Markdown, only on sites built from it ([Markdown content](https://midcode.app/docs/frameworks/static-generators.md)) | Anything but plain words |

An attribute's value is split into what's written and what's computed: in `class="card {{ extra }}"`, `card` can be changed and `{{ extra }}` is left as it is.

Haml, Slim, Pug and Razor (`.cshtml`) aren't read. Elements written in them aren't found.

Templates are looked for in the whole project, except in folders that hold what's installed or built: `node_modules`, `vendor`, a Python virtual environment, `storage`, `tmp`, `log`, `dist`, `build`, `out`, `_site`, `staticfiles`, `wp-admin`, `wp-includes`, and any folder whose name starts with a dot. In a Rails or Laravel app and in a Hugo site, `public/` is skipped too. A template bigger than 400 KB is skipped.

## What you can edit

- **Text**: double-click it ([Text, images and video](https://midcode.app/docs/editor/text-and-media.md)). It has to be written in the template, as the whole content of its element.
- **Classes and styles**: everything in [the style panel](https://midcode.app/docs/editor/styles.md). The written part of `class` is changed; computed parts stay.
- **Attributes** written plainly: a link's `href`, an image's `src` and `alt`, a form field's settings.
- **The tag** of a text element (a heading, a paragraph, a `<span>`), with **Tag** under Typography in the right panel.
- **Structure**: insert from [the Insert panel](https://midcode.app/docs/editor/insert.md), [drag to move](https://midcode.app/docs/editor/select-move-resize.md) inside the same file, duplicate, delete. With several selected, `⌫` removes them, `⇧A` wraps them in a stack and dragging one moves them all. `⌥`-drag leaves the element where it is and puts a copy where you drop it, in the same file.

Changing a heading and the padding of its section, in a project without Tailwind:

```diff title="templates/home.html"
-<section class="hero">
-  <h1>Fresh bread, every morning</h1>
+<section class="hero mid:p-6">
+  <h1>Bread, pastries and coffee</h1>
```

Every edit is one step of `⌘Z` and shows in [Publish](https://midcode.app/docs/publish/publish.md), like in any other project.

Text you type is escaped for the language: a `{{` typed into a Blade view is written `@{{`, and in a Twig, Jinja or Liquid file as `&#123;{`, so it stays text.

## What can't be edited from the canvas

- **Computed output**. `{{ post.title }}`, `<?= $title ?>`, `<%= @post.title %>`: the words on the page aren't in the template. Before giving up, midcode looks for those exact words in the project's `.json`, `.js`, `.ts` and `.md` files (a data file, a locale, front matter) and changes them there when they're written in one place ([Text, images and video](https://midcode.app/docs/editor/text-and-media.md)). It doesn't search `.php`, `.py`, `.rb`, `.yml` or `.toml` files, nor other templates. When nothing is found it says "This text isn't written there: it comes from a variable or prop." Change it where the value is written.
- **Content from a database**: a WordPress post's body, a product's description. It isn't in any file.
- **HTML a helper builds**: Rails' `link_to` and `image_tag`, Django's `{{ form.as_p }}`, a WordPress menu. No template writes those tags, so they get no mark.
- **Elements a condition splits**: a tag opened in one branch of an `if` and closed in another can't be moved or removed from the canvas. Its classes and text still can.
- **Components that need an import**: the interactive components of the Insert panel are React components. In a template they're refused ("This component needs a React page").

## Pages that redraw themselves

A page that changes after it loaded is watched: htmx swapping a fragment, Turbo navigating, a Livewire update, a client-side router. When elements arrive without a mark, or a marked one loses its mark, midcode matches the whole page again, a few times a second at most. An element that isn't found this time keeps the mark it had. A text you're typing into right now is left alone.

## After an edit

midcode writes the template, and the server renders it again on the next request. If the site reloads its own pages (Hugo and Eleventy do), that's all. If not, midcode reloads the page in every breakpoint a moment after the edit. A site that rebuilds, like Jekyll, may not be done yet: when the page comes back the same as before the edit, midcode loads it again a little later, up to two more times.

A change you make outside midcode shows when the page loads again: press **Reload breakpoints** in the top bar. Templates are read again whenever they change, so the marks stay right.

## Styles

With Tailwind 4 in the project, midcode writes Tailwind's own classes ([Tailwind CSS](https://midcode.app/docs/styling/tailwind.md)). Without it, midcode writes its `mid:` utilities and keeps their CSS in a file called `midcode.css` ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)).

In these sites `midcode.css` goes in the folder the stack serves as it is, and every layout links it. A layout is any template that closes a `<head>`. The link is added on your first style edit, as one undoable step:

```diff title="layouts/_default/baseof.html"
     <link rel="stylesheet" href="/style.css">
+    <link rel="stylesheet" href="/midcode.css">
   </head>
```

| Stack | Where `midcode.css` goes | How layouts link it |
| --- | --- | --- |
| Hugo, Zola | `static/` | `/midcode.css` |
| Jekyll | The project's root folder | `/midcode.css` |
| Eleventy that copies `public/` to its root | `public/` | `/midcode.css` |
| Rails, Laravel without Vite | `public/` | `/midcode.css` |
| PHP | Next to `index.php` | `/midcode.css` |
| Flask | The app's `static/` | `/static/midcode.css` |
| Django | The folder in `STATICFILES_DIRS` | Under `STATIC_URL` |
| A WordPress theme | The theme's folder | `get_theme_file_uri()` |

midcode starts one command. If your CSS is compiled by a watcher of its own (Tailwind's CLI, a `Procfile.dev`), run it yourself, or a new Tailwind class won't have its CSS.

Where midcode can't tell which folder is served (FastAPI, a whole WordPress install, a Django project without `STATICFILES_DIRS`), it writes `midcode.css` at the top of the project (in `src/` when there is one) and says it couldn't tell where to import it. Add the `<link>` to your layout yourself.

## New pages and Site settings

midcode adds and removes pages where a page is a file it knows how to write: `content/about.md` in Hugo, `about.md` in Jekyll, a template beside the home page in Eleventy, and a Blade view with its `Route::view` line in Laravel. Each stack's page shows the file. In Django, Flask, FastAPI, Rails, WordPress and plain PHP a page is code (a route, a view, a controller), so the page menu has no plus there: write it yourself, or ask your agent.

[Site settings](https://midcode.app/docs/editor/site-settings.md), the globe in the top bar, writes the title, the description, the language, search engines, the favicon and the social image as tags in the site's `<head>`. That's the first layout (a template that closes a `<head>`), in alphabetical order of its path. What the template computes there (`{{ .Site.Title }}`, `@yield('title')`, `<%= content_for(:title) %>`) is shown as code and isn't written. The images are copied to the folder `midcode.css` goes in (the table above). Where midcode can't tell which folder that is and the project has no `public/` folder, it asks you to put the image where the site serves it and link it in the code. There's one form for the whole site. WordPress has no Site settings: it keeps them in its database. Tried with Hugo, Jekyll and Laravel.

## Limits

- Matching is finding, not knowing. On a page built from many near-identical fragments in different files, some elements stay unmarked.
- If the project's `package.json` lists Next.js, Vite, Astro, Nuxt, SvelteKit, React Router or Remix, midcode opens it as that kind of project and doesn't match templates. Laravel with Vite is the exception.
- Inside an inline `<svg>`, only the `<svg>` itself is matched.
- The stylesheet link is written for layouts in `.html`, `.php`, `.erb`, `.ejs`, `.twig`, `.njk`, Jinja, Handlebars and Go template files. A layout in another kind of file (`.phtml`, `.heex`, a `.liquid` layout outside a Shopify theme) needs the link added by hand.
- A page is read up to 8,000 elements.
- Elements move inside one file. Moving one from a partial into the page that includes it is done in the code.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects. [Component mode](https://midcode.app/docs/editor/components.md) and [variables](https://midcode.app/docs/editor/variables.md) aren't available in these templates.
- With more than one layout, Site settings writes the first by path, which may not be the one your pages use. The note under the form's images names the file it writes.
- Replacing an image from the panel copies the new file into `public/`. That's where Laravel, Rails and many PHP sites serve files from. It hasn't been tried on stacks that serve them from another folder (Hugo's `static/`, Django's and Flask's static files, a WordPress theme): there, set the image's `src` by hand.
- Phoenix (`.heex` is read as ERB; its `<.components>` and `{@values}` stay as text), ASP.NET, Zola and MkDocs start with their own command but haven't been tried. See [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).

## Troubleshooting

**Nothing on the page can be edited.** The **Code** section of the right panel says "midcode can't edit this project's code yet" when midcode found no template it reads, looking up to five folders deep. Check the table of template files above. A `.php` file counts only if it has markup in it.

**One element has no file and line, and its neighbours do.** It's built by a helper, comes from a database, or is written in two places midcode can't tell apart. In that last case, give it an `id` or a class of its own in the template, and it will be found on the next load.

**The site doesn't start.** Open the **Dev server log** in the top bar to see what the command printed. **Change how it runs** on the error card lets you set your own command and address, saved in `.midcode/server.json` ([Any other stack](https://midcode.app/docs/frameworks/custom-server.md)). Matching works the same however the site is served, including a site that already runs somewhere else.

---

# Monorepos

> How midcode opens a site inside a workspace, finds its package manager and dependencies at the repository's top, and picks the site when you open the top.

- Page: https://midcode.app/docs/frameworks/monorepos
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

A site inside a monorepo is edited like the same site on its own. The project, for midcode, is the site's folder (`apps/web`), not the repository. What changes is where midcode looks for the things a workspace keeps at the top: the lockfile, and often `node_modules`.

You can open the site's folder or the top of the repository. Opened at the top, midcode goes into the one site it finds there. It starts that site only: an API or another app in the same repository is yours to run.

## At a glance

| | Monorepos |
| --- | --- |
| Detected by | `pnpm-workspace.yaml`, or `workspaces` in a `package.json`, up to five folders above the site. `nx.json` and `lerna.json` count too |
| Runs with | The site's own framework, as on its page. The package manager is the one whose lockfile is at the top |
| Editing | Whatever the site's framework allows, in files inside the site's folder |
| Tried with | A pnpm workspace and an npm workspace with dependencies at the top (Vite + React, Vite + Preact) |

## Opening the site's folder

Open `apps/web` and midcode detects its framework from its own `package.json`, as usual. Three things are then answered from the repository around it when they aren't beside the site.

**Is this folder part of a workspace?** midcode walks up, at most five folders, looking for one that declares the site as one of its packages:

```yaml title="pnpm-workspace.yaml"
packages:
  - 'apps/*'
  - 'packages/*'
```

or, for npm, yarn and bun:

```json title="package.json"
{
  "workspaces": ["apps/*", "packages/*"]
}
```

The site's path has to fit one of those patterns. A repository with an `nx.json` or a `lerna.json` and no `workspaces` is taken to keep its packages in `apps/*`, `packages/*` and `libs/*`.

**Which package manager?** The site's own lockfile decides if it has one. If not, the lockfile at the top of the workspace does: `pnpm-lock.yaml`, `bun.lockb` or `bun.lock`, `yarn.lock`, `package-lock.json`. With none, npm.

**Is it installed?** Yes if there's a `node_modules` beside the site or at the top of the workspace. A `.pnp.cjs` (Yarn Plug'n'Play) counts too. So midcode doesn't offer to install because the folder next to the site is missing. When nothing is installed anywhere, "Install with pnpm" runs the install in the site's folder, with the workspace's package manager.

The dev server is then started the way the site's framework page describes. Its tools are found wherever they were installed: `next` and the framework's command the way Node resolves them, and `vite`, for the config midcode puts in front of yours, by walking up the folders until a `node_modules/vite` appears (npm hoists it to the top).

## Opening the top of the repository

Open the repository's top folder and midcode checks what's there first. If the top is itself a project it recognises, that's what opens. Otherwise it looks for the site inside:

- In a workspace, the folders its patterns name (`apps/*` means each folder of `apps/`).
- In any other repository, the folders at the top. This covers a repository that keeps its halves side by side, like `frontend/` and `backend/`, or `client/` and `server/`.

Folders that are never the site are skipped: `node_modules`, `vendor`, `dist`, `build`, `out`, `public`, `static`, `docs`, `scripts`, `test`, `tests`, `e2e`, and anything that starts with a dot.

A folder is a site when its `package.json` depends on `next`, `@react-router/dev`, `@remix-run/dev`, `astro`, `@sveltejs/kit`, `nuxt`, `vite`, `@angular/core`, `gatsby` or `@docusaurus/core`. A package with only `vite` also has to look like an app (an `index.html`, or a `src/main.tsx`, `.ts` or `.jsx`): a library built with Vite has no page to show.

Then:

- One site: midcode opens it.
- Several: it opens the one whose folder is called `web`, `www`, `site`, `website`, `app`, `frontend`, `front`, `client`, `ui`, `marketing`, `landing` or `storefront`, if exactly one is.
- Still several, or none: midcode doesn't guess. The top stays the project. If it has a `dev` script, midcode runs that and the site shows without marks, to look at and comment on. Without one, the canvas asks how the site runs. Open the site's folder instead.

When it went inside, the dev server log says so:

```text
acme holds more than a site: midcode opened apps/web and starts only that. If the site needs the rest (an API, a backend), run it yourself.
```

The project keeps the repository's name, not `web`: a generic folder name (`web`, `app`, `site`, `frontend`, `client`…) is replaced by the folder around it, and `apps` or `packages` are skipped on the way up.

## What midcode writes, and where

Everything midcode adds goes in the site's folder: `.midcode/`, and `midcode.css` when the site has no Tailwind 4. The file and line each element is marked with are relative to that folder too (`src/App.tsx:5:5`). See [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).

Publish works on the repository the site is in, but lists and commits only the files under the site's folder. See [Publish](https://midcode.app/docs/publish/publish.md).

## Limits

- midcode writes only inside the folder it opened. A component that lives in another package of the workspace (`packages/ui`) is outside it: an edit to one of its elements is refused with "Outside the project". Edit it in code.
- Only the site is started. A script at the top that runs everything (`turbo dev`) isn't used, so whatever the site calls has to be running already.
- If the top-level `package.json` lists a framework itself (`vite` for tests, say), midcode takes the top as the project and doesn't look inside. Open the site's folder.
- A `.midcode/server.json` at the top also keeps midcode there: see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md).
- When midcode looks for the site from the top, patterns are read one level deep: `apps/*` and `apps/**` both mean the folders of `apps/`.
- Turborepo, Nx and yarn workspaces have never been tried, and there's no record for bun or Lerna. What was tried is pnpm and npm, with Vite sites. Yarn Plug'n'Play counts as installed, but starting a dev server without a `node_modules` has not been tried.

## Troubleshooting

**midcode opened the wrong app, or the whole repository without marks.** It couldn't tell which folder is the site. Open that folder directly (`⌘O`, then `apps/web`).

**"Dependencies are missing" in a repository that is installed.** midcode didn't find the workspace: the site's folder doesn't fit a pattern in `pnpm-workspace.yaml` or `workspaces`, or the top is more than five folders up. Installing from the card still works.

**The site starts but its data doesn't load.** The API it calls isn't running. Start it yourself, in a terminal or in midcode's own (see [Code view](https://midcode.app/docs/editor/code.md)).

The framework pages cover the rest: [Next.js](https://midcode.app/docs/frameworks/nextjs.md), [React with Vite](https://midcode.app/docs/frameworks/react-vite.md), [React Router and Remix](https://midcode.app/docs/frameworks/react-router.md), [Svelte and SvelteKit](https://midcode.app/docs/frameworks/svelte.md).

---

# Any other stack

> The stacks midcode recognises by their files, the command it runs for each, the form it shows when it can't tell, and the .midcode/server.json format.

- Page: https://midcode.app/docs/frameworks/custom-server
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens any folder. When the project isn't one of the frameworks it starts with its own plugin, it works out how the site is served from the files it finds, runs that command and shows the result on the canvas. When it can't tell, it asks you, and keeps your answer in `.midcode/server.json`. Of the projects on this page, midcode 1.1.2 and earlier open only the ones with a `dev` script in `package.json` or an `index.html`, and only to view and comment.

## At a glance

| | Any other stack |
| --- | --- |
| Detected by | Files at the project's root, a script in `package.json`, or your answer in `.midcode/server.json` |
| Runs with | The stack's own command, in your login shell, on a free port |
| Elements are marked by | Matching each loaded page against the project's templates, when it has any |
| Editing | Text, classes, attributes and structure where an element is found in a template. View and comment otherwise |
| Pages | The stack's routes where midcode can read them. Any path can be typed |
| Styles | `mid:` utilities. Where `midcode.css` goes depends on the stack |
| Tried with | Laravel, PHP, Django, Flask, FastAPI, Hugo, WordPress, Shopify and Angular. Rails and Jekyll through `server.json` |

## What midcode tries, in order

1. **Your answer.** A `.midcode/server.json` with a command or an address comes before everything else.
2. **A framework it starts itself**: Next.js, React Router, Remix, Astro, SvelteKit, Nuxt or Vite in `package.json`. Each has its own page.
3. **A stack it knows by its files**: the table below.
4. **A `dev` script** in `package.json`, run with your package manager. midcode reads the address from what it prints.
5. **An `index.html` at the root**: [plain HTML](https://midcode.app/docs/frameworks/html.md), served by midcode.
6. **Another script**: the first of `start`, `serve`, `develop` and `docs:dev`.
7. **Nothing fits**: the canvas asks "How does this site run?"

At the top of a repository that keeps its site in a subfolder, midcode opens that site instead: see [Monorepos](https://midcode.app/docs/frameworks/monorepos.md).

## Stacks midcode recognises

The first row that fits wins.

| Stack | Recognised by | Command |
| --- | --- | --- |
| Laravel | `artisan` | `php artisan serve --host=127.0.0.1 --port=$PORT` |
| Django | `manage.py` | `python manage.py runserver 127.0.0.1:$PORT` |
| Rails | `bin/rails` or `config/application.rb` | `bin/rails server -b 127.0.0.1 -p $PORT` |
| Shopify theme | `layout/theme.liquid` | `shopify theme dev --path $THEME --host 127.0.0.1 --port $PORT`, plus `--store <store>` once it's known |
| Hugo | `hugo.toml`, `hugo.yaml`, `hugo.yml` or `hugo.json`; or `config.toml` / `config.yaml` with `content/` and `layouts/` or `themes/` | `hugo server --bind 127.0.0.1 --port $PORT` |
| Jekyll | `_config.yml` or `_config.toml` | `jekyll serve --host 127.0.0.1 --port $PORT`, through `bundle exec` when there's a `Gemfile` |
| Zola | `config.toml` with `templates/` and `content/` | `zola serve --interface 127.0.0.1 --port $PORT` |
| Phoenix | A `mix.exs` that names `:phoenix` | `mix phx.server` |
| ASP.NET | A `.csproj`, `.fsproj` or `.vbproj` at the top, with `Pages/`, `Views/` or `wwwroot/` | `dotnet watch run --urls http://127.0.0.1:$PORT` |
| Flask | `flask` among the Python dependencies, and a module that makes `Flask(…)` | `python -m flask --app <module> run --debug --host 127.0.0.1 --port $PORT` |
| FastAPI | `fastapi` among the Python dependencies, and a module with `app = FastAPI(…)` | `python -m uvicorn <module>:<app> --reload --host 127.0.0.1 --port $PORT` |
| MkDocs | `mkdocs.yml` or `mkdocs.yaml` | `python -m mkdocs serve -a 127.0.0.1:$PORT` |
| WordPress | `wp-load.php`, or a theme folder inside a WordPress | `php -d auto_prepend_file=$WP_PREPEND -S 127.0.0.1:$PORT` |
| Angular | `angular.json` | `NG_CLI_ANALYTICS=false ./node_modules/.bin/ng serve --host 127.0.0.1 --port $PORT` |
| PHP | `index.php` at the root, or in `public/`, `web/` or `webroot/` | `php -S 127.0.0.1:$PORT`, with `-t <folder>` when it's not the root |
| Deno | No `package.json`, and a `dev`, `start` or `serve` task in `deno.json` or `deno.jsonc` | `deno task <task>` |

`python` is the project's own: `.venv/bin/python`, `venv/bin/python` or `env/bin/python` when one exists, else `uv run python`, `poetry run python` or `pipenv run python` by the lockfile it finds, else `python3`.

Some of these do more than the table says, and have their own page:

- [Laravel](https://midcode.app/docs/frameworks/laravel.md): midcode serves the app with PHP's own server when it can, so Blade views are marked as they compile, and shows a site already running at its `APP_URL`.
- [WordPress](https://midcode.app/docs/frameworks/wordpress.md): what `$WP_PREPEND` is, and opening a theme folder.
- [PHP and Twig](https://midcode.app/docs/frameworks/php.md), [Django, Flask and FastAPI](https://midcode.app/docs/frameworks/python.md), [Ruby on Rails](https://midcode.app/docs/frameworks/rails.md), [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md): templates, pages and styles for each.
- [Shopify themes](https://midcode.app/docs/shopify/themes.md): what `$THEME` is, and what the canvas asks for instead of the terminal.
- [Angular](https://midcode.app/docs/frameworks/angular.md): templates, external and inline.

## How $PORT works

Before it runs a command, midcode picks a free port, starting at 4310, and puts it wherever the command or the address says `$PORT` (or `${PORT}`). The same number is in the `PORT` environment variable, which many tools read by themselves. Some don't, and would take their usual port: when midcode runs a script of your `package.json` that is only a call to one of those (`eleventy`, `rsbuild`, `rspack`, `vue-cli-service`, `webpack`, `webpack-dev-server`, `docusaurus`, `gatsby`, `parcel`, `vitepress`, `vuepress`) and names no port, it adds `--port` with that number.

The command runs in your login shell, from the project's folder, so it finds what your terminal finds. midcode also sets `BROWSER=none`, so a tool doesn't open a browser tab of its own.

Then midcode waits, up to two minutes, for something to answer at:

- the address you gave, if you gave one;
- a local address the command prints (its "Local:" line when it has one, else the first `localhost` or `127.0.0.1` address);
- `http://localhost:$PORT` and `http://127.0.0.1:$PORT`, when no address was given.

A stack that may already be running is asked first. A Laravel app that answers at its `APP_URL`, or a WordPress at the `WP_HOME` of its `wp-config.php`, is shown as it is, and the log says so: `Already running at http://shop.test: midcode shows it.`

## When midcode asks

When nothing fits, the canvas shows a form instead of the site:

- **How does this site run?** "Give midcode the command that starts it, the address where it's already running, or both."
- **Command**, with the example `bin/rails server -p $PORT`.
- **Address**, with the example `http://localhost:$PORT`.
- A note under them: "$PORT is a free port midcode picks. With no command, midcode only shows the address. Saved in .midcode/server.json."
- **Start** saves your answer and starts the site.

The same form is behind **Change how it runs**, the link under the card "The server didn't start". There it opens filled in with your saved answer, or with the stack midcode recognised ("It looks like Rails. Change the command if yours is another."). **Reset** ("Forget this and let midcode work it out") clears a saved answer.

## .midcode/server.json

The form writes one small file in your project. You can write it yourself too:

| Field | What it is |
| --- | --- |
| `command` | What starts the site, as you'd type it in a terminal at the project's root. May be empty |
| `url` | Where the site answers. Without `http://`, midcode adds it. Only the origin counts: a path after it is dropped. May be empty |

With both empty, or with a file that isn't valid JSON, midcode goes back to working it out by itself.

**A command.** midcode finds the address in what the command prints, or at the port it handed over:

```json title=".midcode/server.json"
{
  "command": "php -S 127.0.0.1:$PORT -t public_html",
  "url": ""
}
```

**A command and an address.** Here the stack is one midcode knows, but with a Ruby that isn't on your `PATH`:

```json title=".midcode/server.json"
{
  "command": "/opt/homebrew/opt/ruby/bin/bundle exec jekyll serve --host 127.0.0.1 --port $PORT",
  "url": "http://127.0.0.1:$PORT"
}
```

If the command chooses its own port, write that address instead (`http://localhost:8080`).

**Only an address.** The site already runs somewhere (Herd, Valet, Docker, another terminal), and midcode starts nothing:

```json title=".midcode/server.json"
{
  "command": "",
  "url": "https://shop.test"
}
```

midcode waits 20 seconds for it to answer, then says `Nothing answers at https://shop.test. Start the site, then try again.` Over `https`, a certificate the server made for itself is accepted on `localhost`, `127.0.0.1` and `*.localhost`. Any other host needs a certificate macOS trusts.

After changing the file by hand, open the **Dev server log** in the top bar and press **Restart**. Whether to commit the file is up to you: it's right for everyone who runs the project the same way. [What midcode adds to your project](https://midcode.app/docs/start/project-files.md) lists it with the rest of `.midcode/`.

> [!WARNING]
> In a project midcode starts with its own plugin (Next.js, Vite, Astro, Nuxt, SvelteKit, React Router, Remix), a `server.json` replaces that start. The site then arrives without marks, so you can view and comment but not edit. The same goes for a folder of plain HTML. To go back, delete the file and restart the server.

## What you can edit

For the stacks on this page, that depends on what the folder holds:

- **Templates a server fills in** (`.html`, `.php`, `.blade.php`, `.erb`, `.ejs`, `.twig`, `.njk`, `.liquid`, `.hbs` and the like): when a page loads, midcode looks each element up in those files and marks the ones it's sure about. Text, classes, attributes and structure are then written into the template. On sites built from Markdown (Hugo, Jekyll, Eleventy, Zola, MkDocs), the words of the content's `.md` files are found and edited the same way. [Sites a server renders](https://midcode.app/docs/frameworks/server-templates.md) explains the matching and its limits.
- **JSX or Vue built with webpack or Rspack**: marked as the site builds. See [Create React App, Vue CLI, Gatsby, Docusaurus](https://midcode.app/docs/frameworks/webpack.md).
- **Neither**: nothing is marked. You can check every breakpoint, use the site in Preview (`P`) and leave [comments](https://midcode.app/docs/editor/comments.md) for your agent.

## Pages

Where midcode can read a stack's routes, they're the page list: `routes/web.php` in Laravel, `config/routes.rb` in Rails, `urls.py` in Django, the `@app.route` lines of Flask, Angular's route files, the content files of Hugo, Jekyll and Eleventy, and a Shopify theme's templates. Anywhere else the list has the home page alone, and any path can be typed in the page menu in the top bar ("Search, or type a path and press Enter").

## Styles

Without Tailwind 4, midcode writes its own `mid:` utilities and keeps their CSS in `midcode.css` ([Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)). Where midcode knows which folder a stack serves as it is (`static/` in Hugo, `public/` in Rails, Laravel and Angular, the document root in PHP), the file goes there and every layout gets a `<link>` to it. For a stack it doesn't know, midcode may not find where to link it. It creates `midcode.css`, tells you it couldn't tell where to import it, and you link the file from your layout yourself.

## Limits

- Phoenix, ASP.NET, Zola, MkDocs and Deno are recognised by their files, but were never tried.
- There's no terminal behind the command. One that stops to ask a question can't be answered.
- midcode starts one process. If the site needs a second one (a database, an API, a queue), start it yourself.
- [The free canvas](https://midcode.app/docs/editor/free-canvas.md) is for Next.js projects on the App Router.
- Pages are added from midcode in Hugo, Jekyll, Eleventy and Laravel only, and [Site settings](https://midcode.app/docs/editor/site-settings.md) needs a layout that closes a `<head>`: see [New pages and Site settings](https://midcode.app/docs/frameworks/server-templates.md).

## Troubleshooting

**"… isn't installed on this Mac (or not on your shell's PATH)."** The shell didn't find the command's first word. If it works in your terminal, write its full path in the command, as in the Jekyll example above.

**"The server stopped (code 1)".** The command ran and quit. **View log** on the card shows what it printed.

**"Nothing answers at …" or "The server did not answer in time".** The command is running, but not where midcode is looking. Either it ignores `$PORT` (give the address it really uses), or it takes longer than two minutes to come up.

**The wrong site shows.** Something else was already answering at that address. Stop it, or give the command a `$PORT` of its own.

---

# Shopify themes

> How midcode runs a Shopify theme with your own Shopify CLI, what you can edit in its Liquid and JSON, and how the theme reaches your store.

- Page: https://midcode.app/docs/shopify/themes
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

midcode opens a Shopify theme's folder and shows your storefront at every [breakpoint](https://midcode.app/docs/editor/canvas.md), drawn by Shopify with your store's own products. Click an element and midcode knows the `.liquid` file and line it's written in. Text, classes, attributes and layout are written into the theme's files: the Liquid markup, or the JSON template or locale file where a text really lives.

Everything goes through your own Shopify CLI, signed in as you. midcode stores no Shopify token. It works on a development theme, so the theme your visitors see doesn't change until you send or publish it yourself.

Two more pages cover the rest: [Sections and blocks](https://midcode.app/docs/shopify/sections.md) for what Shopify's theme editor has in its sidebar, and [Store](https://midcode.app/docs/shopify/store.md) for products, orders and the store's other data.

## At a glance

| | Shopify themes |
| --- | --- |
| Detected by | A `layout/theme.liquid` file in the folder |
| Runs with | Your Shopify CLI: `shopify theme dev`, on a copy of the theme |
| Elements are marked by | midcode, in that copy. Your own files are never marked |
| Editing | Text, classes and attributes; insert, move and delete elements in `.liquid` files; text kept in `templates/*.json` and `locales/*.json`; section settings |
| Components | Not recognized. A snippet is edited where it's written |
| Pages | The theme's templates, at the addresses your store gives them |
| Styles | `mid:` utilities on the element, their CSS in `assets/midcode.css` |
| Tried with | Dawn, end to end, on a development store |

## Open a theme

Press `⌘O` and choose the theme's folder (see [Open a project](https://midcode.app/docs/start/open-a-project.md)). You need a Shopify account that can sign in to the store: a Partner account, or a staff account of the store.

The first time, the canvas shows a card for each thing the Shopify CLI would have asked in a terminal, in this order. A card only shows when its answer is missing.

| Card | What runs | Where the answer is kept |
| --- | --- | --- |
| Install the Shopify CLI | `npm install -g @shopify/cli@latest` | On your Mac, as a global npm package |
| Sign in to Shopify | `shopify auth login` | In the Shopify CLI's own session |
| Which store? | `shopify store list` | `.midcode/shopify.json`, in the theme |
| The storefront's password | Nothing: it's handed to `shopify theme dev` | Encrypted on your Mac, outside the project |

### Install the Shopify CLI

Shows when `shopify` isn't on your shell's path. "Install it" runs npm in your own login shell and shows what it prints. You can also run `npm install -g @shopify/cli` in a terminal yourself. Without npm on the Mac, midcode says so: install Node.js, or the Shopify CLI with Homebrew, and try again.

### Sign in to Shopify

"Sign in" runs `shopify auth login`. Your browser opens Shopify's sign-in, and the card shows a verification code to check against the one in the browser. midcode waits up to 10 minutes; "Cancel" stops it. The session belongs to the CLI: if you had already signed in from a terminal, this card doesn't show.

### Which store?

The card lists the stores of your account, with development stores marked "Development". Pick one, or type another in the field (`your-store.myshopify.com`, the store's name alone, or its admin address) and click "Use it". midcode writes it into the theme's folder:

```json title=".midcode/shopify.json"
{
  "store": "your-store.myshopify.com"
}
```

That file holds the store's address and nothing secret (it's listed with everything else in [What midcode adds to your project](https://midcode.app/docs/start/project-files.md)). When it isn't there, midcode reads the store from what the theme already says and doesn't ask: a `--store` in the command of `.midcode/server.json`, or a `store = "…"` line in `shopify.theme.toml`.

### The storefront's password

Every development store is behind a password, and so is any store with password protection on. `shopify theme dev` stops when it meets one, and the canvas asks for it. It's in the store's admin, under Online Store → Preferences. Type it and click "Continue".

midcode keeps the password encrypted on your Mac (`~/Library/Application Support/midcode/shopify.bin`), never in the project, and hands it to the CLI each time it starts the theme. If Shopify refuses it, the card says "Shopify didn't take that password. Check it and try again."

A fifth card, "Connect the store", is only for the store's data: see [Store](https://midcode.app/docs/shopify/store.md).

## How midcode runs it

Liquid is rendered by Shopify from the files the CLI uploads, so nothing of midcode's can run there. The marks get in another way.

First, midcode copies the theme into its own data folder (`~/Library/Application Support/midcode/shopify/`): the folders `assets`, `blocks`, `config`, `layout`, `locales`, `sections`, `snippets` and `templates`, plus `.shopifyignore` and `shopify.theme.toml`. In the copy, each element of each `.liquid` file says where it's written:

```liquid title="sections/hero.liquid, as it is in the copy"
<h2 data-mc="sections/hero.liquid:42:5" class="banner__heading">{{ section.settings.heading }}</h2>
```

Then it runs your CLI on that copy:

```bash
shopify theme dev --path <the copy> --host 127.0.0.1 --port <a free port> --store your-store.myshopify.com
```

The CLI uploads the copy to a development theme in your store and serves its preview. That preview is what the canvas shows.

An edit is written to your real file. A moment later the copy follows (marked again), the CLI uploads the change and the preview reloads. With Dawn, an edit showed in about 2 seconds.

Your folder never carries a mark, so `git diff` shows your edit and nothing else. The copy is made new each time the theme starts. The live theme is not touched by any of this.

"Change how it runs", under each card, lets you set the command yourself (see [Any other stack](https://midcode.app/docs/frameworks/custom-server.md)). Keep `--path $THEME` in it: `$THEME` is the copy. With your own folder as the path the storefront still shows, but its elements carry no marks and there's nothing to edit by.

## What you can edit

### Liquid

In a `.liquid` file midcode edits what's written as markup and leaves alone what Liquid computes.

- **Elements**: select, restyle, change attributes, delete, insert, and move within the same file. Several can be deleted, moved or wrapped in a stack (`⇧A`) at once, and `⌥`-drag leaves a copy in the same file. A tag with a hyphen (`<product-info>`, `<slider-component>`) is a custom element, and an element like any other.
- **Text** written between tags is edited with a double-click (see [Text, images and video](https://midcode.app/docs/editor/text-and-media.md)).
- **Expressions**: `{{ … }}` and `{% … %}` are shown, not edited. A heading that is `{{ section.settings.heading }}` has no text in that file (see below).
- **Classes**: the ones written in `class="…"` are changed. What Liquid adds to the attribute stays as it is.
- **Whole blocks**: `{% schema %}`, `{% javascript %}`, `{% stylesheet %}`, `{% style %}`, `{% raw %}` and `{% doc %}` are left as they are, and `{% comment %}` is a comment. The settings a schema declares are edited in the [Section panel](https://midcode.app/docs/shopify/sections.md).
- **Snippets**: an element inside `snippets/card-product.liquid` is written once. Changing it changes every place the snippet is rendered.

An element opened in one branch and closed in another can't be moved or removed, because midcode can't tell where it ends:

```liquid
{% if block.settings.link != blank %}
  <a href="{{ block.settings.link }}" class="card">
{% else %}
  <div class="card">
{% endif %}
```

midcode answers "An expression draws this element ({…}). Move or remove it in the code." Its classes and attributes can still be changed.

[Insert](https://midcode.app/docs/editor/insert.md) adds plain markup (frames, stacks, text, sections). midcode's interactive components are React, and a theme refuses them: "This component needs a React page".

### Text that isn't in the .liquid file

A theme's texts are rarely in its Liquid. Double-click a heading: midcode tries the `.liquid` file first, and when the text is printed by an expression it looks for that exact text in the theme's JSON and changes it there. A section's own text is in the template:

```diff title="templates/index.json"
       "settings": {
-        "heading": "Summer sale",
+        "heading": "Summer collection",
```

A text of the theme itself is in a locale file:

```diff title="locales/en.default.json"
   "cart": {
-    "title": "Your cart",
+    "title": "Your bag",
```

- The text has to be a whole value in the JSON. A rich text setting keeps its tags (`"<p>…</p>"`), so it isn't found this way: change it in the [Section panel](https://midcode.app/docs/shopify/sections.md).
- If the same text is written in several places, midcode names them and doesn't guess: "That text appears in 3 places (…). Open the right one in your editor." Short words that many locale files share end up here.
- Text handed to a snippet (`{% render 'button', label: 'Shop now' %}`) is Liquid code: change it in the code.

Each edit is one `⌘Z` step and shows in Publish.

## Pages

The page menu in the top bar lists the templates the theme has, at the store's addresses. A template counts when `templates/<name>.json` or `templates/<name>.liquid` exists.

| Template | Address |
| --- | --- |
| `index` | `/` |
| `list-collections` | `/collections` |
| `collection` | `/collections/all` and `/collections/[handle]` |
| `product` | `/products/[handle]` |
| `page` | `/pages/[handle]` |
| `blog` | `/blogs/[blog]` |
| `article` | `/blogs/[blog]/[handle]` |
| `cart` | `/cart` |
| `search` | `/search` |

An address with brackets is one template drawn for many things. midcode lists the real ones from your storefront (its sitemap and the links on its pages, up to 200 per address), so you design the product template looking at an actual product. See [Pages and navigation](https://midcode.app/docs/editor/pages.md).

## Styles

A theme has no Tailwind, so [the style panel](https://midcode.app/docs/editor/styles.md) writes midcode's own utilities, `mid:` (see [Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md)). The first style edit creates `assets/midcode.css` and adds its tag at the end of the `<head>` of `layout/theme.liquid`:

```diff title="layout/theme.liquid"
     {{ content_for_header }}
+    {{ 'midcode.css' | asset_url | stylesheet_tag }}
   </head>
```

From then on a style is a class on the element, and its CSS is kept in that file:

```liquid title="sections/hero.liquid"
<h2 class="banner__heading mid:text-[56px] mid:md:text-[80px]">{{ section.settings.heading }}</h2>
```

The theme's own CSS and classes are not touched. `assets/midcode.css` is part of the theme and goes to the store with it.

## Languages

The theme's `locales/*.json` are its languages. The file named `en.default.json` marks the default, and the `*.schema.json` files (the theme editor's own labels) are left out. With two or more languages, Translations lists every text per language and writes each value into those files: see [Languages](https://midcode.app/docs/data/languages.md). In a theme the language menu doesn't switch the canvas to another language.

## Create a theme

"New project" in the hub has Shopify as a technology (see [New project](https://midcode.app/docs/start/new-project.md)). It needs the CLI and a sign-in, and asks with the same two cards.

| Starter | What runs |
| --- | --- |
| Dawn | `shopify theme init <name> --path <folder> --clone-url https://github.com/Shopify/dawn.git` |
| Skeleton | `shopify theme init <name> --path <folder>` |
| A theme from your store | `shopify theme pull --store <store> --theme <id> --path <folder>` |

For the first two, choose the "Store to work on it with", or "Decide later". For a theme from your store, choose the store and the theme, then "Download and open".

## Send the theme to your store

Two things are separate here.

[Publish](https://midcode.app/docs/publish/publish.md) commits and pushes the theme's code with git (see also [GitHub](https://midcode.app/docs/publish/github.md)). It doesn't send anything to Shopify. If the theme in your store is connected to that GitHub branch, Shopify updates it from the push.

Store → Themes sends the folder itself, with `shopify theme push` from your real folder, never from the marked copy. In a theme, the Publish panel has "Send the theme to your store" at the top, which opens it.

| Button | What it does |
| --- | --- |
| Send as a new theme | Uploads the folder as a new, unpublished theme named `<project> (midcode)` |
| Send here | Replaces an existing theme's files with the folder's. Files that aren't in the folder are removed from it |
| Publish | Makes an unpublished theme the store's theme (`shopify theme publish`) |

"Send here" and "Publish" ask first. On the live theme the question is "Send this theme to the live store?", and it says what that means: it replaces what every visitor sees, right away. Each theme also has "Preview" and "Customize", which opens it in Shopify's editor. If Shopify takes the theme but finds something wrong in some files, midcode lists them.

## Limits

- Tried end to end with Dawn on a development store: 488 elements marked on the home page. Other themes were not tried.
- What Liquid prints (`{{ product.title }}`) is data from your store. It's changed in [Store](https://midcode.app/docs/shopify/store.md), not on the canvas.
- Templates outside the table above (customer accounts, `404`, `password`, `gift_card`, alternates such as `product.featured.json`) are not in the page menu.
- Only `layout/theme.liquid` gets the stylesheet's tag. Another layout, such as `layout/password.liquid`, doesn't load `assets/midcode.css`.
- A theme folder whose `package.json` depends on Vite, Next.js, Astro, SvelteKit, Nuxt, React Router or Remix is opened as that kind of project, not as a theme.
- Component mode and creating pages from midcode are not available in a theme. A page of a store is made in Shopify's admin, or in [Store](https://midcode.app/docs/shopify/store.md).
- Site settings wasn't made for themes and wasn't tried in one. The globe shows, because a theme's layouts close a `<head>`, but the form reads the first of them by name (`layout/password.liquid` before `layout/theme.liquid`), and a theme prints its title and description with Liquid, which the form shows as code and doesn't write. Set a store's title, description and social image in Shopify's admin.
- Two midcode tabs on the same store share one development theme: it belongs to the CLI.

## Troubleshooting

**The canvas keeps asking for the password.** Shopify refused it. Copy it again from Online Store → Preferences. A wrong password also makes the CLI forget one it had remembered from a terminal.

**"Sign in" never finishes.** Click "Cancel" and try again, or run `shopify auth login` in a terminal and open the project again.

**The storefront shows but no element can be edited.** The command was changed and no longer has `--path $THEME`, so the page has no marks. Put it back under "Change how it runs".

For a theme that won't start at all, see [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

---

# Sections and blocks

> Change a Shopify section's settings from midcode's right panel, add, hide, move and remove sections and blocks, and see what each one writes in the theme's JSON.

- Page: https://midcode.app/docs/shopify/sections
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.

In a Shopify theme a page is a list of sections, and each section has settings and blocks. Which settings a section has is declared in its `{% schema %}` (`sections/<type>.liquid`). Their values, and which sections a page has in which order, are kept in JSON: the page's template (`templates/index.json`) or a section group (`sections/header-group.json`).

Shopify's theme editor changes that JSON from its sidebar. midcode does the same from its right panel, as edits to the files in your folder: the smallest change that says it, undoable, and listed in Publish. To open a theme in midcode, see [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## The Section panel

In a theme, the right panel has a group named "Section".

- With an element [selected](https://midcode.app/docs/editor/select-move-resize.md), it shows the section that element belongs to.
- With nothing selected, it shows the page's sections, starting on the first one of the template.

The "Section" list at the top has every section of the page in the order it's drawn: the section groups above the page (the header), the template's own sections, then the footer's group. Each one says which file it's in (`index`, `header-group`), and a hidden one is struck through. Pick one to see it without selecting anything on the canvas. "Shopify's editor", beside the title, opens the store's themes in Shopify's admin.

### How the section is found

Shopify wraps each section of a page in an element whose id carries the section's key in the JSON (`shopify-section-template--…__image_banner`). When the selected element sits inside one, that key is the section.

When it doesn't, the file the element is written in names the type (`sections/image-banner.liquid` is `image-banner`), and the page's first section of that type is taken. If the page has two, pick the other in the list.

The template comes from the page's address: a product page reads `templates/product.json`, the home page `templates/index.json`. An element written in `layout/theme.liquid` belongs to no section, and the panel doesn't show for it.

## Settings

The panel shows each setting of the schema with the control for its type. Labels come from the schema, and a `t:` label is read from `locales/en.default.schema.json`. A setting with no value in the JSON shows the schema's `default`.

| Setting type | Control |
| --- | --- |
| `text`, `url`, `inline_richtext`, any type not listed here | A text field |
| `textarea`, `richtext`, `html`, `liquid` | A field of several lines. Rich text is edited as its HTML (`<p>…</p>`) |
| `number` | A field that takes a number |
| `range` | A slider with the schema's `min`, `max`, `step` and `unit` |
| `checkbox` | A switch |
| `select`, `radio` | A list of the schema's options |
| `color`, `color_background` | A field for the value, with its swatch |
| `color_scheme` | A list of the theme's color schemes (from `config/settings_data.json`) |
| `image_picker`, `product`, `collection`, `page`, `blog`, `link_list` | Picked from the store (below) |
| `header`, `paragraph` | Words to read: nothing to set |
| `video`, `product_list`, `collection_list`, `article`, `font_picker`, `metaobject`, `metaobject_list` | Shown, not changed here |

A typed value is written when you leave the field (or press `Return` in a one-line field), a slider when you let go, a switch or a list at once. In the trial on a development store the preview showed a setting about a second and a half after it was written.

The last row is what midcode has no picker for yet. The panel shows what's picked and says "Picked from the store: changed in Shopify's editor for now."

## Things from the store

A setting that points at something of the store opens a picker: `image_picker` (an image of the store's files), `product`, `collection`, `page`, `blog` and `link_list` (a menu). Click the field and type in "Search the store". "None" clears the setting.

For an image, the list has the store's images, newest first, and "Upload an image…", which puts a file of your Mac into the store's files (JPG, PNG, WebP, GIF, AVIF or HEIC, up to 20 MB) and picks it.

The picker reads the store through its Admin API, so the store has to be connected. When it isn't, the picker says so and offers "Open the Store view to connect it": see [Connect the store](https://midcode.app/docs/shopify/store.md).

What's written is what a theme keeps, not the thing itself:

| Picked | Written in the JSON |
| --- | --- |
| A product, a collection, a page, a blog | Its handle: `"linen-shirt"` |
| A menu | Its handle: `"main-menu"` |
| An image | `"shopify://shop_images/hero.jpg"` |

> [!NOTE]
> An uploaded image is in your store from that moment. `⌘Z` takes back the setting, not the upload.

## Add, remove, hide and move sections

The buttons under the "Section" list act on the section that's shown.

- **"Move up" / "Move down"** move it among the sections of its own file. A section of the template doesn't move into the header group.
- **"Hide this section"** keeps it in the theme and stops the page from drawing it. "Show this section" brings it back.
- **"Remove this section"** takes it out of the file. Nothing asks first: `⌘Z` brings it back.
- **"Add a section"** lists the kinds the theme lets you add there. The new one goes right after the section that's shown, with the blocks and settings of its first preset, and the panel moves to it.

A kind of section can be added when its file in `sections/` has `presets` in its schema, and its `enabled_on` and `disabled_on` don't close the template or the group you're in. In older themes the schema's own `templates` list is read the same way.

## Blocks

Under the settings, "Blocks" lists the section's blocks in order, each with its name and its first text. Click one to open its settings, which use the same controls. The buttons on its row are "Move up", "Move down", "Hide this block" (or "Show this block") and "Remove this block".

"Add a block" lists the block types of the section's schema that still fit: a type under its own `limit`, while the section is under its `max_blocks` (50 when the schema doesn't say). The new block goes last, with the settings its type has in the section's first preset, if any.

## What midcode writes

Every change is made to the JSON as text, on the lines it touches. The comment Shopify puts at the top of the file stays, and so does the rest of the file, byte for byte. The examples are from a home page, `templates/index.json`.

### One value

```diff title="templates/index.json"
       "settings": {
-        "image_overlay_opacity": 40,
+        "image_overlay_opacity": 60,
         "image_height": "large"
       }
```

A setting that had no value yet is one new line, last in `settings`, indented like its neighbours:

```diff title="templates/index.json"
       "settings": {
         "image_overlay_opacity": 60,
-        "image_height": "large"
+        "image_height": "large",
+        "show_text_box": false
       }
```

### A new section

The section gets a key made the way Shopify's editor makes them: its type and six letters and digits. Its entry goes into `sections` after the one it follows, and its key into `order`.

```diff title="templates/index.json"
     "image_banner": {
       "type": "image-banner",
       "settings": {
         "image_overlay_opacity": 60
       }
     },
+    "rich_text_Xk3mPq": {
+      "type": "rich-text",
+      "blocks": {
+        "heading_a8FjkL": {
+          "type": "heading",
+          "settings": {
+            "heading": "Talk about your brand"
+          }
+        },
+        "text_Tn4GhR": {
+          "type": "text",
+          "settings": {
+            "text": "<p>Share information about your brand.</p>"
+          }
+        }
+      },
+      "block_order": [
+        "heading_a8FjkL",
+        "text_Tn4GhR"
+      ],
+      "settings": {}
+    },
     "featured_collection": {
```

```diff title="templates/index.json"
   "order": [
     "image_banner",
+    "rich_text_Xk3mPq",
     "featured_collection"
   ]
```

A new block is written the same way: its entry last in the section's `blocks`, its key last in `block_order`.

### Hidden

```diff title="templates/index.json"
     "featured_collection": {
       "type": "featured-collection",
+      "disabled": true,
       "settings": {
```

Showing it again takes that line out. A block is hidden the same way, inside its own entry.

### Moved

Only `order` changes (`block_order` for a block). The list is written again whole, one key per line, as Shopify writes it.

```diff title="templates/index.json"
   "order": [
     "image_banner",
-    "rich_text_Xk3mPq",
     "featured_collection",
+    "rich_text_Xk3mPq",
     "collage"
   ]
```

### Removed

The section's entry leaves `sections` and its key leaves `order`. Adding a section and then removing it leaves the file exactly as it was.

Before saving, midcode reads the result back as Shopify would. If it couldn't be read, nothing is written and midcode says it can't read the file right now.

## Undo and Publish

Each change is one edit: `⌘Z` undoes it, and [Publish](https://midcode.app/docs/publish/publish.md) lists it by what it was ("Add a section (index.json)", "Hide a section (index.json)"). Like every edit in a theme, it reaches the development theme through the Shopify CLI. It reaches your other themes when you send the theme: see [Send the theme to your store](https://midcode.app/docs/shopify/themes.md).

## Limits

- Tried with Dawn's files, and live on a development store: the section is found from the page's real ids, and a setting written, a section added, hidden or removed showed on the storefront in about a second and a half. The pickers were tried with that store's real files and products.
- Only JSON templates and section groups. A section a layout includes by name (`{% section 'announcement' %}`), whose values are in `config/settings_data.json`, isn't in the panel. A template written in Liquid (`templates/page.liquid`) has no sections to list.
- Theme settings, the ones Shopify's editor has under "Theme settings" (colors, fonts), are not in the panel.
- The default template of each kind of page is read. A product assigned to `templates/product.featured.json` still shows the sections of `templates/product.json`.
- App blocks (`@app`) and theme blocks (`@theme`, the files in `blocks/`) can't be added. A theme block that's already in a section shows with "Nothing to set in this block.", and blocks nested inside a block aren't listed.
- A color is typed, not picked.
- Setting types in the last row of the table are changed in Shopify's editor.

---

# Store

> Manage the products, orders, customers, discounts, pages, blog posts and menus of the Shopify store behind a theme, from midcode and through your own Shopify CLI.

- Page: https://midcode.app/docs/shopify/store
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt
- Status: This ships with the next release of midcode. The version you can download today (1.1.2) doesn't have it yet.
- Beta: midcode labels this beta.

When the project is a Shopify theme, the top bar has one more place beside Design, Code, CMS and Database: Store. It opens where the canvas is and shows the store the theme is worked on with: its orders, products, collections, customers, discounts, pages, blog posts, menus and themes.

Everything is read from the store and written to the store, through the Shopify CLI you're signed in to. midcode keeps no copy of the data and no token. That makes Store different from the rest of midcode in one way that matters: nothing here is a file, so there is no `⌘Z` and nothing to publish. What you save is in your store at once.

To open a theme and choose its store, see [Shopify themes](https://midcode.app/docs/shopify/themes.md).

## Open the Store

Click "Store" in the middle of the top bar. On the left are its parts: Overview, Orders, Products, Collections, Customers and Discounts, then Pages, Blog posts and Menus under "Content", and Themes under "Online store". The store's address at the bottom opens Shopify's admin in your browser.

`Esc` leaves the field you're in, then closes what's open, then goes back to the canvas. Going from Design to Code, or to another place of the top bar, closes Store too.

Store needs the same things the theme does, and asks for what's missing with the same cards: the Shopify CLI, a sign-in and a store (see [Open a theme](https://midcode.app/docs/shopify/themes.md)). Then it needs one more.

## Connect the store

Serving a theme doesn't give access to a store's data. For that the Shopify CLI needs your approval in the store's admin, and the card "Connect the store" asks for it: "To show and change products, orders, customers and the rest, the Shopify CLI needs your go-ahead in the store's admin. midcode keeps no key of its own."

Click "Connect". midcode runs:

```bash
shopify store auth --store your-store.myshopify.com --scopes <the scopes below>
```

Your browser opens the store's admin. Approve there what midcode asks for. midcode waits up to 5 minutes, and "Cancel" stops it.

These are the scopes, and they're only what the Store view uses:

| For | Scopes |
| --- | --- |
| Products, stock | `read_products`, `write_products`, `read_inventory`, `write_inventory`, `read_locations` |
| Orders, shipping | `read_orders`, `write_orders`, `read_fulfillments`, `write_fulfillments`, `read_merchant_managed_fulfillment_orders`, `write_merchant_managed_fulfillment_orders` |
| Customers | `read_customers`, `write_customers` |
| Content | `read_content`, `write_content`, `read_online_store_pages`, `write_online_store_pages`, `read_online_store_navigation`, `write_online_store_navigation` |
| Discounts | `read_discounts`, `write_discounts` |
| Images | `read_files`, `write_files` |
| Sales channels | `read_publications`, `write_publications` |

The token belongs to the CLI and lasts about a day. When it runs out, the part you're on shows the same card again. As the card says: "Shopify asks again after a day or so: one click each time."

Themes is the one part that doesn't need this step.

## What each part does

| Part | What you can do |
| --- | --- |
| Overview | See sales of the last 30 days and by day, orders still to ship, product and customer counts, and the latest orders |
| Orders | Mark as shipped with tracking, mark as paid, archive, cancel; edit the note and tags |
| Products | Create, edit, duplicate, delete. Title, description, status, price, compare-at price, SKU, stock, images, type, vendor, tags, search engine listing |
| Collections | Create, edit, delete. Title, description, and its products picked by hand |
| Customers | Create, edit, delete. Name, email, phone, note, tags. Shows their orders, what they spent and their addresses |
| Discounts | Create, edit, delete, turn on and off: codes that take a percentage or an amount off the whole order |
| Pages | Create, edit, delete, make visible or hidden. Title and content |
| Blog posts | The same, plus excerpt, author and tags |
| Menus | Create, edit, delete. Links up to three levels, reordered and removed |
| Themes | Preview, customize, send this folder as a theme, publish: see [Send the theme to your store](https://midcode.app/docs/shopify/themes.md) |

Each list shows 50 rows at a time, with "Show more" for the next ones. Every list but Menus has a search field, and Products, Orders, Pages, Blog posts and Discounts have a "Show" filter (products by status, orders "To ship" or "To be paid", pages "Visible" or "Hidden"). "Read it again" asks the store for the list again.

## Editing and saving

Click a row and it opens in a form beside the list. "New product", "New page" and the others open an empty one.

- What you type is a draft. Nothing goes to the store while you type.
- "Save", or `⌘S`, sends only the fields you changed. A new thing has "Create" instead.
- "Discard" drops the draft.
- Some things are done at once and aren't part of the draft: adding or removing a product's image, putting a product in a collection or taking it out, turning a discount on or off, "Duplicate", and the buttons of an order.
- The "More" menu of a form has "Open in Shopify admin", for whatever midcode doesn't do, and "Delete".

> [!WARNING]
> There is no undo here. A save changes the store, and "Delete" asks once and then deletes from the store for good.

Saving and deleting need a license or a running trial, like every edit in midcode (see [Install and license](https://midcode.app/docs/start/install.md)).

### Products and stock

A new product is a draft unless you set its status, has one variant, and is made available in the Online Store sales channel. With several variants, the form lists each with its price, SKU and stock. Adding variants or options is done in Shopify's admin.

"In stock" is the total you have. Typing a number for a variant that wasn't counted ("Not counted") starts counting it. When a product is kept at several locations, the difference goes to the first location it's stocked at and the others keep theirs.

Images are JPG, PNG, WebP, GIF, AVIF or HEIC, up to 20 MB. Shopify takes a few seconds to process one, and midcode waits for it before showing the product again.

### Orders

Orders come from the store's checkout: they can't be created or deleted here.

- "Mark as shipped…" asks for a tracking number and a carrier (both optional) and whether to "Email the customer". It ships everything in the order still waiting to ship.
- "Mark as paid" shows when Shopify says the order can be.
- "Archive" and "Unarchive".
- "Cancel order…" asks first. The items go back to stock and nothing is refunded: "Refunds and more in Shopify" opens the order in the admin.

### Descriptions

A product's or collection's description and a page's or post's content open in a small editor: bold, italic, heading, lists, link. "Edit the HTML" switches to the code and "Edit as text" back.

HTML that comes from the store is made safe before midcode shows it: text, links, images and tables stay, scripts and event handlers don't. If that would drop something the page needs (an embed, a video, a script, a style block), the editor opens on the HTML instead and says "It has code the editor would drop: edited as HTML", so a save never removes it without you seeing it.

### Discounts

midcode makes and edits one kind of discount: a code that takes a percentage or an amount off the whole order, with its start and end dates (typed as `YYYY-MM-DD`), "Times it can be used" and "Once per customer". Any other kind (automatic, buy X get Y, free shipping, limited to some products) is listed and can be turned on or off, and is edited in Shopify's admin.

### Collections, posts and menus

A collection Shopify fills by rules shows its rules. They're changed in Shopify's admin, and its products can't be picked by hand.

A new blog post goes in the store's first blog. If the store has none, one named "News" is made.

In a menu, a link is an address of the store (`/collections/all`, `/pages/about`) or any other (`https://…`). A link tied to a product, a collection or a page stays tied to it until you click it to type an address instead.

## How it talks to Shopify

Each read and each write is one operation on the store's Admin API (GraphQL), run by your CLI:

```bash
shopify store execute --store your-store.myshopify.com --version 2026-10 --query-file <file> --variable-file <file> --json
```

- The API version is pinned to `2026-10`. Every operation midcode sends was checked against that version's schema.
- A write adds `--allow-mutations`. Without it the CLI refuses to change anything.
- Each operation is a run of the CLI, a few at a time, which is why a list takes a moment to show.
- midcode holds no token. The session and the store's approval are the CLI's, and they're what a terminal on your Mac would use. See [Privacy and security](https://midcode.app/docs/reference/privacy.md).

## Limits

- **Order actions were never tried against a live store.** Mark as shipped, mark as paid, cancel and archive are written against the API's schema, but the store used for testing had no orders. Try them first on an order you can afford to get wrong.
- What was tried on a development store: every list and every form, and creating, editing and deleting a product (price, SKU, stock, an uploaded image, a duplicate), a collection (adding and removing a product), a customer, a discount (percentage to amount, on and off), a page, a blog post and a menu.
- Not here, and done in Shopify's admin: refunds, payments, shipping settings, variants and options, stock per location, a collection's rules, other kinds of discount, choosing a post's blog.
- Overview adds up the latest 250 orders of the last 30 days. A store with more than that shows less than its real total.
- Store shows only in a theme's project.
- Two midcode tabs on the same store share one development theme, because it belongs to the CLI.

## Troubleshooting

**The "Connect the store" card came back.** The approval lasts about a day. Click "Connect" again.

**A list shows a message and "Try again".** The message is what Shopify or the CLI answered. "Try again" asks once more. When what's missing is something midcode can ask for (a sign-in, the store, the approval), its card shows instead.

**"The Shopify CLI isn't installed on this Mac."** Store uses the same CLI as the theme: see [Install the Shopify CLI](https://midcode.app/docs/shopify/themes.md).

---

# Keyboard shortcuts

> Every key and modifier in midcode, grouped by what you're doing: tools, selection, editing, moving, the canvas, text, code and the database.

- Page: https://midcode.app/docs/reference/shortcuts
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode's shortcuts follow Framer and Figma where there's a habit to follow. Single keys (`V`, `C`, `F`) work whenever you aren't typing, in the editor and after a click inside a frame. They do nothing while a text field has the cursor, while you edit a text on the canvas, or while Settings is open.

Commands with `⌘` are also in the menu bar, under "File", "Edit", "Element" and "View".

## Tools

| Key | Action |
| --- | --- |
| `V` | Inspect: click to select. |
| `C` | Comment: click an element to pin a comment. Opens the "Comments" list. |
| `P` | Preview the site, full size and running. `P` or `Esc` comes back. |
| `F` | In a Next.js App Router project: draw a frame on the canvas. Elsewhere, and while editing a component: insert a frame. |
| `Esc` | Let go, one thing at a time: the frame tool, a picked guide, floating elements picked together, a comment being written, the open comment, the selection, the tool, the Insert or Comments panel, the component being edited. |

## Insert

These add the item at the selection, or at the end of the page when nothing is selected. See [Insert](https://midcode.app/docs/editor/insert.md).

| Key | Inserts |
| --- | --- |
| `F` | A frame, in projects where `F` doesn't draw one |
| `S` | A stack |
| `T` | A text |
| `⇧G` | A grid |
| `⇧I` | An image (asks for a file) |
| `⇧V` | A video (asks for a file) |

## Select

| Key | Action |
| --- | --- |
| Click | Select the element. |
| `⇧Click` | Add it to the selection, or take it out. On the canvas and in Layers. |
| `⌘Click` | Inside the selection: select its parent. Again for the next one up. |
| `⌘↑` | Select the parent. |
| `⌘A` | Add every sibling of the selection. With nothing selected: everything floating on the canvas. |
| Double-click | Edit a text. On a component instance: open the component. |
| `Esc` | Deselect. |

## Edit

| Key | Action |
| --- | --- |
| `⌘Z` | Undo the last edit. |
| `⇧⌘Z` | Redo. |
| `⌘C` | Copy the element: midcode keeps it for `⌘V`, and the system clipboard gets its reference (what it is and its `file:line:col`), to paste to an agent. |
| `⌘X` | Cut. |
| `⌘V` | Paste after the selection. With an image or files on the clipboard: paste those. |
| `⌘D` | Duplicate. |
| `⌫` | Delete the selection. `Delete` does the same. |
| `⇧A` | Wrap the selection in a stack. |
| `⌘;` | Hide or show the element. |
| `⌥⌘C` | Copy styles. |
| `⌥⌘V` | Paste styles. |
| `⇧⌘C` | Copy only the element's reference ("Copy Reference" in the Element menu). |
| `⌘R` | Rename the layer. |
| `⌥⌘R` | Auto rename the layer (Apple Intelligence). |

With several elements selected, `⌘C`, `⌘X`, `⌘D`, `⌫` and `⇧A` apply to all of them, and `⌘C` puts their code on the system clipboard. In files that aren't JSX, see the limits in [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md).

## Move, resize and rotate

| Key | Action |
| --- | --- |
| Arrow keys | Move a positioned or floating element 1 px. |
| `⇧` + arrow keys | Move it by the nudge amount (10 px, or what you set in Settings). |
| `⌥` while dragging | An element in the flow, or a floating one: leave a copy where you release. The element stays. In files that aren't JSX, from the next release and within the same file. |
| `⇧` while dragging | A positioned or floating element: move along one axis. |
| `⌘` or `⌃` while dragging | No snapping. Press it once the drag has started. |
| `⇧` on a corner handle | Keep the proportions. |
| `⇧` while rotating | Turn in steps of 15°. |
| `Esc` while dragging | Cancel the move. |

"Positioned" is an element placed with left and top; "floating" is one on [the free canvas](https://midcode.app/docs/editor/free-canvas.md). An element in the flow moves by dragging: see [Select, move and resize](https://midcode.app/docs/editor/select-move-resize.md).

### Padding, gap and radius handles (next release)

| Key | Action |
| --- | --- |
| `⌥` on a padding handle | Set the opposite side too. |
| `⌥⇧` on a padding handle | Set all four sides. |
| `⌥` on a radius handle | Round that corner only. |

## Canvas and view

| Key | Action |
| --- | --- |
| Scroll | Pan. |
| `Space` + drag | Pan. |
| Pinch, or `⌘` + scroll | Zoom. |
| `⌘=` | Zoom in. |
| `⌘-` | Zoom out. |
| `⌘0` | Actual size. |
| `⌘1` | Zoom to fit. `⇧1` does the same. |
| `⇧2` | Fit the first frame. |
| `R` | Show or hide the rulers and guides. `⇧R` does the same. |
| `⌫` | With a guide clicked: remove it. |
| `Esc` in the Preview | Back to the canvas. With the interface hidden: show it. |

## Text and fields

| Key | Action |
| --- | --- |
| Double-click | Edit a text in place. |
| `Enter` | Save the text. |
| `Esc` | Cancel. |
| `↑` `↓` in a number field | Add or take 1. The element changes when the keys rest. |
| `⇧↑` `⇧↓` in a number field | Add or take the nudge amount. |
| `⇧` while dragging a field's unit | Scrub in steps of the nudge amount. |
| Arrow keys on a slider | One step. With `⇧`: ten. |
| `⌥` while dragging a slider | Move in single units instead of the slider's steps. |
| `Enter` on a slider | Type a value. |

## Comments and layers

| Key | Action |
| --- | --- |
| `C` | The comment tool. |
| `⌘↵` | Save the comment you're writing. |
| `Esc` | Cancel it, or close the open comment. |
| Double-click a layer | Rename it. `Enter` keeps the name, `Esc` drops it. |
| Double-click a breakpoint in Layers | Bring its frame into view. |

## Code

In "Open code" and in the Code view. See [Code view](https://midcode.app/docs/editor/code.md).

| Key | Action |
| --- | --- |
| `⌘S` | Save the file. It's one undoable edit, listed in Publish. |
| `⌘F` | Find in the file. |
| `⌘Z` | Undo in the editor: your typing, not the project's edits. |
| `Tab` | Indent. |
| `Esc` | Close "Open code" and go back to the canvas. |
| `` ⌃` `` | Show or hide the terminal, in the Code view. |

## Agent

In the prompt of the agent's chat. See [Your agent in midcode](https://midcode.app/docs/agents/overview.md).

| Key | Action |
| --- | --- |
| `Enter` | Send. |
| `⇧Enter` | A new line. |
| `@` | Add context: the selected element, the open comments, the page, files. |
| `/` | At the start of the prompt: the agent's commands. |
| `↑` `↓`, then `Enter` or `Tab` | Choose in the `@` or `/` menu. |
| `Esc` | Close the menu, stop picking, or stop the agent while it works. |

## Database (next release)

The SQL editor:

| Key | Action |
| --- | --- |
| `⌘↵` | Run what's selected, or everything. |
| `⌘S` | Save the query. |
| `Tab` | Accept the completion. |

A table:

| Key | Action |
| --- | --- |
| Arrow keys | Move between cells. `⇧↑` and `⇧↓` jump a screen of rows. |
| `Enter`, or start typing | Edit the cell. |
| `Enter` | While editing: keep the value. |
| `Tab`, `⇧Tab` | While editing: keep it and go to the next or previous column. |
| `⌘↵` | In the editor for a long value: keep it. |
| `Esc` | While editing: drop the change. Otherwise: deselect. |
| `⌘C` | Copy the cell. |
| `⌫` | Delete the rows you picked. |
| `⌘S` | Save the waiting changes to the database. |

## The app

| Key | Action |
| --- | --- |
| `⌘N` | From the next release: a new project (the hub, with "New project" open). |
| `⌘O` | Open a folder. |
| `⇧⌘H` | Back to the projects, without closing the tab. |
| `⌘,` | Settings. |
| `Esc` | Close what's in front: Settings, a menu, the CMS, Languages or Site settings (back to the canvas). From the next release, Database and Store too. |

---

# Troubleshooting

> What to do when a project doesn't start in midcode, an element can't be edited, a style doesn't show or a push is refused, and what's in a report.

- Page: https://midcode.app/docs/reference/troubleshooting
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

Each entry here is a message midcode shows, or something you see, with why it happens and what to do. If yours isn't here, [send a report](#send-a-report): it has what it takes to find out.

## The project doesn't start

Start with the log. The button at the right of the top bar (a dot beside a terminal icon) opens it, and an error opens it by itself. Its first line is the command midcode ran:

```text
$ next dev --port 4310  (/opt/homebrew/bin/node)
```

What your dev server printed after that is usually the answer. [Open a project](https://midcode.app/docs/start/open-a-project.md) says how midcode decides what to run.

### "Dependencies are missing"

The project has a `package.json` and no `node_modules`. Click "Install with pnpm" (or npm, yarn, bun). midcode runs that install in your shell and then starts the server.

"Next.js is not in node_modules. Install the dependencies." means the same for one package: the folder is there, the framework isn't. The same button fixes it.

### "pnpm isn't installed on this Mac (or not on your shell's PATH)"

midcode runs commands the way your terminal would: it asks your shell for its `PATH`, once, and keeps the answer. A tool installed after that isn't in it yet.

1. Check that the command works in a new terminal window.
2. Try again in midcode. After a failed install it reads your `PATH` again, so a tool installed a moment ago is found.
3. If it's still not found, quit midcode and open it again.

With no Node on the Mac at all, midcode still runs your dev server with its own. It can't install dependencies, though: that needs your package manager.

### "The server stopped (code 1)" or "The server did not answer in time"

Your dev server exited, or never answered. The reason is in the log: a missing env variable, a syntax error in a config, a port your script insists on.

- Run your own `dev` script in a terminal. If it fails there too, fix that first.
- If it works in your terminal and not in midcode, [send a report](#send-a-report).

After 25 seconds of "Starting the server…" the canvas says "It's taking longer than usual" and offers the log. midcode keeps waiting: 45 seconds for its own way of starting a project, 2 minutes for your script.

### "A Next server is already running for this project"

Next.js allows one `next dev` per folder, and yours is running somewhere, usually in a terminal. midcode can't use that one: it runs without the hook that tells the canvas where each element is written.

- Click "Stop it and use midcode". midcode stops that process after checking it is a Next.js server.
- Or stop it yourself, then click "Restart" in the log.

If midcode says "Couldn't stop process …", close it yourself and try again.

### The site shows, but nothing can be edited

A message said: "midcode couldn't start this project its own way, so it runs your dev script". For Vite, SvelteKit, React Router, Remix, Astro and Nuxt projects, midcode starts the server with its plugin added. When that doesn't come up in 45 seconds it falls back to your `dev` script, so the site still shows, without the marks editing needs.

The log says what went wrong the first time. Common causes: a config that needs something only your script sets up (an env file, another process), or a version of the framework midcode doesn't know yet. Use "Send report" on that message so it can be fixed.

From the next release there's a second reason: a `.midcode/server.json` in a Next.js, Vite, Astro, Nuxt, SvelteKit, React Router or Remix project. With it the site runs the project's own way, with no marks. Delete the file, then click "Restart" in the log.

### "Vite is running, but the site isn't answering at …"

A Laravel app. Vite only builds its assets; the pages come from PHP at the `APP_URL` of your `.env`. Start the site (Herd, Valet, or `php artisan serve`) and click "Try again". If `APP_URL` is a plain `http` address on this Mac, midcode starts `php artisan serve` itself, which needs `php` on your `PATH`.

### A port is taken

midcode doesn't use your usual port. It picks the first free one from 4310 up, so it runs beside whatever you have on 3000 or 5173. "No free ports" means the hundred ports from 4310 are all taken, which points at dev servers that never stopped: quit them.

A `dev` script with a fixed port is different: if that port is busy the script fails, and what it printed is in the log. Stop the other copy. From the next release, a script that only calls a tool that takes `--port` (rsbuild, rspack, webpack, vue-cli-service, docusaurus, gatsby, parcel, vitepress, vuepress, eleventy) and names no port is started on midcode's port, so it no longer lands on the tool's usual 3000, 8000 or 8080.

### "How does this site run?" (next release)

midcode couldn't tell how to serve the folder. Give it a command, an address, or both, and click "Start". On any failed start, "Change how it runs" opens the same form. [Any other stack](https://midcode.app/docs/frameworks/custom-server.md) has examples for each stack.

"Nothing answers at …" means the address you gave isn't serving. Start the site, or fix the address.

## Send a report

Wherever a start fails or drags on, there are two buttons:

- "Send report" opens the feedback form with what happened already written. Add what you were doing, and your email if you want an answer.
- "Copy report" puts the same text on the clipboard, to paste in an email to `hello@midcode.app` or in an issue at `github.com/agusdellaquila/midcode/issues`.

"Feedback" at the top of the window sends a message at any time, with the same details unless you untick them.

### What a report contains

The form shows the whole report before it goes: click "What's sent".

| In it | Never in it |
| --- | --- |
| Your Mac's model, chip, memory, macOS version and system language | Your source files, other than the dev config below |
| midcode's version and its own recent errors | Values from `.env` (only a Laravel app's `APP_URL`) |
| The project's name and folder, the framework, package manager and Node, with versions | Tokens, keys and passwords midcode stores |
| Your `package.json` scripts and dependency list | The path of your home folder: it's written `~` |
| The names of the files at the top of the project | |
| Your dev config files, whole: `vite.config`, `next.config`, `svelte.config`, `astro.config`, `nuxt.config`, `react-router.config` and `remix.config` at the project's root, up to 6,000 characters each | |
| Your shell's `PATH` | |
| The dev server's log, whole | |

> [!NOTE]
> The log is what your dev server printed, and a config file goes as it's written. If your server prints something private, or a config has a key in it, it's in the report, so read it before you send it.

## An element can't be selected or edited

### The whole project is view-only

The right panel says so, for example "Nuxt: preview and comments". midcode has no marks for this stack, so it shows the site and lets you comment, and that's all. [What works with what](https://midcode.app/docs/start/supported-stacks.md) says which stacks are edited, and which arrive in the next release.

### "A library draws this element"

The element comes from a package in `node_modules`, so it isn't written in your files. Select its parent, or the component that uses it.

### "This text isn't written there: it comes from a variable or prop"

The text is computed, or passed in from somewhere midcode couldn't follow. midcode edits text that's written out: in the markup, or as a string in a data file. Use "Open code" and change it there, or ask your agent. [Code that midcode can edit](https://midcode.app/docs/agents/editable-code.md) says how to keep text editable.

"That text appears in 3 places (…)" means the same words are written in several files and midcode won't guess which one this element shows.

### "The class … isn't written in …: it comes from a prop or a condition"

The class you're changing isn't written out as text in that element's `className`. It's built by code (`text-${size}`), comes from a prop or a constant, or is looked up (`SIZES[size]`). A class that is written inside a condition (`active && 'bg-black'`, a branch of a ternary, a `clsx({ … })` key) doesn't give this message: midcode takes it out of that branch and writes the new class unconditionally. "This element's classes come from a variable" is the same for a whole `className={className}`. Edit those in the code. See [Tailwind CSS](https://midcode.app/docs/styling/tailwind.md).

### "Couldn't find the element at … (did the file change?)"

The file was saved, by you or your agent, and the canvas hasn't reloaded yet, so the element isn't on the line the page remembers. Wait for the reload and do it again. "The text in the code doesn't match the preview" is the same thing for text. If it doesn't go away, reload the breakpoints from the top bar.

### "This is written in Markdown" (next release)

In a Hugo, Jekyll or Eleventy site, a heading, a paragraph or a list item of a `.md` file is found by its words. You can change those words, turn a heading into another level or into a paragraph, and remove it. It has no tag to hang a class or an attribute on, and it can't be moved or have elements inserted: "its words can be changed here, not its classes or attributes. Style it from the template around it." See [Hugo, Jekyll and Eleventy](https://midcode.app/docs/frameworks/static-generators.md).

### "Item 3 of a list: editing the code changes all of them"

Not an error. One line of code draws every item of a `.map()`, so a class changed on one changes them all. The text of each item is edited on its own when it's written in your data.

## Pages and Site settings

### There's no plus beside "Pages", or no globe in the top bar

In the released version, new pages and [Site settings](https://midcode.app/docs/editor/site-settings.md) are for Next.js projects. From the next release:

- The plus shows where midcode knows how the framework keeps a page: Next.js, Astro, SvelteKit, Nuxt with a `pages/` folder, plain HTML, Remix, React Router, TanStack Router, Qwik City, Hugo, Jekyll, Eleventy and Laravel. Where pages are code (a Vite app without file routes, Angular, Django, Rails, Flask), make the page in code or ask your agent. [Pages and navigation](https://midcode.app/docs/editor/pages.md) has what each one writes.
- The globe shows where the site's `<head>` is written in a file: `index.html`, `src/app.html`, `public/index.html`, an Astro layout, a server-rendered site's layout. Nuxt and Docusaurus keep those settings in their config file, and midcode writes them there. WordPress keeps them in its database and Gatsby in its own config, which midcode doesn't write: Site settings isn't for them yet. Neither is it for a project whose `<head>` is built in code, such as React Router or Remix with a `root.tsx`.

### "This is written in code here: change it in …" (next release)

Outside Next.js, Site settings writes tags in your `<head>`. A title or description the template computes (`{{ .Site.Title }}`, `@yield('title')`, `%VITE_APP_TITLE%`) is shown as code and left to the code: click "Open code" and change it there.

## A style doesn't show

### In a project without Tailwind 4

midcode writes the CSS for its `mid:` classes to `midcode.css`, and that file has to be imported in your app. midcode adds the import itself. When it can't tell where, it says: "midcode added midcode.css but couldn't tell where to import it. Import it in your app's entry so its styles show."

```tsx title="src/main.tsx"
import './midcode.css'
```

[Without Tailwind](https://midcode.app/docs/styling/without-tailwind.md) lists where the import goes in each framework.

### On the deployed site, not on the canvas

`midcode.css` wasn't published, or it's out of date because classes were written outside the app. Commit it with your changes, or build it in your pipeline with [the midcode package](https://midcode.app/docs/styling/package.md). The package needs `.midcode/theme.css` in the repository for your colors, fonts and text styles, and Publish doesn't tick that file by default: tick it. Version 0.1.0 of the package doesn't read classes written in server templates (`.liquid`, `.php`, `.erb`, `.twig` and the like): for those sites, publish the `midcode.css` the app wrote.

## Undo says the file changed

"The file changed outside midcode, so that edit can't be undone". midcode only undoes an edit when the file is exactly as that edit left it. Something else wrote to it since: your editor, a formatter on save, your agent. Nothing is lost. Undo that part in your editor, or with git.

The undo history is kept until you quit midcode. [How midcode works](https://midcode.app/docs/start/how-it-works.md) has the rules.

## Publish

### "None of your GitHub accounts (…) can push to …"

Before a push to GitHub, midcode asks each account it knows whether it can push to that repository: the one connected in Settings, then every account logged in to the GitHub CLI. None of them can. Log in with the one that has access:

```bash
gh auth login
```

That adds the account and keeps the others. Then click "Try the push again". The commit was already made and is safe locally. After a push that worked, Publish says which account it went out as ("as …"). [GitHub](https://midcode.app/docs/publish/github.md) explains how the account is chosen.

### "Committed", not "Published"

The commit was made and the push failed, or the repository has no remote. The panel says why and offers "Try the push again"; the next time you open Publish, "Push" sends what's waiting. midcode never forces a push.

### "git isn't installed on this Mac"

Publishing needs git. Install Apple's command line tools, then open Publish again:

```bash
xcode-select --install
```

"This project doesn't use git" means the folder isn't a repository. Everything else in midcode works without one.

## Shopify (next release)

### "The storefront's password"

Every development store sits behind a password, and the Shopify CLI can't ask for it from inside midcode, so midcode asks. It's in the store's admin, under Online Store → Preferences. midcode keeps it encrypted on your Mac, never in the project.

"Shopify didn't take that password": check it and type it again. A wrong password also makes the CLI forget the one it remembered from your terminal.

### "Connect the store" comes back

The Store view works through the Shopify CLI's approval in the store's admin, and Shopify's token lasts about a day. Click "Connect" and approve again. See [Store](https://midcode.app/docs/shopify/store.md).

## A database opens read-only (next release)

The table says it's read-only, and to turn on "Allow changes". A database that isn't on this Mac opens without permission to change anything. That's on purpose: it may be the one your live site uses.

Turn on "Allow changes" beside the connection. It lasts for the session. A database on this Mac (a SQLite file, a Postgres on `localhost`) allows changes from the start. See [Database](https://midcode.app/docs/data/database.md).

## The app itself

### midcode doesn't update

It only updates itself from the Applications folder. If you run it from the disk image or from Downloads, it shows "Move midcode to Applications"; if you dismissed that, drag midcode to Applications in Finder and open it from there.

### The license key is refused

| Message | What to do |
| --- | --- |
| "Couldn't reach the license server. Check your connection and try again." | Activating needs a connection. |
| "This key is already active on 3 Macs." | Free one: "Deactivate" in Settings on a Mac you no longer use, or the Polar customer portal linked in your order email. |
| "That license key didn't work. Check it and try again." | Paste the whole key, as it is in your email. |
| "That key is for another product, not midcode." | It's a key from another purchase. |

See [Install and license](https://midcode.app/docs/start/install.md).

### "midcode needs a license or a trial to edit."

The trial ended, or a license hasn't reached the license server in 30 days. Connect and open midcode again, or paste your key.

---

# Privacy and security

> What midcode keeps on your Mac, every place it connects to and what it sends there, where tokens and keys are stored, and how the app is protected.

- Page: https://midcode.app/docs/reference/privacy
- From the midcode docs. Every page as Markdown: https://midcode.app/llms.txt

midcode is a desktop app that edits files on your Mac. There's no midcode account, no server that sees your projects, and no analytics or telemetry in the app. Your code is read and written locally. What leaves the Mac is listed on this page: every destination, when it's contacted, and what's sent.

## What stays on your Mac

- **Your code and every edit.** midcode reads your files to find where to write, writes the change, and that's all. Nothing is uploaded to be edited.
- **Your site.** The canvas shows your own dev server, running on this Mac.
- **Comments, layer names, breakpoints and the rest of `.midcode/`**: files in your project. See [What midcode adds to your project](https://midcode.app/docs/start/project-files.md).
- **The list of changes, recent projects, thumbnails and settings**: in `~/Library/Application Support/midcode`.
- **Layer naming and translation with Apple Intelligence.** They use Apple's on-device model through a small helper inside the app. midcode sends nothing anywhere for them, and they work offline.

midcode also turns off the telemetry of the dev servers it starts, where they have a switch: Next.js and Astro. From the next release it does the same for the Angular and Shopify CLIs, and for the tools [New project](https://midcode.app/docs/start/new-project.md) runs.

## What goes out, and when

| Destination | When | What's sent |
| --- | --- | --- |
| `www.midcode.app` | You start the trial | The email you typed and midcode's version. Sent again at launch until it arrives. |
| `api.polar.sh` | You activate a key; then about once a day; when you deactivate | The license key, this Mac's name (as the label of the activation) and midcode's version. |
| GitHub Releases (`agusdellaquila/midcode`) | A few seconds after launch and every 4 hours | A request for the release feed, then the download of the new version. Nothing about you. |
| `midcode.app` | You send feedback or a report | Your message, your email if you gave one, and the report if you left it ticked. It's shown before it goes. |
| `api.iconify.design` (and its mirrors `api.simplesvg.com`, `api.unisvg.com`) | You browse or search icons and stickers | The set you opened or the words you searched. Results are cached on your Mac. |
| `github.com`, `api.github.com` | You connect GitHub, and before a push to a GitHub repository | The token, to read your account's name and to ask whether it can push to that repository. |
| `api.vercel.com` | You connect Vercel, and after each publish while it's connected | The token, and the repository's address or the linked project's id, to find the deploy that push started. |
| Your git remote | You publish | The commit, through your own `git`. |
| `api.anthropic.com` | You save an Anthropic API key for the agent chat | The key, once, to check that it works. |
| The npm registry | You install dependencies, or start the Claude Code or Codex chat | Whatever `npm` and `npx` send to fetch packages. |

In the next release:

| Destination | When | What's sent |
| --- | --- | --- |
| Shopify | You open a theme or the Store view | Everything goes through Shopify's own CLI, signed in as you: the theme's files to your store, and Admin API requests. An image you add to a product is uploaded to the address Shopify gives for it. |
| Your database's host | You open Database | A direct connection from your Mac, with the connection string from your `.env` or the one you typed. |
| Package registries | You make a [new project](https://midcode.app/docs/start/new-project.md) | `npx`, `composer` and `pip` fetch the framework's tool and its packages. |

Three more things connect, and none of them is midcode talking to a server of its own:

- **Your dev server** does whatever your site does: its API calls, its fonts, its images.
- **Your agent** talks to its provider with your account. See [below](#your-agent).
- **Links** midcode opens (the changelog, the checkout, a token page) go to your browser, never inside the app.

## Where secrets are kept

Secrets are stored in `~/Library/Application Support/midcode`, encrypted with a key from your macOS Keychain, and never inside a project.

| Secret | File | Sent to |
| --- | --- | --- |
| License key | `license.bin` | Polar's license server |
| GitHub and Vercel tokens | `accounts.json` (the token encrypted, the account name readable) | GitHub and Vercel, and the `git push` to your GitHub remote |
| Anthropic API key for the agent chat | `agent-keys.bin` | The agent process, as `ANTHROPIC_API_KEY` |
| Database connections you add by hand (next release) | `data-connections.bin` | That database |
| A Shopify storefront's password (next release) | `shopify.bin` | The Shopify CLI, for `shopify theme dev` |

Things to know:

- If the Keychain isn't available, midcode refuses to store GitHub and Vercel tokens. The other files are then saved unencrypted, readable only by your user.
- "Use my GitHub CLI login" and "Use my Vercel CLI login" read the token those CLIs already have. Before a push, midcode also asks the GitHub CLI for the tokens of the accounts logged in to it, to find one that can push. Those stay in memory until you quit and are never written to disk.
- For a Shopify store's Admin API, midcode keeps no token at all. The Shopify CLI holds the session.
- A connection string that's in your `.env` stays there. midcode reads it each time and saves no copy.

## What the window never gets

midcode has two parts: the main process, which reads files, runs commands and holds secrets, and the window you see. The window is treated as the less trusted one, because your site runs inside it.

- **Tokens, API keys and passwords** never reach the window. It's told that GitHub is connected and as which account, never the token.
- **Database connection strings** never reach it either. It knows where a database is (host, port, name), never how to get in. They aren't put in reports or handed to the agent.
- **Values of environment variables.** The [Environment variables](https://midcode.app/docs/data/env.md) view knows whether a variable is set, not what it holds. A value you type is written to the file and forgotten.
- **Paths.** The window asks for changes by project, and the main process checks that every file it writes is inside that project's folder.
- **Your site can't talk to the main process.** Every request is checked to come from midcode's own page; one from a frame of the canvas is refused.

A value you type into a field (a token, a connection string, a password) passes through the window once, on its way in.

## Your agent

The [Agent tab](https://midcode.app/docs/agents/overview.md) runs an agent you already have (Claude Code, Codex, Gemini CLI, OpenCode, Cursor) as a program on your Mac, in your project's folder, signed in with your account. midcode shows the conversation, but it isn't in the middle of the agent's traffic, and none of it goes to midcode. What the agent sends to its provider is between you and that provider.

- midcode gives the agent what you send it: your message, attachments, and the references you picked (an element, a comment, a CMS item).
- A database table or row goes to the agent only if you pick it. A connection string never does.
- In the chat, midcode answers the agent's requests to read and write files only for files inside the project, and shows its permission requests for you to answer.
- The agent is still a program running as you, with its own tools. Its own permission settings decide what else it can do.

## The canvas and your site

- The window frames one thing: your dev server. In the released version that means addresses on this Mac. From the next release a site can live on another host (`app.test`), and a frame is allowed only when it's the site of a project you opened.
- A site may forbid being framed (`X-Frame-Options`, `frame-ancestors`). midcode removes that for your dev server's address only.
- A dev server's self-made `https` certificate is accepted for `localhost`, `127.0.0.1` and `*.localhost` only. Every other host is checked like any site.
- A link in your site that tries to take over the window opens in your browser instead.
- midcode's own interface runs no script from the network. Its Content Security Policy allows scripts and styles from the app only.

## Edits and the trial

- The main process refuses every write without a license or a running trial. The paywall isn't the only lock.
- The trial's start date is kept in three places, so deleting midcode's folder doesn't restart it: `license.bin`, the file `~/Library/Preferences/app.midcode.trial`, and a Keychain item named `app.midcode`. The last two hold a date and nothing else.
- midcode remembers the latest time it has seen, so setting the clock back doesn't extend a trial.

## The app

- **Signed and notarized.** Releases are built, signed and notarized in CI and published to the public repository `agusdellaquila/midcode`. The source is not public.
- **Updates are verified.** The updater checks the signature of what it downloaded before installing it.
- **It only runs its own code.** The app loads only the bundle it was signed with; a changed one doesn't start.
- **No debugger.** The released app has no developer tools and quits if started with a remote debugging or inspector flag.
- **A sandboxed window.** The window runs sandboxed and isolated from Node, and reaches the main process only through a fixed list of calls.

## What a report contains

"Send report", "Copy report" and the Feedback form send the same text, and the form shows it before it goes. It has your Mac's model, how the project is set up, the project's dev config files whole (`vite.config`, `next.config`, `svelte.config`, `astro.config`, `nuxt.config`, `react-router.config` or `remix.config` at its root, up to 6,000 characters each) and the dev server's whole log. It never has any other source file, `.env` values or secrets. The full list is in [Troubleshooting](https://midcode.app/docs/reference/troubleshooting.md).

## Limits

- midcode starts tools that aren't its own: your package manager, your framework's dev server, `git`, `npx`, the Shopify CLI, your agent. Each of them has its own network behavior and its own privacy policy.
- The dev server log and the dev config files are part of a report. If your server prints a secret, or a config file has one written in it, the report has it: read it before sending.
- Avatars of your GitHub and Vercel accounts are loaded from those services when Settings is open.
- Anyone with access to your Mac user account can read midcode's folder. The encrypted files need your Keychain to open.

---

# Integrations

## midcode + Next.js

URL: https://midcode.app/integrations/nextjs
Status: Available

midcode is a macOS app that opens a Next.js project on a live canvas and edits it visually. It starts your own next dev, shows the site at every breakpoint, and writes each change (text, Tailwind classes, images, layout, new sections) into your .tsx files as a minimal diff. There is nothing to install in the project and no config to change.

- Status: Available, the most complete
- Edits: .tsx and .jsx files
- Runs: Your own next dev
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Styles from your Tailwind theme: Type, color, spacing and radius come from your @theme tokens. midcode swaps classes in place, per breakpoint, per hover state, per variant.
- Components with variants and states: Open a component on its own canvas: variants as columns, Hover, Pressed and Focus as rows. Props are read from your TypeScript types and edited in the panel.
- Pages and site settings: Create, reorder and remove pages. Titles, descriptions, icons and social images are written as Next metadata: export const metadata, or generateMetadata on a dynamic route.
- Build with the Insert panel: Frames, stacks, grids, text, forms, whole sections and icons, each with a real preview. Drag one in and it’s written into your code.

### How it works

1. Open the project folder: midcode starts next dev for you, with a loader that tags every JSX element with its file and line. The loader is added in memory when the server starts: your next.config stays as it is.
2. Edit on the canvas: Click, double-click, drag. Each change is written to the file as you make it, Fast Refresh shows it on every breakpoint, and ⌘Z undoes it.
3. Publish: Review the changed files, then commit and push in one step. On a repository connected to Vercel, that push is a deploy.

### What it doesn't do

- macOS only.
- Text that comes from a variable or a fetch is edited where the string lives: midcode finds it in your arrays and data files, but not in a remote API.

### Coming next

- A table and SQL editor for the database behind the site (Postgres and SQLite first).

### Questions

**Does midcode change my next.config or add a dependency?**
No. midcode starts next dev with its own loader added in memory. Your next.config, your package.json and your lockfile are not touched. The only folder it creates is .midcode, for comments and layer names, which you can commit or ignore.

**Does it work with Server Components?**
Yes. midcode edits the source files, so it doesn’t matter whether a component renders on the server or the client. In a client component, page metadata goes in a layout beside it.

**What does the diff look like?**
Only the lines you changed. midcode never reformats or reprints a file: a text edit is the new string, a style edit is the classes that changed.

**Do I need Tailwind?**
No. With Tailwind CSS 4, midcode writes your own utility classes. Without it (plain CSS, CSS modules, Tailwind 3), it writes its own prefixed utilities and compiles them to a plain CSS file in your project.

---

## midcode + React + Vite

URL: https://midcode.app/integrations/react
Status: Available

midcode opens a Vite project written in React, Preact or Solid on a live canvas and edits its JSX visually. It starts Vite with your own config plus one plugin of its own, so you see your real app at every breakpoint, and each change to text, classes, images or layout is written into the component’s file.

- Status: Available
- Edits: .tsx and .jsx files
- Runs: Vite, with your config
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Components with variants and states: Edit a component alone on its own canvas: variants as columns, Hover, Pressed and Focus as rows. Turn a text, an image or a color into a prop with one click.
- Build with the Insert panel: Frames, stacks, grids, text, forms, whole sections and icons, each with a real preview. Drag one in and it’s written into your code.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.

### How it works

1. Open the project folder: midcode starts Vite with a config of its own that loads yours and adds one plugin, the one that tags each JSX element with its file and line. That config lives outside your project.
2. Edit on the canvas: Each change is written to the file as you make it. Vite’s hot reload shows it on every breakpoint.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Creating pages and editing site metadata from the app are Next.js only for now.
- A project that needs its own start (env files, another process, a fixed port) starts with your dev script instead, and midcode says so in the log.

### Questions

**Does midcode edit my vite.config?**
No. midcode writes a small config of its own, outside your project, that imports your vite.config and adds one plugin. Your file is never modified.

**Does it work with Preact and Solid?**
Yes. Any Vite project that writes its interface in JSX is edited the same way, in its .tsx or .jsx files.

**What if my app isn’t styled with Tailwind?**
It’s edited all the same. midcode writes its own prefixed utilities (mid:p-6, mid:md:flex) and compiles them to a plain CSS file imported next to your app’s entry. Your own classes are never touched.

---

## midcode + React Router

URL: https://midcode.app/integrations/react-router
Status: Available

midcode opens a React Router project on a live canvas, with each route as a page you can go to. It runs the project’s dev server with your own Vite config plus one plugin, and writes every edit to text, classes, images and layout into the route or component file it belongs to.

- Status: Available
- Edits: .tsx and .jsx files
- Runs: Your dev server, on Vite
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Build with the Insert panel: Frames, stacks, grids, text, forms, whole sections and icons, each with a real preview. Drag one in and it’s written into your code.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.

### How it works

1. Open the project folder: midcode reads your routes, starts the dev server with your Vite config and its own plugin, and lays out every breakpoint.
2. Edit on the canvas: Move between routes from the top bar. Each change is written to the file as you make it.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Creating routes and editing meta from the app are Next.js only for now: you write those in code, or ask your agent.

### Questions

**Where do styles go when the app has no Tailwind?**
In a midcode.css file next to root.tsx, imported there. It holds the plain CSS for the utilities midcode wrote, and nothing else in your styles changes.

**Does it work with loaders and actions?**
Yes, they run as they always do: the canvas shows your real app from your real dev server. midcode edits the markup, and the text that’s written in your files.

---

## midcode + Remix

URL: https://midcode.app/integrations/remix
Status: Available

midcode opens a Remix project that runs on Vite and edits it on a live canvas. Your routes are the pages, your loaders run as usual, and every change to text, classes, images or layout is written into the JSX of the route or component as a minimal diff.

- Status: Available
- Edits: .tsx and .jsx files
- Runs: Your dev server, on Vite
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Build with the Insert panel: Frames, stacks, grids, text, forms, whole sections and icons, each with a real preview. Drag one in and it’s written into your code.
- Undo for every edit: Each change is one entry in the history and one line in Publish. ⌘Z takes it out of the file again.

### How it works

1. Open the project folder: midcode starts the dev server with your Vite config and one plugin of its own, kept outside the project.
2. Edit on the canvas: Click, double-click, drag. Each change lands in the file and shows on every breakpoint.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Remix on the classic compiler (before Vite) opens to view and comment, without editing.

### Questions

**Do I have to move to React Router first?**
No. A Remix app on Vite is edited as it is. If you do move later, midcode opens the React Router project the same way.

**Does midcode change how my app builds?**
No. The plugin that tags elements only runs in the dev server midcode starts. Your build, your config and your dependencies stay the same.

---

## midcode + SvelteKit

URL: https://midcode.app/integrations/svelte
Status: Available

midcode opens SvelteKit and Vite + Svelte projects on a live canvas and edits their .svelte files directly. It reads each component with the Svelte compiler your project already has, so text, static classes, attributes, new elements and reordering are written exactly where they live in the markup.

- Status: Available
- Edits: .svelte files
- Reads with: Your project’s Svelte compiler
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Props in the panel: The props a component declares with $props() show up as controls on each place it’s used.
- Insert, as Svelte: What you drag in from the Insert panel is converted to Svelte markup before it’s written: class, not className.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.

### How it works

1. Open the project folder: midcode starts the dev server with a plugin that runs before Svelte’s own and tags each element with its file and line.
2. Edit on the canvas: Each change is written into the .svelte file and shows on every breakpoint.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- The component canvas with variants and states, and turning a value into a prop from the canvas, are JSX only for now.
- A class that’s computed in an expression is left alone: midcode edits the static ones.

### Questions

**Which Svelte version does it need?**
midcode uses the svelte/compiler installed in your project to read your files, so it follows the version you’re on. Props are read from $props().

**Where do images and stickers go?**
Into static/, SvelteKit’s public folder, with the reference rewritten in the markup.

**What about styles in a <style> block?**
They keep working. midcode’s panel writes utility classes on the element: your Tailwind classes, or its own prefixed ones compiled to a CSS file imported in +layout.svelte.

---

## midcode + Astro

URL: https://midcode.app/integrations/astro
Status: Next release

midcode opens an Astro project on a live canvas and edits the markup of its .astro files: text, classes, attributes, new elements and their order. The frontmatter and anything in { } stay exactly as you wrote them. It runs astro dev with one Vite plugin of its own, and your astro.config is not modified.

In the current version: Today’s version opens Astro projects on the canvas and edits their React and Svelte islands. Editing the .astro files themselves ships with the next release.

- Status: .astro editing in the next release
- Edits: .astro files, and your islands
- Runs: Your own astro dev
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.
- Undo for every edit: Each change is one entry in the history and one line in Publish. ⌘Z takes it out of the file again.

### How it works

1. Open the project folder: midcode starts astro dev with one Vite plugin that tags each element in your .astro files with its file and line.
2. Edit on the canvas: Each change is written into the markup. What’s between --- and what’s inside { } is never rewritten.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Text that an expression produces ({title}) is edited where the value is written, not on the canvas.
- An element that an expression returns (inside a .map, a condition) can be restyled, but not moved or removed.
- Dragging in something that needs an import isn’t there yet for .astro files.

### Questions

**Does midcode edit Markdown and MDX content?**
Yes, from the CMS view: a folder of .md or .mdx files with front matter shows up as a collection, and each field is edited in the file.

**What happens with islands?**
A React, Preact, Solid or Svelte island is edited in its own file, like in any other project of that framework.

**Where do styles go without Tailwind?**
In a midcode.css file imported from the frontmatter of each layout. It holds the plain CSS for the classes midcode wrote.

---

## midcode + Vue

URL: https://midcode.app/integrations/vue
Status: Next release

midcode opens a Vite + Vue project on a live canvas and edits the <template> of its single-file components: text, classes, attributes, new elements and their order. Your <script> and anything in {{ }} are left exactly as written. It runs Vite with your config and one plugin of its own.

In the current version: Today’s version opens Vue projects to check every breakpoint and leave comments for your agent. Editing on the canvas ships with the next release.

- Status: Editing in the next release
- Edits: The template of .vue files
- Runs: Vite, with your config
- Adds to your project: Nothing

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.
- Undo for every edit: Each change is one entry in the history and one line in Publish. ⌘Z takes it out of the file again.

### How it works

1. Open the project folder: midcode starts Vite with a config of its own that loads yours and tags each element of your templates with its file and line.
2. Edit on the canvas: Each change is written into the template. Hot reload shows it on every breakpoint.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Text that comes from {{ }} is edited where the value is written, not on the canvas.
- A component’s props aren’t edited from the panel yet: you select its elements, not the instance.
- Dragging in something that needs an import isn’t there yet for .vue files.

### Questions

**Does it work with the Composition API and <script setup>?**
Yes. midcode edits the template and doesn’t read or rewrite your script, so it works with either style.

**Does it edit classes bound with :class?**
It edits the static class attribute. A :class binding is an expression, and midcode leaves expressions alone.

---

## midcode + Nuxt

URL: https://midcode.app/integrations/nuxt
Status: Next release

midcode opens a Nuxt project on a live canvas and edits the templates of its pages, layouts and components. It starts the Nuxt dev server with a layer of its own that tags each element with its file and line, so your nuxt.config isn’t touched, and every change is written into the .vue file it belongs to.

In the current version: Today’s version opens Nuxt projects to check every breakpoint and leave comments for your agent. Editing on the canvas ships with the next release.

- Status: Editing in the next release
- Edits: The template of .vue files
- Runs: nuxi dev, with a layer added
- Tried with: Nuxt 4

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.
- Undo for every edit: Each change is one entry in the history and one line in Publish. ⌘Z takes it out of the file again.

### How it works

1. Open the project folder: midcode starts nuxi dev extended with its own layer, kept outside your project.
2. Edit on the canvas: Each change is written into the template and shows on every breakpoint.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Text that comes from {{ }} is edited where the value is written, not on the canvas.
- Component props aren’t edited from the panel yet.

### Questions

**Does midcode change my nuxt.config?**
No. What midcode needs comes from a Nuxt layer it passes when it starts the dev server. Your config and your modules stay as they are.

**Where do styles go without Tailwind?**
In a midcode.css file imported from app.vue, with the plain CSS for the classes midcode wrote.

---

## midcode + Plain HTML

URL: https://midcode.app/integrations/html
Status: Next release

midcode opens a folder of .html files, with no framework and no build step, and edits it on a live canvas. It serves the folder itself and reloads when a file changes. Text, classes, attributes, images and the order of elements are written into the .html file, with the rest of the file left byte for byte as it was.

In the current version: Today’s version opens HTML sites to check every breakpoint and leave comments. Editing on the canvas ships with the next release.

- Status: Editing in the next release
- Edits: .html files
- Runs: midcode’s own static server
- Needs: No Node, no build

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.
- Undo for every edit: Each change is one entry in the history and one line in Publish. ⌘Z takes it out of the file again.

### How it works

1. Open the folder: midcode serves it on your Mac and lists every .html file as a page.
2. Edit on the canvas: Each change is written into the file. The page reloads on every breakpoint.
3. Publish: If the folder is a git repository, review what changed, then commit and push in one step.

### What it doesn't do

- Markup that a script builds in the browser is edited in that script, not on the canvas.

### Questions

**How does it style a site with no Tailwind?**
midcode writes its own prefixed utilities on the element (mid:p-6) and keeps a midcode.css at the root of the site with their plain CSS. Each page gets one <link> to it. Your own stylesheets aren’t edited.

**Does it tidy or reformat my HTML?**
No. midcode’s reader is tolerant on purpose: unclosed tags and odd markup stay as they are, and only the range you edited changes.

---

## midcode + Laravel

URL: https://midcode.app/integrations/laravel
Status: Next release

midcode opens a Laravel app on a live canvas and edits its Blade views: text, classes, attributes, new elements and their order, written into the .blade.php file. Your {{ }} output, @directives and PHP blocks are left exactly as written. midcode serves the app with PHP’s own server and tags the views as Blade compiles them, without changing a file in the project.

In the current version: Today’s version shows a Laravel app that uses Vite at its APP_URL, to check every breakpoint and leave comments. Editing Blade views ships with the next release.

- Status: Blade editing in the next release
- Edits: .blade.php views
- Needs: PHP on your Mac
- Tried with: Laravel 13, PHP 8.5

### What it does

- Click to code: Select any element and read where it’s written: the file and the line. Copy that reference into your agent, or open the file on that line.
- Edit text in place: Double-click a heading, a button or a paragraph and type. The new text replaces the old one in the file, and nothing else in it changes.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Routes as pages: The GET routes in routes/web.php are the pages you move between from the top bar.
- Swap images and video: Drop a new image on an element, or paste one with ⌘V. midcode copies the file into your project and rewrites the reference.
- Drag to reorder: Move an element before, after or inside another one, on the canvas or in Layers. The markup moves in the file, with the comment above it.

### How it works

1. Open the project folder: midcode serves the app the way artisan serve does, with one file loaded first that has Blade hand each view over to be tagged. Compiled views go to a folder of midcode’s, not to storage/.
2. Edit on the canvas: Each change is written into the view. The page reloads when anything in resources/ changes.
3. Publish: Review what changed, then commit and push in one step.

### What it doesn't do

- Text that PHP prints ({{ $title }}) is edited where the value is written, not on the canvas.
- Blade components (<x-card>) and Livewire components are shown, and edited in their own view: the instance itself isn’t selectable yet.
- Not tried yet with Herd, Livewire or Inertia.

### Coming next

- The database behind the app: its tables and SQL, read from the DB_* values in your .env.

### Questions

**Does midcode change my Laravel project to do this?**
No. The tags are added while Blade compiles, by a file PHP loads before your app, and the compiled views are kept outside the project. Nothing in vendor/, storage/ or your views is modified until you edit something.

**Does it work with Vite and Tailwind?**
Yes. With Vite, midcode runs it beside the app. With Tailwind CSS 4 the panel writes your own utilities. Without Tailwind it writes its own prefixed ones.

**What if PHP isn’t installed?**
The app still opens if something is already serving it at its APP_URL (Herd, Valet): you can check breakpoints and comment. Editing Blade needs php on your PATH.

---

## midcode + Shopify

URL: https://midcode.app/integrations/shopify
Status: Next release

midcode opens a Shopify theme folder on a live canvas and edits its code visually. Click anything on your store’s preview to see the Liquid file and line it comes from, change text, classes, images and layout, and the edit is written into your theme’s files: the .liquid markup, or the JSON template and locale file where the text really lives. It runs the Shopify CLI’s theme dev against your own store.

In the current version: Today’s version edits Next.js, React, React Router, Remix and SvelteKit projects. Shopify themes ship with the next release, and every update is included in the license.

- Status: Next release
- Edits: .liquid, templates/*.json, locales/*.json
- Needs: Shopify CLI and a store
- Tried with: Dawn, on a development store

### What it does

- Click to Liquid: Select any element on your storefront and read the section or snippet it’s written in, with the line. On Dawn’s home page that’s 488 elements you can click.
- Edit text where it lives: A theme’s text is rarely in the .liquid file. Double-click a heading and midcode finds the string in templates/*.json or locales/*.json and changes it there.
- Every breakpoint at once: Your site runs live at Desktop, Tablet and Phone, side by side, at full page height. A style set on one breakpoint is written for that breakpoint.
- Style without touching the theme’s CSS: The panel writes its own prefixed utilities on the element and keeps their plain CSS in assets/midcode.css, loaded from layout/theme.liquid. The theme’s own styles stay as they are.
- Changes show in about two seconds: Each edit is uploaded to your development theme by the Shopify CLI and the preview reloads.
- Your agent, on the same files: Point at a product card and ask Claude Code or Codex to rebuild it. Its changes show on the canvas as they land, each one a diff you can undo.

### How it works

1. Open the theme folder: The one with layout/theme.liquid. midcode asks for your store once and runs shopify theme dev on a tagged copy, so your own files are never tagged.
2. Edit on the canvas: Click, double-click, restyle. Each change is written to the theme file as a minimal diff, and undone with ⌘Z.
3. Publish: Review what changed, then commit and push. A theme connected to GitHub in Shopify updates from that push.

### What it doesn't do

- It edits theme code. Products, collections, orders and the rest of your store’s data stay in the Shopify admin.
- What Liquid prints ({{ product.title }}) is data from your store: it’s shown, not edited.
- {% schema %} blocks are left whole. Section settings are still edited in the theme editor, or in the JSON.
- A password-protected storefront needs the password once: run the command in a terminal, or add --store-password.

### Coming next

- Section and block settings from the panel.

### Questions

**Can I edit my Shopify store visually with midcode?**
You can edit your store’s theme: the Liquid, JSON and CSS that decide how it looks. midcode shows your storefront’s preview at every breakpoint, and what you change is written into the theme’s files on your Mac. It doesn’t edit products or orders.

**How is this different from Shopify’s theme editor?**
The theme editor changes the settings a section exposes. midcode changes the section’s code: the markup, the classes, the text in any file, anything the theme’s developer could change by hand, and it leaves a git diff you can review.

**Is it safe for my live store?**
midcode works on a development theme, the one shopify theme dev creates for you. Your published theme changes only when you push or publish the code yourself.

**What do I need installed?**
The Shopify CLI, signed in to your store, and the theme’s code in a folder on your Mac. Nothing is added to the theme except assets/midcode.css, the first time you change a style.

**Which themes does it work with?**
Online Store 2.0 themes written in Liquid. It has been tried end to end with Dawn on a development store.

---

## midcode + Tailwind CSS

URL: https://midcode.app/integrations/tailwind-css
Status: Available

midcode is a visual editor for projects styled with Tailwind CSS 4. Its panel reads your @theme tokens (colors, fonts, spacing, radius) and writes utility classes on the element you selected, swapping the old class for the new one in place. Breakpoints, hover states and component variants become the prefixes you’d write by hand: md:, hover:, data-[variant=primary]:.

- Status: Available
- Reads: Your @theme tokens
- Writes: Utility classes, in place
- Tailwind 3: Edited too, another way

### What it does

- Your tokens in every control: Color pickers show your palette, type shows your fonts and sizes, spacing shows your scale. Pick one and the class that carries it is written.
- One class out, one class in: Changing a padding replaces p-4 with p-6. The diff is that change and nothing else: no reordering, no reformatting.
- Mobile first, like you’d write it: A value set on Tablet or Phone is written with the right screen prefix, from a table of values per breakpoint that follows the real cascade.
- States and variants: Hover, Pressed and Focus are hover:, active: and focus-visible:. A component’s variants are data-[variant=…]: classes on its root and group-data-[…]: inside.
- Edit the theme itself: The Design panel changes the tokens in your @theme and your text styles, in your CSS file.
- Arbitrary values when you need them: Drag a handle or type a number that isn’t on your scale and you get w-[412px], the way you’d write it.

### How it works

1. Open the project: midcode finds your CSS entry and reads the tokens in @theme. Nothing to configure.
2. Select and change: The panel works out which classes to remove and which to add for the breakpoint, state and variant you’re on.
3. Read the diff: One line changed, in the file the element is written in.

### What it doesn't do

- Classes built at runtime (a template string with a variable in it) are left alone: midcode edits the ones written out.

### Questions

**Does midcode work with Tailwind CSS 3?**
Yes, another way: midcode doesn’t rewrite Tailwind 3 classes. It adds its own prefixed utilities (mid:p-6) next to them and compiles those to a plain CSS file, so what you set on the canvas wins.

**Will it reorder or sort my classes?**
No. midcode replaces or adds the classes that changed and leaves the rest of the attribute as you wrote it.

**Does it understand cn() and clsx()?**
It edits the string literals where the classes are written, inside those calls too. A class picked by a condition at runtime is left alone.

---

## midcode + Plain CSS & Bootstrap

URL: https://midcode.app/integrations/plain-css
Status: Available

midcode styles projects that don’t use Tailwind CSS 4 (plain CSS, CSS modules, Bootstrap, Sass, Tailwind 3) without asking you to adopt anything. It writes its own utilities on the element with a mid: prefix, like mid:p-6 or mid:md:flex, and keeps a midcode.css file in your project with their plain CSS. Your own classes and stylesheets are never touched.

- Status: Available
- Writes: mid: utilities on the element
- Adds to your project: midcode.css, one import
- Needs installed: Nothing

### What it does

- The same panel as with Tailwind: Type, color, spacing, layout, size, breakpoints, hover states: every control works, in a project that has never heard of Tailwind.
- Never collides with your classes: Every utility carries the mid: prefix, so it can’t clash with your .flex or Bootstrap’s .p-3. midcode reads only its own classes and treats yours as yours.
- Plain CSS in your repo: midcode.css sits next to your app’s entry and holds exactly the rules for the classes in your code. It’s committed with the rest, and your build needs nothing new.
- A theme of your own: Colors, fonts and text styles you define in the Design panel live in .midcode/theme.css and show up in every control.
- Build it without the app: The midcode package for npm, pnpm and yarn regenerates midcode.css in your own build: a CLI, a Vite plugin and a Next.js wrapper.
- Scoped reset for what you insert: What you drag in from the Insert panel gets a reset that applies to that element only, never to the rest of your site.

### How it works

1. Change a style: The first style you change sets it up: midcode.css is created and imported once, as its own commit.
2. midcode compiles: midcode carries the Tailwind 4 compiler inside the app and turns the mid: classes in your code into plain CSS, before each edit lands.
3. Ship it: The CSS file is in your repository. Your site doesn’t depend on midcode to build or run.

### What it doesn't do

- midcode’s rules are !important, because an edit on the canvas has to win over the site’s own CSS.
- Your existing stylesheets are read by the browser, not by the panel: a value set in your .css shows on the canvas, and changing it from the panel adds a mid: class over it.

### Questions

**Do I have to install Tailwind?**
No. The compiler is inside midcode. Your project gets a plain CSS file and an import line, nothing in package.json.

**What if someone edits the code without midcode?**
The mid: classes are plain strings in your markup. If someone adds or removes one by hand, the midcode package regenerates the CSS in your build, or midcode does it the next time the project is open.

**Can I stop using midcode later?**
Yes. midcode.css is ordinary CSS and the classes are ordinary classes. Nothing breaks if the app is gone.

---

## midcode + Claude Code

URL: https://midcode.app/integrations/claude-code
Status: Available

midcode is a visual editor that runs Claude Code beside a live canvas of your site. Click an element and Claude gets its file and line as context, so “make this card wider” needs no explaining. Every file Claude changes shows on the canvas as it lands, as a diff you can undo, and the small things (a color, a line of copy, a padding) you change by hand without spending a token.

- Status: Available
- Account: Your own Claude Code sign-in
- Runs: Chat, or Claude Code in a terminal
- Changes: Diffs you can undo

### What it does

- Point instead of describing: The crosshair in the prompt takes the next thing you click: an element on the canvas, a CMS item, a text. Claude gets the file, the line and the components around it.
- A chat made for the canvas: Attachments, @ context (the selection, your comments, the page), Claude Code’s own slash commands, its plan, and pickers for mode, model and effort.
- Every change is a diff: Each file Claude writes goes into midcode’s history and the Publish list. One ⌘Z per tool call takes it back.
- Comments become briefs: Pin notes to elements while you review, attach files, then hand Claude all of them with their file and line.
- No tokens on a nudge: Moving a button 4 px or fixing a typo is a click on the canvas, not a prompt.
- Or the terminal you know: Switch the panel to Terminal and it’s Claude Code’s own CLI in your project folder, with the selection pasted in as context.

### How it works

1. Open your project: midcode finds Claude Code on your Mac and uses the sign-in it already has.
2. Point and ask: Select an element, write what you want. Claude works in your project folder and asks before it runs anything that needs permission.
3. Finish by hand: Adjust what Claude built on the canvas, review everything in Publish, commit and push.

### What it doesn't do

- The chat works with a Claude Console account or an API key. With a Claude subscription (Pro or Max), use the Terminal view, which runs Claude Code with your plan.
- midcode doesn’t sell or include model usage: the agent runs on your account.

### Questions

**Do I pay for Claude through midcode?**
No. midcode has no AI subscription and no markup. Claude Code runs with your own account, and midcode’s license is a single payment for the editor.

**Where is my API key kept?**
A key is optional. If you add one, it’s checked against the API, kept encrypted on your Mac, and never leaves the app’s main process.

**Can Claude and I edit at the same time?**
Yes. You both edit the same files. What Claude changes shows on the canvas as it lands, and what you change on the canvas is in the file when Claude reads it next.

**Does it work with my existing CLAUDE.md and settings?**
Yes. Claude Code runs in your project folder, so it reads the same instructions and settings as when you start it from a terminal.

---

## midcode + Codex

URL: https://midcode.app/integrations/codex
Status: Available

midcode runs OpenAI’s Codex beside a live canvas of your site. You click an element, Codex gets its file and line, and every file it changes shows up on the canvas as a diff you can undo. It uses the Codex login already on your Mac, so there’s no second account and nothing extra to pay midcode for.

- Status: Available
- Account: Your own Codex login
- Runs: Chat, or the Codex CLI in a terminal
- Changes: Diffs you can undo

### What it does

- Point instead of describing: Click an element and its file, line and surrounding components go into the prompt as a reference.
- Its plan and its diffs: Codex’s plan, its tool calls and each file it writes are shown in the thread. Every change is one ⌘Z.
- Model and effort in the prompt bar: The options Codex offers for the session are pickers in the chat, remembered for next time.
- Comments become briefs: Review on the canvas, pin notes to elements, then hand Codex all of them at once.
- Finish by hand: Spacing, copy and color are faster to change on the canvas than to prompt for.
- Publish what you both did: Your edits and Codex’s are in the same list. Check the files, commit, push.

### How it works

1. Open your project: midcode starts Codex in your project folder, with the login it already has.
2. Point and ask: Select, write, send. Permission requests show as cards in the thread.
3. Review and publish: Every changed file is in Publish, whoever changed it.

### Questions

**Do I need an OpenAI API key?**
You need Codex set up on your Mac the way you already use it. midcode starts it with that login and never sees your credentials.

**Can I switch between Codex and Claude Code?**
Yes. The chat lists every agent it finds on your Mac, and each one keeps its own model and mode.

---

## midcode + Gemini CLI

URL: https://midcode.app/integrations/gemini-cli
Status: Available

midcode runs Google’s Gemini CLI beside a live canvas of your site. The element you click goes into the prompt as a file and line, Gemini’s changes show on every breakpoint as they land, and each one is a diff you can undo. It uses the Gemini CLI already signed in on your Mac.

- Status: Available
- Account: Your own Gemini CLI sign-in
- Runs: Chat, or Gemini CLI in a terminal
- Changes: Diffs you can undo

### What it does

- Point instead of describing: Click an element and its file and line go into the prompt as a reference.
- See it at every breakpoint: What Gemini writes shows at Desktop, Tablet and Phone at once, so a layout that breaks on a phone is caught right there.
- Every change is a diff: Each file Gemini writes goes into the history and the Publish list.
- Comments become briefs: Pin notes to elements while you review, then send them all with their file and line.

### How it works

1. Open your project: midcode starts Gemini CLI in your project folder.
2. Point and ask: Select an element, write what you want, send.
3. Review and publish: Check the changed files, commit and push.

### Questions

**Which Gemini account does it use?**
The one Gemini CLI is signed in with on your Mac. midcode starts the CLI and talks to it; it never handles your Google credentials.

---

## midcode + OpenCode

URL: https://midcode.app/integrations/opencode
Status: Available

midcode runs OpenCode beside a live canvas of your site, with whichever models you’ve configured in it. The element you click becomes context for the prompt, every file OpenCode changes shows on the canvas as a diff you can undo, and the last adjustments are a click instead of a prompt.

- Status: Available
- Account: Your own OpenCode setup
- Runs: Chat, or OpenCode in a terminal
- Changes: Diffs you can undo

### What it does

- Point instead of describing: Click an element and its file and line go into the prompt as a reference.
- Your models: OpenCode’s model and mode options are pickers in the prompt bar.
- Every change is a diff: Each file it writes goes into the history and the Publish list.
- Finish by hand: Change spacing, copy and color on the canvas, without another round trip.

### How it works

1. Open your project: midcode starts OpenCode in your project folder.
2. Point and ask: Select an element, write what you want, send.
3. Review and publish: Check the changed files, commit and push.

### Questions

**Does midcode need its own key for the model?**
No. OpenCode runs with the providers and keys you set up in it. midcode only starts it and shows what it does.

---

## midcode + Cursor

URL: https://midcode.app/integrations/cursor
Status: Available

midcode works next to Cursor on the same project folder. Click any element on the canvas to get its file and line, copy that reference or a full brief into Cursor, and watch the canvas update on every breakpoint as Cursor saves. Cursor’s CLI agent also runs in midcode’s terminal view, with the selection pasted in as context.

- Status: Available
- Account: Your own Cursor account
- Runs: Cursor’s CLI in a terminal, or Cursor beside midcode
- Changes: Diffs you can undo

### What it does

- A reference for anything you see: Select an element and copy where it’s written: file, line and the components it sits inside. Paste it into Cursor’s chat.
- Briefs from comments: Pin notes on the canvas as you review. They’re saved in your project’s .midcode folder, where Cursor can read them, and copy out as one brief.
- Open in Cursor on the line: Set Cursor as your editor and “Open in editor” takes you to the element’s file at its line.
- Live on every breakpoint: Whatever Cursor saves shows on the canvas at Desktop, Tablet and Phone, because midcode runs your real dev server.

### How it works

1. Open the same folder: midcode and Cursor both work on your project’s files. There’s nothing to connect.
2. Copy the reference: Click what you want changed, copy its reference or a brief, and give it to Cursor.
3. Finish on the canvas: Adjust the result by hand, then publish.

### What it doesn't do

- Cursor doesn’t run inside midcode’s chat: that’s for Claude Code, Codex, Gemini CLI and OpenCode. Cursor runs in the terminal view or in its own window.

### Questions

**Do I use midcode instead of Cursor?**
No, beside it. Cursor writes and refactors code. midcode shows the result on a canvas and lets you change what’s faster to change by eye.

**Will the two overwrite each other?**
midcode writes only the range you edited and won’t undo into a file that changed since. If Cursor saved the file in between, midcode reads it again first.

---

## midcode + GitHub

URL: https://midcode.app/integrations/github
Status: Available

midcode publishes what you edit on the canvas to your git repository: it lists every change with its diff, commits only the files you check, and pushes, all in one step. It works with any git remote and uses the credentials your Mac already has. Connecting a GitHub account is optional and lets midcode push as the account that has access to the repository.

- Status: Available
- Commits: Only the files you check
- Force push: Never
- Account: Optional

### What it does

- See every change before it goes: Each edit is a line in Publish, with the file and its diff. Undo one and it leaves the list.
- Commit and push in one step: git add, commit and push for the files you marked. Anything else in your working tree is left alone.
- Branches: Switch branches or create one from the top bar before you start, like you would in a terminal.
- The right account, on its own: With several GitHub accounts on your Mac, midcode asks GitHub which one can push to the repository and uses that one.
- A failed push isn’t a lost commit: If the push fails, the commit stays local and the panel offers Push again.
- A project inside a bigger repo: Publishing works from a site that lives in a folder of a monorepo.

### How it works

1. Edit: Every change you or your agent make is collected as you go.
2. Review: Open Publish, read the diffs, uncheck what shouldn’t go yet.
3. Publish: Write the commit message and push.

### What it doesn't do

- midcode commits and pushes. Pull requests, reviews and merges stay in GitHub.

### Questions

**Do I have to connect my GitHub account?**
No. Publish uses git on your Mac with the credentials it already has. Connecting GitHub helps when you have more than one account, and lets you follow what happens after the push.

**Where is my GitHub token kept?**
Encrypted on your Mac, in the app’s main process. It’s never sent to midcode’s servers or to any other host.

**Does it work with GitLab or Bitbucket?**
Publishing is plain git, so any remote your Mac can push to works. The account connection is for GitHub.

---

## midcode + Vercel

URL: https://midcode.app/integrations/vercel
Status: Available

With a repository connected to Vercel, publishing from midcode is a deploy: midcode commits the files you changed and pushes them, and Vercel builds from that push as it always does. Connect your Vercel account in midcode, which is optional, and you can follow the deploy right after you publish.

- Status: Available
- Deploys: Through your git push
- Account: Optional
- Changes to your Vercel project: None

### What it does

- Publish is a deploy: Push to your production branch and Vercel ships it. Push to another branch and you get a preview deployment to share.
- Follow it without leaving: With Vercel connected, midcode shows the deploy that your push started.
- Edit copy without a ticket: A typo on the live site is a double-click, a review of one diff, and a push.
- Nothing new in the pipeline: midcode doesn’t deploy on its own or add a build step. Your Vercel project builds your repository, as before.

### How it works

1. Edit on the canvas: Change what you need. Each edit is written to your files.
2. Publish: Review the diffs, commit and push from the Publish panel.
3. Vercel builds: The push starts the deploy. Follow it from midcode if your account is connected.

### Questions

**Does midcode need access to my Vercel account?**
No. Deploys happen because your repository is connected to Vercel. Connecting your account in midcode only lets it show you the deploy.

**Does it work with Netlify or Cloudflare Pages?**
Yes, in the same way: any host that deploys from a git push deploys when you publish. Following the deploy inside midcode is for Vercel.

---

## midcode + Postgres

URL: https://midcode.app/integrations/postgres
Status: In development

midcode is adding a table editor and a SQL editor for the Postgres database behind your site. It finds the database from the connection string your project already has in its .env files (DATABASE_URL and the like), lists the tables with their columns and rows, and runs the SQL you write. A database that isn’t on your Mac opens read-only until you allow changes.

In the current version: This is being built and isn’t in the version you download today. Leave your email to hear when it ships.

- Status: In development
- Finds it from: Your .env files
- Remote databases: Read-only by default
- Credentials: Stay on your Mac

### What it does

- Tables without a second app: Every table in the database, with its columns and its rows, in the same window as the site.
- A SQL editor: Write a query, run it, read the result as a table. Queries you save are kept with the project.
- See the plan first: Ask how the database would run a statement, without running it.
- Warnings that matter: An UPDATE or DELETE with no WHERE tells you it touches every row, and asks before it runs.
- Found, not configured: DATABASE_URL, DIRECT_URL, POSTGRES_URL or Laravel’s DB_* values: midcode reads what the project uses. You can add a connection by hand too.
- Read-only where it counts: A database that isn’t on this Mac may be the one your site runs on. midcode opens it read-only and says so.

### How it works

1. Open your project: midcode looks for the database the project already points at. Connection strings stay in the app’s main process and are never shown.
2. Browse and query: Open a table to read its rows, or write SQL and run it. Save the queries you’ll want again.
3. Allow changes when you mean to: A database on your Mac can be changed. One that isn’t opens read-only until you turn on “Allow changes”.

### What it doesn't do

- Changes to a database have no undo and aren’t part of Publish: they happen in the database, for real.
- Migrations stay in your project’s own tools.

### Coming next

- MySQL and Turso.
- Sign-in for your site, set up visually.

### Questions

**Does it work with Supabase and Neon?**
They’re Postgres, reached with a connection string, so they open like any other Postgres database. Being remote, they open read-only until you allow changes.

**Where do my database credentials go?**
Nowhere. midcode reads the connection string from your .env on your Mac and connects from your Mac. A connection you add by hand is kept encrypted, outside the project.

**When does it ship?**
It’s being built now. The email list at the bottom of this page is told first.

---

## midcode + SQLite

URL: https://midcode.app/integrations/sqlite
Status: In development

midcode is adding a table editor and a SQL editor for SQLite. It finds the .db, .sqlite or .sqlite3 file your project keeps in the usual places (the root, prisma/, db/, data/, database/, storage/), shows its tables with their rows, and runs the SQL you write on it. It’s a file on your Mac, so there’s no server to start and nothing to connect.

In the current version: This is being built and isn’t in the version you download today. Leave your email to hear when it ships.

- Status: In development
- Finds: .db, .sqlite and .sqlite3 files
- Server: None
- Setup: None

### What it does

- Open the file, see the tables: The development database of a Prisma, Drizzle, Laravel or Django project, without installing a database browser.
- A SQL editor: Write a query, run it, read the result as a table. Queries you save are kept with the project.
- Warnings that matter: An UPDATE or DELETE with no WHERE tells you it touches every row, and asks before it runs.
- Next to the page it feeds: Run a query, look at the canvas: the data and the page that reads it share a window.

### How it works

1. Open your project: midcode looks for the database the project already points at. Connection strings stay in the app’s main process and are never shown.
2. Browse and query: Open a table to read its rows, or write SQL and run it. Save the queries you’ll want again.
3. Allow changes when you mean to: A database on your Mac can be changed. One that isn’t opens read-only until you turn on “Allow changes”.

### What it doesn't do

- Changes to a database have no undo and aren’t part of Publish.

### Coming next

- Turso.

### Questions

**Do I need SQLite installed?**
No. midcode reads the file itself.

**When does it ship?**
It’s being built now. The email list at the bottom of this page is told first.

---

# Changelog

### 1.1.2 (2026-10-03): HTTPS dev servers, Laravel and reports

- Dev servers on HTTPS now start: a project that serves with its own local certificate opens on the canvas like any other, whether midcode starts it or your dev script does.
- Laravel with Vite: the canvas shows your site at its APP_URL (served by Herd, Valet or php artisan serve) with Vite running beside it, and tells you when the site isn’t being served.
- When a project doesn’t start, “Send report” sends what it takes to fix it: the log, how the project is set up and your Mac’s model, all shown before it goes. “Copy report” gives you the same text to send any other way. No source files, nothing from your .env.
- A start that takes too long offers the log and the report instead of spinning in silence.
- On a start error, the log button now hides and shows the log, and the log no longer covers the error.

### 1.1.1 (2026-10-03): Snapping, variables and a steadier start

- Projects that won’t start midcode’s way now start with your own dev script (a SvelteKit or Vite project that needs its env files, another process or a fixed port), and midcode tells you why in the log.
- Snapping and guides: what floats lines up with what’s around it, its edges and centers, the breakpoints and your guides, and shows the distance to its neighbours. Rulers on the canvas (R): drag a guide out of one, click it and press ⌫ to remove it.
- Option-drag to duplicate. ⌘C and ⌘V never paste on top of the original: the copy goes beside it.
- Several selected: right-click, copy, duplicate, delete and ⇧A (wrap in a stack) work on all of them, and dragging one moves them all. ⌘A selects everything beside the selection.
- Variables in components: the + beside a text, an image, a link, a padding, a radius or a color turns it into a prop, so every use of the component can set its own.
- Drag the unit of a number field (px, %) sideways to change the value.
- Your agent stays beside the code, the CMS, the texts and the site settings, and can pick a CMS item or a text to talk about. In Code view the files are on the right, with a preview of the site beside the code.
- Translate a site that’s in one language: its texts are all there to edit and translate, and your agent finds the translations ready when it sets the languages up.
- Fixes: an element on the canvas no longer jumps to another’s place when moved, reordering inside a stack works by dragging, and a stack no longer gets a background it doesn’t have.
- The free trial asks for your email, so you hear about updates.

### 1.1.0 (2026-10-01): Build, chat, and style anything

- Builder improvements: the Insert panel has frames, stacks, grids, text, media, embeds, forms, whole sections, icons and interactive components (carousel, tabs, slideshow, ticker), each with a real preview. Drag one onto the canvas and it’s written into your code.
- Canvas expansion: press F and drag to draw a frame. Anything you draw, drop or paste on the empty canvas floats there, outside your breakpoints and never published. Move, resize and rotate it, select several with a drag, and drag it into a page when it’s ready.
- Your agent in a chat made for midcode: Claude Code, Codex, Gemini or OpenCode with your own account, with attachments, @ context (the selection, your comments, the page), the agent’s commands, its plan, and every change shown as a diff you can undo.
- Components on their own canvas: variants as columns, states (Hover, Pressed, Focus) as rows. What you change in a cell is written for that variant and state, in the component’s file.
- Typed props in the panel, read from your TypeScript types, and settings for inputs, selects, forms, buttons, embeds, audio and video.
- Styles in any project, with or without Tailwind. Where there’s no Tailwind 4 (plain CSS, CSS modules, Bootstrap, Tailwind 3) midcode writes its own utilities, mid:p-6, mid:md:flex, and turns them into plain CSS. Nothing to install, and your own classes are never touched.
- The midcode package for npm, pnpm and yarn: a CLI, a Vite plugin and a Next.js wrapper that build those styles in your own build, without the app.
- Preview: press P to use the site at full size, with the canvas always in design mode.
- Paste an image with ⌘V: it’s copied into your project and lands on the canvas, or next to the selected element.
- Drag elements between breakpoints and the canvas. Arrow keys nudge an element 1 px, and with Shift by an amount you choose in Settings.
- A simpler left panel: Agent, Layers and Assets. Layers are grouped by breakpoint, with what floats on the canvas below.
- The selection’s outline and handles turn with a rotated element, and number fields change the element as you press ↑ and ↓.
- Publish works from a project that lives in a folder of a bigger repository.
- Docs: how midcode works, step by step, at midcode.app/docs.

### 1.0.0 (2026-09-28): midcode 1.0

- Design and Code, side by side: switch to Code for the whole project as files, with tabs, an editor and a terminal. Every save is undoable and shows up in Publish.
- Your agent inside midcode: Claude Code, Codex, Gemini, Cursor or OpenCode in a panel on the left, running in your project with your own account. Send it the selected element or your open comments in one click.
- Languages: every text of your site grouped by page, in every language, with flags. Translate what’s missing with Apple Intelligence on your Mac, or hand it to your agent. Add a language in one click.
- CMS (beta): the lists in your code, JSON files and Markdown posts as tables you can edit, each change written into the file.
- Padding, radius and borders per side or corner.
- Get started: a short checklist in your first project that points at where things happen.
- Next.js 15 projects on webpack are fully editable.
- Publish pushes as the GitHub account that can, and a failed push can be retried.
- Opened from the disk image, midcode offers to move itself to Applications so it can update itself.
- Try it free for 3 days, then one payment: yours for life, every update included.

### 0.6.0 (2026-09-25): Beyond Next.js

- Open more than Next.js: Vite + React, React Router, Remix and the React islands of Astro are edited on the canvas like Next.js projects, with the same stamps and no changes to your config.
- SvelteKit, Nuxt, plain HTML and any project with a dev script open too: check every breakpoint, play the site and leave comments. A folder of HTML is served by midcode and reloads when you save.
- Send feedback from the top bar, with your Mac’s model and the log attached if you want.
- An update banner: downloading, ready to restart, and what’s new after updating.
- Comment pins show only while commenting or on the Comments tab, and C turns the pointer into a crosshair.
- Project cards in the hub get a menu: open, show in Finder, open in your code editor, copy the path, remove.

### 0.5.0 (2026-09-25): Move things around & site settings

- Drag to reorder: grab any element or section on the canvas or in Layers and drop it before, after or inside another. A blue line shows where it lands, and the code moves with it.
- Sections that are components (<Hero />, <Faq />) move where they’re used, and Layers now shows their names.
- Site settings: title, title template, description, language, site URL, favicon and social image, with a search result preview.
- Page settings for every page, and {{variables}} on dynamic pages like /work/[slug], written as Next.js metadata.
- A plain block of blocks, like a <main> of sections, is a vertical stack: align and space it from the panel.
- Resize handles only where the size is Fixed (width, height or both), and smaller.
- Custom colors open on the picker, with their value.
- No more jumps when an edit rebuilds the page’s CSS.

### 0.4.0 (2026-09-25): Build on the canvas

- Insert elements: Frame, Stack, Grid, Text, Heading, Button, Image and Video, from the toolbar or with a key (F, S, T…). They’re written straight into your code.
- Drag components from Assets onto the canvas to add an instance, imported for you.
- Open any component on its own: its code, a live preview of just that component, and the style panel to edit it. Props are editable too.
- Your own breakpoints: add, rename and resize them, and pick the primary one. Changes at other breakpoints are overrides, shown in blue, and one right-click removes them.
- A built-in code editor with a live preview of the element, so you don’t need to leave midcode for your IDE.
- A Framer-style panel: position, size (Fixed, Relative, Fill, Fit), min and max, stacks and grids, opacity, visibility per breakpoint, borders and shadows.
- Resize handles on the canvas.
- Assets tab: your components, layouts and styles in one place. Create text styles and link styles, remove the ones you don’t use.
- Pages as a tree you can reorder, with dynamic routes like /work/[slug] you can switch between.
- Optional GitHub and Vercel connections: publish over https and follow your deploy.
- The selection’s parent is outlined, and Cmd-click climbs to it.
- A floating toolbar, filled inputs, Geist everywhere and a new arrow icon.

### 0.3.0 (2026-09-24): Play, preview & media

- The interface is now available in English and Spanish.
- New Settings window (⌘,) for language and preferences.
- Play and Inspect modes: Play runs the site, with videos, animations and clickable menus. Pause to inspect and select.
- Full-size preview for each breakpoint, plus Hide UI for a clean full-screen view.
- Custom controls across the editor: selects, switches and tooltips built for midcode.
- Text styles and tags: apply your project’s type styles and switch between h1–h6, p and more from the panel.
- Copy reference: copy an element’s file:line to paste straight into your agent.
- Replace images, videos and backgrounds right from the canvas.
- Edit alt text for images.
- Rename layers in the Layers panel.
- Name layers with Apple Intelligence. It runs on-device, offline and free.
- A new app icon.

### 0.2.0 (2026-09-16): Styles & publish

- Breakpoints now render at full page height, side by side.
- Pause animations to inspect any state of the page.
- Tailwind style panel: typography, colors from your @theme tokens, spacing and radius.
- Style edits swap Tailwind classes in place, so every change is a minimal diff.
- Publish: review what changed, then commit and push in one step.
- Groundwork for automatic updates.

### 0.1.0 (2026-09-08): First canvas

- A project hub to open and reopen your Next.js projects.
- Live breakpoints on an infinite canvas: Desktop, Tablet and Phone.
- Click any element to select it and see where it’s written (file:line).
- Double-click text to edit it. Changes are written straight to the source.
- Comments pinned to elements, stored in your project’s .midcode folder.