Skip to content

Configuration

Jump to bottom
yCENzh edited this page Sep 19, 2026 · 1 revision

Configuration

Everything you configure lives in shirones/config/ as TypeScript modules. There is no YAML, no JSON blob, and no merge step.

Shadowing

A file in shirones/config/ replaces the theme's module of the same name, wholesale.

// shirones/config/siteConfig.ts
import type { SiteConfig } from "@/types/config";

export const siteConfig: SiteConfig = {
  site: "https://example.com/",
  title: "My Blog",
  themeColor: { hue: 315, fixed: false, style: "tonalSpot", spec: "2025" },
  // …
};

Two consequences worth internalising:

It is a replacement, not a merge. If the theme's siteConfig has twenty fields and yours has three, you get three. That is why init scaffolds a complete copy of every module rather than a stub — start from the file it wrote, not from an empty one.

Deleting the file reverts it. The integration looks in your config directory first and falls back to the packaged default. Removing your copy is the whole undo operation.

The @/ alias resolves into the theme's source; tsconfig.json sets it up. shirones/types/config works too if you prefer an explicit package path.

What is in there

init scaffolds 33 modules. Roughly grouped:

Area Modules
Identity siteConfig, profileConfig, footerConfig, navBarConfig, sidebarConfig
Writing articleConfig, postListConfig, permalinkConfig, licenseConfig, seriesConfig
Features momentsConfig, albumsConfig, animeConfig, friendsConfig, projectsConfig, skillsConfig, gamesConfig, devicesConfig, timelineConfig, compassConfig
Presentation fontConfig, imageBloomConfig, fabConfig, contextMenuConfig, announcementConfig, expressiveCodeConfig
Plumbing i18nConfig, commentConfig, musicConfig, umamiConfig, aboutConfig, llmsConfig, sitemapFilter

Plus shirones/config/data/, which holds the list content — friends.ts, projects.ts, skills.ts, games.ts, devices.ts, timeline.ts, anime.ts, compass.ts, music.ts. Those are separate from config because they are records to render rather than settings to read, and because a long friends list should not live next to your site title.

Two files in the theme's own src/config/ are deliberately not scaffolded: index.ts is a barrel, and integrationsConfig.ts is compiled into the integration at build time, so a copy in your project would never be read.

Types

Every module exports a typed value, and the types come from the theme:

import type { FontConfig } from "@/types/fontConfig";
export const fontConfig: FontConfig = { /* … */ };

Your editor will complete fields and catch typos. This works because the integration bundles your config with esbuild at config time rather than importing it through Astro — see How it works if you are curious why that matters.

When a config module fails to load

A syntax error in one of your config files stops the build with the module named:

[shirones] Failed to bundle "config:siteConfig" from /you/my-blog/shirones/config/siteConfig.ts:
  shirones/config/siteConfig.ts:4:2: ERROR: Expected "}" but found "trailingSlash"

A module that does not exist at all tells you where it looked:

[shirones] Could not find config module "siteConfig".
  Looked in: /you/my-blog/shirones/config
         and: /you/my-blog/node_modules/shirones/src/config
  Run `npx shirones init` to scaffold the default configuration.

Stale config after an upgrade

If the theme renames a config module, your old file stops being read — the integration asks for the new name, does not find your copy, and quietly uses the packaged default. Your edits are still on disk, just inert.

To catch that, the integration warns at startup about any file in shirones/config/ or shirones/config/data/ that matches no module the theme loads:

[shirones] [overrides] 1 config file(s) match no module the theme loads, so they are never read:
  - /you/my-blog/shirones/config/siteConfig.ts
  This usually means the theme renamed a config module — check the release notes and move your edits across.

npx shirones init reports the same thing as part of its drift check, with the added detail of which fields the theme added since you copied the file. See Updating.

Note that this check covers the config directories only. Your src/components/ tree is shared with your own components, so an unmatched file there is not reported — it is indistinguishable from a component you wrote yourself.

Reading config at runtime

Config modules are ordinary TypeScript. If you are writing an override component and need a value:

---
import { siteConfig } from "@/config/siteConfig";
---
<h1>{siteConfig.title}</h1>

The overlay applies to these imports too, so inside an overridden component @/config/siteConfig resolves to your copy, exactly as it does inside the theme's own components.

Next

Clone this wiki locally