Debugging Guide

When things go wrong, use these strategies to identify the root cause.

Dev Server Issues

If the dev server behaves unexpectedly (styling broke, infinite reload loop, etc.):

1. Stop the server: Press Ctrl + C.
2. Clear cache: Run rm -rf node_modules/.vite.
3. Restart: Run pnpm dev.

Note

Sometimes simply restarting the server fixes weird caching issues, especially after installing new packages.

Debugging Build Issues

Production builds can fail even if the dev server works. This is often due to stricter type checking or missing files.

How to debug:

1. Run pnpm build locally.
2. Read the error log carefully from the top. The first error is usually the root cause.
3. Check for “Is not assignable to parameter of type” errors—this indicates a TypeScript mismatch.

Network Debugging

When fetching data from Ghost CMS or other APIs:

1. Check the Network Tab: Open Browser DevTools (F12) -> Network.
2. Filter by Fetch/XHR.
3. Look for red (4xx or 5xx) requests.
4. Inspect the Response: Click the request and check the “Response” tab to see the API error message.

VS Code Extensions

We recommend these extensions to catch errors early:

• Astro: Syntax highlighting and IntelliSense for .astro files.
• ESLint: Real-time linting errors.
• Prettier: Automatic formatting.
• Tailwind CSS IntelliSense: Autocomplete for utility classes.

”It works on my machine”

If it works locally but fails on Cloudflare Pages:

1. Check Node Version: Ensure Cloudflare is using the same Node version (check .nvmrc or package.json engines).
2. Check Environment Variables: Are production secrets set in the Cloudflare dashboard?
3. Check Case Sensitivity: Linux (CI/CD) is case-sensitive. Image.png and image.png are different files. macOS is usually case-insensitive.