Stardrive - the Astro boilerplate for the AI age

🚀 Intro and Philosophy

Stardrive is a very opinionated boilerplate for Astro.

The core idea is to have a strong boilerplate to...

1. skip the first 36 steps of creating a high-class website, if you do it manually;
2. make sure all the important basics (security, SEO, meta data, accessibility, ...) are included when using AI agents.
3. focus on providing the best technical foundation, not necessarily the most fancy design.

We are building on the amazing Astro project, because it is the maybe most performant and stable, yet flexible frontend framework out there at the very moment. It also enables you to include components from any other big JavaScript framework, like React, Vue, Svelte, or Solid.

We recommend deploying on Cloudflare as Astro and Stardrive are optimized for their workers, but you are also free to use any other hoster.

---

▶️ Demo

See astro-stardrive.com for a live demo.

It actually is a hosted version of this exact boilerplate, which already comes with all batteries included 🤩.

---

✨ Features

Everything you need to launch a fast, modern, AI-ready website - batteries included.

🤖 Built for the AI age

• LLM-friendly by design - Super well documented, so AI agents immediately know what to do.
• WebMCP prepared - Ship tools your visitors' AI agents can actually use.
• llms.txt auto-populated - Your content, served on a silver platter to LLMs.
• Schema.org auto-generated - Rich, structured data without the busywork.

🛠️ Developer experience

• Fully typed - TypeScript end to end.
• TailwindCSS - Utility-first styling, ready to go.
• ESLint & Prettier - Linting and formatting, pre-configured.
• Use any package manager - npm, pnpm, yarn, or bun.
• Centralized config - Tweak most things from a single theme.config.ts.
• Cloudflare Worker prepared - Deploy to the edge in seconds.

🎨 Design & UX

• Hot theme included - Looks great out of the box.
• Light / Dark mode - Automatic and toggleable.
• Full i18n support - Go global from day one.
• Smooth page transitions & animations - Polished feel, zero fuss.
• Dynamic header - Adapts to different use cases.
• References marquee - Show off your logos in style.
• Highly configurable pricing table - Switch between monthly, annual, and lifetime tiers, toggle prices with or without taxes, and drive everything (plans, features, prices, currency) from a single typed config file - ready for hard-coded or API-fed (Paddle/Stripe) prices.
• Optional promotional elements - Banners, signups, and more when you need them.

📝 Content

• Powerful blog - Auto-generated Table of Contents, optimized YouTube embeds, auto-highlighting of external links, reading-time calculation, and proper auto-generated social preview images.
• Events - Markdown-driven, i18n-ready, with one-click "Add to Calendar" buttons, time zones, and rich detail pages. Optionally bridge to Add to Calendar PRO for external, code-free event management.
• Markdown-based FAQ - Manage answers as simple files.

🖖 Accessibility & SEO

• WCAG prepared - Accessibility baked in.
• A thousand tiny tweaks - Optimized for SEO, social sharing, page-speed scores, and more…

---

📦 Installation

Creation

It is highly recommended to create a new project via:

npm create stardrive@latest

or

pnpm create stardrive@latest

or

yarn create stardrive@latest

bun also works as long as Node is installed as well.

The installer helps you to already adjust the boilerplate a little bit to your needs right from the beginning.

Tip

Use the flag --no-install to skip the dependency install. Use the flag --version X.X.X to use a specific version.

(Alternatively, you can also always simply fork and/or clone the official repository.)

Cleanup

Remove the following as this is only relevant for the official boilerplate demo and repository.

• ./SECURITY.md
• ./CHANGELOG.md
• ./repository-header.png
• ./.github (everything except the copilot-instructions.md; if you are not working with Copilot, remove the whole thing)
• ./scripts/syncVersion.js
• In the package.json, remove the "prebuild" script, the "sync-version" script, and the npm run sync-version && from the "fix" script.

During the further configuration, you will delete and adjust even more content, but this is the stuff, you can and should blindy trash at the very beginning.

Note

