cloudflare-pages-vanilla-preferences.md

name	description	version	author
cloudflare-pages-vanilla-preferences	Follow Bastiaan's Cloudflare Pages preferences when discussing, advising on, generating code for, or debugging Cloudflare Pages projects (especially vanilla HTML/CSS/JS setups). Use this skill whenever the user mentions Cloudflare Pages, Pages Functions, wrangler, static sites on Pages, vanilla JS, routing, dynamic routes, file structure, or related issues.	1.4	Bastiaan Quast (@baquast)

Core Preferences & Rules – Always Obey These

Project Structure & Files – Static Assets

• Prefer flat structure at root (.) for small to medium projects — do NOT introduce subfolders by default.
  • Good small-project layout example:
    • index.html
    • style.css
    • app.js
    • logo.png
    • favicon.ico
  • Only create a subfolder (css/, js/, img/, assets/, fonts/, etc.) when the number of related files reaches roughly 5 or more.
    • Example trigger: 5+ images → move to img/
    • 5+ JS files → move to js/
    • Keep everything flat until that threshold to maximize simplicity and quick scanning.
  • Avoid unnecessary nesting like /public/, /src/, /static/ unless the entire site is intentionally namespaced (very rare in vanilla setups).
• Serverless logic always goes in /functions/ (Pages Functions – Workers runtime)
• Common API pattern: /functions/api/ (→ routes like /api/submit)

Routing Conventions (file-based – syntax is strict)

• Single segment: [id].js → params.id = string (one path part)
• Catch-all / multi-segment: [[catchall]].js → params.catchall = array (zero or more segments)
• Never use ellipsis inside brackets ([[...slug]] breaks the build – invalid syntax)
• More specific routes (fewer wildcards) take precedence
• Trailing slash optional (/foo == /foo/)

Params Access

• Single: context.params.id → string
• Catch-all: context.params.catchall → array (or empty array)

Wrangler & Dashboard

• Minimize wrangler.toml – often breaks Pages deploys
• Bindings (D1, KV, R2, secrets, env vars) → set in dashboard (Pages > Settings > Functions > Bindings / Environment variables)
• wrangler only for compatibility_date, local [vars], basics

JavaScript & Libraries

• Vanilla HTML/CSS/JS – no frameworks or heavy builds if possible
• Avoid CDNs for JS libs (unreliable on Pages):
  • Download minified standalone → commit locally (e.g. /js/lib/htmx.min.js)
  • Include: <script src="/js/lib/htmx.min.js" defer></script>
• CDN only as last resort (huge libs with SRI)

Other Rules

• Fast & minimal – relative paths (./style.css), async/defer on scripts
• Functions for forms, persistence, secrets
• In code examples: use flat root paths unless subfolders are justified by file count
• Remind dashboard bindings for any storage/secret usage