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

> pangu.js inserts whitespace between Chinese, Japanese, or Korean characters and adjacent Latin letters, digits, or symbols. It runs as an npm library, a CLI tool, and a Chrome extension, with an optional AI spacing layer that handles edge cases regular expressions cannot.

**vinta/pangu.js** — Opinionated paranoid text spacing in JavaScript, with on-device AI semantic judgment

- Repository: https://github.com/vinta/pangu.js
- Website: https://chrome.google.com/webstore/detail/paphcfdffjnbcgkokihcdjliihicmbpd
- Stars: 4,833 · Forks: 315
- Language: TypeScript
- License: MIT
- Published: 2026-09-16 · Updated: 2026-09-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/vinta-pangu-js

## 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:

```bash
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`:

```js
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:

```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:

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

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

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

To process an inline string with typesetter mode:

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

To process a file:

```bash
pangu -f path/to/file.txt
```

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

```bash
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.

## 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.

## FAQ

### Can pangu.js process Markdown files?

The README explicitly states that pangu.js should not be used to space Markdown documents. The library is designed for HTML webpages and plain text without any markup language, since inserting spaces around Markdown syntax characters can break formatting.

### Does the AI spacing feature in pangu.js send data to a remote server?

The README states that the AI Spacing feature in the Chrome extension uses Chrome's built-in Prompt API, which runs Gemini Nano on the user's device. The processing is fully offline and nothing leaves the machine.

### Is pangu.js available for languages other than JavaScript?

The README lists official ports in Python (pangu.py), Go (pangu), and Java (pangu.java), along with community-maintained ports in Clojure, Dart, Elixir, Objective-C, PHP, Ruby, Rust, and Swift.

## Sources

- [Issues](https://github.com/vinta/pangu.js/issues)
- [License: MIT](https://github.com/vinta/pangu.js/blob/master/LICENSE)
- [Project website](https://chrome.google.com/webstore/detail/paphcfdffjnbcgkokihcdjliihicmbpd)
- [README](https://github.com/vinta/pangu.js/blob/master/README.md)
- [vinta/pangu.js on GitHub](https://github.com/vinta/pangu.js)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vinta-pangu-js