If you have created your project via the npm create stardrive command, this cleanup already happend automatically!

---

🤖 Getting started with AI

Initial configuration and kick-off

In order to get started with an AI agent or assistant, task them to configure the project first.

You can use the following prompt:

Start the configuration of this new Astro Stardrive Project. Mindt the AGENTS.md and especially the SETUP.md in the .ai folder.

More specifications about the project I want to build:
[put your specs here]

Astro MCP

You might want to add the Astro MCP to your setup. It gives the AI immediately more context. More tokens, but better results.

See their documentation for guidance.

---

🗂️ Structure

The code structure follows the official Astro scheme. It is recommended to rather keep it that way. A clear exception is the component directory. There, we rather keep the amount of files low than splitting everything into atoms. Adjust this based on your project, personal taste, and coding guidelines!

Click here to open

.
├── astro.config.ts              # Base Astro config (integrations, build, adapter)
├── theme.config.ts              # 🎯 Central project config: branding, i18n, blog, promo, llms.txt
├── eslint.config.mjs            # ESLint rules
├── tsconfig.json                # TypeScript config
├── wrangler.jsonc               # Cloudflare Worker deployment config
├── worker-configuration.d.ts    # Auto-generated Cloudflare Worker types
├── package.json                 # Defining the project and its dependencies
├── AGENTS.md                    # Entry point and general guidance for AI agents
│
├── .ai/                         # AI guides on specific topics and tasks. Triggered via AGENTS.md
│
├── public/                       # Served as-is at the site root
│   ├── _headers                  # Cloudflare HTTP headers (security, caching)
│   ├── _redirects                # Cloudflare redirects (keep updated on migrations)
│   ├── favicon.svg               # Dynamic light/dark favicon (handled inside the SVG)
│   ├── favicon.ico               # Classic favicon fallbacks (+ dark-mode variant)
│   ├── apple-touch-icon.png      # iOS home-screen icon (sits on a theme color)
│   ├── web-app-manifest-*.png    # PWA manifest icons (192/512)
│   ├── data/                     # Public downloadable files (articles/ for blog assets)
│   ├── images/                   # Stable-URL images: og.png, x.png, structured-preview.png (social fallbacks)
│   └── map/
│       └── office.pmtiles        # Demo map tiles for the contact page (replace/remove)
│
├── scripts/
│   ├── generateLLMFiles.js       # Builds llms.txt from your content
│   ├── postbuild.js              # Post-build hook (runs the steps below)
│   ├── processSocialImages.js    # Auto-generates social preview images for articles
│   ├── purgeCloudflareCache.js   # Purges CF cache after deploy (needs CF_PURGE_* env vars)
│   └── syncVersion.js            # ⛔ Demo/repo only - delete in your project
│
├── types/                        # Global type definitions
│
└── src/
    ├── content.config.ts         # Astro content collections schema (articles, faq, integrations, events)
    │
    ├── pages/                    # File-based routing - one file per route
    │   ├── index.astro           # Home page
    │   ├── about.astro · contact.astro · features.astro · pricing.astro · examples.astro · faq.astro
    │   ├── signup.astro · get-listed.astro · legal-notice.astro · privacy-policy.astro
    │   ├── 404.astro             # Not-found page
    │   ├── robots.txt.ts         # Generates robots.txt (honors the ROBOTS env override)
    │   ├── rss.xml.js            # Generates the blog RSS feed
    │   ├── site.webmanifest.ts   # Generates the PWA manifest from theme.config.ts
    │   ├── dynamic-events-sitemap.xml.ts   # Generates a sitemap for events dynamically, if we pull them in from an external API
    │   ├── [lang]/               # i18n routes (string-translated pages share this folder)
    │   ├── de/ · es/ · fr/       # Per-language folders for hard-coded/long-form content
    │   ├── blog/                 # Blog routes: [...article], [...page], categories/, tags/
    │   ├── docs/                 # Docs pages (index, guide, configuration)
    │   ├── events/               # Event listing routes: detail/[...event], [...year]
    │   └── integration/          # Integration listing routes: [type]/, index
    │
    ├── layouts/
    │   ├── default.astro         # Base page layout
    │   └── article.astro         # Blog article layout
    │
    ├── components/               # Kept intentionally coarse (not atomic)
    │   ├── headline.astro · contact-form.astro · contact-map.astro · integration-list.astro
    │   ├── webmcp-tools.astro    # Experimental WebMCP tools exposed to visitor AI agents
    │   ├── head/                 #  bits: base.astro (favicons), hreflang.astro, ogx.astro (OG/X meta)
    │   ├── layout/               # header, footer, hero, references, language + light-mode switchers, nav/
    │   ├── blog/                 # ToC, list/single, pagination, social-share, cat-tag-list
    │   ├── promo/                # Optional promo slots: banners, nav-ad, newsletter signup
    │   └── structured/           # Schema.org JSON-LD (website.astro, article.astro)
    │
    ├── content/                  # Markdown-based content collections
    │   ├── articles/             # Blog posts (per language)
    │   ├── faq-answers/          # FAQ entries as Markdown (per language)
    │   ├── events/               # Events as Markdown (per language)
    │   └── integration-options/  # Integration data (per language)
    │
    ├── i18n/                     # Translation strings - one JSON per language
    │
    ├── data/                     # Static data files (e.g. examples.json, pricing.ts)
    │
    ├── images/                   # Build-optimized images (logos, content/, references/)
    │
    ├── plugins/                  # Markdown/rehype plugins
    │   ├── external-linking.ts   # Auto-highlights & secures external links
    │   └── youtube-embed.ts      # Optimized YouTube embeds in Markdown
    │
    ├── styles/
    │   ├── tailwind.config.css   # 🎯 Tailwind base: fonts, colors/branding, breakpoints
    │   ├── global.css            # Custom global rules + single-source-of-truth styles (e.g. buttons)
    │   ├── long-text-content.css # Styling for text-heavy pages (e.g. privacy policy)
    │   ├── blog.css              # Styling for the blog section (excluding the markdown styling)
    │   └── markdown.css          # Styling for rendered markdown pages
    │
    └── utils/                    # Helpers

