starter-backendkit

Scaffold a production-ready Node.js backend in seconds.

Usage

npx starter-backendkit my-app

or install globally:

npm i -g starter-backendkit
backendkit my-app

Pick a tech stack, and you get a ready-to-run project.

Stacks

Pick from four starter options:

• Node.js + Express + MongoDB + React — Fullstack monorepo combining Express + MongoDB API with a Vite + React SPA styled with custom Vanilla CSS.
• Node.js + Express + MongoDB — Backend only: REST API with Mongoose, JWT auth, Zod validation, and error middleware.
• Node.js + Express + PostgreSQL + React — Fullstack monorepo combining Express + PostgreSQL API (raw SQL) with a Vite + React SPA styled with custom Vanilla CSS.
• Node.js + Express + PostgreSQL — Backend only: REST API with raw pg client queries, JWT auth, Zod validation, and database init scripts.

What's inside the templates

Fullstack Stacks (+React)

my-app/
├── backend/            # Express REST API
├── frontend/           # Vite + React SPA (AuthContext, page router, Lucide icons, custom CSS)
├── package.json        # Root package coordinating installation and concurrent execution
└── README.md

Backend-Only Stacks

src/
├── app.js          # Express app entry
├── middleware/     # Auth, validation, and error handlers
├── utils/          # JWT tokens, connection layers
└── modules/        # Module folders containing auth, users, and posts routes/logic

After scaffolding

Backend-Only Stacks:

cd my-app
cp .env.example .env   # fill in your database & jwt secrets
npm install
npm run db:init        # PostgreSQL stack only — creates tables
npm run dev

Fullstack Stacks:

cd my-app
npm install            # installs root dependencies, frontend, and backend packages
cp backend/.env.example backend/.env # fill in secrets
npm run db:init --prefix backend     # PostgreSQL stack only — creates tables
npm run dev            # launches both client and server concurrently

🛠️ Developer Guide (Contributing)

If you are developing this CLI tool or want to add/edit the tech stack templates, here is what you need to know:

1. Project Folder Structure

• bin/cli.js: The CLI script entry point. It uses @clack/prompts to guide the user, resolves output paths, copies the selected template, and updates the generated project's package.json.
• templates/: Contains the project boilerplates:
  • node-mongo/: Express + MongoDB boilerplate template.
  • node-postgres/: Express + PostgreSQL boilerplate template.

2. Important: .gitignore Renaming Caveat

NPM automatically ignores and removes any files named .gitignore during the publishing process.

• Rule: Always rename .gitignore to gitignore (no leading dot) inside your template folders under templates/.
• The CLI script (bin/cli.js) automatically renames it back to .gitignore when scaffolding the user's project.

3. Local Development & Testing

To test your changes locally:

1. Navigate to the starter-backendkit folder.
2. Link the package globally on your system:

   npm link

3. Now, you can test the CLI command anywhere on your machine:

   backendkit my-test-app

4. Once you are done testing, unlink the package:

   npm unlink -g starter-backendkit

4. Adding a New Tech Stack Template

1. Place your new boilerplate template in the templates/ folder (e.g. templates/node-mysql). Ensure any .gitignore file inside is named gitignore.
2. Open bin/cli.js and add your new stack to the STACKS array:

   const STACKS = [
     { value: 'node-mongo', label: 'Node.js + Express + MongoDB' },
     { value: 'node-postgres', label: 'Node.js + Express + PostgreSQL (raw SQL)' },
     { value: 'node-mysql', label: 'Node.js + Express + MySQL' }, // Example
   ];

3. Add the next steps/commands for your new stack in the NEXT_STEPS object in bin/cli.js so they print properly at the end.

5. Publishing Changes to NPM

1. Make sure your local tests pass.
2. Increment the version number in package.json (e.g., from 1.2.1 to 1.2.2 or 1.3.0).
3. Publish the package:

   npm login
   npm publish

License

MIT