Cheatsheet
Use this cheatsheet when you already know the product and need the shortest path to the next correct action. It is designed to work on screen and as a browser-generated PDF.
Daily workflow
| Need | Action / file | Notes |
|---|---|---|
| Install deps | npm install | Run once after checkout or dependency changes. |
| Start locally | npm run dev | Runs the Worker through Wrangler for local testing. |
| Validate | npm run check | Builds and checks generated runtime artifacts before deploy. |
| Deploy | git push | GitHub and Cloudflare automation publish the Worker. |
Repositories
| Surface | Repository | Deploys to |
|---|---|---|
| Redirector | vanityURLs/code | https://VanityURLs.link |
| Documentation | vanityURLs/website | https://www.VanityURLs.link |
| Generated output | build/, src/ | Do not edit directly. |
Core files
| File | Use | Owner |
|---|---|---|
custom/v8s-links.txt | Human-authored redirect list. | Instance |
custom/v8s-site-config.json | Branding, contacts, languages, timezone. | Instance |
custom/v8s-policies.json | Allow domains, blocked domains, keyword policy. | Instance |
defaults/ | Product baseline copied or merged during build. | Product |
Link row format
| Field | Example | Notes |
|---|---|---|
| Slug | docs | Public path segment. Keep it readable and durable. |
| Target | https://example.com/docs | Destination URL after policy checks. |
| State | active | Controls whether the redirect should resolve. |
| Metadata | title, owner, notes | Helps review, audit, dashboard display, and handoff. |
Schedules
| Need | Syntax | Notes |
|---|---|---|
| Timed target | @schedule | Indent schedule blocks below the link row. |
| Timezone | America/Toronto | Use IANA timezone names accepted by the runtime. |
| Exact links | /launch | Schedules apply to exact links, not splat namespaces. |
| Fallback | Link row target | The normal target remains the default outside windows. |
Redirect behavior
| Input | Behavior | Check |
|---|---|---|
| Known active slug | Redirects to target. | Confirm target and policy allow it. |
| Inactive or expired slug | Shows the matching status page. | Review state, dates, and generated registry. |
| Blocked destination | Does not redirect. | Check policy source and generated blocklist. |
| Unknown path | Returns not-found handling. | Check slug spelling and generated routes. |
Customize safely
| Goal | Use | Avoid |
|---|---|---|
| Change links | custom/v8s-links.txt | Editing build/v8s.json. |
| Brand pages | custom/v8s-site-config.json | Copying full templates unless needed. |
| Override assets | custom/public/ | Changing product defaults for one instance. |
| Change Worker code | scripts/workers/ | Editing generated src/. |
Troubleshooting
| Symptom | Check | Likely fix |
|---|---|---|
| Works locally, not live | GitHub action and Worker deploy status. | Push, wait for deploy, then retest. |
| Link missing | Generated build/v8s.json. | Fix source row, then rebuild. |
| Wrong language page | Configured languages and localized overrides. | Add localized page or rely on fallback. |
| Schedule surprises | Operator timezone and date window. | Use explicit IANA timezone names. |
Quick comparisons
| Choice | Use this when | Remember |
|---|---|---|
defaults/ | You are changing the product baseline for every instance. | Review as product behavior. |
custom/ | You are changing one deployed instance. | Best place for operator-owned changes. |
| Exact slug | The public path must resolve to one known destination. | Supports schedule behavior. |
| Splat namespace | A stable prefix should forward nested paths. | Do not use for time-sensitive redirects. |