Setting Up a Node.js Project with Express: Essential Best Practices

Introduction

Setting up a Node.js project with Express isn’t just about writing your first app.get() route. It’s about creating a maintainable, high-quality foundation. In this guide, we’ll walk through setting up a Node.js project with essential tools like Prettier, ESLint, Husky, and Commitlint. These tools will help ensure consistency, catch issues early, and improve your development workflow.

---

Project Setup

Node.js and Package Manager

For this guide, we’ll use Node.js 20.18.0 and PNPM 9.12.3 (or you can use npm or Yarn).

Start by creating a new Node.js project:

mkdir node-express-app
cd node-express-app
pnpm init -y

Install Express:

pnpm add express

Create a basic server file, index.js:

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

Run the server:

node index.js

---

Engine Locking

To ensure consistency in Node.js versions across environments, specify the supported version in package.json:

{
  "engines": {
    "node": ">=18.8.x"
  }
}

Add a .npmrc file:

engine-strict=true

This ensures that incompatible Node.js versions will cause an error during installation.

Commit your changes:

git commit -m 'build: added engine locking'

---

ESLint

Install ESLint to maintain code quality:

pnpm add -D eslint

Initialize ESLint:

pnpm exec eslint --init

Choose the following options during setup:

• How would you like to use ESLint? — “To check syntax, find problems, and enforce code style”
• What type of modules does your project use? — “CommonJS”
• Which framework does your project use? — “None of these”
• Does your project use TypeScript? — “No”
• Where does your code run? — “Node”
• What format do you want your config file to be in? — “JSON”

Update the .eslintrc.json file with stricter rules:

{
  "env": {
    "node": true,
    "es2021": true
  },
  "extends": "eslint:recommended",
  "rules": {
    "no-console": ["error", { "allow": ["warn", "error"] }]
  }
}

Commit your changes:

git commit -m 'build: added ESLint setup'

---

Prettier

Install Prettier for consistent code formatting:

pnpm add -D prettier

Create a .prettierrc file:

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2
}

Ignore unnecessary files using .prettierignore:

node_modules

Add Prettier scripts to package.json:

{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

Commit your changes:

git commit -m 'build: added Prettier setup'

---

Git Hooks with Husky

Install Husky for managing Git hooks:

pnpm add -D husky
pnpm exec husky install

Add a pre-commit hook:

pnpm exec husky add .husky/pre-commit "pnpm format && pnpm lint"

Commit your changes:

git commit -m 'build: added Husky pre-commit hook'

---

Commitlint

Install Commitlint to enforce commit message standards:

pnpm add -D @commitlint/{cli,config-conventional}

Create a commitlint.config.js file:

module.exports = {
  extends: ['@commitlint/config-conventional'],
};

Add a commit-msg hook:

pnpm exec husky add .husky/commit-msg "pnpm commitlint --edit $1"

Test the setup:

git commit -m "invalid message" # This will fail

Commit your changes:

git commit -m 'build: added Commitlint setup'

---

VS Code Setup

Install recommended extensions:

• Prettier
• ESLint

Add workspace settings to .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true
}

Commit your changes:

git commit -m 'build: added VS Code workspace settings'

---

Recap

Setting up a Node.js project with Express is more than just writing code. By implementing these tools and practices, you’ll create a maintainable, high-quality foundation for your application. With proper linting, formatting, and commit standards, your team will enjoy a smoother and more productive development workflow.

Happy coding! ✌️