JavaScript and TypeScript

Install polytypo from npm, call transform and analyze in JavaScript or TypeScript, read error codes, and see which modes and dialects the package covers.

Updated 21 October 2026 · spec 1.12.0

The JavaScript/TypeScript package is published on npm as polytypo; the source is in polytypo/polytypo-js. It claims spec 1.8.0 and covers every mode, both Markdown dialects, all nine rules and all nineteen locales. It ships ESM and CommonJS builds with type declarations, and requires Node 20 or later.

Install #

npm install polytypo

Calling it #

transform(input, options) returns the typeset string. options is a plain object with camelCase keys. Only locale is always required.

import { transform } from "polytypo";

transform(input, { locale: "de-DE" });

// mode "markdown" requires an explicit dialect; "text" and "html" ignore it
transform(input, { locale: "fr", mode: "markdown", dialect: "commonmark" });

// mode "yaml" requires the keys whose values hold prose
transform(input, { locale: "en-US", mode: "yaml", keys: ["description"] });

// switch one rule off; the order of the rest never changes
transform(input, { locale: "en-US", rules: { dashes: false } });

The full option contract is on Options.

Entry points #

The package root loads every parser. Each mode also has its own entry that defaults mode to itself and loads only what that mode needs:

import { transform } from "polytypo/markdown";

transform(source, { locale: "en-US", dialect: "mdx", frontmatterKeys: ["title"] });

Reporting without changing #

analyze(input, options) takes the same options and returns the edits transform would make, as { ruleId, start, end, before, after } records with code-point offsets into the input. See analyze.

Errors #

Every failure is a PolytypoError (exported from the package root) with a stable code. Branch on error.code, never on the message.

import { transform, PolytypoError } from "polytypo";

try {
  transform(input, { locale: "xx" });
} catch (error) {
  if (error instanceof PolytypoError) {
    error.code; // "POLYTYPO_UNKNOWN_LOCALE"
  }
}

The eight codes are listed on Error codes. POLYTYPO_MALFORMED_INPUT is reachable only with mode: "markdown" and dialect: "mdx".

Complete example #

Save as example.mjs after npm install polytypo, then run node example.mjs.

import { transform, analyze, PolytypoError } from "polytypo";

const input = 'She said, "it\'s fine" -- but I wasn\'t sure...';

console.log(transform(input, { locale: "en-US" }));
// She said, “it’s fine”—but I wasn’t sure…

console.log(transform(input, { locale: "de-DE" }));
// She said, „it’s fine“ – but I wasn’t sure…

console.log(transform(input, { locale: "en-US", rules: { dashes: false } }));
// She said, “it’s fine” -- but I wasn’t sure…

console.log(analyze('Wait... "really"?', { locale: "en-US" }));
// [ { ruleId: 'ellipsis', start: 4, end: 7, before: '...', after: '…' },
//   { ruleId: 'quotes', start: 8, end: 9, before: '"', after: '“' },
//   { ruleId: 'quotes', start: 15, end: 16, before: '"', after: '”' } ]

try {
  transform(input, { locale: "xx" });
} catch (error) {
  if (!(error instanceof PolytypoError)) throw error;
  console.log(error.code); // POLYTYPO_UNKNOWN_LOCALE
}

The same call, measured:

Conformance #

The package passes the conformance suite for spec 1.8.0. Modes: text, html, markdown (dialects commonmark and mdx) and yaml. Rules: all nine. The matrix for every runtime is spec/CONFORMANCE.md.

Related #

• Python, Go, Ruby, PHP
• Installation
• Options
• Running polytypo in a build step

Conformance matrix: spec/CONFORMANCE.md.