Astro Theme Provider

Astro Theme Provider is a developer tool for the Astro framework that turns a standard Astro project into a reusable theme integration for other developers.

What is Astro Theme Provider?

Astro Theme Provider takes a normal Astro project—complete with public, src/assets, components, layouts, pages, and styles—and lets the author wrap it with a Zod schema via defineTheme, producing an integration that consumers can install in astro.config.mjs. The tool is currently in Beta and is maintained by the Astrolicious community. It publishes documentation at astro-theme-provider.netlify.app and provides a starter theme template at GitHub.

Key Features

• Standard project authoring — Themes are built exactly like any Astro project using Astro's own components, layouts, pages, and styles, rather than a special theme format.
• Zod schema configuration — Theme authors define a schema with z.object from astro/zod, and consumers pass validated config through the integration's config option.
• Route control — Consumers can toggle routes off (for example setting the /404 route to false) or overwrite a route to a custom path (mapping /blog to /projects).
• Component overrides — Users can replace theme components with their own Astro components via the overrides.components property, such as mapping Hero to a local Custom.astro file.
• Custom stylesheets — Users can add extra CSS files through overrides.styles, an array of local stylesheet paths.
• Beta status — The package is marked Beta on npm, with an active contributing guide, Discord channel, and discussion forum in the repository.

Who is it for?

• Astro theme developers — For building a distributable theme once and letting any Astro project install it as an integration.
• Agencies and freelancers — For reusing a design system across multiple client Astro projects with per-project config and overrides.
• Open-source maintainers — For publishing a blog or portfolio theme that others can configure without editing the theme's source code.

What can you do with it?

• Theme authors: Author a theme as a normal Astro project, declare its configurable options with Zod, and publish the integration to npm.
• Site builders: Install a published theme and customize it with config values, route overwrites, component swaps, and additional stylesheets.
• Teams with multiple sites: Keep a consistent theme while allowing each site to override specific components and routes.

How does it work?

1. Build the theme as a normal Astro project with a package folder containing public, src, and an index.ts entry point.
2. In index.ts, import defineTheme from astro-theme-provider and export the result of defineTheme with a Zod schema for configuration.
3. Consumers install the published package and add it to the integrations array in astro.config.mjs, passing config, pages, and overrides.

FAQ

Is Astro Theme Provider production-ready?

The package is in Beta, as shown on its npm badge. The API may change while the maintainers stabilize the design.

How do I override a theme component?

Use the overrides.components option, for example mapping the theme's Hero component to a local ./src/Custom.astro file. That replaces every instance of that component with your own.

Can I disable a page that the theme provides?

Yes, set the route to false in the pages option, such as pages: { '/404': false }, which turns that route off for the site.

Where is the documentation?

The documentation is hosted at astro-theme-provider.netlify.app, and there is a theme template at github.com/astrolicious/astro-theme-provider-template.