# Pauls Project Setup

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

- Skill: `paulirish/pauls-project-setup` (Agent Skill)
- Install (CLI): `npx skillmds add paulirish/pauls-project-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulirish/pauls-project-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: paulirish (https://skillmd.com/u/paulirish)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/paulirish/pauls-project-setup

---


# 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:

```json
{
  "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:

```json
{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "env": {
    "node": true,
    "browser": true,
    "builtin": 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."
        }
      }
    ]
  }
}
```