Troubleshooting Playbook

Common Pitfalls

❌ Don’t

• Hard-code colors, spacing, shadows, or typography values.
• Create deep descendant selectors (.a .b .c .d { }).
• Add inline HTML strings in JavaScript (XSS risk).
• Commit generated files (index.html, sitemap.xml, tag pages).
• Introduce new breakpoints without justification.
• Skip testing (bun run test and bun run lint) after meaningful changes.
• Make production-facing changes without running the build first.

✅ Do

• Use design tokens from tokens.css.
• Keep selectors shallow and scoped.
• Test dark mode and reduced motion preferences.
• Run bun run verify before committing.
• Check accessibility (labels, alt text, keyboard navigation).
• Document complex patterns with comments.
• Follow existing patterns and conventions.
• Read relevant docs before making changes.

Build Errors

bun run build runs the full site build. Use SKIP_BUILD_HOME=1 bun run build when you intentionally want to reuse existing output for quick local checks.

Issue: bun run build fails with “Cannot find module”

rm -rf node_modules
bun install
bun run build

Issue: Missing shared copy keys

Add keys to app/src/content/site.json:

{
  "foo": {
    "bar": "Translation text"
  }
}

Issue: Astro build fails with component not found

ls app/src/components/MyComponent.astro  # Ensure file exists
# Confirm import path matches the component location

Cloudflare-specific issues

Checklist

• Confirm the project uses the repo-pinned Wrangler version and the local bunx wrangler binary.
• Ensure the social card SVG template is available in assets/social-card.svg and copied into app/dist/assets/ after builds.
• Inspect preview/deploy bundles for Cloudflare API 4xx/5xx errors and ensure required env vars are set.

Verify pinned Wrangler

rg -n "wrangler" package.json          # Check the dev dependency and version
bunx wrangler --version                  # Uses the local binary; confirm version matches package.json
which wrangler                          # Should resolve to node_modules/.bin/wrangler

Verify social card template asset

ls assets/social-card.svg
bun run build
ls app/dist/assets/social-card.svg

Diagnose Cloudflare API errors (4xx/5xx)

sed -n '1,80p' app/dist/_worker.js      # Check the generated worker for fetch/publish URLs
rg "process.env" app/dist/_worker.js   # Confirm env vars are inlined/available

• Review wrangler.toml and .dev.vars for missing or malformed secrets.
• Inspect build logs for Cloudflare-specific errors such as:
  • HTTP status client error (4xx) when calling Cloudflare API
  • HTTP status server error (5xx) when calling Cloudflare API
  • Error: failed to publish worker script
  • Error: The package size is too large
• If previews fail, ensure the worker bundle was written to app/dist/_worker.js and includes patched asset paths.

Test Failures

Issue: Smoke tests fail after content changes

node --test tests/smoke/navigation.smoke.test.mjs
# Often missing navigation keys in site.json

Issue: E2E tests timeout

bun run prepare:tests
pkill -f http-server
bun run test:e2e

For local development:

ls -la .dev.vars
cat .dev.vars  # KEY=value, no quotes
pkill -f wrangler && bun run dev

Site copy issues

Issue: Shared strings not updating

bun run build
ls app/src/content/pages/en/
ls app/src/content/site.json
rg "navigation\\.|pages\\." app/src/content/site.json

Performance Issues

• See ../build-optimizations.md for tuning options.
• Avoid unnecessary watchers; build only what changed:

bun run build
bun run build:site
bun run prepare:tests

• Check emitted CSS sizes with ls -lh app/dist/assets/*.css and trim unused imports in app/src/styles if needed.

Workflow Issues

Issue: Changes not visible in browser

1. Run bun run build:site.
2. Hard refresh (Cmd+Shift+R / Ctrl+Shift+R).
3. Clear browser cache.
4. Check DevTools Console for errors.

Issue: Git refusing to commit

git status
rg -n "index.html|app/dist|sitemap.xml" .gitignore
git rm --cached index.html

Issue: Linter errors blocking commit

bun run lint
bun run format
bun run lint:css
bun run lint:js