Overview

The eminence integration is configured through a single options object. Each key maps to a distinct feature grouped by capability: file generation, icon generation, and global head tag defaults. All features are optional and can be disabled by passing false. Omitting a feature key logs a recommendation warning where applicable.

import { defineConfig } from "astro/config";
import eminence from "eminence-astro-suite";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    eminence({
      // Global head tag defaults (virtual config module)
      headTags: { ... },
      // Icon generation from a source image
      icons: { ... },
      // File generation
      manifest: { ... },
      robotsTxt: { ... },
      securityTxt: { ... },
      sitemap: { ... },
    }),
  ],
});

File Generation

These features generate static files into the build output at build time. Each can be disabled by passing false to its option key.

`manifest`

Generates a /manifest.webmanifest file at build time. Chromium PWA requirements (name/short_name, display/display_override, start_url) are enforced as TypeScript types. See manifest.webmanifest for full option details.

option	type	required	description
`name`	`string`	Yes*	Full app name. Required unless `short_name` is provided.
`short_name`	`string`	Yes*	Short app name. Required unless `name` is provided.
`start_url`	`string`	Yes	URL loaded when the app is launched.
`display`	`string`	Yes**	Display mode. Required unless `display_override` is provided.
`display_override`	`string[]`	Yes**	Ordered display mode candidates. Required unless `display` is provided.
`icons`	`WebManifestIconItem[]`	No	Icons for the app. Generated manifest icons are added first; explicit `manifest.icons` are merged over them by `src`.
(more)			Additional optional fields documented on the manifest page.

Pass manifest: false to disable generation with no warning.

`robotsTxt`

Generates a /robots.txt file at build time. If a robots.txt already exists in the build output, generation is skipped. See robots.txt for full option details.

option	type	required	description
`rules`	`RobotsTxtRule \| RobotsTxtRule[]`	Yes	One or more crawl rules defining agent access.
`sitemap`	`string \| string[]`	No	Absolute URL(s) or site-relative path(s) for `Sitemap:` entries.

Pass robotsTxt: false to disable generation with no warning.

`securityTxt`

Generates a /.well-known/security.txt file at build time following RFC 9116. See security.txt for full option details.

option	type	required	description
`contact`	`string \| string[]`	Yes	`mailto:` address(es) or `https://` URL(s).
`expires`	`Date \| string \| SecurityTxtExpiresDuration`	Yes	Policy expiry. Accepts a `Date`, ISO 8601 string, or duration like `"1 year"`.
`encryption`	`string \| string[]`	No	HTTPS URL(s) to a PGP key.
`policy`	`string \| string[]`	No	HTTPS URL(s) to the security disclosure policy.
`preferredLanguages`	`string \| string[]`	No	BCP 47 language tag(s) for preferred report language(s).
(more)			Additional optional fields documented on the security.txt page.

Pass securityTxt: false to disable generation with no warning.

`sitemap`

Delegates sitemap generation to @astrojs/sitemap, which must be installed as a peer dependency. The integration is registered automatically — no need to add it separately. See Sitemap for full option details.

The sitemap option accepts a SitemapOptions object (forwarded directly to @astrojs/sitemap) or false.

Pass sitemap: false to disable the feature and suppress the peer dependency requirement.

Icon Generation

`icons`

Generates favicon and app icon files at build time from a single source image. The generated icons are automatically injected as <link> tags and, when combined with manifest, contributed to the web manifest. See Icons for full option details.

Icon resolution uses three layers:

icons generates assets and base icon metadata.
headTags.icons merges over generated head icon tags by href.
manifest.icons merges over generated manifest icon entries by src.

option	type	description
`source`	`string`	Global source image used when a keyed icon entry does not provide `source`.
`[filename.ico]`	keyed icon entry	Generates a multi-size `.ico` file and optional head and manifest metadata.
`[filename.svg]`	keyed icon entry	Adds SVG metadata-only icon tags; explicit SVG entries do not generate files.
`[filename.raster]`	keyed icon entry	Generates raster files such as PNG or WebP with inferred `sizes` and MIME type.

Pass icons: false to disable generation entirely with no warning.

Global Head Tags

`headTags`

Sets default values exposed to <head> components via the virtual config module (virtual:eminence-astro-suite/head-tags). Components read from this module automatically, so values configured here apply site-wide without repeating them per page.

All fields are optional.

option	type	description
`charset`	`string`	Default charset for the `Charset` component.
`viewport`	`string`	Default viewport content string for the `Viewport` component.
`base`	`object`	Props forwarded to the `Base` component.
`colorScheme`	`string`	Default color scheme for the `ColorScheme` component.
`titleTemplate`	`string`	Title template string for the `Title` component.
`appleItunesApp`	`object`	Props forwarded to the `AppleItunesApp` component.
`generator`	`boolean`	Whether to render the `Generator` tag.
`icons`	`IconTag[]`	Build-time icon tags merged over generated icon tags by `href`.
`manifest`	`string \| URL \| false`	URL for the `<link rel="manifest">` tag. Pass `false` to opt out.
`openGraphSiteName`	`string`	Site name for Open Graph tags.
`robots`	`object`	Props forwarded to the `Robots` component.
`themeColor`	`string \| { light: string; dark: string }`	Theme color defaults for `Head` and `ThemeColor`.
`humansTxt`	`string \| URL \| false`	URL for the `<link rel="author">` tag. Pass `false` to opt out.
`verification`	`object`	Props forwarded to the `Verification` component.
`extend.link`	`object[]`	Additional free-form `<link>` tags for Head.
`extend.meta`	`object[]`	Additional free-form `<meta>` tags for Head.
`extend.custom`	`string \| string[]`	Raw HTML injected with `set:html` in Head.

Use extend.* for shared configuration defaults. For one-off page tags, prefer inserting tags directly inside the Head component slot.

extend.custom is intentionally unescaped because it uses Astro set:html; only pass trusted or pre-sanitized content.

Coming Soon

The following features are planned and not yet released.

i18n

Coming Soon

Internationalization support for multi-language sites. Will provide locale-aware head tag defaults, alternate link management, and integration with Astro’s built-in i18n routing.

Capo.js Middleware

Coming Soon

An Astro middleware that reorders <head> tags at runtime following the capo.js priority rules. Ensures optimal resource loading order without manual tag ordering in your templates.

Full example

import { defineConfig } from "astro/config";
import eminence from "eminence-astro-suite";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    eminence({
      headTags: {
        charset: "UTF-8",
        viewport: "width=device-width, initial-scale=1",
        titleTemplate: "%s | My Site",
        colorScheme: "light dark",
        humansTxt: "https://example.com/humans.txt",
      },
      icons: {
        source: "./src/assets/icon.svg",
      },
      manifest: {
        name: "My Site",
        short_name: "MySite",
        start_url: "/",
        display: "standalone",
        background_color: "#ffffff",
        theme_color: "#0070f3",
      },
      robotsTxt: {
        rules: { agent: "*", disallow: "/private/" },
        sitemap: "/sitemap-index.xml",
      },
      securityTxt: {
        contact: "mailto:security@example.com",
        expires: "1 year",
        policy: "https://example.com/security-policy",
      },
      sitemap: {},
    }),
  ],
});