Library Stack for Node.js projects

library stack
noun

Multiple libraries and services configured and composed together with the purpose of automating common development practices: compilation, linting, typechecking, testing, test coverage, benchmarking and releasing.

• Composition over hierarchy - While similar to a Framework, providing an opinionated ways of handling certain development topics, it intentionally leaves visible the containing libraries details - configuration file, npm scripts, commit hooks etc.

• 🐝 🌊 Continuous stack refactoring - Configuration freedom and choice over their application core libraries, focusing on zero lock-in and experimentation with new libraries and workflows.

Table of contents

• How to use
• Responsibilities
  • Compile
    • Tools
    • Scripts
  • Lint
  • Typecheck
  • Test
    • All tests one time
    • All tests when something inside src changes
  • Test coverage
  • Benchmark
  • Release
• Changelog

How to use

Responsibilities

Compile

Compile TypeScript files inside src folder, with type definitions and source maps.

Create bundles for both ESM and CommonJS modules. Use package.json fields, main and module, to point to the appropriate bundle depending on who is consuming it.

Tools

1. typescript - tsconfig.json
   A superset of JavaScript that compiles to clean JavaScript output.

2. swc - .swcrc
   A super-fast compiler written in Rust; producing widely-supported JavaScript from modern standards and typescript.

3. swc-register - Transpile JSX, TypeScript and esnext features on the fly with swc. It will respect your tsconfig.json and .swcrc if provided.

Scripts

# "build.types": "tsc --emitDeclarationOnly --outDir dist-types",
# "build.js-esm": "swc src --out-dir dist-esm --config module.type=es6",
# "build.js-cjs": "swc src --out-dir dist-cjs --config module.type=commonjs",
# "prebuild": "rm -rf dist-cjs dist-esm dist-types",
# "build": "npm run build.js-esm && npm run build.js-cjs && npm run build.types",
npm run build

Lint

1. eslint - .eslintrc
   Find and fix problems in your JavaScript code.

2. prettier - .prettierrc
   Opinionated code formatter. Enforces a consistent style by parsing your code and re-printing it with its own rules that take the maximum line length into account, wrapping code when necessary.

3. markdownlint - .markdownlintrc
   Style checker and lint tool for Markdown/CommonMark files.

4. commitlint - .commitlintrc
   Check your commit messages meet the conventional commit format.

5. lint-staged - .lintstagedrc
   Run linters against staged git files and don't let 💩 slip into your codebase!

# "lint.js": "eslint --quiet src",
# "lint.md": "markdownlint '*.md' --ignore CHANGELOG.md",
# "lint": "npm run lint.js && npm run lint.md",
npm run lint

Typecheck

1. typescript - .tscrc
   A superset of JavaScript that compiles to clean JavaScript output.

# "typecheck": "tsc --noEmit",
npm run typecheck

Test

1. tape TAP producing test harness for node and browsers.

2. tap-nirvana
   Tap Nirvana is a proper diffing reporter for TAP.

3. nodemon
   Monitor changes in your application and automatically run an npm script - perfect for development.

All tests one time

# "test": "tape -r swc-register 'src/*.test.ts' 'src/**/*.test.ts' | tap-nirvana",
npm run test

All tests when something inside src changes

# "tdd": "nodemon --watch src --ext js,ts,json --exec 'npm test'",
npm run tdd

Test coverage

1. c8 - .c8rc
   Output coverage reports using Node.js' built in coverage.

2. coveralls.io
   Service for test coverage reporting.

Use either .coveralls.yml or COVERALLS_REPO_TOKEN environment variable to submit the reports to your project, see Coveralls Currently Supports These CIs for details.

# "precoverage": "rm -rf coverage",
# "coverage": "c8 npm test && c8 report --reporter=text-lcov | coveralls",
npm run coverage

Benchmark

1. benny
   A dead simple benchmarking framework for JS/TS libs.

# "prebenchmark": "rm -rf benchmark",
# "benchmark": "node -r swc-register src/**/*.bench.ts",
npm run benchmark

Release

1. semantic-release
   Fully automated version management and package publishing.

2. CircleCI - .circleci/config.yml
   Continuous integration platform.

Changelog

See the releases section for details.