pauls-project-setup

name	pauls-project-setup
description	Paul's modern stack conventions for new projects (pnpm, native node test, esbuild, buildless-types). Consult when starting a new project or repository.

Paul's Project Setup

When setting up a new project or initializing a repository, use this modern stack and these specific configuration conventions.

Core Stack Strategy

We use this specific stack to maximize execution speed, minimize configuration overhead, and avoid slow build steps during development.

• Package Manager: pnpm (for strict dependency resolution and speed)
• Type Checking: buildless-types standard (JSDoc or Erasable Syntax with tsc --noEmit to get type safety without the overhead of a build step)
• Testing: Node.js native test runner (node --test)`. We avoid Jest entirely because it is notoriously slow and requires complex transpilation pipelines.
• Bundler / Dev Server: esbuild (for fast Node.js tooling compilation).
• Linting: oxlint (for ultra-fast linting without ESLint overhead).
• Isomorphic Core: Keep core orchestration, logic, and math in a browser-agnostic library testable directly in Node.js. The Web UI should be a thin presentation layer. This allows coding agents to iterate and test logic instantly via CLI/Node unit tests without browser automation overhead (which is ~20x slower).

Configuration Standards

Apply these baseline settings to enable the preferred workflow.

1. package.json Scripts & Settings

Ensure the project is an ES Module and defines standard scripts inspired by Paul's existing projects:

{
  "type": "module",
  "engines": {
    "node": ">=24.11.0"
  },
  "scripts": {
    "test": "pnpm run typecheck && pnpm run test:node",
    "test:node": "node --test test/**/*.test.js",
    "typecheck": "tsc --noEmit",
    "lint": "oxlint",
    "preflight": "pnpm typecheck && pnpm lint && pnpm test"
  }
}

2. Type Safety (buildless-types)

• Use modern Node.js features to run .ts files directly using erasable syntax, or use complete JSDoc annotations in .js files.
• The tsconfig.json should align with the buildless-types skill constraints (e.g., erasableSyntaxOnly: true, verbatimModuleSyntax: true, allowImportingTsExtensions: true).
• Execute files directly with node script.ts. Do not use tools like npx tsx or ts-node.

3. Testing

• Prefer the built-in Node.js test runner (node --test) for unit and integration testing. It requires zero configuration and runs extremely fast.
• If a richer ecosystem or browser-like testing environment is required, use vitest.
• Avoid jest completely due to its performance overhead and configuration complexity.

4. Bundling

• Use esbuild for fast Node.js CLI tooling compilation or generic JS bundling.

5. Linting

• Use oxlint for ultra-fast linting. Configure it with a .oxlintrc.json file in the root of the project using the following template:

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "env": {
    "node": true,
    "browser": true,
    "es2021": true
  },
  "rules": {
    "no-unused-vars": [
      "error",
      {
        "argsIgnorePattern": "^_",
        "varsIgnorePattern": "^_",
        "caughtErrorsIgnorePattern": "^.*$"
      }
    ],
    "no-explicit-any": "error",
    "typescript/no-restricted-types": [
      "error",
      {
        "types": {
          "unknown": "Restrict weak/imprecise unknown type usages."
        }
      }
    ]
  }
}