Support for developing node.js modules with mocha/eslint/typescript
npm install @xarc/module-devThis module offers common config and setup for developing a node.js module.
Support for standard tools include:
- Language: [TypeScript]
- Testing and code coverage: [chai], [mocha], [nyc], [sinon], [tap], [jest]
- Code linting: [eslint]
- Documentation: [jsdoc], [typedoc]
To start a new module, first create the directory for it:
``sh`
mkdir my-module
cd my-module
Then follow the instructions below to setup development:
1. Within your new project dir, run:
`sh`
npm init --yes
npm install --save-dev @xarc/module-dev
2. Bootstrap: then to bootstrap your project, use the following commands:
`sh`
npx xrun --require @xarc/module-dev init
npm install
- init takes the following options. ie: npx xrun --require @xarc/module-dev init --eslint
- --no-typescript - bootstrap without typescript support.--eslint
- - bootstrap with eslint support.
3. Now you can run npx xrun to see a list of build tasks available for developing your node.js module.
If you want to be able to run xrun directly instead of having to do npx xrun, then you can install globally a simple package [@xarc/run-cli] with the following command.
`sh`
$ npm install -g @xarc/run-cli
This module's setup assumes your project follows a directory structure like below:
`
.gitignore
package.json
tsconfig.json
lib/
index.js
dist/
index.js
index.d.js
index.js.map
src/
index.ts
test/
spec/**
*.spec.js
*.spec.ts
`
If you are writing JavaScript that node.js can execute directly, then you can put them in lib dir.
If you are using TypeScript, then you can put your ts source in src dir, and then run npx tsc to compile them into the dist dir.
.d.ts type definition files and source map files will also be generated into the dist dir.
Once you start writing your code, either as [TypeScript] in src or JavaScript in lib, you should put your tests in the directory test/spec as .spec.js or .spec.ts files.
The following are common build tasks that you would use:
- Run linting and tests: npx xrun testnpx xrun test-only
- Run tests without linting: npx xrun check
- Run linting and tests with coverage:
Your [TypeScript] tests should import your TS code from src directly.
When you are ready to publish your module to [npm], please keep the following in mind:
This module automatically setup [files] in your package.json to include these files to publish:
- lib - If you have JavaScript in lib dirdist
- - If you are writing your code in [TypeScript].
For [TypeScript], your code from src directory is not included. If you want to include src dir, please add that to [files].
- If you have any other files or dirs that you want to publish, then add them to the files list.npm publish --dry-run
- You can run to see what [npm] will do without actually publishing for real.npm publish
- When you are ready to publish for real, you can run .
If you boostrapped your project without [TypeScript], but then want to add it later, you can run the typescript build task any time:
`sh`
npx xrun typescript
npm install
mkdir src
And now you can start writing typescript code in the src directory
After this module created tsconfig.json for you, you can change it as you like. This module won't override your settings.
#### esModuleInterop
The default tsconfig.json will set esModuleInterop to true for you so you can import classic modules directlyimport Path from "path"
like . Set it to false if you don't want this.
#### tslib and importHelpers
tslib is automatically added to your module's dependencies and importHelpers set to true in your tsconfig.json. If this is not needed or wanted, then feel free to remove them. They won't be touched again.
If you didn't bootstrap your project with [eslint] support, you can always add it later by running npx xrun eslint, and then npm install.
You need to create a .eslintrc.js file. If you want to use the eslint config this module setup, set it to:
`js`
const { eslintRcNodeTypeScript } = require(".");
module.exports = {
extends: eslintRcNodeTypeScript,
};
The configs available are:
- eslintRcNode - Node.jseslintRcNodeTypeScript
- - Node.js for typescripteslintRcTest
- - Unit test codeeslintRcTestTypeScript
- - typescript unit test code
You can invoke the linting task with npx xrun lint
The build task check will run linting also. You can invoke it with npx xrun check.
If you need to disable certain eslint rules for a specific source file, you can add the following comment to the top of your file.
`js`
/ eslint-disable no-console, no-magic-numbers, max-statements /
This comment disables the following three rules:
- no-consoleno-magic-numbers
- max-statements
-
If you've enabled [eslint], then linting rules for [jsdoc] is added with the plugin [eslint-plugin-jsdoc].
If you've enabled [TypeScript], then [typedoc] is added to automatically generate HTML in docs from your [jsdoc] in your code in the src directory.
To generate the docs manually, run npm run docs. And then open docs/index.html to see the generated HTML docs.
[typedoc] treats every filenames as a module and that doesn't work well with the practice of one class per file.
To customize modules for [typedoc], install the module typedoc-plugin-external-module-name.
Then in the .ts files:
- Use the following command to assign a file to a module.
`js`
/**
* @packageDocumentation
* @module index
*/
- Use the following command to ignore a file:
`js`
/ @ignore / / /
- Use the following command before any export to ignore it.
`js`
/* @ignore /
export function internallySharedFunction() {}
You can add JSX support by updating your tsconfig.json with following options:
`js`
{
compilerOptions: {
"jsx": "react"
}
}
- To compile React JSX components:
1. Add [react] to your dependencies: npm install react
- To compile Preact JSX components:
1. Add [preact] to your dependencies: npm install preactcompilerOptions
2. Update in tsconfig.json:
`js`
{
"compilerOptions": {
"lib": ["dom"],
"jsxFactory": "h"
}
}
If you need to compile your src to multiple targets, you can do this by:
1. Make a copy of tsconfig.json for your target. ie: tsconfig.es5.jsonnpm scripts
2. Add a to run tsc with --build option. ie: tsc --build tsconfig.es5.jsonbuild
3. Update script to have xrun run your new compile script. So if you named it compile.es5, your build would be: xrun -n compile compile.es5
- In your additional target config, you don't need tsc to generate the .d.ts files. You can turn it off by setting declaration to false`
Licensed under the Apache License, Version 2.0
---
[@xarc/run-cli]: https://www.npmjs.com/package/@xarc/run-cli
[typescript]: https://www.typescriptlang.org/
[eslint]: https://eslint.org/
[mocha]: https://mochajs.org/
[chai]: https://www.chaijs.com/
[nyc]: https://istanbul.js.org/
[sinon]: https://sinonjs.org/
[jsdoc]: https://jsdoc.app/
[typedoc]: https://typedoc.org/
[eslint-plugin-jsdoc]: https://www.npmjs.com/package/eslint-plugin-jsdoc
[files]: https://docs.npmjs.com/files/package.json#files
[npm]: https://www.npmjs.com/
[react]: https://reactjs.org/
[preact]: https://preactjs.com/
[tap]: https://www.npmjs.com/package/tap
[jest]: https://jestjs.io/