pfraces / node-template

Template for Node.js projects

Node Template

Template for Node.js projects, tailored for library authors.

Usage

Create a new node-template-based project using degit.

npx degit pfraces/node-template/root project-name
cd project-name
git init
npm install

Replace project-name with the name of your project.

Keep in mind: Run git init before npm install so husky can install its git hooks.

Post-install

• Change project name and description in README.md and package.json
• Change project name in package-lock.json

What's included

Editor settings

• EditorConfig
• Visual Studio Code

Version control

• Git
• husky
• lint-staged

Linters and formatters

• Prettier
• ESLint
• markdownlint

Unit testing

• Mocha
• Chai

Project structure

./
  src/
    lib/
      lib.js
    index.js
    index.spec.js

./

The root of the project. It contains all the config files and directories.

src/

Where the development happens. It contains the source files and its companion unit tests.

npm test is configured to execute all .spec.js or .test.js files inside the src/ directory.

npm scripts

{
  "test": "mocha src/**/*.{test,spec}.js",
  "format": "prettier --write --cache .",
  "lint:js": "eslint .",
  "lint:md": "markdownlint-cli2 **/*.md !node_modules"
}

ES module imports

VSCode is configured to include file extensions from import path suggestions (via .vscode/settings.json) which are required for ES modules.

Absolute paths

The project is configured to support absolute paths from both Node.js (via package.json) and VSCode (via jsconfig.json).

In Node.js, path aliases must start with #.

Since it is not possible to alias the src/ folder as #/, as a workaround we recommend to create an alias for each src/ subfolder.

Set your path aliases in package.json for Node.js:

{
  "imports": {
    "#lib/*": "./src/lib/*"
  }
}

Set your path aliases in jsconfig.json for VSCode:

{
  "compilerOptions": {
    "paths": {
      "#lib/*": ["./src/lib/*"]
    }
  }
}

To use absolute paths, prefix your import files with the alias for a src/ subfolder, such as #lib/. VSCode will give you the right file suggestions.

Learn more:

• Node.js Subpath imports
• VSCode jsconfig.json Reference

Package entry points

The project is configured to export src/index.js as main entry point.

Learn more: Package entry points.

VSCode recommended extensions

• editorconfig.editorconfig
• esbenp.prettier-vscode
• dbaeumer.vscode-eslint
• davidanson.vscode-markdownlint

VSCode is configured to recommend the previous extensions from the extensions view (via .vscode/extensions.json).

Publishing to npm

npm is configured to prevent accidental publication. To enable package publication remove { "private": true } from package.json.

Licensing

You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.

Set the license in your package.json:

{ "license": "<SPDX license identifier>" }

Learn more:

• Configuring npm - license
• Choose an open source license