Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 37 ยท Projects and Practice

Astro Practice: Common Mistakes, Debugging and Exercises

Review the most common Astro mistakes (islands, hydration, paths, SSR, images), learn a debugging routine and practise with exercises and a final checklist.

You now know the whole Astro toolbox, from routing to server islands. This closing lesson is a practice set: the mistakes people make most often, a repeatable way to debug, and exercises to cement the skills. Work through them in a scratch project.

Fifteen common mistakes

# Mistake Why it hurts Fix
1 Adding client:load to everything Ships framework code for static content Start with no directive; use visible/idle
2 Forgetting a client directive Component renders but buttons do nothing Add the directive that fits
3 Passing functions as island props Not serialisable; build error Handle events inside the island or use stores
4 Reading window in a server render window is not defined Use effects/onMount, or client:only
5 Assuming scoped CSS reaches slotted or child markup Styles "do nothing" :global() on that part
6 Dynamic Tailwind class names Classes never generated Write full class names
7 Images in public/ No optimisation Import from src/assets/ and use <Image />
8 Remote image without size or inferSize Build error or layout shift Provide dimensions, allow the domain
9 Using cookies or Astro.request on a prerendered page Empty data, build warnings prerender = false for that page
10 Sharing state between islands with React context Islands are separate roots Nano Stores or events
11 Page-load scripts with ClientRouter Run once, not per navigation astro:page-load
12 Wrong site/base/trailingSlash Broken links and sitemaps Decide early; use BASE_URL
13 Secret in a PUBLIC_ variable Exposed in the bundle Server-only variable
14 Trusting client input in endpoints Security holes Validate with Zod; re-check auth
15 Testing performance on the dev server Misleading numbers astro build && astro preview

A debugging routine

  1. Read the error top to bottom. Astro prints the file, the line and a hint. The first line usually names the cause.
  2. Decide where it happens: build time, server render, or browser. The terminal shows the first two; the browser console shows the third.
  3. Reduce. Comment out islands until the page works, then add them back one by one.
  4. Check the generated HTML with "View source". If the content is there, your component is fine and the problem is hydration or CSS. If it is missing, the data or route is wrong.
  5. Inspect hydration. Islands appear as <astro-island> elements with component-url and client attributes. No element means no directive.
  6. Verify the build. Run astro check for type errors and astro build for static-generation errors.
  7. Compare dev with preview. If a bug appears only after build, suspect prerendering, hashing or base paths.

Exercises

Do these in order; each reuses the previous work.

  1. Static foundation. Create a three-page site (Home, About, Contact) with a shared layout, a navigation component that marks the current page with aria-current, and scoped styles. No JavaScript should ship (check the Network tab).
  2. Collection. Add a books collection from a JSON file with fields title, author, year and tags. Generate a list page and a detail page per book with getStaticPaths. Add a schema rule that rejects a year in the future.
  3. Images. Add a cover image per book using <Image /> with two widths. Compare the file sizes with the originals.
  4. Island. Add a search box island (any framework) that filters the list by title. Try client:load, client:idle and client:visible; note when each fires.
  5. Shared state. Add a "favourites" store with Nano Stores. A heart button on each card adds a book, and a header badge shows the count, persisting across reloads.
  6. Endpoint. Add /api/books.json (static) and /api/random (dynamic, returns one random book). Return correct status codes for bad methods.
  7. Middleware. Add middleware that adds x-request-id to responses and logs method and path. Protect /admin with a cookie check.
  8. Action. Add a "suggest a book" form as an Action with Zod validation that works without JavaScript.
  9. Transitions. Add <ClientRouter />, morph the cover image between list and detail, and keep an audio element persisting.
  10. Ship it. Set site, add a sitemap and RSS, run Lighthouse on a throttled mobile profile, and deploy to a static host. Then write down your three biggest numbers (JS KB, LCP, CLS).

Self-check quiz (explain, don't memorise)

Try answering these out loud before checking:

  • What is the difference between client:visible and client:idle, and which would you pick for a comment box?
  • Why must transition:name values be unique?
  • When would you choose an Action over an endpoint?
  • What can a prerendered page not know at build time?

Try it: a static-analysis checker for mistakes

Real linters do this properly; this stand-in uses simple patterns on page source text to flag a few of the mistakes above. Paste different snippets to see which rules fire.

JS Astro mistake detector

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: rate your build with a score card

A tiny stand-in that turns your final numbers into a report, so you can compare versions of your site.

JS Performance score card

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A button inside a React component does nothing when clicked. What is the most likely cause?

    Without a client:* directive Astro renders the component to HTML and does not hydrate it, so handlers never attach.
  2. 2. In the debugging routine, what does viewing the page source tell you?

    If the content is in the source, the server render worked and the issue is in hydration or styling.
  3. 3. Which is the correct response to window is not defined during the build?

    Server rendering has no browser globals. Defer browser-only code until the component runs in the browser.
  4. 4. Why test performance with astro preview rather than astro dev?

    The dev server is unminified and unhashed; only the production build shows real numbers.

Summary

  • Most Astro bugs come from a handful of mistakes around directives, serialisation, server versus browser code, paths and caching.
  • Debug by locating the stage (build, server, browser), reducing, and reading the generated HTML.
  • Ten exercises take you from a static site to a deployed, measured, interactive one.
  • Keep your own checklist; measure with the production build.

Next: Back to the Astro track