Install Matchina

There are two ways to use matchina: install it from npm into a bundled project, or load it from a CDN with no build step. The latter is well-suited to demos, learning, AI-generated artifacts, and anywhere a build pipeline is overkill.

Install from npm

npm

npm install matchina

pnpm

pnpm add matchina

yarn

yarn add matchina

bun

bun add matchina

Then import as usual:

import { matchina, createStore, defineStates } from "matchina";

Use from a CDN

You can load matchina directly from a CDN inside a <script type="module"> — no package manager, no bundler, no build step.

There are three reasonable approaches, in order from smallest footprint to simplest URL.

Recommended: esm.sh tree-shaken

esm.sh bundles the entry into one file and lets you tree-shake to only the exports you actually use via the ?exports= query parameter. For the typical “machine + store + subscribe” footprint, this comes in around 2.8 KB gzipped.

<script type="module">
  const { matchina, createStore, defineStates } = await import(
    'https://esm.sh/matchina?bundle&exports=matchina,createStore,defineStates'
  );

  const traffic = matchina(
    defineStates({ Red: undefined, Yellow: undefined, Green: undefined }),
    {
      Red:    { next: 'Green',  reset: 'Red' },
      Green:  { next: 'Yellow', reset: 'Red' },
      Yellow: { next: 'Red',    reset: 'Red' },
    },
    'Red'
  );

  traffic.subscribe(ev => console.log(ev.from.key, '→', ev.to.key));
  traffic.next();
</script>

Open the live demo →

Simpler: jsDelivr +esm

jsDelivr’s +esm endpoint also bundles into a single file, but doesn’t take a tree-shake hint — you get the full library (~5 KB gzipped). The URL is shorter and there’s no ?exports= list to maintain.

<script type="module">
  const { matchina, createStore, defineStates } = await import(
    'https://cdn.jsdelivr.net/npm/matchina/+esm'
  );

  // ... same machine code as above
</script>

Open the live demo →

With a view library

Matchina runs state machines. Rendering is your view library’s job. To pair it with a reactive view library over CDN (VanJS, Preact, Solid, Vue, petite-vue, Stimulus), see HTML Artifacts for the patterns, a side-by-side comparison, and heuristics.

Footprint comparison

Approach	Raw	Gzipped	Requests
esm.sh ?bundle&exports=…	6.6 KB	2.8 KB	2
jsDelivr +esm	14 KB	5.0 KB	1
unpkg (raw dist/)	n/a	n/a	37+

unpkg serves the published files verbatim, which for matchina is a re-export shim that fans out into ~37 chained requests — don’t use it.