Create a fully configured, publish-ready npm package named $ARGUMENTS.
If no package name was provided, ask the user for one before proceeding.
Phase 1: Discovery
Before scaffolding, ask the user these questions (present as a numbered list, accept answers in one shot):
- Package description — One-line summary of what this package does.
- Scope — Should it be scoped (e.g.,
@org/package)? If so, what org? - Runtime target — Node.js only, browser only, or universal?
- Entry point style — Single entry point or multiple subpath exports (e.g.,
pkg/utils,pkg/core)? - Test framework preference — Vitest (default) or Jest?
- CI provider — GitHub Actions (default), or other?
- License — MIT (default), Apache-2.0, ISC, or other?
- Minimum Node.js version — 18 (default) or 20+?
Use sensible defaults if the user says "defaults" or "just go with defaults."
Phase 2: Scaffold the Package
Create the following directory structure. Adapt based on Phase 1 answers.
<package-name>/
├── src/
│ └── index.ts # Main entry point
├── tests/
│ └── index.test.ts # Initial test file
├── .github/
│ └── workflows/
│ └── ci.yml # CI pipeline
├── .changeset/
│ └── config.json # Changeset config for versioning
├── package.json
├── tsconfig.json
├── tsconfig.build.json # Build-only tsconfig (excludes tests)
├── tsup.config.ts # Build config (dual ESM/CJS)
├── vitest.config.ts # Or jest.config.ts based on choice
├── eslint.config.mjs # Flat config ESLint
├── prettier.config.mjs # Prettier config
├── .gitignore
├── .npmignore # Or use "files" field in package.json
├── LICENSE
├── README.md
└── CHANGELOG.md
2.1 — package.json
Generate with these critical fields:
{
"name": "<package-name>",
"version": "0.0.0",
"description": "<from Phase 1>",
"type": "module",
"exports": {
".": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
}
}
},
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.mts",
"files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
"scripts": {
"build": "tsup",
"dev": "tsup --watch",
"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
"format:check": "prettier --check .",
"typecheck": "tsc --noEmit",
"prepublishOnly": "npm run build",
"prepack": "npm run build",
"changeset": "changeset",
"release": "changeset publish",
"version": "changeset version",
"check": "npm run typecheck && npm run lint && npm run test"
},
"engines": {
"node": ">=18"
},
"sideEffects": false,
"license": "MIT",
"keywords": [],
"repository": {
"type": "git",
"url": ""
},
"publishConfig": {
"access": "public"
}
}
Adapt based on Phase 1:
- If scoped → set name to
@org/packageand ensurepublishConfig.accessis"public"(or"restricted"if private) - If browser-only → omit
requireexports, add"browser"field - If multiple subpath exports → add each subpath to
"exports"map - If Node 20+ → update
enginesfield
2.2 — tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"lib": ["ES2022"],
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noUncheckedIndexedAccess": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"exactOptionalPropertyTypes": true,
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "tests"]
}
2.3 — tsconfig.build.json
{
"extends": "./tsconfig.json",
"exclude": ["node_modules", "dist", "tests", "**/*.test.ts", "**/*.spec.ts"]
}
2.4 — tsup.config.ts
import { defineConfig } from "tsup";
export default defineConfig({
entry: ["src/index.ts"],
format: ["esm", "cjs"],
dts: true,
splitting: false,
sourcemap: true,
clean: true,
treeshake: true,
outExtension({ format }) {
return {
js: format === "esm" ? ".mjs" : ".cjs",
};
},
});
Adapt: If multiple entry points from Phase 1, add them to entry array.
2.5 — vitest.config.ts (default) or jest.config.ts
Vitest:
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
globals: true,
coverage: {
provider: "v8",
reporter: ["text", "json", "html"],
thresholds: {
statements: 80,
branches: 80,
functions: 80,
lines: 80,
},
},
},
});
Jest (if chosen):
import type { Config } from "jest";
const config: Config = {
preset: "ts-jest/presets/default-esm",
testEnvironment: "node",
extensionsToTreatAsEsm: [".ts"],
coverageThreshold: {
global: {
statements: 80,
branches: 80,
functions: 80,
lines: 80,
},
},
};
export default config;
2.6 — eslint.config.mjs
import eslint from "@eslint/js";
import tseslint from "typescript-eslint";
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.strictTypeChecked,
...tseslint.configs.stylisticTypeChecked,
{
languageOptions: {
parserOptions: {
projectService: true,
tsconfigRootDir: import.meta.dirname,
},
},
rules: {
"@typescript-eslint/no-unused-vars": [
"error",
{ argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
],
},
},
{
ignores: ["dist/", "node_modules/", "coverage/", "*.config.*"],
}
);
2.7 — prettier.config.mjs
/** @type {import("prettier").Config} */
export default {
semi: true,
singleQuote: false,
tabWidth: 2,
trailingComma: "all",
printWidth: 100,
};
2.8 — CI Workflow (.github/workflows/ci.yml)
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
check:
name: Check
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [18, 20, 22]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm run typecheck
- run: npm run lint
- run: npm run test:coverage
- run: npm run build
publish-dry-run:
name: Publish Dry Run
runs-on: ubuntu-latest
needs: check
if: github.event_name == 'pull_request'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm run build
- run: npm pack --dry-run
Adapt: Adjust Node versions matrix based on Phase 1 minimum Node version.
2.9 — .changeset/config.json
{
"$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
2.10 — .gitignore
node_modules/
dist/
coverage/
*.tsbuildinfo
.DS_Store
*.local
.env
.env.*
2.11 — Starter Source (src/index.ts)
Write a minimal, meaningful starter based on the package description from Phase 1. Include:
- At least one exported function with proper TypeScript types
- JSDoc documentation on the export
- A well-defined return type (no implicit
any)
Example:
/**
* Greets the given name.
*
* @param name - The name to greet
* @returns A greeting string
*/
export function greet(name: string): string {
return `Hello, ${name}!`;
}
2.12 — Starter Test (tests/index.test.ts)
Write tests for the starter source. Include:
- At least one happy-path test
- At least one edge-case test
- Use
describe/itblocks
2.13 — README.md
Generate a README with these sections:
- Title & badges (npm version, CI status, license)
- Install (
npm install <name>) - Quick Start (minimal usage example)
- API (brief docs for exported functions/types)
- Development (how to build, test, lint)
- Contributing (link to issues, PR process)
- License
2.14 — LICENSE
Generate the full license text for the chosen license. Use the current year and ask the user for the copyright holder name (or default to the npm/git user).
2.15 — CHANGELOG.md
# Changelog
All notable changes to this project will be documented in this file.
See [Changesets](https://github.com/changesets/changesets) for commit guidelines.
Phase 3: Install Dependencies
Run npm install in the package directory to install all dependencies:
Production dependencies: none by default (keep it lean).
Dev dependencies:
typescript tsup @changesets/cli
eslint @eslint/js typescript-eslint
prettier
vitest @vitest/coverage-v8
If Jest was chosen instead:
typescript tsup @changesets/cli
eslint @eslint/js typescript-eslint
prettier
jest ts-jest @types/jest
Phase 4: Verify Everything Works
Run these commands sequentially and fix any issues before proceeding to the next:
npm run typecheck— must pass with zero errorsnpm run lint— must pass with zero errors (fix any auto-fixable issues)npm run test— must passnpm run build— must producedist/with.mjs,.cjs,.d.mts,.d.ctsfilesnpm pack --dry-run— verify the package contents look correct (no test files, no src/)
If any step fails, diagnose and fix before continuing. Do not skip verification.
Phase 5: Initialize Git
git initgit add .- Create an initial commit:
chore: initial package scaffold
Phase 6: Summary
Present a summary to the user:
Package "<name>" created successfully.
dist outputs: ESM (.mjs) + CJS (.cjs) + types (.d.mts, .d.cts)
test runner: vitest (or jest)
linter: eslint (strict TypeScript)
formatter: prettier
versioning: changesets
CI: GitHub Actions (Node 18/20/22)
license: MIT
Next steps:
1. cd <name>
2. Update package.json "repository" field
3. npm run dev — watch mode for development
4. npx changeset — create a changeset before publishing
5. npm publish — publish to npm (runs build automatically)