Installation

With a bundler

1. Install the package.

   npm install sigmx

2. Create an instance and register the plugins you want. Nothing registers implicitly.

   import { createSigmx } from 'sigmx'
   import { signals, text, on, show, bind, httpGet, httpPost, applyElements, applyState } from 'sigmx/plugins'
   
   createSigmx({ plugins: [signals, text, on, show, bind, httpGet, httpPost, applyElements, applyState] })

3. Or start from a preset.

   import { createSigmx } from 'sigmx'
   import { all } from 'sigmx/presets/all'       // every plugin
   import { minimal } from 'sigmx/presets/minimal' // signals, text, show, on
   
   createSigmx({ plugins: all })

Prefer not to maintain the list by hand? Auto mode scans your source and registers exactly what it uses.

The instance scans the document once the DOM is ready and keeps watching it, so markup added later (by a server patch, a template, or any other script) is picked up automatically.

Script tag

The standalone build registers every plugin and starts immediately. Copy dist/sigmx.standalone.js from the package or serve it from your own CDN.

<script type="module" src="/sigmx.standalone.js"></script>

It exposes the instance as window.sigmx.

Astro

npm install sigmx @sigmx/astro

astro.config.mjs

import { defineConfig } from 'astro/config'
import sigmx from '@sigmx/astro'

export default defineConfig({ integrations: [sigmx()] })

The integration injects the client on every page and gives your endpoints helpers for reading signals and streaming patches. See the Astro SDK.

Any other server

The client does not care what produced the response. The protocol is HTML over HTTP, optionally a JSON object of signals, and a plain text event stream for several patches in one request; it is described in full in Talking to the server. Use whatever renders your HTML today: sigmx/server gives JavaScript runtimes (Node, Bun, Deno, Cloudflare Workers) the request readers and response builders, the Rust crate does the same for axum and Workers, @sigmx/hono is middleware for Hono, and any other language writes the responses by hand: a text/html body whose root element carries the id to morph, or event: and data: lines for a stream.

Options

createSigmx({
  plugins: [...],                       // required for anything to happen
  prefix: 'data-',                      // or ['data-', 'hx-', 's-'] while migrating
  eventPrefix: 'sigmx-',                // server event names to accept, e.g. ['sigmx-', 'datastar-']
  compile: cspCompiler(nonce),          // strict-CSP expression compiler, from 'sigmx/csp'
  expressions: precompiled(table),      // build-time compiled expressions; see the guide
  onError: (error, { plugin, el, attr }) => {},  // default: console.error
  store: sharedStore,                   // share signals with another instance
  autoStart: true,                      // false to call instance.apply() yourself
})

The returned instance has store, $ (the root store proxy, so sigmx.$.count++ works from JavaScript), apply(root), use(...plugins) and destroy().

Browser support

Modern evergreen browsers. sigmx uses Proxy, MutationObserver, fetch with streaming bodies and ReadableStream, and optional APIs it feature-detects: moveBefore, the Web Animations API, localStorage, ResizeObserver, IntersectionObserver.