Ship HTML by default, and add JavaScript only where it earns its place.
Astro renders to HTML at build time and ships no JavaScript unless a component asks for it. For content-heavy sites — documentation, publications, marketing pages — that default is the whole argument.
Reach for it when most of the page is content and interactivity is localised: a search box, a theme toggle, a carousel. Reach for a full application framework when most of the page is application state, because Astro’s island model stops paying off once the islands cover the screen.
Two concepts carry most of the day-to-day work. Output mode decides whether
pages are built ahead of time or rendered per request, and it can be mixed —
output: 'server' with export const prerender = true on the static routes
gives you edge-cached HTML for the pages that do not change and a server only
where you need one. Content collections give schema-validated content, so a
malformed frontmatter field fails the build instead of rendering a broken page.
Deployment is where the version-specific detail lives. A fully static build is a directory of files and needs no adapter at all. Server output needs an adapter matching the host, and the entry point it produces only exists after a build — which is why the most common deployment failure is a config pointing at a file that was never generated.
The other thing worth internalising early is that import.meta.env is a
build-time inline. Anything read through it in a prerendered or client context
is baked into the output. Secrets belong in a server route reading from the
runtime environment, and nowhere else.
Start here
Ship a static or server-rendered Astro site to Cloudflare Workers with Wrangler — adapter setup, wrangler.jsonc, nodejs_compat, secrets, custom domains and the errors you hit on the first deploy.
A reading order that builds Astro knowledge in the sequence it is actually needed.
Failure modes that come up repeatedly with Astro, and where each one is solved.
Ship a static or server-rendered Astro site to Cloudflare Workers with Wrangler — adapter setup, wrangler.jsonc, nodejs_compat, secrets, custom domains and the errors you hit on the first deploy.
Ship a static or server-rendered Astro site to Cloudflare Workers with Wrangler — adapter setup, wrangler.jsonc, nodejs_compat, secrets, custom domains and the errors you hit on the first deploy.
When something has to be decided per request — a session, a redirect based on headers, a form handler. Keep the rest prerendered with `export const prerender = true` so only those routes pay the cost.
No. Astro components handle most of a content site on their own. Add React, Svelte or Vue only for the islands that genuinely need client-side state, because each integration adds to the bundle.
Type-safe, schema-validated content. You define a schema, Astro validates every file against it at build time, and the build fails on a bad frontmatter field rather than rendering a broken page.