

To build an Astro website, create a project with npm create astro@latest, add pages and a shared layout, put your content in collections or a CMS, add interactive islands only where you need them, and deploy the built files to a host such as Cloudflare Workers. This guide walks through each step in the order we follow, with the decisions that matter along the way.
seahawkmedia.com is an Astro site with more than 20,000 pages, so the advice here comes from running one in production. If you have never used Astro and want a gentler start, Astro Nursery has free, beginner-friendly tutorials for building your first site.
Is Astro right for your website?
Astro is an open-source framework for content-driven websites. It turns pages into plain HTML when the site is built and sends JavaScript to the browser only for components that need it. That makes it a strong fit for:
- Marketing and brochure sites, service pages, and landing pages.
- Blogs, publications, and documentation.
- Sites where page speed and a small security surface are business goals.
- Teams that will have a developer or agency own the code.
It is a weaker fit for logged-in applications where nearly every screen is interactive, and for teams that want to build and edit the whole site themselves without a developer. Our What Is Astro? guide explains the framework, and WordPress vs Astro helps you decide for a small business site.
Step 1: Set up the project
You need Node.js on the machine that builds the site; current Astro 7 releases require Node.js 22.23.4 or later. Check with node --version, then create a project:
npm create astro@latest
The setup wizard asks for a folder name and a starting template. The minimal template is the cleanest base for a custom design; the blog template is useful if you want working examples. Then start the development server:
cd my-site
npm run dev
Your site is now running at http://localhost:4321 and updates as you save files. A new project has a predictable layout:
src/pages/: one file per page or route.src/layouts/: shared page shells, such as the header, footer, and head tags.src/components/: reusable pieces of the design.public/: files served as they are, such as the favicon and robots.txt.astro.config.mjs: site settings and integrations.
Before you go further, set your production address in astro.config.mjs with site: 'https://www.example.com'. Astro uses it to build canonical URLs and the sitemap.
Step 2: Create pages and routes
Astro uses file-based routing. src/pages/index.astro becomes your home page, src/pages/about.astro becomes /about/, and src/pages/services/design.astro becomes /services/design/. Plan your URL structure now, because changing it after launch means redirects.
For pages generated from content, such as blog posts, use a dynamic route. A file named src/pages/blog/[slug].astro exports a getStaticPaths() function that returns one entry per post, and Astro builds a page for each. Decide early whether URLs end with a trailing slash and set trailingSlash in the config so every link is consistent.
Step 3: Build a layout and components
An .astro file is HTML with a short script block at the top. A layout wraps every page in the same shell and puts each page's content where the <slot /> is:
---
// src/layouts/Base.astro
const { title, description } = Astro.props;
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>{title}</title>
<meta name="description" content={description} />
<link rel="canonical" href={canonical} />
</head>
<body>
<slot />
</body>
</html>
Build the rest of the design as small components (header, footer, cards, calls to action) and pass them data through props. Astro components render to HTML with no JavaScript sent to the browser, so you can use as many as the design needs.
Step 4: Add your content
For most sites, content lives in content collections: folders of Markdown or data files with a schema you define in src/content.config.ts. Astro checks every entry against the schema when it builds, so a post with a missing title fails the build instead of going live broken. Pages then query the collection:
---
import { getCollection } from 'astro:content';
const posts = (await getCollection('blog'))
.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<ul>
{posts.map((post) => (
<li><a href={`/blog/${post.id}/`}>{post.data.title}</a></li>
))}
</ul>
If non-technical people will edit the site, the content can come from a CMS instead: a Git-based editor, headless WordPress, a platform such as Sanity or Storyblok, or EmDash. Our Astro CMS guide compares the options; step 9 below covers how to choose.
Step 5: Add interactivity with islands
Most of a content site needs no JavaScript. For the parts that do, such as a mobile menu, a search box, or a calculator, Astro uses islands: individual components that load JavaScript while the rest of the page stays static. Add a UI framework with one command, for example npx astro add react, then mark each interactive component with a directive:
client:loadloads it as soon as the page loads.client:idlewaits until the browser is idle.client:visiblewaits until the component scrolls into view.
Leave the directive off and the component renders to HTML with no JavaScript at all. Small behaviors, like toggling a menu, can also be a few lines in a plain <script> tag without a framework. For contact forms, either post to a form service or add an adapter and handle the submission on the server. Our guide to Astro integrations covers which ones to add first.
Step 6: Handle images and performance
Use Astro's built-in <Image /> component from astro:assets for images in your project. It resizes them, converts them to modern formats, sets width and height to avoid layout shift, and lazy-loads them by default. Put large photos through it rather than in public/, which serves files untouched.
Beyond images, keep performance by keeping JavaScript to the islands that need it, loading only the font weights you use, and checking third-party scripts such as chat widgets and analytics, which often cost more than the site itself. Test key pages with PageSpeed Insights on mobile before launch.
Step 7: Cover the SEO basics
- Titles, descriptions, and canonicals come from your layout, as in the example above. Give every page its own.
- A sitemap comes from the official integration: run
npx astro add sitemap. It needs thesitesetting from step 1. - Redirects for any URLs that change can go in the
redirectsoption inastro.config.mjs, or in your host's redirect rules. - Structured data is a JSON-LD script in the layout, filled from page data.
- A custom 404 page is
src/pages/404.astro.
If you are moving an existing site to Astro, map every old URL to its new address before launch. Our guide to the best CMS for SEO explains which controls matter most.
Step 8: Deploy
Run npm run build and Astro writes the finished site to dist/: HTML, CSS, JavaScript for your islands, and optimized images. A pre-built site needs no server, so almost any host can serve it.
- Cloudflare Workers: what we use for this site. A pre-rendered build needs only a short Wrangler config pointing at
dist. Our step-by-step guide to deploying Astro to Cloudflare Workers covers the config, custom domains, and deploying from CI on every push. - Netlify and Vercel: connect the repository and they detect Astro and build it for you.
- Any static host or CDN: upload the
dist/folder.
If some pages must render on demand, such as a members area or a search results page, add the adapter for your host with npx astro add and opt those pages out of pre-rendering. Everything else stays static. Our list of Astro and EmDash hosts compares the options.
Step 9: Decide how content will be edited
This is the decision that most affects life after launch. Answer one question: who edits the site, and how often?
- A developer, a few times a year: Markdown in content collections is enough.
- A non-technical person, occasionally: a Git-based CMS gives them a web editor without adding a database.
- An editorial team, daily: a headless CMS, or headless WordPress if they already know it.
- A team that wants a full admin, structured content, or AI agents publishing: EmDash, the CMS built for Astro.
Our stack page shows how these setups compare with WordPress.
Step 10: Maintain the site
An Astro site has fewer moving parts than a plugin-heavy CMS, but it still needs care:
- Update regularly.
npx @astrojs/upgradeupdates Astro and its official integrations together. Update other dependencies on a schedule, and test the build before deploying. - Budget for major versions. Major releases can bring breaking changes, so plan time for them as you would for any platform upgrade.
- Keep the build green. Run the build in CI on every change so broken content or code never reaches production.
- Monitor the live site. Uptime checks, broken link scans, and Search Console reports catch problems that a build cannot.
- Back up anything outside Git. Code and Markdown are versioned already; CMS content and media need their own backups.
Launch checklist
- The
sitesetting matches the production domain. - Every page has a unique title, description, and canonical URL.
- The sitemap builds and robots.txt points to it.
- Redirects are in place for any changed URLs.
- The 404 page works on the live host.
- Images go through the
<Image />component and key pages pass a mobile speed test. - Forms deliver to the right inbox.
- Analytics and Search Console are set up.
- Deploys run from CI, and someone owns updates.
Getting help
If you would rather not build it yourself, Em Workers builds and looks after Astro and EmDash sites for small businesses. For larger or headless projects, Seahawk VIP builds Astro front ends on WordPress, EmDash, and other headless platforms.
Frequently asked questions
Do I need to know how to code to build an Astro website?
Yes, at least HTML and CSS. Astro is a developer tool, not a drag-and-drop builder: pages are files, and the design is written as components. JavaScript helps for interactive parts, and React or another framework is optional. If you would rather not code, a developer or agency can build it and add a CMS so you can edit content yourself.
How long does it take to build an Astro website?
A developer who knows Astro can set up a small brochure site in days once the design and content are ready. A larger site with custom content types, a headless CMS, and integrations takes weeks. Most of the time goes into design, content, and CMS setup, not into Astro itself, which is quick to configure.
Where can I host an Astro website?
A pre-built Astro site is a folder of HTML, CSS, and images, so almost any host can serve it: Cloudflare Workers, Netlify, Vercel, or any static host or CDN. If some pages render on demand, you need a host with an Astro adapter, such as Cloudflare, Netlify, Vercel, or a Node.js server.
Can I edit an Astro website without a developer?
Yes, if a CMS is added. Out of the box, content lives in files that developers edit. A Git-based CMS gives editors a web interface for those files, a headless CMS such as WordPress or Storyblok gives them a full editor, and EmDash adds a WordPress-style admin built for Astro. Choose based on who edits and how often.
Is an Astro website good for SEO?
Astro gives you a strong technical base: pages are pre-built HTML that search engines can read without running JavaScript, pages load quickly, and you control every tag. It does not do SEO for you. You still need unique titles and descriptions, canonical URLs, a sitemap, redirects for changed URLs, structured data, and good content.
How do I move my WordPress site to Astro?
You can keep WordPress as the editor and rebuild only the front end in Astro (headless), or move content into Markdown or EmDash and retire WordPress. Either way, rebuild the theme as Astro components, replace plugin features, map every old URL with redirects, and carry over SEO fields. EmDash includes an importer for WordPress content.


