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