docs / getting started / installation
Installation
Install from npm, load from a CDN, self-host the script, or use browser-native ES modules.
##Develop from source
To work on Swarm Troopers itself, clone the repository. Development requires Node.js 20.19+, 22.12+, or 24 and later. Swarm Troopers itself has no runtime dependencies. From the directory containing package.json:
npm ci
npm run build
python3 -m http.server 8765Open http://localhost:8765/ for the landing page, or /demo/index.html for the full-page example. Serve files over HTTP; opening an ES module directly from a file: URL is not an equivalent test.
##One script tag
Load the pinned file from the CDN, or self-host it by copying dist/swarmtroopers.core.iife.js from node_modules/swarmtroopers into your public directory. This lightweight script embeds the mark and uses a vector finale. Choose dist/swarmtroopers.iife.js instead for the self-contained bundle with layered high-five artwork. Do not load both script profiles on one page.
<script src="https://unpkg.com/swarmtroopers@0.4.0/dist/swarmtroopers.core.iife.js"
data-swarmtroopers-init='{
"root": "main",
"auto": true,
"inspect": true,
"controls": { "position": "bottom-right" }
}'></script>data-swarmtroopers-init must contain valid JSON, including double-quoted keys. An empty attribute uses default options. Without that attribute, the script only makes window.SwarmTroopers available and registers the custom element; it does not create an instance automatically.
<script src="https://unpkg.com/swarmtroopers@0.4.0/dist/swarmtroopers.core.iife.js"></script>
<script>
const swarmtroopers = SwarmTroopers.create({ root: 'main', auto: true });
SwarmTroopers.controls(swarmtroopers);
</script>Automatic startup stores the instance as window.swarmtroopers and dispatches window’s swarmtroopers-ready CustomEvent with the instance in event.detail. Register your listener before loading the automatic script if you need it.
##Install from npm
Install the package from your application directory.
npm i swarmtroopersimport { create, controls } from 'swarmtroopers';
const swarmtroopers = create({ root: 'main', auto: true });
controls(swarmtroopers);Call swarmtroopers.destroy() when the view is removed, inside its unmount or teardown callback. See the framework recipes for cleanup that runs at the right time.
##Agent skill
To let Claude Code integrate Swarm Troopers for you, copy the packaged skill into your project. Add --global to install it for every project, or --dir <path> to choose the folder.
npx swarmtroopers skillThen ask Claude Code to add Swarm Troopers to a section of your site. Read the skill before installing it: skills/swarmtroopers-overlay on GitHub. The package itself is swarmtroopers on npm.
##Optional layered finale
The main ESM and CommonJS entries contain no raster completion images. Enable the supplied artwork in ESM with a side-effect import before creating instances:
import { create } from 'swarmtroopers';
import 'swarmtroopers/finale';
const swarmtroopers = create({ root: 'main', auto: true });For CommonJS, use require('swarmtroopers/full'). The self-contained dist/swarmtroopers.iife.js script includes the same artwork for classic-script integrations. Even in that full build, completion images are prepared only when enabled build work starts; disabled finales and inspection-only instances do not decode them.
##Native ES modules and CommonJS
For browser-native modules, copy the entire dist/ directory, including generated chunk-*.js files. Its small swarmtroopers.js entry imports a shared chunk; copying that entry alone will fail.
<script type="module">
import { create } from '/vendor/swarmtroopers/swarmtroopers.js';
create({ root: 'main', auto: true });
</script>Keep adjacent CommonJS registry files when copying artifacts manually; installing the complete package handles this. Node toolchains can resolve the CommonJS entry with require('swarmtroopers'). Importing the package is safe during server rendering, but calling create() requires a mounted browser document.
| Entry | Purpose |
|---|---|
dist/swarmtroopers.core.iife.js | Lightweight self-contained classic script; exposes window.SwarmTroopers. |
dist/swarmtroopers.iife.js | Full single-file profile with layered completion artwork. |
dist/finale.js | Optional ESM artwork registration; retain its shared chunks. |
dist/swarmtroopers.js | ES module entry with adjacent shared chunks. |
dist/swarmtroopers.cjs | CommonJS entry for compatible toolchains. |
dist/element.js | Custom-element registration entry; keep its chunks alongside it. |
dist/types/, dist/types-cjs/ | Separate ESM and CommonJS declarations selected by package exports. |
##Avoid a first-paint flash
Omit preload by default. For a noncritical animation region that needs anti-flash behavior, copy the optional preload snippet into head and explicitly mark eligible elements with data-swarmtroopers-preload. Never hide all of main or a critical hero. The snippet leaves marked controls and containers with controls or skipped descendants visible.
The snippet respects Off and reduced motion, and removes its class after 2.5 seconds if Swarm Troopers never loads. Swarm Troopers also clears the class on initialization or configuration failure. Match its storage prefix to storageKey. With JavaScript disabled it does not hide content.
A strict CSP needs a nonce or hash on the preload script and style, or the snippet should be omitted. See Content Security Policy for the library’s own image and stylesheet behavior.