Configuration Reference

StarryBio reads one strict TypeScript object from config/starrybio.config.ts. End the object with satisfies StarryBioConfig; this keeps editor type checking while the same schema validates the configuration during pnpm validate, pnpm dev, and pnpm build.

import type { StarryBioConfig } from "../src/config/schema";

const config = {
  // configuration
} satisfies StarryBioConfig;

export default config;

Top-level settings

Setting	Required	Purpose	Default when omitted
pageTitle	Yes	Browser tab title and fallback SEO title.	None
favicon	No	Local public/ asset or HTTP(S) favicon URL.	No favicon link emitted
profile	Yes	The profile name, description, image, and optional image/text layout.	None
sections	Yes	Ordered groups of profile links.	None
featured	No	Prominent link cards.	[]
theme	No	Preset name or visual settings object.	midnight-based defaults
layout	No	Card, grid, link, and featured-card placement.	Centered/card defaults
animation	No	Star and shooting-star multipliers.	Both 1
status	No	Client-side availability indicator and schedule dialog.	Not rendered
announcement	No	Dismissible site-wide notice.	Not rendered
seo	No	Description, canonical URL, sharing image, and theme color.	Derived from page/profile/theme
ogImage	No	Build-time social image generator.	Disabled
qr	No	Build-time QR generator with an optional profile download action.	Disabled
analytics	No	One supported external analytics provider.	{ provider: 'none' }
contactCard	No	Build-time downloadable vCard generator.	Disabled
footer	No	Custom copyright text.	© <current year> StarryBio

The pages linked below explain the behavior of each group. This page records the contract and exact fallback values.

Required identity

{
  pageTitle: 'Ada Lovelace',
  favicon: 'assets/images/default/favicon.svg',
  profile: {
    name: 'Ada Lovelace',
    description: 'Mathematician and programmer.',
    image: 'assets/images/default/profile.svg',
    layout: 'vertical', // optional: 'vertical' or 'horizontal'
  },
  sections: [],
}

profile.name, profile.description, and profile.image must be non-empty. Local image paths resolve under public/; store your own images under public/assets/images/. An image may instead be an HTTP(S) URL. See Assets and Generated Downloads.

Theme, layout, and motion defaults

theme can be a preset string, such as theme: 'aurora', or an object. The supported preset values are nebula, midnight, classic-blue, aurora, eclipse, cosmic-gold, minimal, terminal, supernova, black-hole, pulsar, andromeda, mars, lunar, solar-flare, deep-space, starlight, event-horizon, quasar, voyager, apollo, alien, cyber-orbit, ice-moon, titan, saturn, red-giant, and white-dwarf.

theme: {
  preset: 'midnight',
  accent: '#7ddf9b', // optional #RGB, #RRGGBB, or #RRGGBBAA
  buttonStyle: 'glass', // glass, solid, outline, minimal, terminal
  background: 'starfield', // starfield, gradient, minimal
  animationIntensity: 'normal', // none, subtle, normal, high
},
layout: {
  mode: 'centered', // see Appearance and Branding
  linkStyle: 'cards', // cards, buttons, minimal, terminal
  profilePosition: 'top', // top or left
  featuredPosition: 'above-links', // above-links or below-links
},
animation: {
  starMultiplier: 1,
  shootingStarMultiplier: 1,
},

If theme is absent, defaults are the intentionally dark midnight preset, glass buttons, starfield background, and normal intensity. Every preset defines its own light or dark appearance; there is no manual appearance override. minimal, starlight, voyager, and apollo are the intentionally light presets. minimal also defaults to a minimal background, while terminal defaults to terminal button styling. Other layout defaults are centered, cards, top, and above-links.

Both multipliers must be numbers greater than or equal to zero. 0 disables that effect. The visitor’s reduced-motion preference also stops nonessential animated movement, regardless of the chosen intensity.

See Appearance and Branding for practical combinations and current layout behavior.

Visibility fields

Sections, individual links, and featured cards can each use these optional fields:

{
  enabled: true,
  visibleFrom: '2026-10-01T09:00:00Z',
  visibleUntil: '2026-11-01T00:00:00Z',
}

enabled: false hides the item. The timestamp format must be an ISO date-time with a time component. visibleFrom is inclusive; visibleUntil is exclusive and must be later than visibleFrom. Visibility is evaluated when the site is built, not by each visitor. A timed campaign will not appear or disappear on an already deployed static site until the next build and deployment.

URL and file safety rules

• Link destinations accept HTTP(S), mailto:, tel:, root-relative paths, normal relative paths, and—where allowed—hash links. Root-relative internal paths are rebased for GitHub Pages project sites; normal relative paths remain page-relative. javascript: and protocol-relative URLs are rejected.
• Featured-card URLs do not accept a hash target. Link and announcement URLs do.
• Asset URLs must be HTTP(S) or a safe path under public/; parent traversal is rejected.
• Generated output must stay under public/. OG and QR outputs must end in .png or .svg; vCards must end in .vcf.
• Every object is strict. Misspelling a field produces a validation error rather than silently doing nothing.

Configuration that needs its own guide

• Managing Content covers sections, links, featured, icons, and scheduled visibility.
• Availability and Announcements covers status and announcement.
• Assets and Generated Downloads covers favicon, local assets, ogImage, qr, and contactCard.
• SEO and Analytics covers seo and analytics.
• Appearance and Branding covers theme, layout, animation, and footer.

StarryBio has no runtime configuration environment variables. For a customized build, STARRYBIO_CONFIG_PATH can select another TypeScript config module; it defaults to config/starrybio.config.ts and the module must have a default export. Keep credentials out of every configuration file.