Monorepos

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

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:

packages:
  - 'apps/*'
  - 'packages/*'

or, for npm, yarn and bun:

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

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.

Publish works on the repository the site is in, but lists and commits only the files under the site’s folder. See Publish.

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.

• –

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

The framework pages cover the rest: Next.js, React with Vite, React Router and Remix, Svelte and SvelteKit.