Description

Spintax for JavaScript / TypeScript


Framework-agnostic spintax engine for JS/TS — parse, render,
validate, and extract variables from spintax templates, with zero WordPress dependency.
Runs on Cloudflare Workers, Node 18+, and in the browser.

npm install @spintax/core

→ @spintax/core on npm · package docs in
packages/core.

> Status: released & stable. The engine (@spintax/core) is feature-complete — parse, render,
> validate, extract, analyze, neutralize. Its deterministic golden corpus passes against **every
> engine in the family** — this one, both PHP engines (the Composer package and the WordPress
> plugin), Python and Object Pascal — and it’s proven by a reference Cloudflare Worker
> (examples/worker, M4). See the spec and packages/core.

Try it live 🎮

• 🤖 Telegram bot — @spintaxnetbot — paste a spintax template and

it validates it and replies with random variations; or /draft and an AI writes the
template for you.

• 🌐 Reference Worker API — validate-template / preview-render / extract-variables /

analyze-template / render-batch over HTTP.

Both are thin reference consumers built on @spintax/core (they import the engine, never the other
way round) — source in examples/.

What this is

The open-source core engine behind the Spintax ecosystem. It is a companion to the
Spintax WordPress plugin — an independent TypeScript
implementation that shares the same syntax and a machine-checked parity contract: a shared
golden corpus that passes against every sibling engine (verified, not just intended). Not a line-by-line port.

One engine, many surfaces: the planned Cloudflare Workers API, a Telegram authoring bot, and
a client-side playground on spintax.net are all consumers of this package.

The same engine, other runtimes

| | install | |
| — | — | — |
| JavaScript / TypeScript | npm i @spintax/core | this package |
| PHP | composer require spintax/core | investblog/spintax-php — MIT, zero deps |
| Python | pip install spintax-core | investblog/spintax-py — MIT, zero deps |
| Object Pascal | investblog/spintax-win | Free Pascal 3.2.2+ — MIT, zero deps |
| WordPress | wordpress.org/plugins/spintax | templates, ACF / post-meta bindings, WooCommerce context, WP-CLI |
| OpenCart 3.x | Spintax SEO | product / category copy and SEO URLs |

The parity contract is not a promise — it is a job. php-parity runs the
corpus in this repository against both PHP engines on every pull request, so a fixture cannot
land here unless the engines it binds already satisfy it.

Agent skills

Three Agent Skills teach an agent to write spintax, debug the syntax and wire an
engine into an application. They install into Claude Code, Codex, Cursor and the other agents the
skills command supports:

npx skills add https://spintax.net      # straight from the site
npx skills add investblog/spintax-js    # from this repository

The files are in skills/.

Spintax syntax (at a glance)

• {a|b|c} — enumeration (pick one), nestable {a|{b|c}}
• [a|b|c] — permutation (pick N, shuffle, join), configurable separators
• %var% — variable reference · #set %v% = value — local macro · #def %v% = value — local value, picked once per render
• {?VAR?then|else} — conditional · {plural : one|few|many} — plural agreement
• #include "slug-or-id" — embed another template · /# … #/ — comments
• /! … !/ — verbatim: kept exactly as written, e.g. a markdown link /!Docs!/ or a GSA macro

Full authoring reference lives in the parent project’s docs/gtw-syntax-reference.md.

Repository layout

packages/
  core/              # @spintax/core — the engine (published)
  conformance/       # the shared golden corpus — the cross-engine parity gate
  authoring-prompt/  # @spintax/authoring-prompt — the canonical LLM prompt for writing spintax (published)
examples/
  worker/            # Cloudflare Worker — HTTP API (validate/render/extract/analyze); deployed
  telegram-bot/      # Telegram bot @spintaxnetbot — validate + preview + AI /draft; deployed
skills/              # Agent Skills — copies of the ones spintax.net publishes
docs/spec-npm-engine.md  # governing spec (design source of truth)
LICENSE              # MIT

Consumers import the engine and never feed back into it — the purity boundary (spec §8) is
about direction, not import count. The bot, for instance, imports both @spintax/core and
@spintax/authoring-prompt, and contributes to neither: a consumer proves the API, it must not
pollute it. The prompt lives in its own package precisely so that no surface grows a private
dialect of it.

Design & specs

Releases publish from CI with provenance via npm Trusted Publishing — see
RELEASING.md. Deploying the two reference Workers (the HTTP API and the
Telegram bot) — accounts, secrets, the webhook, and what to verify live — is
DEPLOYING.md.

The governing spec is docs/spec-npm-engine.md in this repo —
it holds the locked decisions, the parity contract, and the milestone plan. It mirrors the
behavior contract of the parent Spintax WordPress plugin
(the PHP engine this port is verified against).

License

MIT. The Spintax WordPress plugin remains GPL; MIT/Expat is GPL-compatible, so
the two coexist cleanly.

—

Part of the 301.st toolset. Product home: spintax.net.