Skip to content
Static Bloom

Astro integration

@static-bloom/astro themes an Astro site. Its integration does two things on every page: it inlines the flavor script in <head>, so the stored flavor is applied before the first paint, and it imports the Static Bloom stylesheet. The package also ships three components and the runtime as a library.

  1. Install the integration and the CSS it imports.

    Terminal window
    pnpm add @static-bloom/astro @static-bloom/css

  2. Register it.

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    import staticBloom from '@static-bloom/astro'
    

    export default defineConfig({
      integrations: [staticBloom({ flavors: { dark: 'midnight' }, accent: 'plasma' })],
    })

  3. Use the sb-* classes, or the Layout component for a complete document.

    src/pages/index.astro
    ---
    import Layout from '@static-bloom/astro/components/Layout.astro'
    ---
    <Layout title="Night shift">
      <main class="sb-container sb-stack">
        <h1>Night shift</h1>
        <button class="sb-btn">Connect</button>
      </main>
    </Layout>

Options

Section titled “Options”
Option Values Default
flavors.dark 'dusk', 'midnight', 'blackout' 'midnight'
flavors.light 'daybreak' 'daybreak'
defaultFlavor 'auto', 'dusk', 'midnight', 'blackout', 'daybreak' 'auto'
accent any of the 12 accents 'plasma'
styles 'full', 'tokens', false 'full'
  • flavors.dark and flavors.light are the flavors auto resolves to when the system prefers a dark or a light color scheme.
  • defaultFlavor applies when the visitor has stored nothing. A stored choice always wins.
  • accent is set as data-accent on <html> and re-points the primary color.
  • Invalid values and unknown option names throw a StaticBloomOptionsError at startup, naming the option and the allowed values.

Styles

Section titled “Styles”
styles Imports on every page Use when
'full' @static-bloom/css: tokens, fonts, base, components and utilities You use the sb-* classes
'tokens' @static-bloom/css/tokens.css and @static-bloom/css/fonts.css Your own CSS styles elements and components
false nothing Your global stylesheet imports what it needs

With Tailwind, use styles: false and let the stylesheet bring the theme, fonts and tokens:

astro.config.mjs
import { defineConfig } from 'astro/config'
import staticBloom from '@static-bloom/astro'
import tailwindcss from '@tailwindcss/vite'


export default defineConfig({
  integrations: [staticBloom({ styles: false })],
  vite: { plugins: [tailwindcss()] },
})
src/styles/global.css
@import 'tailwindcss';
@import '@static-bloom/tailwind';
@import '@static-bloom/vue/tailwind.css'; /* with @static-bloom/vue */

Import that stylesheet in your layout. The Vue islands page continues this setup.

The flavor runtime

Section titled “The flavor runtime”

The inline script reads localStorage['static-bloom:flavor'], resolves auto through prefers-color-scheme, and sets data-flavor, data-theme, data-accent and color-scheme on <html>. It also updates every <meta name="theme-color"> marked with data-static-bloom-theme-color to the active flavor’s base color. Then it exposes a small controller:

window.staticBloom.getFlavor() // stored preference, 'auto' included
window.staticBloom.resolve() // flavor in use, e.g. 'midnight'
window.staticBloom.setFlavor('blackout') // persists, applies, dispatches the event


document.addEventListener('static-bloom:flavor-change', ({ detail }) => {
  console.log(detail.flavor, detail.resolved, detail.theme)
})

The event fires on start, once the DOM is ready, after every setFlavor, and on system color scheme changes while the preference is auto. setFlavor throws a TypeError for an unknown value; when storage is blocked, the choice still applies to the current page. To type window.staticBloom and the event in a client script, import the package’s types:

import type {} from '@static-bloom/astro'

Flavors & theming explains the model, and Vue’s useFlavor delegates to this runtime when it is present.

Library exports

Section titled “Library exports”
Export Purpose
staticBloom(options?) (default) The integration
buildFlavorScript(options?) The validated inline runtime as a string, for your own <script is:inline>
resolveFlavor(stored, prefersLight, options?) Pure resolution of a stored value to a flavor
flavorRuntime(config) The runtime function itself; buildFlavorScript stringifies it
normalizeOptions(options?), isFlavorPreference(value), StaticBloomOptionsError Option validation
FLAVOR_STORAGE_KEY, FLAVOR_CHANGE_EVENT 'static-bloom:flavor', 'static-bloom:flavor-change'
FLAVOR_IDS (alias flavorIds), darkFlavorIds Flavor ids from the palette 
import { resolveFlavor } from '@static-bloom/astro'


resolveFlavor('auto', true) // 'daybreak'
resolveFlavor(null, false, { flavors: { dark: 'blackout' } }) // 'blackout'

Types: StaticBloomOptions, FlavorConfig, FlavorRuntimeConfig, FlavorPreference, FlavorController, FlavorChangeDetail, FlavorName, DarkFlavorName and AccentName.