---

🎛️ Configuration

General

The configuration for your project happens on multiple levels.

First, you should adjust the theme.config.ts to match your requirements and specifications. This already gives the boilerplate your branding.

Second, you would adjust the whole codebase to your needs. This is an Astro project. The boilerplate brings in the easy-to-use general theme config as well as a pre-structured website. You still need to build the actual website 😉.

Third, some things are configurable via env variables at build time.

• SITE_OVERRIDE: Would override the global site url. Useful for dev environments.
• ROBOTS: Would override the global default robots setting. Useful for dev environments. Settings on the page level would still override this again!
• CF_PURGE_API_KEY and CF_PURGE_ZONE_ID: Required if you want to use the Cloudflare purge script when hosting on Cloudflare workers.
• ADD_TO_CALENDAR_PRO_API_KEY: If you want to use the pre-configured adapter for dynamically infusing events, set your API key via env variable.

Step by Step Guide

We have created a step by step guide, so you do not miss anything.

1. If you did not use the create stardrive@latest command to create the project, check the Trimming Guide to remove those features you do not need first! The guide is built for AI agents, but can also be used for manual actions. At least check the .gitignore file and update the "# Lock files" part to match your package manager (if not using npm). If you went for create stardrive@latest case, mind that npm run check would find some issues. We are intentionally not cleaning up everything in order to have some functionality still in place, if the project, for example, establishes new content collections. Use the npm run check findings to clean up manually.

2. Adjust the package.json to reflect your project.

3. Adjust the README.md file to at least hold the name of your project as headline. This makes it easier for you to identify your project later.

