Repository files navigation

This 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:

mkdir my-modulecd my-module

Then follow the instructions below to setup development:

1. Within your new project dir, run:

npm init --yesnpm install --save-dev @xarc/module-dev

2. Bootstrap: then to bootstrap your project, use the following commands:

npx xrun --require @xarc/module-dev initnpm 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 runnpx xrun to see a list of build tasks available for developing your node.js module.

If you want to be able to runxrun directly instead of having to donpx xrun, then you can install globally a simple package@xarc/run-cli with the following command.

$ npm install -g @xarc/run-cli

This module's setup assumes your project follows a directory structure like below:

.gitignorepackage.jsontsconfig.jsonlib/  index.jsdist/  index.js  index.d.js  index.js.mapsrc/  index.tstest/  spec/**    *.spec.js    *.spec.ts

If you are writing JavaScript that node.js can execute directly, then you can put them inlib dir.

If you are using TypeScript, then you can put yourts source insrc dir, and then runnpx tsc to compile them into thedist dir.

.d.ts type definition files and source map files will also be generated into thedist dir.

Once you start writing your code, either asTypeScript insrc or JavaScript inlib, you should put your tests in the directorytest/spec as*.spec.js or*.spec.ts files.

The following are common build tasks that you would use:

• Run linting and tests:npx xrun test
• Run tests without linting:npx xrun test-only
• Run linting and tests with coverage:npx xrun check

YourTypeScript tests should import your TS code fromsrc directly.

When you are ready to publish your module tonpm, please keep the following in mind:

This module automatically setupfiles in yourpackage.json to include these files to publish:

• lib - If you have JavaScript inlib dir
• dist - If you are writing your code inTypeScript.

ForTypeScript, your code fromsrc directory is not included. If you want to includesrc dir, please add that tofiles.

• If you have any other files or dirs that you want to publish, then add them to thefiles list.
• You can runnpm publish --dry-run to see whatnpm will do without actually publishing for real.
• When you are ready to publish for real, you can runnpm publish.

If you boostrapped your project withoutTypeScript, but then want to add it later, you can run thetypescript build task any time:

npx xrun typescriptnpm installmkdir src

And now you can start writing typescript code in thesrc directory

After this module createdtsconfig.json for you, you can change it as you like. This module won't override your settings.

The defaulttsconfig.json will setesModuleInterop totrue for you so you can import classic modules directlylikeimport Path from "path". Set it tofalse if you don't want this.

tslib is automatically added to your module'sdependencies andimportHelpers set totrue in yourtsconfig.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 witheslint support, you can always add it later by runningnpx xrun eslint, and thennpm install.

You need to create a.eslintrc.js file. If you want to use the eslint config this module setup, set it to:

const{ eslintRcNodeTypeScript}=require(".");module.exports={extends:eslintRcNodeTypeScript,};

The configs available are:

• eslintRcNode - Node.js
• eslintRcNodeTypeScript - Node.js for typescript
• eslintRcTest - Unit test code
• eslintRcTestTypeScript - typescript unit test code

You can invoke the linting task withnpx xrun lint

The build taskcheck will run linting also. You can invoke it withnpx 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.

/* eslint-disable no-console, no-magic-numbers, max-statements */

This comment disables the following three rules:

• no-console
• no-magic-numbers
• max-statements

If you've enabledeslint, then linting rules forjsdoc is added with the plugineslint-plugin-jsdoc.

If you've enabledTypeScript, thentypedoc is added to automatically generate HTML indocs from yourjsdoc in your code in thesrc directory.

To generate the docs manually, runnpm run docs. And then opendocs/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 fortypedoc, install the moduletypedoc-plugin-external-module-name.

Then in the.ts files:

• Use the following command to assign a file to a module.

/** *@packageDocumentation *@module index */

• Use the following command to ignore a file:

/**@ignore *//** */

• Use the following command before anyexport to ignore it.

/**@ignore */exportfunctioninternallySharedFunction(){}

You can add JSX support by updating yourtsconfig.json with following options:

{compilerOptions:{"jsx":"react"}}

• To compile React JSX components:

1. Addreact to your dependencies:npm install react

• To compile Preact JSX components:

1. Addpreact to your dependencies:npm install preact
2. UpdatecompilerOptions intsconfig.json:

{"compilerOptions":{"lib":["dom"],"jsxFactory":"h"}}

If you need to compile yoursrc to multiple targets, you can do this by:

1. Make a copy oftsconfig.json for your target. ie:tsconfig.es5.json
2. Add anpm scripts to runtsc with--build option. ie:tsc --build tsconfig.es5.json
3. Updatebuild script to havexrun run your new compile script. So if you named itcompile.es5, yourbuild would be:xrun -n compile compile.es5

• In your additional target config, you don't needtsc to generate the.d.ts files. You can turn it off by settingdeclaration tofalse

Licensed under theApache License, Version 2.0