Configuration

Configuration

Configuration happens on a few levels: the central theme.config.ts, the codebase itself, and a handful of build-time environment variables. Work through the steps below from top to bottom - each one builds on the previous.

Astro is a frontend framework

Everything here runs on the client (static output, with optional on-demand rendering). Never store secrets or backend logic in this project - sensitive work belongs in a real backend service.

1. theme.config.ts

Branding, i18n, blog, promo and llms.txt - all fully typed.

2. The codebase

This is a real Astro project - you still build the actual website.

3. Env variables

A few build-time overrides like SITE_OVERRIDE and ROBOTS.

Step-by-step

Trim what you do not need

If you did not use the create stardrive command, first remove the demo- and repo-only files. The Trimming Guide is written for AI agents but works fine for manual cleanup too.

Make the project yours

Adjust the basics so you recognise the project later:

  • Update package.json to reflect your project.
  • Set at least the headline in README.md.

Replace favicons & social images

Swap the icon files in ./public/ (we like realfavicongenerator.net). The web manifest is generated from theme.config.ts, so you only replace image files. Also replace the social fallbacks og.png, x.png and structured-preview.png in ./public/images/.

Light & dark favicons

Stardrive ships separate light/dark icons. If you do not need that, drop the dark variants and adjust ./src/components/head/base.astro. For the SVG, handle light/dark directly inside the SVG code.

Configure theme.config.ts

This is the heart of the setup. Everything is typed, so your IDE surfaces the docs inline. Work through it in this order:

  • Set the base info (site URL, primary color, …).
  • Decide your languages, add a JSON file per language in ./src/i18n/, and wire up the i18n block.
  • Pick your expressiveCodeThemes - one for light, one for dark mode.
  • Configure blog article defaults (and replace the fallback image if you use it).
  • Set or disable promotion slots.
  • Define how llms.txt is generated.

Fonts & Tailwind base

Stardrive ships with Geist via Fontsource. Swap it for your own (npm un @fontsource/geist, then install yours). Adjust the import statements at the layout files. Then adjust./src/styles/tailwind.config.css:

  • Update the font section.
  • Adjust the branding colors (change hex codes; only remove lines once the demo content is gone).
  • Tweak breakpoints if you like.

Layer in your styles

Extend the CSS files in ./src/styles/ following the layering convention:

  • Tailwind as the base.
  • global.css for custom rules and single-source-of-truth styles (e.g. buttons).
  • Page-specific CSS files (e.g. long-text-content.css) imported per page.
  • Very custom bits stay scoped in the page or component.

Prune unused languages

Delete the subfolders in ./src/content/ and ./src/pages/ for languages you do not support. Running a single language? You can also drop ./src/pages/[lang] plus the language switcher components.

Build your pages & navigation

Shape your structure under ./src/pages/ (one file per route). Pages that differ only by translated strings go into [lang]; pages with large or differing text get an explicit language subfolder with hard-coded content. Then adjust the navigation in ./src/components/layout/nav/ and the other layout files.

Content translations

While building the layout, keep the JSON files in ./src/i18n/ in sync with your project.

Swap the demo content

Replace the demo images in ./src/images (keep the folder structure!), update or remove the./public/map/office.pmtiles used on the demo contact page, and check the Open Graph / X meta in./src/components/head/ogx.astro.

Then validate everything:

Catch broken links after trimming
npm run check:astro

Prepare for deployment

On Cloudflare, adjust _headers and _redirects in ./public/ and thewrangler.jsonc, then link your repository to a Worker. For migrations, map old paths in _redirects. Not on Cloudflare? Configure your host accordingly.

Cache purging on Cloudflare

Set CF_PURGE_API_KEY and CF_PURGE_ZONE_ID and run npm run purge:cloudflareafter each build. Also enable Media → Images → Transformations in your Cloudflare dashboard.

Disable Speed Brain

Turn off Speed Brain in your Cloudflare dashboard (Speed → Optimization → Speed Brain). Stardrive ships with Astro's own prefetching, which conflicts with Speed Brain and can cause double-fetches, stale content, or broken navigation.

Build-time environment variables

SITE_OVERRIDE
Overrides the global site URL. Handy for dev environments.
ROBOTS
Overrides the default robots setting. Page-level settings still win.
CF_PURGE_API_KEY
CF_PURGE_ZONE_ID
Required for the Cloudflare cache purge script.
ADD_TO_CALENDAR_PRO_API_KEY
Enables the pre-built adapter for dynamically infused events.

Site running? Time for content.

Learn the everyday workflows: blog, FAQ, integrations, pricing and events.

Guide