4. Replace the favicon and web-app-manifest files in ./public/. We recommend to use realfavicongenerator.net to do so. You only need to replace the image files. The webmanifest is generated dynamically based on the theme.config.ts. Mind that for the favicons, we have different ones for light vs. dark mode users (refering to their device, not the website). This makes sense for transparent or black/white icons. If you do not use this, also adjust ./src/components/head/base.astro and drop the dark-mode icons. For the svg file, we recommend to handle light/dark mode directly in the svg code - you can check our demo favicon.svg for reference.

5. Also replace the social preview images (og.png, x.png, structured-preview.png) in ./public/images/. They act as a general fallback, For articles, we auto-generate them from the article's main image.

6. Adjust the theme.config.ts:

   • Set the base information first - like the site url, primary color, and so on. Everything is typed here - your IDE should be able to read-he comments from the types to help you understand the respective settings.
   • Decide which languages you want to support, create a respective json file in the ./src/i18n/ directory, and import it in the config file. Adjust the "i18n" block respectively.
   • Load the expressiveCodeThemes you want to use. Pick two. 1 for light and 1 for dark mode. If you do not use dark mode, only pick one. Find the available options at the Expressive Code repository.
   • If you are using the blog feature, specifying basic article settings would be next. This mainly defines the general layout and functionality. if you decide to use the image fallback feature, check the demo fallback image and replace it.
   • Set promotion slots, if you want to - you can adjust the content later. Drop it or set everything to false, if you do not need this at the moment.
   • Last but not least, define how the llms.txt file is created. As of today, it is not clearly stated whether this is really useful or not - however, Lighthouse has started testing for it, so it doesn't hurt.

7. If you want to use Webfonts, add them by installing via fontsource. The boilerplate comes with "Geist". You might want to uninstall this with npm un @fontsource/geist and install your own. Mind to import them on the layout level!

8. Adjust the TailwindCSS base config at ./src/styles/tailwind.config.css.

   • Adjust the font section. For example, replace "Geist" with your main font or even add new font styles.
   • Adjust the colors section (Branding and maybe Utility). We recommend to only adjust color hex codes and optionally add additional ones. If you remove lines, this breaks the demo content, which can be confusing - only do this at the very end when you replaced the demo content with your own!
   • Adjusting breakpoints could be a thing for design nerds.
   • Add anything else you already know you require. But, of course, you can also adjust things any time later.

9. If you already have some CSS you want to use, adjust/extend the global.css file to your needs. Also have a look at the other CSS files in the ./src/styles folder and adjust to your needs and taste. Our logic for styling goes as follows:

   • TailwindCSS as base
   • global.css to add custom rules and base styling. We also put things there, that are duplicated a lot and where the Tailwind classes should have a single source of truth (e.g. buttons).
   • Additional CSS files for special pages (gets imported in addition on the page level). For example, we have a long-text-content.css, which is super useful to style boring things like the privacy policy page.
   • Super custom stuff goes into the respective page or component; and on that level, as Tailwind classes or into its own scoped CSS block, if we would have a lot of class duplication otherwise (mind to set the reference to the tailwind.config.css file in those <style> blocks!).

10. Delete the subfolders in ./src/content/ and ./src/pages/ for those languages (e.g. "/fr"), which you do not want to support (see step 2). If you are only using 1 language, you can also drop the ./src/pages/[lang] folder as well as the language-switcher.tsx and language-select.astro files in the components folder.

11. Check what we put into the <head> for open graph and x at ./src/components/head/ogx.astro. Extend if you want to.

12. Define your page structure and adjust the given demo structure under ./src/pages/ by creating a file (can be empty at first) per page. If you support >1 language, you should have a subfolder for that language as well as the generic [lang] folder. Pages, where i18n only happens via translated string go into [lang]. This keeps things simple. If you are changing a lot per language (different content) or have huge text blocks, put them in the explicit subfolder and hard-code the text.

13. In the astro.config.ts, we went for static site generation. You can specify some content collections to be still rendered on-demand. You can specify them in the theme.config.ts file. Integrations are set to "on-demand" for the purpose of this demo. Revert this, if your hosting solution only (!) supports static files. Also mind that you will need an Astro server adapter if you are not going for Cloudflare and want to use on-demand rendering! On-demand collections also have deferRender enabled, so their entries are not rendered eagerly during sync — lowering memory usage for large collections at the cost of not caching rendered HTML across builds.

