Duolith docs

0042. A project's public/ folder is copied to the site as it is

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP7 (kit: images), project layout

Context

Apps ship files of their own that no page compiles: photos, an icon, a JSON file. The kit's Image needs local images for its example and tests (decision 0038), and a project had no place for them: the build output held only what the compiler made. The router (decision 0031) answers every path that has no file with the app shell, so a file must be part of the build to be served.

Decision

  • **public/ at the project root** holds files served as they are, at the same path from the site's root: public/photos/lake.jpg is /photos/lake.jpg. Folders inside it are kept.
  • Any file, byte for byte. Photos (PNG, JPEG, WebP, AVIF), fonts and icons are copied like SVG and JSON. The build keeps public files apart from compiled ones: compiled files are text, public files are bytes, and duolith build and duolith dev write and serve both.
  • Nothing from outside the folder, nothing hidden. Entries whose names start with a dot (.DS_Store, .env, .git/) are left out, and symbolic links are never followed, to files or to folders, so a link cannot copy something from elsewhere on the machine into the site.
  • No public file in the build's place (E0161). A public file under _duolith/, or at the path of a file the build writes (a page's index.html, the 404.html app shell), fails the build with the file named. Neither file silently replaces the other.
  • duolith dev serves public files with their content type (SVG as image/svg+xml, PNG as image/png, and so on) and rebuilds when one changes. A path that is in neither the build nor public/ still gets the app shell, as the router expects.
  • Served from the app's own origin. An SVG in public/ is a document of the site: opened directly it can run script with the app's origin. Only put SVG files there that you trust as you trust your own code; <image> shows them as pictures, where their scripts do not run.

Alternatives considered

OptionWhy not
Images as data: addresses in pagesNot cacheable apart from the page, unreadable in the source, and every copy repeats the bytes
Importing assets from scriptsNeeds an asset pipeline (hashing, a module per file) before it is needed
Text files only, binaries refusedPhotos are what apps ship most; refusing them made public/ a half feature
Compiled files win on a clashA public file that is never served, with no word why
Follow links, require the target to stay under public/Same safety with more to get right; a link in public/ is rare enough to leave out

Consequences

  • Build output has two kinds of file, text and bytes; the editor tools only ever see compiled text.
  • Native targets will bundle public/ into the app the same way, at the same paths, with the same rules.