Overview

The eminence integration is configured through a single options object. Each key maps to file generation, public icon discovery, response middleware, or global head tag defaults. Features 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({
      // Opt-in final head ordering
      capojs: "typescript",
      // Global head tag defaults (virtual config module)
      headTags: { ... },
      // Detect supported icons in public/
      icons: true,
      // File generation
      manifest: { ... },
      robotsTxt: { ... },
      securityTxt: { ... },
      sitemap: { ... },
    }),
  ],
});

Head Ordering Middleware

`capojs`

capojs: "typescript" registers middleware that performs a stable reorder of direct <head> children using the Capo.js priority rules. It works while Astro prerenders static pages and on each HTML request for server-rendered pages. The default is disabled; omit the option or pass false to register no middleware. See Capo.js for behavior and performance considerations.

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	Explicit installable-application icons.
(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.

Public Icon Discovery

`icons`

Detects favicon.svg, favicon.png, and apple-touch-icon.png in Astro’s publicDir and exposes matching <link> tags. Files are never generated or modified. favicon.ico is detected only to decide whether to show a fallback-icon recommendation; no tag is emitted for it. See Icons for details.

Icon resolution uses three layers:

icons detects supported public files and creates base icon metadata.
headTags.icons merges over detected tags by href.
<Icons /> runtime overrides merge last.

option	type	description
`icons`	`boolean`	Enabled by default. Pass `false` to disable discovery and recommendation.

Pass icons: false to disable discovery 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[]`	Icon tags merged over detected public 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.

Full example

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

export default defineConfig({
  site: "https://example.com",
  integrations: [
    eminence({
      capojs: "typescript",
      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: true,
      manifest: {
        name: "My Site",
        short_name: "MySite",
        start_url: "/",
        display: "standalone",
        background_color: "#ffffff",
        theme_color: "#0070f3",
        icons: [
          { src: "/icon-192.png", sizes: "192x192", type: "image/png" },
          { src: "/icon-512.png", sizes: "512x512", type: "image/png" },
        ],
      },
      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: {},
    }),
  ],
});