Nondeterministic Programming Methodology

    @xarc/module-dev
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.0 • Public • Published

    node.js modules development support

    This module offers common config and setup for developing a node.js module.

    Support for standard tools include:

    Installation

    To start a new module, first create the directory for it:

    mkdir my-module
    cd my-module

    Then follow the instructions below to setup development:

    1. Within your new project dir, run:
    npm init --yes
    npm install --save-dev @xarc/module-dev
    1. Bootstrap: then to bootstrap your project, use the following commands:
    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.
    1. Now you can run npx xrun to see a list of build tasks available for developing your node.js module.

    @xarc/run-cli

    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.

    $ npm install -g @xarc/run-cli

    Project Structure

    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.

    Developing

    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 test
    • Run tests without linting: npx xrun test-only
    • Run linting and tests with coverage: npx xrun check

    Your TypeScript tests should import your TS code from src directly.

    Publishing

    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 dir
    • dist - 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.
    • You can run npm publish --dry-run to see what npm will do without actually publishing for real.
    • When you are ready to publish for real, you can run npm publish.

    TypeScript Support

    If you boostrapped your project without TypeScript, but then want to add it later, you can run the typescript build task any time:

    npx xrun typescript
    npm install
    mkdir src

    And now you can start writing typescript code in the src directory

    tsconfig.json

    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 directly like import Path from "path". 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.

    eslint Support

    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:

    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 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.

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

    This comment disables the following three rules:

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

    jsdoc linting

    If you've enabled eslint, then linting rules for jsdoc is added with the plugin eslint-plugin-jsdoc.

    typedoc Support

    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.

    Fix typedoc externals

    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.
    /**
     * @packageDocumentation
     * @module index
     */
    • Use the following command to ignore a file:
    /** @ignore */ /** */
    • Use the following command before any export to ignore it.
    /** @ignore */
    export function internallySharedFunction() {}

    Compiling JSX

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

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

    React

    • To compile React JSX components:
    1. Add react to your dependencies: npm install react

    Preact

    • To compile Preact JSX components:
    1. Add preact to your dependencies: npm install preact
    2. Update compilerOptions in tsconfig.json:
    {
      "compilerOptions": {
        "lib": ["dom"],
        "jsxFactory": "h"
      }
    }

    Additional Targets

    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.json
    2. Add a npm scripts to run tsc with --build option. ie: tsc --build tsconfig.es5.json
    3. Update build 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

    License

    Licensed under the Apache License, Version 2.0


    Install

    npm i @xarc/module-dev

    DownloadsWeekly Downloads

    107

    Version

    4.1.0

    License

    Apache-2.0

    Unpacked Size

    115 kB

    Total Files

    31

    Last publish

    Collaborators

    • arunvishnun
    • srinathm85
    • chandub
    • divyakarippath
    • jchip