This template is aimed for Node.js packages development.
Node 18 is the target version.
https://nodejs.org/en/about/releases/
Up to date recommendations: https://nodejs.org/api/packages.html#packages_dual_commonjs_es_module_packages
This template assumes the library is going to be stateless.
Some tooling in downstream packages might need this.
See nodejs/node#33460 and tsmodule/tsmodule#1.
TSConfig reference: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
rollup bundler allows certain things that tsc CLI doesn't, such as more flexible output files naming - this is a must for a dual package.
Docs: https://rollupjs.org/guide/en/
TypeScript support is provided by the official plugin: https://github.com/rollup/plugins/tree/master/packages/typescript/#readme
Alternative TypeScript plugin with some extra features: https://github.com/ezolenko/rollup-plugin-typescript2
Concurrently is the closest substitute for npm-run-all that is not abandoned.
Sequential run can be achieved with -m 1 arg.
There is also this fork of npm-run-all that receives package updates: https://github.com/bcomnes/npm-run-all2
ESlint with TypeScript plugin is currently the preferred way to lint .ts files.
Only recommended configs are included with the template, with a minimal set of overrides (same applies to all linting tools).
Rules: https://eslint.org/docs/rules/
Various plugins can conflict with each other so it's a good idea to usee overrides in .eslintrc.json to keep configuration for different file types separate.
Separate tsconfig.eslint.json file allows to lint test files.
TSDoc: https://tsdoc.org/
ESlint plugin: https://tsdoc.org/pages/packages/eslint-plugin-tsdoc/
Generate API documentation in the /docs folder based on code and TSDoc comments.
TypeDoc: https://typedoc.org/
Markdown plugin: https://github.com/tgreyuk/typedoc-plugin-markdown (became more powerful in version 4).
Fast food of code formatting. Minimum decisions, quite wide range of supported file formats.
Options: https://prettier.io/docs/en/options.html
Prettier is basically unusable for json files. It is therefore disabled for those.
Apparently the most solid solution to lint and format JSON files. It reuses ESlint rules where appropriate. Not all defaults play nicely with all configs though, so a couple of overrides is provided.
Rules: https://ota-meshi.github.io/eslint-plugin-jsonc/rules/
Rules: https://github.com/DavidAnson/markdownlint/blob/main/README.md
https://github.com/DavidAnson/markdownlint-cli2 seems to be a better CLI all around at this point.
https://github.com/igorshubovych/markdownlint-cli followed more conventional approach but is not going to receive future improvements.
My test framework of choice. Macros and snapshots are pleasure to work with in AVA. Jest often causes various troubles.
TypeScript support via https://github.com/tapjs/tsimp
More notes on TypeScript support: https://github.com/avajs/ava/blob/master/docs/recipes/typescript.md
tsd is the most known tool for type tests but turns out it is rather opinionated and has some limitations.
https://github.com/mmkal/expect-type seems to be a better alternative.
A common observation about type testing: it is not well compatible with unit testing. The best approach I see is to keep it separate and just run tsc --noEmit over it.
Many tools come with their own watchers, others don't. https://github.com/Qard/onchange seems to be the most straightforward solution to add this feature where it is missing.
https://github.com/M-Zuber/npm-watch might be a suitable alternative in some cases.
- https://docs.github.com/en/free-pro-team@latest/actions/guides/building-and-testing-nodejs
- https://github.com/actions/setup-node
GitHub workflow status badge: https://docs.github.com/en/free-pro-team@latest/actions/managing-workflow-runs/adding-a-workflow-status-badge
GitHub itself currently doesn't provide badges for coverage. But coverage data can be sent to an external service. For some of them it is as easy as using a ready-made action.
List of coverage providers supported by Shields_io: https://shields.io/category/coverage
Codecov seems to be the most practical one. https://about.codecov.io/for/open-source/
https://github.com/bcoe/c8 is used for coverage reports generation with AVA and Mocha. More on c8: https://medium.com/the-node-js-collection/rethinking-javascript-test-coverage-5726fb272949.
Depfu seems to be useful as a display for the state of dependencies. But their "reasonably up-to-date" policy - a feature that should make their product more pleasing to use - doesn't seem to work as expected and appears way too "lazy".
Dependabot is a part of GitHub now, it delivers security updates automatically and can be configured to create regular dependency updates. Among the list of package managers such as npm it also has Github Actions. Documentation.
https://github.com/dylang/npm-check is a handy tool when you need to manage deps manually. It is meant to be installed globally though, so it's only mentioned here.
https://marketplace.visualstudio.com/items?itemName=idered.npm extension for VSCode had a good premise but seems to be dropped half-baked. I only use it now to quickly see the list of available versions for some packages.
https://marketplace.visualstudio.com/items?itemName=codeandstuff.package-json-upgrade extension for VSCode is currently the most helpful tool for me to update dependencies.
This part is left out for now. No good template solution can be provided yet.
This repository is a mere template without own functionality, a configuration for external tools and libraries. And as such, it shouldn't be considered a subject of copyright. Instead, you are encouraged to copy it and apply the license of your choice to the product you build.