pangu.js: Automatic CJK-to-Latin Spacing for JavaScript, Node, and the Browser

What Paranoid Text Spacing Means and Why It Matters

The project's name references a typographic concept the README calls 'Pangu's whitespace'. The principle is simple: a space character should separate full-width CJK glyphs from half-width Latin letters, digits, and most symbols. Without it, Chinese and English text appears visually cramped and harder to read.

Regex rules handle the common case well. A pattern that matches any CJK character followed by any ASCII character can insert a space. But some symbols carry different semantic weight depending on context. The minus sign in a negative temperature is different from the hyphen used as a separator in a title. Regular expressions cannot distinguish these cases from the character sequence alone.

This is the problem pangu.js v10 takes on. The library handles the deterministic cases with regex. An optional AI layer in the Chrome extension handles the ambiguous ones using Chrome's built-in Prompt API.

Installing pangu.js and the Three Usage Contexts

The package is published on npm. Install it with:

npm install pangu --save-exact

The `--save-exact` flag pins the version, which the README recommends.

For browser use inside a bundler, import from `pangu/browser`:

import pangu from 'pangu/browser';

const text = pangu.spaceText('當你凝視著bug，bug也凝視著你');
// text = '當你凝視著 bug，bug 也凝視著你'

pangu.spaceNode(document.getElementById('main'));

The `pangu/browser` build includes `spaceNode()` and `autoSpacePage()`, which are DOM-specific methods. The README notes this import path must be used with a bundler; for a no-bundler context, use `pangu/browser/standalone` instead.

For Node.js:

import pangu from 'pangu';

const text = pangu.spaceText('與PM戰鬥的人，應當小心自己不要成為PM');
// text = '與 PM 戰鬥的人，應當小心自己不要成為 PM'

const content = await pangu.spaceFile('/path/to/text.txt');

The `spaceFile()` method reads and processes a text file directly. The Node.js build does not include DOM methods.

For projects that do not use a bundler, the package is also available from CDN hosts. jsDelivr, unpkg, and cdnjs all carry pangu.js. The CDN builds come in two forms: `pangu.umd.js` for scripts loaded with a `<script>` tag and `pangu.js` as a self-contained ESM module. The version number appears in the URL path, so pinning to a specific release is straightforward. The package.json marks the package as `"sideEffects": false`, which allows bundlers to tree-shake the library when only `spaceText()` is used and DOM methods are not imported.

CLI Usage for Scripting and Pipelines

The package installs a `pangu` binary that supports several modes. Pass text as a positional argument:

pangu "不能信任那些Terminal或Editor用白底的人"

The output is the spaced string written to stdout, which makes it composable with pipes:

echo "他們在release的前一天爆炸" | pangu

To process an inline string with typesetter mode:

pangu -t "你在每個commit裡修改的程式碼越多，你在code review時被發現的錯誤就會越少"

To process a file:

pangu -f path/to/file.txt

The `-c` flag checks whether a string needs correction and exits with code 1 if it does:

pangu -c "盤古新聞網：工程師會議中默不作聲，PM恐成最大贏家"; echo $?

This is useful for pre-commit hooks or CI checks that enforce spacing conventions.

AI Spacing in the Chrome Extension: Mechanism and Scope

The Chrome extension applies pangu.js to every page you visit. The AI Spacing feature handles symbols that regex cannot classify correctly. The README gives the minus sign as an example: `-273.15` uses it as a numeric sign, while `博客來-4% 法則` uses it as a separator.

The feature uses Chrome's built-in Prompt API, which runs Gemini Nano on the user's device. The README notes that all processing is local and offline, and that nothing leaves the machine. The prompts for Gemini Nano are written and tuned through a separate automated process: a larger model proposes changes, tests them against real Gemini Nano in Chrome, and refines them when cases fail.

This AI path is only available in the Chrome extension. The npm library and CLI use regex rules only. Developers who need AI-assisted spacing in custom applications would need to implement their own integration with a local model API.

A Known Limitation: No Markdown Support

The README contains an explicit warning: pangu.js should not be used to space Markdown documents. The library is designed for HTML pages and plain text. In Markdown, spacing rules interact with syntax: inserting a space before or after a backtick, an asterisk, or a bracket character can break formatting.

The README links to issue 127 for context. Teams working on documentation pipelines that involve both CJK content and Markdown output need a different tool or need to apply pangu.js selectively after Markdown has been rendered to HTML.

The library also makes no guarantees about idempotency in edge cases. Running `spaceText()` twice on the same string should be safe in practice, but the README does not document this as a formal invariant.

Ecosystem and Alternatives

The pangu family spans multiple languages. The README lists official ports in Python (pangu.py), Go (pangu), and Java (pangu.java), plus community ports in Clojure, Dart, Elixir, Objective-C, PHP, Ruby, Rust, and Swift. There is also pangu.space, a website and HTTP API.

Pandoc, a general document converter, handles some CJK typography through its filter system, but it operates at the document conversion level rather than as a focused text-spacing utility. It does not expose a JavaScript API.

For teams outside the JavaScript ecosystem, the Go or Python ports provide the same core algorithm with the same opinionated spacing rules. For JavaScript projects that need only the browser extension without a library dependency, the Chrome Web Store extension is the direct option.

The package exports are structured carefully to avoid bundler confusion. The main entry point is for Node.js and CommonJS environments; the `pangu/browser` and `pangu/browser/standalone` exports are browser-specific. A `pangu/shared` export exists for code that runs in both environments. The package.json uses the `exports` field with separate `import` and `require` conditions, covering both ESM and CommonJS consumers.

The package is MIT-licensed. The repository had its last push on 2026-09-26 and the npm package is at version 10.4.1.

Editorial conclusion

pangu.js is the correct tool when you need to enforce CJK-to-Latin spacing rules in JavaScript, whether in the browser DOM, a Node.js pipeline, or from the command line. It is not suitable for spacing Markdown documents, as the README explicitly states the library is designed for HTML and plain text only. The Chrome extension adds an AI-assisted mode for ambiguous symbols, using Chrome's built-in Gemini Nano API with no data leaving the device. The project had its last push on 2026-09-26 and ships regularly in the v10.x series.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vinta/pangu.js on GitHub