Craft CMS + Astro Starter

Craft CMS + Astro Starter is a boilerplate project that combines an Astro 5 frontend with a headless Craft CMS backend, using Craft's built-in GraphQL API as the communication layer between them.

What is Craft CMS + Astro Starter?

It is a starter template maintained by the Craft CMS team, hosted on GitHub as craftcms/starter-astro. The project takes a standard Craft CMS installation configured in headless mode and an Astro 5 static site generator, and connects the two through GraphQL queries and mutations. The repository is split into a backend/ directory containing the Craft CMS application and a frontend/ directory containing the Astro project. It is designed to run locally with DDEV, which provides the required PHP, MySQL, and Node.js environments plus pre-configured nginx virtual hosts for both the front end and the API.

Key Features

• Headless Craft CMS — Craft runs in headless mode, meaning it skips element routing and template rendering and only responds to control panel, action, and static asset requests.
• GraphQL API support — Astro queries posts and pages and creates guestbook entries through Craft's GraphQL API; all GraphQL queries are centralized in the frontend/queries/ directory.
• Live Preview with shareable draft URLs — Craft's native live preview works for Astro pages, and you can copy a secure, shareable URL for any draft.
• Native pagination — The blog listing is paginated in a way that mirrors Craft's native handling, updating the URL and browser history as you move between pages.
• Split project structure — backend/ and frontend/ each maintain their own .gitignore and .env files, making the boundary between Craft and Astro explicit.
• DDEV integration — A custom ddev fe command runs npm tasks inside the frontend/ directory, and nginx configuration files for both sites are included.

Who is it for?

• Developers starting a headless CMS project — who want a working Craft CMS + Astro pairing without configuring the integration from scratch.
• Agencies and freelancers building Craft CMS sites — who can use this starter as a base for client projects that need a blog, pages, and a simple GraphQL API.
• Developers evaluating Craft CMS headless mode — who want a concrete reference for using Craft's GraphQL API, live preview, and control panel with a modern frontend framework like Astro.

What can you do with it?

• Content editors: manage blog posts and pages in the Craft control panel, then preview drafts on the Astro frontend via Craft's live preview and secure shareable links.
• Developers: experiment with GraphQL mutations by implementing the guestbook feature that writes entries through the API.
• Publishers: publish paginated blog content where the URL and browser history update naturally through Astro pages.

How does it work?

After cloning the repository, you run ddev composer install and ddev craft install to set up the Craft backend, then generate a GraphQL token for the Posts schema using ddev craft graphql/create-token. You copy frontend/.env.example to frontend/.env, fill in the token and host URLs, and run ddev fe npm install and ddev fe npm run dev to start the Astro development server.

FAQ

What development environment is required?

DDEV is the recommended and assumed environment. The starter includes DDEV configuration files that provision the web server, nginx virtual hosts, and environment variables for both the front end and the Craft API.

Where is the Craft control panel?

By default, the control panel is at https://api.starter-astro.ddev.site/admin. You log in with the username and password created during ddev craft install.

Does live preview work with Astro?

Yes. Craft's live preview works as expected on the Astro frontend, and you can generate secure, shareable URLs to any draft so collaborators can view it without logging in.

How do I use a different domain?

You need to update the DDEV project name and hostnames in .ddev/config.yaml, change the server_name directives in the two nginx files, and adjust BASE_URL in frontend/.env and CRAFT_BASE_CP_URL in backend/.env.