The Pretext text layout library is published on npm as @chenglou/pretext. This page is the package-management-focused reference: how to install it, what version to pin to, what the bundle adds to your app, what dependencies to expect, and how to verify the install actually worked.
If you searched "npm pretext" or "pretext npm", you're probably one command away from using the library. The command is:
npm install @chenglou/pretext
The rest of this page covers the considerations that come up after that command runs.
The package is published under the @chenglou scope on the public npm registry:
# npm
npm install @chenglou/pretext
# yarn
yarn add @chenglou/pretext
# pnpm
pnpm add @chenglou/pretext
# bun
bun add @chenglou/pretext
No additional flags or peer-dependency installs needed. Pretext has zero runtime dependencies and no peer dependencies.
Pretext follows semantic versioning. The current release tempo:
x.y.Z) — every couple of weeks; bug fixes and small internal improvements. Always safe to take.x.Y.0) — when new public API is added or when a script-segmentation behavior changes. Usually safe; review the release notes for behavioral changes that affect your text.X.0.0) — rare. Have not occurred at the time of writing. Will signal breaking API changes that need code-side updates.For production apps, pin to a minor version range:
{
"dependencies": {
"@chenglou/pretext": "^1.4.0"
}
}
The ^ accepts patch and minor updates but not majors. For maximum stability — for example, if you've baked specific layout dimensions into snapshot tests — pin to an exact version:
{
"dependencies": {
"@chenglou/pretext": "1.4.7"
}
}
Be aware that exact pinning means you'll miss bug fixes until you manually bump. Pick based on how stable your testing surface is.
Pretext is roughly 15KB minified (about 5KB gzipped) for the full library. Tree shaking works cleanly via the package's exports map — if you only import prepare and layout, your bundle includes only what's needed for those two functions.
Verify the impact in your bundle with:
# After building
npx source-map-explorer dist/main.js
# or
npx vite-bundle-visualizer
The Pretext footprint should appear as a single small chunk. If it appears as 15KB even when you only import prepare, your bundler isn't tree-shaking — check that you're using ES modules ("type": "module" in package.json or module: "esnext" in tsconfig.json).
The package ships both ESM and CJS builds, with ESM preferred. The package's exports field looks roughly like:
{
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
}
}
}
Modern bundlers (Vite, esbuild, Rollup, Webpack 5+, Bun, Turbopack) will pick the ESM build automatically. Older Webpack 4 setups and CommonJS-only Node environments will fall back to the CJS build, which works but may not tree-shake as cleanly.
For Node-side usage (server-rendering, build scripts), use the ESM build via "type": "module" in your package.json, or use --experimental-vm-modules for Jest-flavored setups.
Runtime dependencies: zero. Pretext has no dependencies in its package.json.
Peer dependencies: zero. The library is framework-agnostic and does not require React, Vue, or any specific runtime environment.
Optional dependencies: zero.
This is unusual for a modern npm package and intentional. Pretext's design ethos is to be a small, focused engine you can drop into any environment without worrying about transitive dependency conflicts.
A 30-second smoke test that confirms the package is installed correctly:
// smoke-test.ts
import { prepare, layout } from '@chenglou/pretext';
const prepared = prepare("Hello, world.", "16px sans-serif");
const result = layout(prepared, 200);
console.log(result);
// Expected: { height: 19.something, lineCount: 1 }
Run with npx tsx smoke-test.ts or in a browser. If the import resolves and the result has height and lineCount numbers, you're set.
If the import fails:
npm install. Check that your registry is registry.npmjs.org (not a private registry that doesn't proxy public packages).tsconfig.json moduleResolution.prepare is not a function — you likely imported the default export. Pretext is named-exports only.Pretext requires a browser with canvas support and Unicode segmentation:
@napi-rs/canvas for prepare() to work server-sideFor older browsers, you'll need to polyfill Intl.Segmenter. The most common polyfill is the intl-segmenter-polyfill package.
There are several unrelated npm packages whose names contain "pretext." If you searched "pretext npm" you might land on one of them by mistake. The canonical package is:
@chenglou/pretext (note the @chenglou scope)If your package.json shows a different scope (e.g. pretext without scope, or @pretextbook/something), you've installed a different package. Uninstall and reinstall the correctly scoped one.
Pretext's framework-agnostic design means you don't need to coordinate versions with React, Vue, Svelte, etc. The library works the same way in:
The single compatibility consideration is the runtime: you need a canvas (browser) or a canvas polyfill (Node).
To update to the latest release:
npm update @chenglou/pretext
To check for available updates:
npm outdated @chenglou/pretext
When updating, the safe practice is to:
npm uninstall @chenglou/pretext
Then search your codebase for imports from @chenglou/pretext and remove the corresponding code paths. Because Pretext has no peer dependencies and no plugin system, removal is clean — there's nothing else hanging on to it.
The canonical npm page is npmjs.com/package/@chenglou/pretext. From there you can see the install command, the list of versions, the dependents (other packages depending on Pretext), the package size, and the README content.
The npm page's "Used by" section is an interesting place to discover production users — packages that have already integrated Pretext into their build, often with their own framework adapter or higher-level helper.
If you want the API reference for the functions Pretext exports, see the Pretext API reference. If you want to understand what the library does conceptually, the Pretext library overview is the right starting point. For React-specific integration, see the Pretext + React guide; for TypeScript-specific patterns, see the Pretext + TypeScript guide.
The library lives at github.com/chenglou/pretext and the package is at npm @chenglou/pretext.
pretext.cool is a community-maintained showcase, not affiliated with Cheng Lou or the official Pretext project.