14. Adjust the navigation in the ./src/components/layout/nav folder.

15. Check the other layout files at ./src/layouts and also everything within ./src/components/layout. Adjust to match the general layout of your website.

16. Already while building the layout, adjust the content of the json files in ./src/i18n/ to match your project.

17. Adjust or delete the map data file, which is used at the demo contact page.

18. Delete the demo content in ./src/images. Mind to keep the folder structure for the content! The images for your website should go into this images folder, images for articles and integrations into their respective subdirectoy. Fyi: Use ./public/images/ for images that need to be available via a clean and stable url to external pages/services/bots and are not about articles. Use ./public/data/ for public files you want to share - files used in articles go into the respective subfolder.

19. Run npm run check:astro and resolve all potential erros that popped up due to now missing links or stuff. This easily happens when you delete some demo content while you keep other demo files untouched.

20. Adjust the _headers and _redirects files - only if on Cloudflare. Check their documentation. If your project is a migration from an existing website, when using Cloudflare, adjust ./public/_redirects to redirect old paths to the new structure. If not using Cloudlfare, set up your hosting setup accordingly.

21. Prepare for deployment. If going with Cloudflare, you can use the integrated wrangler/worker config. Adjust the wrangler.jsonc to your needs and link your (usually) GitHub repository with a Cloudflare worker. Set environment variables for CF_PURGE_API_KEY and CF_PURGE_ZONE_ID and set npm run purge:cloudflare as command after build to clean the cache on each deployment. If you do this, you should consider setting up a rule on Cloudflare to cache all requests and not only static files. Also mind to activate Media > Images > Transformations in the Cloudflare dashboard for your Zone/Worker!

    ⚠️ Important: Disable Speed Brain in your Cloudflare dashboard (Speed → Optimization → Speed Brain). Stardrive (like Astro in general) ships with its own prefetching logic that conflicts with Cloudflare's Speed Brain, which can cause double-fetches, stale content, or broken navigation. Keep it off for any zone/worker serving an Astro site.

Tip

Find this guide in a more interactive style at our demo page!

Additional things you might want to check

1. Check the astro.config.ts file. It holds the base Astro configuration. Theoretically, you do not need to touch it, if your project is close to the boilerplate. See the official Astro docs for more information on what you can set up there.
2. In ./src/components/structured, we define a Schema.org structure for the website. This is covering an opinionated base scope. Extend, if you want to go wild on this.
3. The webmcp-tools.astro presents some basic tools to the new concept of WebMCP. This is rather experimental and acts as base and inspiration. Extend it to your needs, if you want.
4. Adjus the ESLint, Typescript, and Prettier rules, if you have special needs here and do not like the default.
5. In astro.config.ts, we explicitly disabled the session functionality, so the page can be easier deployed. Check it, if you require session handling.

Warning

Mind Astro's frontend nature! Astro is a frontend framework. This means it runs as a static site on the client side. Do never add any sensitive information here! Any backend data needs to be processed by a respective backend service. While there are things that can act as a backend service (mainly Astro's on-demand server-side rendering, optionally combined with Middleware), it still is a frontend framework.

---

🤗 Support it!

You like this project? It would be awesome if you would support it, so it lives on!

• ⭐ Star the repository in order to stay up-to-date and save it for later!
• 📣 Spread the word! On X, Medium, Discord, Facebook, ...
• 💌 Send us some positive feedback at the discussion board.

⚡ Changelog

Find all minor and major changes at the CHANGELOG.md.

🙌 Contributing

Anyone is welcome to contribute. Mind the guidelines:

• Bug reports
• Feature requests
• Pull requests

IMPORTANT NOTE: Run npm run fix to auto-fix linting issues!

📃 Copyright and License

Created by Jens Kuerschner (Peltmonger Ventures GmbH).

Licensed under the MIT License.