twee-ts

TypeScript reimplementation of Tweego — a command-line compiler for Twine/Twee interactive fiction projects.

Zero runtime dependencies (the parsers it uses, parse5 and acorn, are bundled). Node.js 24+.

Upgrading from 1.x? Read Migrating to 2.0.

Documentation

Install

npm install @rohal12/twee-ts

Quick Start

npx @rohal12/twee-ts --init               # scaffold a new project
npx @rohal12/twee-ts -o story.html src/   # compile
npx @rohal12/twee-ts -w -o story.html src/ # watch mode

Or with a config file (twee-ts.config.json):

{
  "sources": ["src/"],
  "output": "story.html"
}

npx @rohal12/twee-ts

Programmatic API

import { compile } from '@rohal12/twee-ts';

const result = await compile({
  sources: ['src/'],
  tagAliases: { library: 'script' },
});
console.log(result.diagnostics);

Build Plugins

// vite.config.ts
import { tweeTsPlugin } from '@rohal12/twee-ts/vite';

export default {
  plugins: [tweeTsPlugin({ sources: ['src/'] })],
};

Also available: @rohal12/twee-ts/rollup. In both plugins, compile errors fail the build and emit no HTML; warnings go through the bundler's warnings.

Documentation

Full docs at rohal12.github.io/twee-ts:

• Getting Started
• Differences from Tweego
• Migrating to 2.0
• CLI Reference
• Configuration
• Tag Aliases
• Output Modes
• Programmatic API
• Vite & Rollup Plugins
• Story Formats
• Packaging Formats

Development

You need Node.js 24 or later and pnpm 12, the version packageManager in package.json pins; devEngines makes the install fail on an older Node.js. Get pnpm 12 with npm install -g pnpm@12, or run corepack enable and let Corepack read the pinned version. A standalone pnpm 10 or 11 cannot install the project: it tries to switch to the pinned pnpm 12 and fails with ERR_PNPM_NO_MATCHING_VERSION for @pnpm/[email protected] (pnpm 12 renamed its platform packages), so update pnpm first. CONTRIBUTING.md lists the checks a change has to pass.

pnpm install
pnpm test            # run tests (including every example in these docs)
pnpm run typecheck   # type-check
pnpm run lint        # ESLint
pnpm run build       # bundle
pnpm run docs:dev    # local docs dev server
pnpm run docs:build  # build docs for deployment
pnpm run test:contracts  # build, then run the compiler contract matrix against it

Releases need recorded validation evidence: see Compiler Validation and Releases.

License

The twee-ts source code is free and unencumbered software released into the public domain. See UNLICENSE.

The published package is not entirely public domain:

• twee-ts reimplements Tweego and ports parts of its Go source. Tweego is © Thomas Michael Edwards under the BSD 2-Clause licence.
• The JavaScript in dist/ bundles third-party packages (such as parse5 and acorn), which keep their own licences (MIT and BSD 2-Clause).

THIRD_PARTY_NOTICES lists every bundled package with its licence text, reproduces Tweego's notice, and ships in the npm package. The build regenerates it from what it actually bundled. If you redistribute twee-ts, or bundle it into your own build, keep that file with it.