ExpressCraft is a command-line tool that allows you to quickly generate an Express application scaffold, getting you up and running with a basic Express server structure in no time.

Installation

ExpressCraft needs Node.js >= 16. Install it globally with your package manager of choice:

npm install -g expresscraft
# or
yarn global add expresscraft
# or
pnpm add -g expresscraft

Or run it without installing:

npx expresscraft

Usage

Run the tool and answer the prompts:

npx expresscraft

You'll be asked for project metadata (name, description, author) and can either pick a preset or fully customize every choice. ExpressCraft then:

1. Collects all your answers.
2. Builds a single package.json from them.
3. Generates a structured project (see Generated Project Structure).
4. Runs one dependency install at the end (npm / yarn / pnpm).

Non-interactive mode

Pass flags to skip the prompts — handy for scripting and CI:

expresscraft my-api --preset api --yes
expresscraft --name blog --preset mvc --pm pnpm --yes

CLI options

| Flag | Description | | ---- | ----------- | | -n, --name <name> | Project name | | -p, --preset <name> | Preset: minimal | api | mvc | fullstack | | --pm <manager> | Package manager: npm | yarn | pnpm | | --ts / --js | Language (TypeScript / JavaScript) | | -y, --yes | Non-interactive (use preset/flag defaults) | | -f, --force | Overwrite an existing folder without asking | | --docker | Add Dockerfile + docker-compose | | --ci | Add a GitHub Actions workflow | | --hooks | Add Husky + lint-staged pre-commit | | --logger | Add a pino HTTP logger | | --ai <list> | Generate AI assistant configs (skills + agents): claude | copilot | cursor | agents (comma-separated) | | --ai-skills <list> | Limit AI skills to specific ids (default: all for your stack), e.g. express,prisma,jwt | | --fetch-skills | Download official skills (where they exist) via npx skills add | | -h, --help | Show help |

Add to an existing project

Already have an Express app? Run expresscraft add inside it to layer on features without touching your source files:

cd my-existing-app
expresscraft add                                   # interactive picker
expresscraft add --db postgresql --orm prisma --yes
expresscraft add --auth jwt --testing jest --dry-run

It detects your package manager (from the lockfile) and language (TypeScript/JavaScript), then:

• Merges new dependencies and scripts into your package.json (your existing versions/scripts win; a package.json.bak backup is written).
• Writes only new files — existing files are skipped with a warning (--force to overwrite).
• Appends any missing keys to .env / .env.example.
• Writes EXPRESSCRAFT_SETUP.md with the exact imports/middleware/bootstrap lines to paste into your app (ExpressCraft never edits your source).
• Optionally generates AI assistant skills + agents for the features you add (--ai, see AI assistant skills & agents).
• Runs a single install at the end.

Use --dry-run to preview every change without writing anything.

Auto-wiring (--inject): instead of only printing instructions, ExpressCraft can insert the safe parts directly into your entry file (the one with const app = express()):

expresscraft add --auth passport --inject --yes

• Inserts new imports after your last import/require and middleware (app.use/app.set) after your last existing one — matching your actual app variable name.
• Backs the file up to <file>.bak, skips lines already present (idempotent), and falls back to the guide if it can't confidently locate the app.
• Bootstrap lines (e.g. await connectDB()) are never injected — they need an async context — so they stay in EXPRESSCRAFT_SETUP.md for you to place.

Presets

| Preset | Language | PM | Stack | | ------ | -------- | -- | ----- | | minimal | JavaScript | npm | Express base only | | api | TypeScript | npm | PostgreSQL + Prisma, Jest, JWT, ESLint, Swagger | | mvc | JavaScript | npm | EJS + Bootstrap + Sass, MongoDB + Mongoose, Jest, Passport, ESLint | | fullstack | TypeScript | pnpm | EJS + Tailwind + Sass, PostgreSQL + Prisma, Jest, JWT, ESLint, Swagger |

api adds CI + Husky + logger; fullstack adds Docker + CI + Husky + logger on top.

Features

• Presets or full customization of every choice
• Interactive prompts or non-interactive flags (CI-friendly)
• Builds one package.json from your choices — with keywords/tags, license, and engines derived from your stack — then a single install at the end
• Pinned dependency versions for reproducible installs
• Generates a comprehensive project README (tech stack, prerequisites, env vars, run/build commands, scripts, structure, setup notes)
• Generates a real project structure (routes, middleware, config, .env)
• Working database/auth boilerplate, not just installed packages
• Baseline middleware out of the box: helmet, cors, morgan, JSON parsing, error handler, /health route
• Optional extras: Docker, GitHub Actions CI, Husky + lint-staged, pino logger
• AI assistant configs: per-tool skills + agents for Claude, Copilot, Cursor, or AGENTS.md — with optional download of official skills from officialskills.sh
• Overwrite protection + rollback if generation fails
• Update notifier — tells you when a newer ExpressCraft is available

Modules and Frameworks

ExpressCraft supports the following modules and frameworks:

Package Manager

