create-node-starter-kit
v0.1.2
Published
Scaffold highly customizable Node.js applications and packages by composing compatible features: project type, language, module system, framework, testing, linting, databases and more.
Maintainers
Readme
create-node-starter-kit
Scaffold highly customizable Node.js applications and packages by composing compatible features: project type, language, module system, framework, testing, linting, databases and more.
Unlike opinionated generators, create-node-starter-kit lets you pick each
dimension of your project independently — and validates that the combination
is coherent before a single file is written.
Quick start
# Interactive: prompts for every unspecified option
npx create-node-starter-kit my-app
# Equivalent shorthand via npm init (resolves to create-node-starter-kit)
npm init node-starter-kit my-app
# Non-interactive: accept defaults for everything not passed explicitly
npx create-node-starter-kit my-api --type api --framework express --testing vitest --yes
# Start from a preset, then override individual choices
npx create-node-starter-kit my-api --preset production-api --database prismaRequires Node.js >= 22.13.0.
Presets
Presets are plain starting points — every value they set can be overridden by an explicit flag, a config file, or an interactive prompt.
| Preset | Description |
| ---------------- | ------------------------------------------------------------------ |
| minimal | JavaScript, ESM, flat structure. Just Node.js — nothing else. |
| typescript-api | Express REST API with Vitest, ESLint and Prettier. |
| production-api | Feature-based Express API with env validation, Zod, Docker and CI. |
| cli-package | TypeScript command-line application with Vitest and ESLint. |
What you can compose
| Dimension | Choices | Default |
| --------------- | ---------------------------------------- | ------------ |
| Project type | minimal api cli library worker | minimal |
| Language | javascript typescript | typescript |
| Module system | esm commonjs | esm |
| HTTP framework | none express fastify hono | none |
| Structure | flat src feature-based | src |
| Testing | none node vitest | none |
| Linting | none eslint | none |
| Formatting | none prettier | none |
| Database | none mongoose prisma | none |
| Package manager | npm pnpm yarn | npm |
none as the HTTP framework is a real implementation for REST APIs: a
dependency-free node:http server with a /health endpoint, structured
app / server / health.routes modules, and graceful shutdown — no
framework dependency installed. Express, Fastify and Hono generate the same
structure on top of the respective library.
Optional integrations (each independently togglable with --flag / --no-flag):
--env— environment-variable support (.env.example+ loader)--zod— Zod validation with an example schema--docker— Dockerfile and.dockerignore--editorconfig—.editorconfig--husky— Husky git hooks infrastructure--lint-staged— lint-staged with a pre-commit hook--commitlint— commitlint with a commit-msg hook--path-aliases— runtime-resolved#src/*path alias--github-actions— GitHub Actions CI workflow
Option precedence
Values are resolved in a strict precedence chain; only options that no layer specified are prompted for interactively:
CLI flags > config file > preset > built-in defaults > promptsPass -y / --yes to accept defaults without prompting.
Safety
- Existing files are never silently overwritten. If the destination contains files, generation fails by default.
--conflict-mode skipskips existing files and generates only the missing ones;--conflict-mode fail(default) aborts instead.--dry-runprints the full generation plan — every file that would be written — without touching the filesystem.- Project names are validated against npm package-name rules before anything is created.
Configuration files
Store your team's standard stack in a JSON file and pass it with
--config <path>:
{
"version": 1,
"defaults": {
"type": "api",
"language": "typescript",
"moduleSystem": "esm",
"framework": "fastify",
"structure": "src",
"testing": "vitest",
"linting": "eslint",
"formatting": "prettier",
"features": { "env": true, "docker": true }
}
}See docs/CONFIGURATION.md for the full reference and examples/ for ready-made config files.
Programmatic API
The generator can be embedded without the CLI:
import { generateProject, PRESETS } from 'create-node-starter-kit';
const { plan, generation } = await generateProject(
{ name: 'my-service', type: 'api', framework: 'hono', testing: 'vitest' },
{ cwd: '/workspaces', conflictMode: 'fail' },
);
console.log(`wrote ${generation?.written.length ?? 0} files`);generateProject validates the name and Node version, resolves features,
builds a plan and writes the files. Extend the feature registry with
extraFeatures, or build custom pipelines from the exported
createRegistry, FeatureRegistry and resolveFeatures primitives.
Generation is silent by default; pass verbose: true for progress output.
Development
npm install # install dependencies
npm run build # compile src/ to dist/
npm run typecheck # strict typecheck of the whole project
npm run lint # eslint
npm test # unit + integration tests (vitest)
npm run test:e2e # end-to-end tests against the built CLILicense
MIT
