Add API reference generation and website (#89)

* Add API reference generation tooling

* Add static API reference website

* Deploy API reference website with GitHub Pages

* Complete public API documentation

Author: SandroMaglione

.changeset/api-reference-generator.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Add Effect-compatible TypeDoc API reference generation and a lightweight static reference website with module navigation, declaration pages, source links, responsive layouts, and local search. Document the public API with library-native version metadata and focused examples for the primary machine, persistence, testing, reactivity, and Cluster workflows.

.github/workflows/release.yml

@@ -4,6 +4,10 @@ on:
   push:
     branches: [main]
 
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   pull-requests: write
@@ -13,6 +17,8 @@ jobs:
   release:
     runs-on: ubuntu-latest
     environment: npm
+    outputs:
+      published: ${{ steps.changesets.outputs.published }}
     steps:
       - uses: actions/checkout@v7
       - uses: pnpm/action-setup@v6
@@ -23,8 +29,18 @@ jobs:
           registry-url: https://registry.npmjs.org
       - run: pnpm install --frozen-lockfile
       - run: pnpm check
-      - uses: changesets/action@v1
+      - id: changesets
+        uses: changesets/action@v1
         with:
           publish: pnpm release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  deploy-website:
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    uses: ./.github/workflows/website.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write

.github/workflows/website.yml

@@ -0,0 +1,52 @@
+name: Website
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - id: pages
+        uses: actions/configure-pages@v5
+      - run: pnpm docs:site
+        env:
+          API_REFERENCE_BASE_PATH: ${{ steps.pages.outputs.base_path }}
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: .data/api-reference-site/v4
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 references/
+.data/
 *.tgz
 .DS_Store
 .pnpm-store

CONTRIBUTING.md

@@ -55,3 +55,26 @@ understands imports, re-exports, and dynamic imports, and enforces:
 
 The checker has executable fixture tests and runs as part of `pnpm check`. Add
 new rules only with a failing fixture that demonstrates the boundary.
+
+## API reference data
+
+`pnpm docs:api` generates an Effect-compatible TypeDoc dataset under
+`.data/api-reference/v4`. The dataset contains a top-level manifest, a package
+manifest, and one checksummed reflection JSON file per module configured in
+`api-reference.config.json`. Generated data is not committed.
+
+`pnpm docs:api:check` runs the API reference unit tests, generates the complete
+dataset in a temporary directory, validates its manifests and checksums, and
+ensures every reflection can be consumed by the site-facing normalizer. It runs
+as part of `pnpm check`.
+
+`pnpm docs:site` turns that dataset into a multi-page static website under
+`.data/api-reference-site/v4` and creates its Pagefind search index. Run
+`pnpm docs:site:serve` to preview the latest generated site locally. Site output
+is also generated data and is not committed.
+
+The release workflow calls the GitHub Pages workflow after Changesets publishes
+a package. The Pages workflow can also be run manually to deploy the current
+commit before a release without invoking the package-release job. Pages supplies
+`API_REFERENCE_BASE_PATH` during the build so project URLs and custom domains
+use the same generated site without configuration edits.

api-reference-site.config.json

@@ -0,0 +1,7 @@
+{
+  "input": ".data/api-reference/v4",
+  "output": ".data/api-reference-site/v4",
+  "basePath": "/",
+  "title": "Effect Machine",
+  "description": "API reference for Effect Machine"
+}

api-reference.config.json

@@ -0,0 +1,72 @@
+{
+  "channel": "v4",
+  "output": ".data/api-reference/v4",
+  "tsconfig": "tsconfig.json",
+  "barrels": [
+    {
+      "export": ".",
+      "source": "src/index.ts"
+    },
+    {
+      "export": "./testing",
+      "source": "src/testing/index.ts"
+    },
+    {
+      "export": "./reactivity",
+      "source": "src/unstable/reactivity/index.ts"
+    },
+    {
+      "export": "./cluster",
+      "source": "src/unstable/cluster/index.ts"
+    }
+  ],
+  "modules": [
+    {
+      "export": "./Machine",
+      "source": "src/Machine.ts",
+      "barrel": ".",
+      "examples": [
+        "after",
+        "decodeSnapshot",
+        "defineStates",
+        "effect",
+        "encodeSnapshot",
+        "event",
+        "invoke",
+        "invokeEffect",
+        "make",
+        "plan",
+        "planInitial",
+        "resume",
+        "start",
+        "transition"
+      ]
+    },
+    {
+      "export": "./testing/MachineTest",
+      "source": "src/testing/MachineTest.ts",
+      "barrel": "./testing",
+      "examples": [
+        "coverage",
+        "explore",
+        "invariants",
+        "probe",
+        "run",
+        "scenarios",
+        "verify"
+      ]
+    },
+    {
+      "export": "./unstable/reactivity/AtomMachine",
+      "source": "src/unstable/reactivity/AtomMachine.ts",
+      "barrel": "./reactivity",
+      "examples": ["make", "matches", "select", "selectChild"]
+    },
+    {
+      "export": "./unstable/cluster/ClusterMachine",
+      "source": "src/unstable/cluster/ClusterMachine.ts",
+      "barrel": "./cluster",
+      "examples": ["make"]
+    }
+  ]
+}

package.json

@@ -54,9 +54,16 @@
     "perf:runtime": "pnpm build && node --expose-gc scripts/runtime-performance.mjs",
     "format": "dprint fmt",
     "format:check": "dprint check",
+    "docs:api": "node scripts/api-reference/generate.mjs",
+    "docs:api:test": "node --test scripts/api-reference/*.test.mjs",
+    "docs:api:check": "pnpm docs:api:test && node scripts/api-reference/generate.mjs --check",
+    "docs:site": "pnpm docs:api && node scripts/api-reference-site/generate.mjs && pagefind --site .data/api-reference-site/v4",
+    "docs:site:test": "node --test scripts/api-reference-site/*.test.mjs",
+    "docs:site:check": "pnpm docs:site:test && pnpm docs:api && node scripts/api-reference-site/generate.mjs --check",
+    "docs:site:serve": "node scripts/api-reference-site/serve.mjs",
     "test:consumer": "node scripts/test-consumer.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "check": "pnpm format:check && pnpm check:architecture && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check",
+    "check": "pnpm format:check && pnpm check:architecture && pnpm docs:api:check && pnpm docs:site:check && pnpm typecheck && pnpm build && pnpm test && pnpm test:types && pnpm test:consumer && pnpm pack:check",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "pnpm build && changeset publish"
@@ -70,8 +77,10 @@
     "@types/node": "25.7.0",
     "dprint": "0.55.2",
     "effect": "4.0.0-beta.107",
+    "pagefind": "1.5.2",
     "tinybench": "2.9.0",
     "tstyche": "7.2.1",
+    "typedoc": "0.28.20",
     "typescript": "6.0.3",
     "vitest": "4.1.10",
     "xstate-v5": "npm:xstate@5.32.5",