| Package Manager | Description | | --------------- | ----------- | || NPM is the default package manager for the JavaScript runtime environment Node.js.| || Yarn is a package manager for your code. It allows you to use and share code with other developers from around the world.| || pnpm is a fast, disk-space-efficient package manager that uses a content-addressable store.|

Language

| Language | Description | | -------- | ----------- | || JavaScript is a programming language that conforms to the ECMAScript specification.| || TypeScript is a superset of JavaScript that compiles to plain JavaScript.|

Version Control

| Version Control | Description | | --------------- | ----------- | || Git is a distributed version control system for tracking changes in source code during software development.| || Apache Subversion is a software versioning and revision control system distributed as open source under the Apache License.|

Template Engine

| Template Engine | Description | | --------------- | ----------- | || EJS is a simple templating language that lets you generate HTML markup with plain JavaScript.| || Pug is a high-performance template engine heavily influenced by Haml and implemented with JavaScript for Node.js and browsers.| || Twig is a modern template engine for PHP.| || Handlebars provides the power necessary to let you build semantic templates effectively with no frustration.|

CSS Framework

| CSS Framework | Description | | ------------- | ----------- | || Tailwind CSS is a utility-first CSS framework for rapidly building custom designs.| || Bootstrap is an open-source front-end framework for developing websites and web applications.| || Bulma is a free, open-source CSS framework based on Flexbox and used by more than 200,000 developers.| || Foundation is a family of responsive front-end frameworks that make it easy to design beautiful responsive websites, apps, and emails.| || Materialize is a modern responsive front-end framework based on Material Design.| || Semantic UI (Fomantic UI fork) helps create beautiful, responsive layouts using human-friendly HTML.|

Tailwind uses the v4 CSS-first workflow (@import "tailwindcss"; + @tailwindcss/cli).

CSS Preprocessor

| CSS Preprocessor | Description | | ---------------- | ----------- | || Sass (Dart Sass). ExpressCraft ships a compiler script (lib/sass_compiler.js) that builds styles/**/*.scss into public/css.| || Less is a backwards-compatible language extension for CSS.| || Stylus is an expressive, dynamic, robust CSS preprocessor.| || PostCSS is a tool for transforming CSS with JavaScript plugins.|

Database

| Database | Description | | -------- | ----------- | || MySQL is an open-source relational database management system.| || PostgreSQL is a powerful, open-source object-relational database system.| || SQLite is a C-language library that implements a small, fast, self-contained, high-reliability, full-featured, SQL database engine.| || MongoDB is a general-purpose, document-based, distributed database built for modern application developers and for the cloud era.|

ORM

| ORM | Description | | --- | ----------- | || Prisma is an open-source database toolkit. It replaces traditional ORMs and makes database access easy with an auto-generated query builder for TypeScript & Node.js.| || Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite, and Microsoft SQL Server.| || TypeORM is an ORM that can run in NodeJS, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, and Electron platforms and can be used with TypeScript and JavaScript.| || Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment.| || Drizzle is a lightweight, type-safe TypeScript ORM with a SQL-like query API for Node.js.|

Testing

| Testing | Description | | ------- | ----------- | || Jest is a delightful JavaScript Testing Framework with a focus on simplicity.| | | Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser, making asynchronous testing simple and fun.| || Jasmine is a behavior-driven development framework for testing JavaScript code.|

Authentication

| Authentication | Description | | -------------- | ----------- | || Passport is authentication middleware for Node.js. Extremely flexible and modular, Passport can be unobtrusively dropped into any Express-based web application.| || JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties.|

Linting

| Linting | Description | | ------- | ----------- | || ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code.| || TSLint is deprecated — selecting it now generates an ESLint setup instead.|

API Documentation

| API Documentation | Description | | ----------------- | ----------- | || Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, and consume REST APIs.| || Postman is a collaboration platform for API development.|

Extras

Optional add-ons (interactive checkbox, --docker/--ci/--hooks/--logger flags, or via a preset):

| Extra | What you get | | ----- | ------------ | || Dockerfile, .dockerignore, and a docker-compose.yml (with a matching DB service when a database is selected).| || A ci.yml workflow that installs deps and runs your lint/test/build scripts (only the ones that exist).| || A pre-commit hook running lint-staged (Prettier), installed automatically via the prepare script.| || pino + pino-http structured request logging wired into the app, with pino-pretty for dev.|

AI assistant skills & agents

ExpressCraft can generate skills (reusable task recipes) and agents (reviewer personas) for your AI coding tools, scoped to the exact stack you picked. Choose Prisma → get a Prisma skill + agent; choose Jest → a Jest skill + agent; and so on for every tool.

Pick the target services interactively, or pass --ai:

expresscraft my-api --preset api --ai claude,copilot --yes
expresscraft my-api --preset fullstack --ai claude,cursor,agents --ai-skills express,prisma,jwt --yes
expresscraft add --db mongodb --ai claude --fetch-skills --yes

Each chosen service gets the same skills rendered in its own format:

| Service (--ai value) | Files generated | | ---------------------- | --------------- | | claude | CLAUDE.md, .claude/skills/<tool>/SKILL.md, .claude/agents/<tool>-agent.md | | copilot | .github/copilot-instructions.md, .github/prompts/<tool>.prompt.md, .github/chatmodes/<tool>.chatmode.md | | cursor | .cursor/rules/<tool>.mdc, .cursor/rules/<tool>-agent.mdc | | agents | a single aggregated AGENTS.md |

