Skip to content

AGENTS.md

Latest commit

 

History

History
173 lines (118 loc) · 4.61 KB

AGENTS.md

File metadata and controls

173 lines (118 loc) · 4.61 KB

Agent Guidelines for Workers Node.js Compat Matrix

This document provides guidelines for AI coding agents working in this repository.

Project Overview

This project audits Node.js API compatibility across different runtimes (Node.js, Bun, Deno, Cloudflare Workers/workerd). It generates JSON dumps of runtime APIs and displays compatibility in a React-based report at https://workers-nodejs-compat-matrix.pages.dev

Build & Development Commands

Prerequisites

  • Node.js v22 (required for generation scripts)
  • fnm (for Node version management) - set FNM_DIR env var to fnm binary location
  • Deno and Bun installed
  • pnpm 10.0.0

Main Commands

# Install dependencies
pnpm install

# Generate full compatibility report (requires Node 18, 20, 22 via fnm)
pnpm run generate

# Scan APIs for specific runtimes only
node ./scan-apis.mjs --only workerd
node ./scan-apis.mjs --only bun,deno

# Generate table data for UI (after scanning)
pnpm run generate:table

# Generate historical trend data (scans multiple workerd versions)
pnpm run generate:historical

# Serve React report locally
pnpm run report:dev

# Build report for production
pnpm run --filter report build

# Deploy to Cloudflare Pages
pnpm run report:deploy

Working with Individual Runtimes

# Workerd (with compatibility date)
node workerd/dump.mjs 2025-01-01

# Bun
bun run bun/dump.js

# Deno
deno run --allow-all deno/dump.js

# Node.js (requires fnm)
fnm exec --using=22 node node/dump.mjs --compare-to-baseline

Project Structure

  • /data/ - Generated JSON dumps (baseline.json, workerd.json, bun.json, deno.json, node-*.json)
  • /node/, /bun/, /deno/, /workerd/ - Runtime-specific dump scripts
  • /report/ - React app for visualizing compatibility
  • /report/src/data/ - Data files consumed by React app (table-data.json, historical-support.json)
  • dump-utils.mjs - Shared utilities for traversing and comparing APIs
  • generate-*.mjs - Scripts for generating various data files
  • scan-apis.mjs - Orchestrates scanning across all runtimes

Code Style Guidelines

Formatting

  • Use Prettier with project config (.prettierrc)
  • Semicolons: required
  • Quotes: double quotes
  • Print width: 80
  • Trailing commas: ES5 style

Imports

Node built-ins first (with node: protocol), then third-party, then local:

import fs from "node:fs/promises";
import path from "node:path";

import shell from "shelljs";

import { visit } from "../dump-utils.mjs";

TypeScript (React App)

  • Strict mode enabled
  • Use type for simple types, interfaces for React props
  • Use Zod for runtime validation
  • JSON imports: import data from "./file.json" with { type: "json" };

Naming Conventions

  • Variables/functions: camelCase
  • Constants: SCREAMING_SNAKE_CASE
  • React components: PascalCase
  • Files: kebab-case for scripts, PascalCase for React components

Error Handling

  • Use try/catch for expected errors
  • Use shell.set("-e") in shell scripts for fail-fast
  • Check for required tools at script start

Data Flow

  1. Baseline generation: Merges Node 18/20/22 APIs into baseline.json
  2. API scanning: Dumps APIs from each runtime, comparing to baseline
  3. Table generation: Creates table-data.json from JSON dumps
  4. Historical tracking: generate-historical-data.mjs tracks workerd support over time
  5. React app: Renders interactive table and trend chart

Key Constants

  • Support states: supported, unsupported, mismatch (no stubs counted)
  • Display icons: ✅ (matching), ❌ (missing), 🩹 (mismatch)
  • Target runtimes: Order in generate-table-data.mjs MUST match App.tsx

Important Notes

  • No unenv/stubs: Stubs are treated as missing/unsupported, not counted toward support
  • Workerd data only: The Cloudflare Workers column uses raw workerd data
  • Historical data: Uses workerd directly with different compatibility dates
  • API dumps are committed to git (not gitignored)
  • Node v22 features required for generation scripts

Common Tasks

Regenerate all data (if you have fnm with Node 18/20/22)

pnpm run generate

Update only workerd data

node ./scan-apis.mjs --only workerd
pnpm run generate:table

Update historical chart

pnpm run generate:historical

Modifying ignored modules

Edit report/src/ignored-modules.js, then:

pnpm run generate:baseline && pnpm run generate:table

CI/CD

GitHub Actions (.github/workflows/deploy-report.yml):

  • Triggers: push to main, daily at 1:15am, manual dispatch
  • Builds and deploys report to Cloudflare Pages
  • Does NOT regenerate API dumps (uses committed data)