Pts at 1.0.3: two module entry points and one gate command
A library for visualization and creative-coding
At a glance
- What is it?
- Pts is William Ngan's canvas library for creative coding, and the repository treats packaging as part of the product: an exports map with two resolvers, a sideEffects list, generated docs committed to the tree, and a single pnpm check that runs a real browser. The version history has one long silence in it, and the manifest sits two patches ahead of the last tag.
- Who is it for?
- Pts fits projects that want canvas 2D geometry, color conversion and curve helpers in a small ESM-first package, as long as you keep your own canvas lifecycle. The README does not mention audio or 3D work, so check the demos at ptsjs.org before relying on either.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 25 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- williamngan/pts5,373 ★ · +26
| Repository | 2026-09-23 | 2026-11-21 |
|---|---|---|
| williamngan/pts | 5.3k | 5.4k |
26 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The exports map decides which build your bundler sees
Pts ships one library through two module entry points, and the manifest is what chooses between them. The package declares its type as commonjs while the project describes itself as ESM first, and the exports map then resolves the same "." specifier two ways. An import receives ./dist/index.mjs with types taken from ./dist/index.d.mts. A require receives ./dist/index.js with types from ./dist/index.d.ts. The map also re-exports ./dist/* and ./package.json, which is what lets a browser page reach the prebuilt bundle through the package itself. Two more fields exist purely for CDN delivery: unpkg and jsdelivr both point at ./dist/pts.min.js. Then there is sideEffects, which names only ./dist/pts.js and ./dist/pts.min.js. A bundler is therefore free to drop unused named imports from the module build while keeping the two classic bundles intact, and pnpm check tests that tree-shaking claim instead of asking you to trust it.
npm install pts, then the import line your bundler has to match
Installing the library is one command, and everything after it depends on how your project resolves modules. The ESM form is the primary path:
npm install ptsimport { CanvasSpace, Group, Line, Pt } from "pts";If your build still emits CommonJS, the compatibility entry hands back the same names:
const { CanvasSpace, Group, Line, Pt } = require("pts");CanvasSpace and Group are the container types, Line and Pt are geometry, and no third import shape is documented, so there is nothing else to configure at install time. The manifest ships dist and src/*.ts, so the TypeScript sources travel with the package for anyone who wants to read them. A page with no bundler takes the same library through one script tag, and the classic build then attaches to globalThis.Pts:
<script src="path/to/pts.min.js"></script>That tag resolves against a local path, the dist directory, or a CDN such as cdnjs, jsDelivr or unpkg. The README also lists pts-starter-kit, pts-react-example and the react-pts-canvas package as starter projects and integrations.
pnpm check is the gate, and it opens a real browser
Contributing to Pts means passing one command, and the maintainer setup is three lines:
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm checkThe middle line is not decoration. pnpm check validates formatting, linting, types, unit tests, deterministic documentation, documentation and bundle behavior in a real browser, reproducible artifacts, the packed package, ESM and CommonJS resolution, declarations, and tree-shaking. Its packed-package integration suite then builds and runs the maintained React, Vue, skia-canvas and single-file vanilla fixtures in test/integrations. A green run therefore means a Chromium binary is installed, four fixtures compile against the packed tarball, and both module systems resolve as the exports map claims. For narrower loops the same work is split into pieces:
pnpm build
pnpm typecheck
pnpm test
pnpm test:browser
pnpm test:integrations
pnpm check:packageThose scripts call real tools rather than shell glue. build runs tsdown, typecheck runs tsc against tsconfig.json, test runs vitest, and test:browser runs node scripts/browser-smoke.mjs. Formatting belongs to Prettier: pnpm format rewrites files once, pnpm format:watch keeps them formatted, and the same check rejects unformatted changes in CI.
Node 24 builds the library, Node 20 and 22 only run it
The maintained build environment is Node 24.18 or newer inside the Node 24 line, and the published library is additionally exercised on the current Node 20 and 22 releases. That split decides what a checkout is for. Contributors work in the 24 line. Consumers of the npm package are covered on 20 and 22. A CI job pinned to Node 20 can install pts and run your own code against it, but it is not the environment the package was built in, so a failure there does not by itself mean the published artifact is broken. The repository records its runtime in files rather than prose: .node-version and .nvmrc sit at the top level next to pnpm-lock.yaml and pnpm-workspace.yaml, which is also why a frozen lockfile install is the documented first step. The last push to this repository was on 2026-10-28, and the newest release, v1.0.1, was published on 2026-09-19.
Three years between v0.11.3 and 1.0.0, and the manifest ahead of the tag
The version history contains one long silence. v0.11.3 was published on 2022-12-08. The next tag, v1.0.0, did not appear until 2026-09-12, and v1.0.1 followed seven days later on 2026-09-19. No release covers the years in between, so CHANGELOG.md at the repository root is the only continuous record of what happened to the source. A smaller gap sits on top of it: the package manifest reads version 1.0.3 while the newest tag is v1.0.1. Anyone pinning a deployment should decide which of those they want, because a tag gives the last published build and the default branch, named master, gives the state the manifest describes as 1.0.3. On licensing the answer is short. The project is under the Apache License 2.0 with a LICENSE file at the root and a copyright line reading 2017-present William Ngan and contributors, and no copyleft clause is stated anywhere in the tree. Issues and small pull requests are taken as they come; larger changes are expected to start as a discussion first.
docs.md, guide.md and llms.txt are generated and checked in
The documentation is a build product, which has consequences for anyone who forks. The generator uses TypeDoc's Node API to rebuild the custom static documentation JSON from explicit source entry points, then writes docs.md, guide.md and llms.txt for agents and other clients that cannot navigate the documentation SPA:
pnpm run docsAll three files are committed, next to the docs/ and guide/ directories. pnpm check:docs regenerates them in memory, reports stale or extra files, and exercises navigation, search, anchors and responsive layouts in Chromium. So a fork that edits a source entry point and skips the regeneration step does not fail on a type error first. It fails on a stale file report, which is the cheaper of the two failures to have. The published site lives at ptsjs.org, with the getting started guide at /guide/Get-started-0100.html and the demo index at /demo/?name=circle.intersectCircle2D. The presence of llms.txt at the repository root says the project expects clients that never open that site at all.
Every demo file is 2D canvas work, and none of it touches audio or 3D
The example files are a fast tour of the API, and reading them beats guessing at a call signature. The listing covers container behavior in canvasspace.action.js and canvasspace.resize.js, geometry in circle.intersectCircle2D.js and circle.intersectLine2D.js, color conversion in color.HSLtoRGB.js and color.LABtoRGB.js, generators in create.flock.js, create.gridcells.js and create.noisePts.js, curves in curve.bezier.js and curve.bspline.js, interpolation in geom.interpolate.js, and text layout in guide.canvas_aligntext.js and guide.canvas_paragraphbox.js. Every one of those files sits under the demo/ directory at the repository root, next to bench/, study/, assets/ and the built docs/.
Two gaps are visible from that list on its own. The README does not mention 3D, WebGL or audio.
Editorial conclusion
Pts fits projects that want canvas 2D geometry, color conversion and curve helpers in a small ESM-first package, as long as you keep your own canvas lifecycle. The README does not mention audio or 3D work, so check the demos at ptsjs.org before relying on either. Verify first that the version you pin matches your Node line: the default branch manifest reads 1.0.3 while the newest tag is v1.0.1, and the maintained build environment is Node 24.18 or newer.
Frequently asked questions
How do I install Pts and use it in a browser?
Run npm install pts and then import { CanvasSpace, Group, Line, Pt } from "pts". With no bundler, load pts.js or pts.min.js from the dist directory or from a CDN such as cdnjs, jsDelivr or unpkg, and the classic script exposes the library as globalThis.Pts.
Does Pts work with CommonJS as well as ESM?
Yes. The project calls itself ESM first and states that it also provides a CommonJS compatibility entry, and the exports map sends require to ./dist/index.js while import resolves to ./dist/index.mjs, each with its own declaration file.
What Node version does building Pts from source require?
The maintained build environment is Node 24.18 or newer within the Node 24 line. The published library is also exercised on the current Node 20 and 22 releases, which are supported for running the package rather than for building the repository.
What does pnpm check actually validate in Pts?
It validates formatting, linting, types, unit tests, documentation, bundle behavior in a real browser, reproducible artifacts, the packed package, ESM and CommonJS resolution, declarations and tree-shaking. It also builds and runs the React, Vue, skia-canvas and single-file vanilla fixtures in test/integrations, which is why a Playwright Chromium install comes first.
What licence is Pts released under?
Apache License 2.0, with the LICENSE file at the repository root and a copyright line reading 2017-present William Ngan and contributors.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/williamngan-pts)Star history chart for your README
[](https://hysenlabs.com/projects/williamngan-pts)Was this useful?