Author API

Default Structure

• Directorypackage/

  • Directorypublic/

    • …
  • Directorysrc/

    • Directoryassets/

      • …
    • Directorycomponents/

      • …
    • Directorylayouts/

      • …
    • Directorypages/

      • …
    • Directorystyles/

      • …
  • index.ts
  • package.json

package/index.ts

import { z } from 'astro/zod'
import defineTheme from 'astro-theme-provider';

export default defineTheme({
  name: "my-theme",
  schema: z.object({
    title: z.string(),
    description: z.sting().optional()
  })
})

Reference

name

Type: string

Required

The name of a theme, must be unique. If you are authoring your theme as a package, it is recomended to use the package name as the name of your theme

schema

Type: Zod Schema

Default: ZodTypeAny

A zod schema for validating the default value of a theme’s config module. The schema must be JSON serializable.

Example:

schema: z.object({
  title: z.string(),
  description: z.string().optional()
})

---
import config from "my-theme:config"

console.log(config.title, config.description)
---

srcDir

Type: string

Default: "src"

Directory that contains a theme’s assets (pages, components, images, css, etc). Assets inside the src directory can be accessed using virtual modules (see imports)

pageDir

Type: string | AstroPagesOption

Default: "pages"

Directory that contains all of the pages for a theme

publicDir

Type: string | AstroPublicOption

Default: "public"

Directory that contains a theme’s static assets (favicon.svg, etc). By default, these assets act as placeholders and can be overwritten by assets located in a user’s public real folder.

middlewareDir

Type: string | false

Default: srcDir

Directory that contains a theme’s middleware. Relative paths are resolved relative to the theme’s srcDir, use false to disable middleware injection

integrations

Type: Array<AstroIntegration | (options: { config: z.infer<Schema>, integrations: string[] }) => AstroIntegration | false | null | undefined>

An array of integrations that will be included with the theme

integrations: [
  mdx(),
  sitemap(),
]

integrations: [
  // Check for other integrations
  ({ integrations }) => {
    if (!integrations.contains('@astrojs/sitemap')) {
      return inoxsitemap()
    }
  },
]

integrations: [
  // Pass user options to integrations
  ({ config }) => {
    if (config.sitemap) {
      return inoxsitemap(config.sitemap)
    }
  },
]

imports

Type: Record<string, Record<string, string> | string[] | string | false>

Default:

imports: {
  assets: "assets**.{jpeg,jpg,png,tiff,webp,gif,svg,avif}",
  components: "components/**.{astro,tsx,jsx,svelte,vue}"
  layouts: "layouts/**.astro",
  styles: "styles/**.{css,scss,sass,styl,less}",
}

Create virtual modules to access assets inside a theme and allow users to override them.

false:

Toggle default virtual modules off

imports: {
  assets: false,
  components: false,
  layouts: false,
  styles: false,
}

string:

Glob files into a virtual module, glob patterns are relative to a theme’s srcDir

• Directorypackage/

  • Directorysrc/

    • Directorycomponents/

      • Hero.astro
      • Card.astro
      • Button.astro

imports: {
  components: "components/**.astro",
}

import { Hero, Card, Button } from "my-theme:components"

array:

Use an array to combine imports into a single virtual module

imports: {
  styles: [
    "./src/styles/reset.css",
    "./src/styles/global.css",
    "./src/styles/utils.css",
  ],
}

import "my-theme:styles"

object:

Use an object to create more complex custom virtual modules

imports: {
  components: {
    imports: [ "./src/styles/global.css" ],
    default: "./src/layout/Layout.astro",
    Head: "./src/components/Head.astro",
    Button: "./src/components/Button.astro"
  }
}

import Layout, { Head, Button } from "my-theme:components"

log

Type: "verbose" | "minimal" | boolean

Default: true

Toggle logging for the theme

Level	Description
false	Zero logging
"minimal" | true	Log warnings
"verbose"	Log everything, including debug information

entrypoint

Type: string

Default: directory of the file the theme is exported from

A path to the root directory, or file inside the root directory, of a theme

Note

For advanced use cases only, this will be infered automatically assuming that this called at the root of the theme (see Default Structure)

Example

Author a theme inside a package similar a normal project

• Directorypackage/

  • Directorypublic/

    • favicon.svg
  • Directorysrc/

    • Directoryassets/

      • logo.png
    • Directorycomponents/

      • Card.astro
    • Directorylayouts/

      • Layout.astro
    • Directorypages/

      • index.astro
    • Directorystyles/

      • global.css
  • index.ts
  • package.json
  • README.md

Export the theme as an integration

package/index.ts

import { z } from 'astro/zod';
import defineTheme from 'astro-theme-provider';

export default defineTheme({
  name: "my-theme",
  schema: z.object({
    title: z.string(),
    description: z.string().optional()
  })
})

Use the generated virtual modules to author the theme

package/src/pages/index.astro

---
import { Layout } from 'my-theme:layouts';
import { Card } from 'my-theme:components';
import { logo } from 'my-theme:assets'
import config from 'my-theme:config'
import 'my-theme:styles';

const {
  title,
  description = "Welcome to my theme"
} = config
---

<Layout>
  <Card {title} {description} img={logo}/>
</Layout>