What midcode adds to your project

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.

At a glance

Files under .midcode/ are listed in Publish 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 reads it.

The .midcode folder

comments.json and attachments/

Comments you leave on the canvas. The file is a list, one object per comment:

[
  {
    "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, or that Apple Intelligence gives them.

{
  "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 has the details.

breakpoints.json

The project’s breakpoints. Until you change them there is no file, and midcode uses three defaults. Written out, they are:

{
  "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, as routes. The home page is always first, so it isn’t listed.

{
  "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:

/*
 * 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 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 are kept by the site’s own text until the languages are wired into the code:

{
  "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.jsonNext release

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

{
  "command": "bin/rails server -b 127.0.0.1 -p $PORT",
  "url": "http://127.0.0.1:$PORT"
}

See Any other stack. 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.jsonNext release

The store a Shopify theme is worked on with. No key or password is in it.

{
  "store": "your-store.myshopify.com"
}

queries/Next release

Each query saved in the SQL editor 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:

# .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:

 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 covers all of them.

The canvas page

In a Next.js App Router project, what you draw or drop outside the breakpoints is code too. It lives in one page:

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.

• –

  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.

• –

  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.

A migration file is the change in words, then its 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 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.

• –

  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.