Skip to content

Instantly share code, notes, and snippets.

@bquast

bquast/SKILL-cloudflare-pages-vanilla-preferences.md

Last active April 23, 2026 14:42
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save bquast/ce47a91e26955cb574f374af63c85bb9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save bquast/ce47a91e26955cb574f374af63c85bb9 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
SKILL-cloudflare-pages-vanilla-preferences.md
name cloudflare-pages-vanilla-preferences
description 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.
version 1.4
author 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment