Astro Theme, Starter or Blank Project?

Choose a blank Astro project, an Astro starter or a full theme by asking how far each is from the site you need. Start blank when you’re learning or the design is fully custom. Use a starter (the official npm create astro templates or a free minimal theme) when you want project structure but plan to design everything yourself. Use a finished theme when it already has the page types and look your site needs, so you change content and branding rather than build.

Key Takeaways

• Blank: maximum control, maximum work. Best for learning and bespoke designs.
• Starter: structure and tooling, little design. Best for developers who’ll design themselves.
• Theme: finished pages for a site type. Best when time matters more than uniqueness.
• All three are plain Astro projects; you can change anything later.

Decision flow

1. Are you learning Astro? Yes → blank (npm create astro@latest, minimal template).
2. Is there a finished design from a designer you must match exactly? Yes → blank or starter.
3. Do you need standard pages (blog, docs) and will design yourself? Yes → starter (official blog template, Starlight for docs).
4. Does a theme exist with the page types your business needs (menus, listings, case studies, pricing)? Yes → theme.
5. Is the site for a client, on a fixed budget? Usually → theme.

Compared

	Blank	Starter	Theme
Time to a live site	Longest	Medium	Shortest
Design	You	Mostly you	Done
Page set	None	Generic (blog, docs)	Niche-specific
Cost	Free	Free	Free or paid
Learning value	Highest	High	Medium
Risk	Scope creep	Moderate	Fit: does it match your needs?

Getting each

# Blank or official starters
npm create astro@latest my-site
npm create astro@latest -- --template blog

# Starlight docs
npm create astro@latest -- --template starlight

# A theme from a repository
git clone <theme-repo> my-site && cd my-site && npm install && npm run dev

Making a theme yours

The order that avoids rework:

1. Set site and site details in config and the theme’s data file.
2. Change design tokens (colours, fonts, radius).
3. Replace content in src/content/ and images in src/assets/.
4. Delete pages you don’t need.
5. Only then edit components.

The best Astro themes guide covers what to check before choosing one, including Astro version and licence, and lists free options like AstroWind and AstroPaper alongside paid ones. Our getting started docs show how to run a Komal theme locally.

FAQ

Is using an Astro theme bad for SEO?

No. A theme’s HTML is yours to change, and Astro’s static output is fast and crawlable. Write your own content and titles.

Can I upgrade Astro in a theme?

Yes, with npx @astrojs/upgrade. Themes built on current APIs upgrade with few changes.

The official project setup guide covers create astro options.