🌐 Devkit Node

📖 Presentation

A Node / Express / Mongoose / JWT stack that can be run as a standalone backend or in a fullstack setup with another repo (ex: Vue, Swift).

Designed to be cloned into downstream projects and kept up-to-date via git merge from the stack repo.

📦 Technology Overview

Subject	Informations
Architecture	Layered Architecture : everything is separated in layers, and the upper layers are abstractions of the lower ones, that's why every layer should only reference the immediate lower layer (vertical modules architecture with Repository and Services Pattern)
Server	Node >= 22 - Express - Helmet - CORS nodemon
Database	MongoDB - Mongoose - GridFS upload Sequelize - PostgreSQL, MySQL, SQLite (option) JOI - Models & Repository validation
Security	passport-jwt - JWT Stateless bcrypt - zxcvbn - Passwords SSL - Express / Reverse Proxy
API	jsend - Default response wrapper: status, message, data or error
Upload	Mongo GridFS - Multer - Sharp - Image stream, all content types
Testing	Jest - SuperTest - Coverage & Watch
CI	GitHub Actions
Linter	ESLint ecmaVersion latest
Developer	Dependabot - Snyk semantic-release - commitlint - commitizen
Dependencies	npm
Deliver	Docker & Docker-compose

🎉 Features Overview

Core

• User : classic register / auth or oAuth (Google, Apple) - profile management (update, avatar upload)
• User data privacy : delete all - get all - send all by mail
• Admin : list users - get user - edit user - delete user

Examples

• Tasks : list - get - add - edit - delete
• File Uploads : get stream - add - delete - image stream & sharp operations

📌 Prerequisites

• Git - Download & Install Git
• Node.js (22.x or 24.x) - Download & Install Node.js
  • Recommended: Use nvm for Node version management
• MongoDB - Download & Install MongoDB

💥 Installation

git clone https://github.com/pierreb-devkit/Node.git && cd Node
npm install

🏃 Running Your Application

Development

npm start   # or: npm run dev

Runs the server at http://localhost:3000/. For auto-reload during development, use npm run debug (nodemon).

CORS Note: When connecting to the Vue stack, ensure CORS is configured:

DEVKIT_NODE_cors_origin=['http://localhost:8080'] npm start

Production

npm run prod

Testing

npm test                  # Run all tests (one-shot)
npm run test:unit         # Run unit tests once (alias of npm test)
npm run test:watch        # Run tests in watch mode
npm run test:coverage     # Generate coverage report

Tests are organized per module in modules/*/tests/

Code Quality

npm run lint              # Check code quality (read-only)
npm run lint:fix          # Auto-fix code quality issues
npm run format            # Format code with Prettier

Database Seeding

npm run seed:dev          # Seed development database
npm run seed:prod         # Seed production database
npm run seed:user         # Seed default user/admin only (no drop)
npm run seed:mongodrop    # Drop database (with confirmation)

Commits & Releases

npm run commit                                    # Commit with commitizen
GITHUB_TOKEN=xxx npm run release:auto             # Semantic release (CI)

🔧 Configuration

Configuration files live in config/defaults/. The development.js file is the base; other files in that folder override it.

Environment variables prefixed with DEVKIT_NODE_ are merged on top. The variable path maps directly to the config object key:

DEVKIT_NODE_app_title='my app'               # sets config.app.title
DEVKIT_NODE_db_uri='mongodb://...'           # sets config.db.uri

🐳 Docker

docker run --env DEVKIT_NODE_db_uri=mongodb://host.docker.internal/NodeDev --env DEVKIT_NODE_host=0.0.0.0 --rm -p 3000:3000 pierreb/node

Build yourself:

docker build -t pierreb/node .

With Vue stack as frontend:

docker-compose up

🤖 AI Setup

This stack ships preconfigured instruction and prompt files for Claude Code, GitHub Copilot, and OpenAI Codex. Each tool requires its own client installation and authentication — the repository provides the configuration so it works out-of-the-box once the tool is set up.

Tool	Config
Claude Code	.claude/ — skills embedded, works on clone
GitHub Copilot	.github/copilot-instructions.md + .github/prompts/
OpenAI Codex	AGENTS.md

Claude Code — Available Skills

Skill	Description
/verify	Run quality loop (lint + tests)
/create-module	Create new module by duplicating the tasks template
/feature	Implement feature following layered architecture rules
/update-stack	Merge stack updates into downstream projects
/naming	Check or apply file and folder naming conventions

Layered Architecture Rules

• Layer order is strict: Routes → Controllers → Services → Repositories → Models
• Controllers must not call repositories directly — always go through services
• Each module is self-contained in modules/{name}/
• Shared code goes in lib/helpers/ or lib/services/ with explicit justification
• Tests are organized per module: modules/*/tests/

Stack Merge Workflow

git remote add devkit-node https://github.com/pierreb-devkit/Node.git
git fetch devkit-node
git merge devkit-node/master

✏️ Contribute

Open issues and pull requests on GitHub.

📜 History

This work is based on MEAN.js and more precisely on a fork named Riess.js. The goal is a simple, easy-to-use toolbox to start and maintain fullstack projects across multiple languages (Vue, Node, Swift ...).

📋 Licence

🔗 Links