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.jpgis/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 buildandduolith devwrite 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'sindex.html, the404.htmlapp shell), fails the build with the file named. Neither file silently replaces the other. duolith devserves public files with their content type (SVG asimage/svg+xml, PNG asimage/png, and so on) and rebuilds when one changes. A path that is in neither the build norpublic/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
| Option | Why not |
|---|---|
Images as data: addresses in pages | Not cacheable apart from the page, unreadable in the source, and every copy repeats the bytes |
| Importing assets from scripts | Needs an asset pipeline (hashing, a module per file) before it is needed |
| Text files only, binaries refused | Photos are what apps ship most; refusing them made public/ a half feature |
| Compiled files win on a clash | A 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.