Custom overrides
Use custom/ for instance-owned files. This keeps your deployment upgradable because default pages, Worker logic, source policy, and local helper settings can move forward without mixing in every local choice.
For the upgrade rationale, read Keeping vanityURLs upgradable with custom overrides. For the build order and generated artifacts, read Configuration files.
Defaults versus custom
defaults/ is the product baseline. custom/ is your instance overlay. Files in custom/ either replace specific defaults or provide instance data that should survive upstream updates.
Keep product changes in defaults/ only when you are contributing back to vanityURLs. Keep instance changes in custom/ when the change is only for your short domain.
Custom file map
| File or path | Use it for | Details |
|---|---|---|
custom/v8s-links.txt | Redirect inventory | Link format and LNK |
custom/v8s-schedules.json | Legacy scheduled link rules for 3.x compatibility | Scheduled links |
custom/v8s-policies.json | Instance allow and block policy | Policy and blocklist |
custom/v8s-site-config.json | Site settings written by setup | Configuration files |
custom/v8s-local-config.json | Workstation helper paths | Local helper |
custom/v8s-custom-overrides.json | Intentional maintenance ignores for custom public files | Public and status pages and v8s-fix |
custom/public/ | Public page, asset, status-page, and header overrides | Public and status pages, Brand, Footer & pages, and Internationalization |
custom/public/_headers | Advanced public response header and CSP overrides | Runtime security approach |
Public pages
Use Public and status pages for the exact custom/public/ paths, status-page placeholders, shared asset cautions, and CSP guidance for custom HTML.
Use custom/public/_headers only when the instance deliberately accepts a different header or CSP policy. The default Worker and static headers already provide the strict product-page CSP, the sandboxed custom-page CSP, no-index rules, HSTS, referrer policy, permissions policy, and raw runtime-file blocks.
Use custom/v8s-custom-overrides.json only for deliberate maintenance exceptions. It tells npm run doctor that a specific custom file is intentionally different, so you do not need to run v8s-fix against work that belongs to the instance.