A mirror serves a folder under a URL prefix exactly as it is on disk. Astro never processes the files: no
bundling, no HTML rewriting. Relative URLs inside keep working, so import '../src/x.js' and
fetch('../examples/a.json') behave as they do with any static server. Use it for playgrounds, demo pages, and
your library’s own source that those demos (and live examples) import.
mirrors: [{ from: './example/apps', to: 'apps' }],// example/apps/hello/index.html → /apps/hello/| Field | Meaning |
|---|---|
from |
Folder to mirror, relative to the project root. May be outside it: '../', '../../my-lib'. |
to |
URL prefix. Nested prefixes ('lib/src') work, and several mirrors may share one. |
include |
Globs relative to from; when given, only matching paths are mirrored. |
exclude |
Globs relative to from; matching paths are skipped. |
Globs: * and ? stay within one path segment, ** crosses segments, {a,b} is either, [abc] a character
class. A pattern that matches a folder covers everything in it (src = src/**). A pattern without a / is
tried against every path segment, so *.test.js or fixtures match at any depth.
Never mirrored: dotfiles and dot-folders (.git, .env), node_modules, and the site’s own folder (and its
dist/) when from contains it. Symlinked files are copied as the file they point to; symlinked folders are
skipped.
Keeping a repo’s layout
Section titled “Keeping a repo’s layout”A demo in demos/ that imports ../src/index.js needs both folders under one prefix. Mirror the repo root with
an include list:
mirrors: [ { from: '../', to: 'lib', include: ['src', 'demos', 'examples/*.json'], exclude: ['*.test.js', '*.map'] },],// → /lib/src/index.js, /lib/demos/playground/, /lib/examples/basic.jsonLink to mirrored pages from anywhere (nav, gallery href, docs links): the links validator accepts every path
under a mirror prefix without checking it.
In dev and at build
Section titled “In dev and at build”astro devserves the files straight from disk with the rightContent-Type(JavaScript for.js/.mjs, JSON, Markdown, images,.wasm, fonts, audio, video) andCache-Control: no-store, so edits show on reload (mirrored pages do not hot-reload). A folder serves itsindex.html;/apps/helloredirects to/apps/hello/. Hidden paths,..and excluded files fall through to Astro (a 404). The dev server logs each mirror at startup:/apps/ → ./example/apps (/abs/path/example/apps).astro buildcopies the files intodist/<to>/after Astro has finished and logs a count and size per mirror (/apps/ ← ./example/apps: 9 files, 8.1 KB).
The build fails when:
-
fromdoes not exist or is not a folder (the error names the resolved path; in CI, check that the repo holding it is checked out); -
tois empty, contains./.., or a segment starting with.; -
a mirrored file would overwrite a file the site builds itself:
[mirror] mirrors[0] (../) would overwrite /index.html, which the site itself builds. Change `to` or exclude the file.
It warns when two mirrors write the same file (the later one wins) and when a mirror matches no files.
On its own
Section titled “On its own”mirror is also exported, for an Astro site that does not use the rest:
import { mirror } from 'astro-project-site';export default defineConfig({ integrations: [mirror([{ from: '../demos', to: 'demos' }])] });