Contributor Guide

Prerequisites

• Node.js 24 — the workspace engines field requires exactly v24
• pnpm 11.3.0 — declared as packageManager in the root package.json

Clone and Install

git clone https://github.com/claudio-darkkenergy/plexis.git
cd plexis
pnpm install

pnpm install runs from the repository root and installs all workspace packages (@tde.io/plexis and @tde.io/docs) from a single lockfile.

Repository Layout

plexis/
  packages/
    plexis/          ← @tde.io/plexis — published library
  apps/
    docs/            ← @tde.io/docs — this Astro Starlight site
  .github/
    workflows/       ← build.yml, smoke-test.yml

Running Tests

From the repository root:

pnpm test

This delegates to @tde.io/plexis and runs all tests via Vitest. Tests live in packages/plexis/tests/.

Building the Library

From the repository root:

pnpm build

Produces three output formats under packages/plexis/dist/:

• dist/esm/ — ES modules
• dist/cjs/ — CommonJS
• dist/types/ — TypeScript declaration files

Typechecking

pnpm typecheck

Runs tsc --noEmit scoped to @tde.io/plexis.

Running Examples

From packages/plexis/:

pnpm run example:order
pnpm run example:payment
pnpm run example:graph

Updating the Docs

Start the local dev server from the repository root:

pnpm docs

This starts the Astro dev server for apps/docs/ at http://localhost:4321. Edit MDX files under apps/docs/src/content/docs/ — the dev server live-reloads on every save.

Build the docs site to verify there are no errors:

pnpm docs:build

This produces a static site under apps/docs/dist/. The docs build is independent of the library build — pnpm docs:build does not require pnpm build to have run first (no docs module imports the library yet).

Version Model

The docs site documents the latest published release of @tde.io/plexis — what users get when they run npm install @tde.io/plexis. The site’s @tde.io/plexis devDependency uses workspace:*, which resolves to the in-repo package. Because the docs currently contain no code that imports the library at build time, this is equivalent to documenting the published version. Update the docs pages in the same PR as any API change so they stay in sync.

If you add a doc page that actually imports from @tde.io/plexis at build time (e.g., the deferred interactive playground), pnpm docs:build will then require the library to be built first (pnpm build). Until that happens, the docs build is independent.

Vercel Preview Deployments

When you push a branch, the Vercel GitHub integration automatically creates a preview deployment and posts a URL to the commit status. This lets reviewers see docs changes live before merging.

Production deploys happen automatically when a commit lands on main.

If the Vercel build fails but pnpm docs:build passes locally, check the Vercel build logs. The most common cause is a workspace dependency resolution issue — verify that the Vercel project settings have Root Directory set to apps/docs and that pnpm workspace detection is enabled. Vercel handles this automatically for monorepos that have a root pnpm-workspace.yaml.

CI Workflows

Job	Trigger	What it does
build	pull request, tag v*.*.*	Typechecks and builds the library; uploads plexis-dist artifact
test	After build job succeeds	Downloads plexis-dist, runs the Vitest test suite
publish	Tag v*.*.* (after test succeeds)	Publishes @tde.io/plexis to npm with OIDC provenance
smoke-test.yml	After publish job succeeds	Installs the published package from npm and validates ESM/CJS exports

CI runs only on pull requests (for development) and on v*.*.* tags (for releases). Plain branch pushes trigger no workflow runs. Docs builds and preview deployments are handled by the Vercel GitHub integration.

Releasing a New Version

1. Bump the version in packages/plexis/package.json.
2. Open a PR and get it merged to main.
3. Push a matching tag to trigger the release:

   git tag v1.2.3 && git push origin v1.2.3

The tag push triggers the build, test, and publish jobs in sequence. After the publish job succeeds, the smoke-test.yml workflow runs to validate the published package.

The Publish workflow authenticates via GitHub OIDC — no NPM_TOKEN secret is needed.

Trusted publishing is coupled to the workflow filename. npm’s trusted-publisher record for @tde.io/plexis (configured at npmjs.com → package access settings) names the exact workflow file that runs pnpm publish — currently build.yml. GitHub mints an OIDC token whose job_workflow_ref embeds that filename, and npm only completes the token exchange when it matches the record. If you ever move or rename the publish job’s workflow file, update the npm trusted-publisher record in the same change — otherwise the next release fails the OIDC token exchange. The publish job guards against this by failing loudly with a remediation hint when OIDC is skipped, rather than silently attempting an unauthenticated publish.