skip to content

Vite's dev server answers 403 for files from a shared packages/maps folder outside the project root; why, and how do you allow them safely?

level: seniorimportance: should knowfreq 7%

answer

  1. a fence around what can be served
  2. strict by default, for years
  3. workspace root, else project root
  4. setting the list drops the detection
  5. the deny list always wins

basics

~20 s

server.fs.strict is on by default, so Vite serves only files inside server.fs.allow, which defaults to the detected workspace root or else the project root. Add packages/maps to the list, keep searchForWorkspaceRoot, and never turn strict off.

solid answer

~40 s

Vite's dev server can serve files by absolute path under `/@fs/`, so it fences them: with `server.fs.strict` (on by default since Vite 2.7), a request for a file outside `server.fs.allow` that no allowed module imported gets a 403. The default allow list is the **workspace root** Vite detects by searching up for a `package.json` with `workspaces`, a `pnpm-workspace.yaml` or a `lerna.json`, falling back to the project root. With no such marker, a sibling `packages/maps` is outside. Setting `allow` replaces that detection, so write `allow: [searchForWorkspaceRoot(process.cwd()), '../../packages/maps']`. `server.fs.deny`, which blocks `.env` files, keys and certificates, `.npmrc` and `.git` by default, still outranks `allow`. Switching `strict` off would serve any readable file to whoever reaches the server.

go deeper

for a junior

Recall that the dev server refuses files outside an allowed set with 403, and that server.fs.allow is where extra folders go.

for a middle

Explain how the default allow list comes from workspace detection, why a sibling package can fall outside it, and how imports from allowed files are still served.

for a senior

Fix it without widening exposure: extend allow with searchForWorkspaceRoot, know that deny outranks allow, and refuse fs.strict false on a server that listens on the network.

for a principal

Set the monorepo convention, a workspace marker every app relies on or explicit allow lists per app, and weigh developer friction against what a reachable dev server can leak.

## Why the dev server fences the file system During development Vite serves source files by URL, and a file outside the project root is addressed by its **absolute path** under a `/@fs/` prefix. Without a fence, anyone who can reach the dev server could ask for any file the process can read: a private key in the home directory, another project's `.env`. That matters more once the server listens beyond loopback, as it must inside a dev container. So Vite restricts serving: - `server.fs.strict` defaults to **`true`**, and has since Vite 2.7. - A request for a file **outside `server.fs.allow`** that was **not imported from an allowed file** gets a **403**. - `server.fs.deny` is a blocklist that wins over everything else. The import clause explains a confusing pattern: a module in `packages/maps` reached through a JavaScript `import` from an allowed file can be served, while a file the browser asks for by its `/@fs/` path with no import vouching for it, such as an asset URL that no import resolved, is refused. ## What the allow list is by default When `server.fs.allow` is not set, Vite searches upward from the project root for a **workspace root**: 1. a `package.json` that has a `workspaces` field, or 2. a directory containing `pnpm-workspace.yaml` or `lerna.json`. If it finds one, that directory is allowed; otherwise the **project root** (the folder with `index.html`) is the boundary. ## Why `packages/maps` is refused The dispatch console's project root is `apps/dispatch`, and the shared map code sits at `packages/maps`, two levels up and across. Two situations put it outside the fence: - The repository has **no workspace marker**, so the allow list is just `apps/dispatch`. - The config **already sets `server.fs.allow`**, perhaps to some other folder. Setting it **disables the automatic workspace detection**, so the workspace root is no longer allowed either. ## The safe fix Extend the list instead of removing the fence, and keep the detection by calling the exported helper: ```ts import { defineConfig, searchForWorkspaceRoot } from 'vite' export default defineConfig({ server: { fs: { allow: [ searchForWorkspaceRoot(process.cwd()), '../../packages/maps', // relative to the project root ], }, }, }) ``` Entries may be directories or single files, and absolute or **relative to the project root**. ## What stays blocked: `server.fs.deny` `server.fs.deny` has **higher priority than `allow`**. Its default is `['.env', '.env.*', '*.{crt,pem,key,p12,pfx,cer,der}', '.npmrc', '.yarnrc.yml', '**/.git/**']`, with picomatch patterns, and a pattern without a `/` matches in any directory. So `packages/maps/.env` stays unreachable even after the folder is allowed. Three caveats from the docs: - The deny list is checked against the module id and the id with its query stripped. - It does **not** apply to the `public` directory, whose files are served unfiltered because they are copied to the output as they are. - A plugin's `load` hook can read any file, including through a symlink to a denied path, so add known alternative paths to `deny` too. ## Fixes that remove the fence | Change | Effect | Why to avoid it | |---|---|---| | `fs.strict: false` | any readable file can be served | anyone who reaches the dev server can read your machine | | `allow: ['/']` | the same, spelled differently | the same | | `allow: ['..']` from a deep root | much more than the shared folder | widens exposure for one folder's sake | | any of these plus `host: true` | the server is reachable from the network | multiplies the exposure | ## Diagnosing a 403 step by step 1. Confirm the refused path is **outside the project root**; inside it, check the deny list, and if every request is refused, the hostname check. 2. Look for a **workspace marker** above the root: `workspaces` in a `package.json`, a `pnpm-workspace.yaml` or a `lerna.json`. 3. Check whether the config **already sets `server.fs.allow`**, which turns the detection off. 4. Check whether the file name matches a **`deny` pattern**, such as `.env.local` or a `.pem` file. 5. Only then add the narrowest folder that fixes it. ## Summary - A 403 for a file outside the root is the **`server.fs` fence**, not a missing file. - The default fence is the **detected workspace root**, or the project root without a marker. - **Add** the folder to `allow` and keep `searchForWorkspaceRoot`; never switch `strict` off. - `deny` still protects `.env` files, keys and `.git`.

  • After adding '../../packages/maps' to server.fs.allow, files elsewhere in the repository start returning 403; what happened?
    Setting `server.fs.allow` turns off the automatic workspace-root detection, so the list now holds only what you wrote. Put `searchForWorkspaceRoot(process.cwd())`, exported by Vite, back into the array beside the custom entry to keep the detected workspace allowed.
  • A teammate proposes server.fs.strict: false because the allow list keeps getting in the way; what do you answer?
    That it removes the only fence between the dev server and every file the process can read, and inside a container the server usually listens on all addresses. Anyone who reaches it could fetch keys or other projects' files. Add the specific folders to `allow`; `deny` keeps protecting `.env` files and keys either way.

  • server.fs.strict is off unless you enable it
  • The allow list is always just the folder holding index.html
  • Adding one folder to server.fs.allow keeps the workspace root allowed too
  • An allowed folder exposes its .env files as well
  • Turning off fs.strict is a harmless dev-only shortcut