Skills are derived from your selected tools (--ai-skills narrows the set). Covered tools include Express, TypeScript, every template engine / CSS framework / preprocessor, all databases & ORMs, test frameworks, Passport/JWT, ESLint, Swagger/Postman, and the extras (Docker, CI, Husky, pino). Agents are generated for the high-value ones (Express, Prisma, JWT, Passport, Jest, Docker).

Official vs. starter skills

The generated skill files are ExpressCraft-authored starters — they are not downloaded from a registry. Where an official, community-maintained skill exists on officialskills.sh (e.g. PostgreSQL → Supabase, MongoDB → MongoDB), ExpressCraft:

• annotates the generated file with the official source URL and its npx skills add … command,
• lists every source in a generated AI_SKILLS.md at the project root, and
• can download the official versions for you (runs npx skills add <repo> --skill <name>).

When your selected tools include one with an official skill, ExpressCraft asks whether to download them during the interactive run. In non-interactive mode, pass --fetch-skills to opt in. Either way, if you decline nothing is downloaded — you just get the starters plus the commands (in AI_SKILLS.md) to fetch the official ones whenever you want.

Getting Started

Run ExpressCraft and answer the prompts (or pass flags):

npx expresscraft

Example session:

  _____                               ____            __ _
 | ____|_  ___ __  _ __ ___  ___ ___ / ___|_ __ __ _ / _| |_
 |  _| \ \/ / '_ \| '__/ _ \/ __/ __| |   | '__/ _` | |_| __|
 | |___ >  <| |_) | | |  __/\__ \__ \ |___| | | (_| |  _| |_
 |_____/_/\_\ .__/|_|  \___||___/___/\____|_|  \__,_|_|  \__|
            |_|

✨ ExpressCraft v1.4.0 — Express.js generator ✨

? What is your project name? ecommerce
? Project description? (optional) Ecommerce API
? Project author? (optional) Ravi Kishan
? Start from a preset, or customize? Preset: api

📋 Project summary:
-----------------------------------
  Name               ecommerce
  Language           typescript
  Package manager    npm
  Version control    git
  Template engine    no template engine
  CSS framework      no css framework
  CSS preprocessor   no css preprocessor
  Database           postgresql
  ORM                prisma
  Testing            jest
  Authentication     jwt
  Linting            eslint
  API docs           swagger
-----------------------------------
? Create the project with these settings? Yes

✅ Generating project...
✅ Folder created.
✅ Express base registered.
✅ Prisma registered.
✅ Jest registered.
✅ JWT registered.
✅ ESLint registered.
✅ Swagger registered.
✅ Project scaffold generated.
✅ README registered.
✅ package.json created from your choices.
✅ Git initialized successfully.
✔ Dependencies installed.

🚀 Your project is ready!

📝 Next steps / notes:
  • Initialize Prisma: npx prisma init --datasource-provider=postgresql, then npx prisma migrate dev.
  • Protect routes with the auth middleware in src/middleware/auth (import authenticate).
  • Mount Swagger UI: app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec)).

Then start the server:

cd ecommerce
npm run dev   # yarn dev / pnpm dev

Visit http://localhost:3000/health — it responds {"status":"ok", ...}.

Generated Project Structure

Every project is scaffolded with a sensible structure (extensions are .ts for TypeScript):

my-app/
├── src/
│   ├── index.js          # server bootstrap: dotenv, db connect, app.listen
│   ├── app.js            # express app: helmet, cors, morgan, json, routes, error handler
│   ├── routes/
│   │   └── index.js      # GET / and GET /health
│   ├── controllers/
│   │   └── home.js       # index + health handlers
│   ├── middleware/
│   │   └── errorHandler.js
│   └── config/           # db.js / prisma.js / passport.js (when applicable)
├── .env                  # PORT and any selected secrets
├── .env.example
├── package.json          # built from your choices, pinned versions
├── .gitignore            # when Git is selected
├── README.md             # project-specific
├── CLAUDE.md             # always: project guide for Claude Code (skills listed when --ai claude)
│
│   # when --ai is used (depending on chosen services):
├── .claude/              # claude: skills/ + agents/
├── .github/              # copilot: copilot-instructions.md, prompts/, chatmodes/
├── .cursor/rules/        # cursor: per-tool .mdc rules
├── AGENTS.md             # agents: aggregated skills + agents
└── AI_SKILLS.md          # skill sources + how to fetch official versions

Selected features wire themselves into the right place — e.g. Mongoose adds connectDB() to the bootstrap, a template engine adds app.set("view engine", …), and JWT adds an auth middleware.

Development (contributing to ExpressCraft)

git clone https://github.com/ravikisha/expresscraft
cd expresscraft
npm install

npm test          # vitest
npm run lint      # eslint
npm run format    # prettier --write

Author

This project is created and maintained by Ravi Kishan.

Changelog

Check out the CHANGELOG for the latest updates and changes to the project.

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.