Development Setup

Development Setup

How to build, test and release Postext itself. To use the library, see Getting Started; for why and where to help, see Contributing.

---

Prerequisites

• Node.js 20 or later (CI and releases use 22).
• pnpm, at the version pinned in the root package.json (packageManager). With Corepack enabled (corepack enable), that version is picked up for you. npm and yarn do not work at the root.
• Optional: Java, to run W3C EPUBCheck on the EPUB samples (pnpm --filter postext-epub epubcheck); pdftoppm (Poppler), to look at PDFs page by page.

---

Clone and install

git clone https://github.com/drnachio/postext.git
cd postext
pnpm install

pnpm install links the workspace packages and applies the patches in patches/ (the wawoff2 patch for the PDF font pipeline).

---

Commands

Run them from the repository root; they go through Turborepo, which builds dependencies first and caches results.

pnpm dev                 # library watchers + the site at http://localhost:3000
pnpm build               # build everything
pnpm turbo run test      # Vitest in every package and in apps/web
pnpm check-types         # tsc --noEmit everywhere
pnpm lint                # ESLint everywhere
pnpm cookbook <command>  # the Cookbook tool (see Cookbook and Showcase)

One package at a time:

pnpm --filter postext test
pnpm --filter postext-pdf build
pnpm --filter web dev

The site reads the packages from their dist/ folders. In pnpm dev, a tsc --watch per package rebuilds them on save; if a test in another package needs a fresh build, run npx tsc in that package first.

---

Branches

• develop: where work lands. Pull requests from contributors target develop.
• main: what is released. A merge of develop into main publishes a release.

---

Making changes

1. Open an issue, or comment on one, before writing code that changes behaviour. A short exchange first saves a long review.
2. Fork the repository and branch from develop.
3. Follow the code around you: strict TypeScript, ESM only, no emojis in source or docs.
4. Add or update tests next to the code (packages/*/src/__tests__/ or beside the file).
5. Update the docs: the MDX in docs/ for every locale the page exists in (English, Spanish, Catalan, Chinese, Arabic), and new interface strings in every message file of apps/web/messages/.
6. Check locally:

   pnpm build && pnpm turbo run test && pnpm check-types && pnpm lint

7. Open a pull request against develop that says what changes and why, and links the issue (Closes #123).

Commit subjects follow the conventional form used in the history: feat(engine): …, fix(sandbox): …, docs(cookbook): ….

---

Tests

Every package uses Vitest. Some suites worth knowing in packages/postext:

File	Covers
exports.test.ts	The public API. An export added or removed without updating it fails.
knuthPlass.test.ts	Line breaking: badness, fitness classes, hyphenation penalties.
orphanWidow.test.ts	Paragraph splits.
numbering.test.ts, numbering-page.test.ts	Heading and page numbering.
measureCache.test.ts	The measurement cache.
math.test.ts	MathJax.
createLayout.test.tsx	postext/react.

apps/web has tests for the docs, the Markdown renditions and the Cookbook (every recipe's metadata, write-ups and capture). postext-epub has an EPUBCheck suite that runs in CI.

CI (.github/workflows/ci.yml) runs on every pull request to develop or main: build, tests, EPUBCheck, type check and lint.

---

Key source files

File	Role
packages/postext/src/pipeline/build.ts	The orchestrator: parse, measure, place, converge.
packages/postext/src/vdt.ts	The Virtual Document Tree.
packages/postext/src/types.ts	Configuration and content types.
packages/postext/src/knuthPlass/	Line breaking.
packages/postext/src/parse/blockParser.ts	Markdown to blocks.
packages/postext/src/measure/rich.ts	Rich-text measurement.
packages/postext/src/defaults/	Defaults and resolvers per section.
packages/postext/src/canvas-backend/, html-backend.ts	Built-in renderers.
packages/postext/src/worker/	The layout worker.
packages/postext-pdf/src/pdf-backend/	The PDF writer.
packages/postext-epub/src/	The EPUB writer (fixed/, reflowable/, package/).
packages/postext-sandbox/src/	The Sandbox.

See Architecture for how they connect.

---

Releases

Releases are automatic and come from main:

1. Open a pull request from develop to main. Label it minor or major when it adds features or breaks something; without a label the release is a patch.
2. When it is merged, the Release workflow (.github/workflows/release.yml) bumps postext, postext-pdf, postext-citeproc, postext-epub and postext-folio, builds and tests them, publishes them to npm, regenerates the showcase layouts for the new engine version, commits chore: release vX.Y.Z, tags every package, and pushes the version back to develop.
3. If publishing fails (for example an expired npm token), fix the cause and run the workflow again from the Actions tab (workflow_dispatch).

---

Updating the wiki

The doc pages of this wiki are generated from the English MDX in docs/. After changing the docs:

git clone https://github.com/drnachio/postext.wiki.git ../postext.wiki
cd apps/web
pnpm wiki ../../../postext.wiki
cd ../../../postext.wiki && git add -A && git commit -m "Sync with docs" && git push

The script (apps/web/scripts/wiki/sync.ts) uses the site's own MDX-to-Markdown conversion, rewrites links between docs to wiki pages, and splits Configuration into the pages listed in the script. A new ## section in the Configuration doc stops the run until it is assigned to a page there. The hand-written pages (Home, Features, Getting Started, Packages, API Reference, Project Structure, this page, Roadmap, Cookbook and Showcase, the sidebar) are not touched; update them by hand when a feature or package changes.

---

Where to ask

• Issues: bugs and concrete tasks.
• Discussions: ideas and questions.
• Pull requests: code review.