Configuration files

vanityURLs keeps product defaults, instance-owned choices, local workstation settings, and generated runtime artifacts in separate files.

Use this page to identify the current configuration files and the schema shape each one follows. The exact implementation contract remains the Git files and scripts in the code repository.

Source configuration

Site Config

custom/v8s-site-config.json is the main setup file written by npm run setup. It stores instance-owned site settings, including languages, branding, operator contacts, legal-page mode, and link CLI overrides. The exact field list is defined by defaults/v8s-site-config.json and the installer. The build deep-merges the default and custom site config, so additive defaults can arrive through defaults/ without rewriting your custom file. The important top-level sections are:

Use IANA timezone names for operator.timezone, such as America/Toronto or Europe/Berlin. Avoid numeric offsets such as -4 or -5; they do not describe daylight saving time transitions and setup rejects them.

Example:

{
  "schema_version": "1.0",
  "i18n": {
    "default_language": "en",
    "supported_languages": ["en", "fr"]
  },
  "links": {
    "random_slug_length": 3,
    "random_slug_alphabet": "34789abcdefghjkmnpqrstvwxy",
    "tag_random_slug_lengths": {
      "training": 4,
      "debug": 2
    }
  },
  "operator": {
    "legal_name": "Example Inc.",
    "short_domain": "example.link",
    "operator_domain": "example.com",
    "abuse_contact": "abuse@example.com",
    "security_contact": "security@example.com",
    "timezone": "America/Toronto",
    "abuse_response_window": "5 business days",
    "legal_pages_enabled": false
  },
  "branding": {
    "domain": "example.link",
    "slogan": {
      "en": "A short-link service for Example Inc.'s projects",
      "fr": "Un service de liens courts pour les projets de Example Inc."
    },
    "custom_public": true,
    "wordmark": {
      "black": "example.",
      "green": "link"
    }
  }
}

Additive fields can appear without changing schema_version. Schema version changes are reserved for incompatible stored-config changes that need migration; the decision is recorded in the code repository ADRs. Additive field changes are tracked in the code repository docs/schema-changelog.md.

Generated configuration

Public overlay order

The public asset build is deterministic:

1. Copy defaults/public/ into build/
2. Overlay custom/public/ when it exists
3. Copy the default defaults/public/_stats/index.html
4. Overlay custom/public/_stats/index.html when it exists
5. Prune unsupported language directories based on v8s-site-config.json
6. Build v8s.json, v8s-blocklist.json, and v8s-site-config.json
7. Generate src/ from scripts/workers/ for Wrangler

Runtime artifacts

The Worker does not read v8s-links.txt on every request. The build creates runtime artifacts from source files, validates them, and deploys them with the Worker assets.

Build inputs include:

• defaults/v8s-links.txt, replaced by custom/v8s-links.txt when present, including inline @schedule blocks
• custom/v8s-schedules.json when present as a deprecated 3.x compatibility source
• defaults/v8s-policies.json, replaced by custom/v8s-policies.json when present
• defaults/v8s-site-config.json, with custom/v8s-site-config.json merged into site-level choices
• static page assets from defaults/public/, overlaid by custom/public/
• generated blocklist feed data when npm run generate:blocklist has produced it

The build writes:

scripts/workers/ is the Worker source of truth. src/ is generated output. Direct public requests for raw runtime files such as /v8s.json, /v8s-blocklist.json, and /v8s-site-config.json should return 404.