Building with Astro?

Astro build broken or islands misbehaving? We ship it properly.

Astro shines on content-heavy sites until a content collection schema changes under you, an island hydrates in the wrong order, or Vercel starts timing out the build because MDX is reparsing every page on every change. We dig through the integrations, the renderer and the Vite config until the site ships again, reliably, on a budget you can predict.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

astro-build.log

still broken

What it is

Astro at a glance

Astro is a web framework by Fred K. Schott, first released in 2021, built around content-first sites and the islands architecture. Pages ship as plain HTML by default, and interactive components (React, Svelte, Vue, Solid, Preact or Lit) are opted into with explicit `client:*` directives, so you pay for JavaScript only where interactivity is actually needed.

Content collections give a typed layer over Markdown, MDX and JSON with Zod schemas, which is a large reason marketing and documentation teams pick it. Astro 4 and later added server islands for partial dynamic rendering, a View Transitions integration, and adapters for Node, Vercel, Netlify, Cloudflare and static output. It is especially common on Vercel and Netlify as a replacement for Gatsby or a hand-rolled Next.js setup.

Type
Content-oriented web framework with islands architecture
First released
2021
License
MIT
Maintained by
The Astro core team and open-source contributors
Typically used for
Marketing sites, documentation, blogs, e-commerce storefronts, content-heavy SaaS landing pages

The honest version

Astro pros and cons

No technology is all upside. This is where Astro earns its place and where it tends to cause trouble.

Where Astro is strong

  • Zero JavaScript by defaultA page ships as HTML and CSS unless a component is explicitly hydrated. Lighthouse scores stay high because the browser is not downloading framework code it will never run.
  • Islands are opt-in`client:load`, `client:idle`, `client:visible` and `client:only` make hydration decisions explicit per component, so the JavaScript payload is a review decision, not an accident.
  • Any UI framework fits inReact, Svelte, Vue, Solid and others coexist in the same project. You can migrate from one to another incrementally instead of doing a Big Rewrite.
  • Content collections with ZodMarkdown and MDX get typed, validated frontmatter, so a missing date or malformed tag fails at build rather than silently rendering a broken page.
  • Built for the edge and for staticThe same codebase can prerender to a bucket, run on Node, or run hybrid on Vercel or Netlify with server islands for dynamic bits only.
  • Fast builds for content sitesContent-only sites build in seconds to a couple of minutes at hundreds-of-pages scale, well inside most CI budgets.

Where Astro bites

  • Not a good fit for app-heavy UIsIf every page is a dashboard with rich interactivity, you lose most of the islands benefit and are better served by Next.js, SvelteKit or Nuxt.
  • Hydration model has edge casesComponents can hydrate out of expected order, shared state across islands needs a store the renderers can all see, and `client:only` pays double for SSR skip plus client cost.
  • Content collection migrations hurtChanging a schema field on a collection with hundreds of entries means fixing hundreds of markdown files, and Astro 5 moved several APIs that mature codebases now have to catch up with.
  • MDX can get slowHeavy MDX with imported React components and remark/rehype plugins compounds build time quickly, and caching does not always help between CI runs.
  • Smaller library ecosystemAstro-specific integrations are a shorter list than the equivalents for Next.js, and some React libraries assume a React tree that does not exist outside an island.
  • Adapter and runtime gotchasNode, Vercel edge, Vercel serverless and Cloudflare each expose slightly different runtime quirks that only surface after the first real deploy.

Sound familiar?

Common Astro problems we fix

The Astro problems that bring people to us, and what you have once each one is fixed.

ZodError: expected date, received string

Content collections fail on build

A markdown file with the wrong frontmatter type, a schema tightened after dozens of posts were written, or a field renamed without a migration sweep across the content folder.

Collections clean, schema matches reality

AstroUserError: Unable to generate static paths

Dynamic routes return nothing or crash

A `getStaticPaths` that fetches from an API the build runner cannot reach, a database env var missing in CI, or a null from a CMS that was not guarded against.

Paths generated reliably in CI

client:load on 180kb component

The site ships more JavaScript than expected

Marketing pages with `client:load` on large components that could have used `client:visible`, or an island importing a whole icon library for one SVG.

Hydration scoped, bundle trimmed

Vercel build timeout at 45:00

Builds are timing out on CI or Vercel

MDX reparsing every page on every change, no incremental caching, or a prerender pass that re-fetches the CMS for every page even when only one changed.

Builds fast enough for the host

no handoff, previous agency unreachable

We inherited an Astro site we cannot rebuild

A repo that builds on one machine, locked deployment credentials, custom integrations with no readme, and environment variables scattered across three dashboards.

Site owned, documented, buildable anywhere

Hydration warning: text content did not match

Hydration mismatches flicker during load

Dates formatted in server locale and then client locale, a random ID generated on both sides, or data fetched differently on server vs client.

Markup consistent across renders

Astro 3.x · integrations behind

Astro upgrades are overdue

Minor versions skipped, integrations frozen at old releases, and new features (server islands, actions) locked out until the upgrade is done properly.

Project on a current, tested version

What we do

Astro help, from rescue to launch

Bring us one failing build, or the whole marketing stack.

Rescue
A build pipeline that will not go green, a content collection that broke overnight, or a Vercel deploy nobody can reproduce locally. We start by making it build again.
Performance review
Audit of `client:*` directives, image handling, prefetching and font loading against your real Lighthouse and Core Web Vitals numbers.
Content migrations
Moving a blog or docs site from Gatsby, Jekyll, Hugo or WordPress into Astro collections, with redirects and SEO continuity accounted for.
Hybrid and server islands
Adding dynamic sections (cart counts, auth state, personalized blocks) to a mostly-static site without regressing the Lighthouse score.
Agency takeover
An Astro site built by someone else, now in your hosting, your repo and your DNS, with a readme that lets any engineer pick it up.
Managed Tech
Version bumps, integration upgrades, image and CMS plumbing watched over time, and someone to call when a Vercel adapter change breaks the pipeline.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Astro alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Astro questions

Something else? Call+1 737 727 7327

Is Astro the right choice over Next.js or SvelteKit?

For content-led sites: usually yes. Marketing pages, documentation, blogs and e-commerce storefronts are where Astro's zero-JS-by-default model pays off directly in Core Web Vitals. For app-first products with heavy interactivity on every page, Next.js or SvelteKit is a better fit, and we will say so rather than push a tool.

Can we migrate a Gatsby or WordPress site to Astro?

Yes, and it is one of the more common migrations we do. We move content into collections with typed schemas, port templates, keep URL paths and canonicals stable so SEO does not take a hit, and set up 301 redirects for anything that does have to move.

Why does our Astro build take 30 minutes on Vercel?

Most often it is MDX with heavy remark/rehype plugins reparsing every file, images not cached between builds, or a content source fetching the full CMS for every page. We profile the build, find the hot path, and get it back inside a sensible CI budget.

Can you take over an Astro project from a previous developer?

Yes. We inventory integrations, pin versions, move the deployment and any CMS or analytics credentials into your accounts, and leave you with a repo and a readme good enough for any engineer to continue from.

Should we use server islands or stay static?

If 95 percent of the site is content and you only need a small dynamic bit (a logged-in header, a cart count, personalization), server islands are a good fit and keep the rest static. If large portions are dynamic, hybrid or full SSR is usually cleaner than peppering islands everywhere.

How much does Astro help cost?

Estimates cost nothing. Share the repo link or a note about what is broken, and a quote lands before any work starts.

Free estimate

Astro site giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.