@micrajs/astro

Astro integration for Micra.js. Ship server-rendered HTML with zero JS by default, then hydrate individual islands — each pulling only its own component as a separate chunk, on the strategy you choose.

Install

npm install @micrajs/astro micra.js

// astro.config.mjs
import { defineConfig } from 'astro/config'
import micra from '@micrajs/astro'

export default defineConfig({
  integrations: [micra()],
})

Use

A component is one file under src/micra/, default-exporting a Micra definition:

// src/micra/counter.ts
import { defineComponent } from 'micra.js'

export default defineComponent({
  state: { count: 0 },
  inc() { this.state.count++ },
  onCreate() { this.state.count = this.prop('start', 0) as number },
})

Drop it on a page with <Micra>. The slot is the template (rendered on the server), and it becomes interactive only when the island's strategy fires:

---
import Micra from '@micrajs/astro/Micra.astro'
---
<Micra name="counter" client="visible" props={{ start: 3 }}>
  <button @click="inc">+</button>
  <span data-text="count"></span>
</Micra>

The counter chunk is fetched only when the island scrolls into view; a page that never shows it never loads it.

<Micra> props

| Prop | Description | | -------- | ------------------------------------------------------------------------ | | name | Component file name under the components directory. | | client | load, idle, visible, or media:(query). Defaults to defaultClient. | | props | Scalars, serialized to data-*, read via this.prop('key') (camelCase key). | | as | Root element tag. Defaults to div. |

props are scalars (string/number/boolean), mirroring Micra's this.prop(). Structured or initial data belongs in this.fetch() inside onCreate, not in an attribute — that is the Micra data model, not a limitation. If you truly want Micra across a whole page instead of per island, drop the core <script> tag as you would on any server-rendered page; this integration is for islands.

Nested islands

An island's slot may contain other <Micra> islands. Each hydrates independently on its own strategy — Micra's scanner treats a nested data-component as a boundary, so an outer component never binds a child's directives.

<Micra name="panel" client="load">
  <button @click="toggle">toggle</button>
  <Micra name="counter" client="visible" props={{ start: 5 }}>
    <button @click="inc">+</button>
    <span data-text="count"></span>
  </Micra>
</Micra>

View transitions

With Astro's <ClientRouter />, islands re-arm after each navigation and torn-down pages release their components automatically. Mark an island transition:persist to keep it — the same element (and its Micra state) survives the swap:

<Micra name="cart" client="load" transition:persist>
  <span data-text="count"></span>
</Micra>

Global setup

Run code once before the first island mounts — register bus listeners, configure data-html sanitizing, etc. — with an entrypoint:

// astro.config.mjs → micra({ entrypoint: '/src/micra.setup.ts' })

// src/micra.setup.ts
import type * as Micra from 'micra.js'
export default (micra: typeof Micra) => {
  micra.config({ sanitize: DOMPurify.sanitize })
  micra.on('cart:add', () => {/* … */})
}

Options

micra({
  componentsDir: '/src/micra', // where component files live (default)
  defaultClient: 'load',       // strategy for <Micra> with no `client` (default)
  rootMargin: '0px',           // visible strategy: hydrate this far before the viewport
  observe: false,              // also arm islands inserted after load (innerHTML, etc.)
  entrypoint: undefined,        // module run once before the first mount
})

A mistyped name is caught at build time with the list of available components. In dev, the Micra panel in Astro's toolbar lists the islands on the page with their strategy and hydration state.

Example

example/ is a runnable gallery of the canonical Micra recipes (counter, todo, data table, form, modal via the event bus, tabs, SSR props, debounced search, a chart.js chart, cross-island coordination), each an island on its own strategy, plus a features page (persist, nested, dynamic). Its production build shows the payoff: every component is its own chunk, and the chart island's ~200 KB of chart.js downloads only on the page that shows it.

cd example && npm install && npm run dev

How it works

• The integration exposes virtual:micra-components, a name -> import() map built with import.meta.glob, so every component is its own Vite chunk.
• A tiny loader is injected on each page. It scans for islands, arms the chosen strategy, then lazy-imports the Micra core plus the one component and mounts it.
• Teardown is removal-driven: autoCleanup() runs onDestroy when an island leaves the DOM, so transition:persist islands (not removed) stay mounted.

Requires no server runtime — works with static output.