Natural Polyglot Machine

    esm-and-other-format-libraries-starter
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    esm-and-other-format-libraries-starter

    This is a start kit for developing ECMAScript standard EM Modules format library with TypeScript.

    Explanation of Build Files.

    ES Module UMD CommonJS
    your-library.esm.js your-library.js your-library.common.js

    Create your library.

    In this chapter, we will explain how to implement libraries in three formats: ECMAScript standard, CommonJS, and UMD.

    1. Create project.

      mkdir your-library && cd $_;
    2. Create project configuration file.

      Execute the following command.
      This will create package.json at the root of the project.

      npm init -y;

      Open package.json and edit as follows.

      ...
      "main": "dist/your-library.common.js",
      "module": "dist/your-library.esm.js",
      "browser": "dist/your-library.js",
      "types": "types/your-library.d.ts",
      ...
      Name Value Description
      main dist/your-library.common.js Library name to output in CommonJS format.
      module dist/your-library.esm.js Library name to output in ES Modules format.
      browser dist/your-library.js Library name output in UMD format.
      types types/your-library.d.ts Set the typescript declaration file.
    3. Install required packages.

      npm i -D \
          typescript \
          ts-node \
          tsconfig-paths \
          rollup \
          rollup-plugin-typescript2 \
          rollup-plugin-terser \
          jest \
          @types/jest \
          ts-jest;
      Name Description
      typescript Used to compile TypeScript source code into JavaScript.
      ts-node Used to execute TypeScript code on a node and immediately check the result.
      tsconfig-paths Used to resolve paths (alias) in tsconfig.json at runtime with ts-node.
      rollup Rollup is a module bundler.
      Used to bundle ES Modules, CommonJS, and UMD libraries for distribution to clients.
      rollup-plugin-typescript2 Plug-in for processing typescript with rollup.
      rollup-plugin-terser Used to compress bundle files.
      jest Jest is a library for testing JavaScript code.
      @types/jest Jest's type declaration.
      ts-jest A TypeScript preprocessor required to test projects written in TypeScript using Jest.
    4. Create a TypeScript compilation configuration.

      Create TypeScript compilation configuration file.

      touch tsconfig.json;

      Add content:

      {
        "compilerOptions": {
          "target": "ESNext",
          "module": "ESNext",
          "declarationDir": "./types",
          "declaration": true,
          "outDir": "./dist",
          "rootDir": "./src",
          "strict": true,
          "noImplicitAny": true,
          "baseUrl": "./",
          "paths": {"~/*": ["src/*"]},
          "esModuleInterop": true
        },
        "include": [
          "src/**/*"
        ],
        "exclude": [
          "node_modules",
          "**/*.test.ts"
       ]
      }
      Option Value Description
      compilerOptions
      target ESNext Specify ECMAScript target version.
      "ESNext" targets latest supported ES proposed features.
      module ESNext Specify module code generation.
      "ESNext" is an ECMAScript standard, and import/export in typescript is output as import/export.
      declarationDir ./types Output directory for generated declaration files.
      declaration true Generates corresponding .d.ts file.
      outDir ./dist Output directory for compiled files.
      rootDir ./src Specifies the root directory of input files.
      baseUrl ./ Base directory to resolve non-relative module names.
      paths {
        "~/*": ["src/*"]
      }
      List of path mapping entries for module names to locations relative to the baseUrl.

      Set the alias of "/ src" directly under the root with "~ /".
      e.g. import Awesome from '~/components/Awesome';
      include [
        "src/**/*"
      ]
      A list of glob patterns that match the files to be included in the compilation.
      Set the source directory.
      exclude [
        "node_modules",
        "**/*.test.ts"
      ]
      A list of files to exclude from compilation.
      Set node_modules and unit test code.
    5. Create a library module with a type script.

      Create a directory to store source files.

      mkdir src;

      Submodule that calculates the subtraction.

      // src/add.ts
      /**
       * Sum two values
       */
      export default function(a:number, b:number):number {
        return a + b;
      }

      Submodule that calculates the addition.

      // src/sub.ts
      /**
       * Diff two values
       */
      export default function(a:number, b:number):number {
        return a - b;
      }

      Main module that imports multiple modules and exports a single library.

      // src/your-library.ts
      import add from '~/add';
      import sub from '~/sub';
      export {add, sub};
    6. Let's run the library on node.

      Run the following command.
      To run on node, it is important to set the module option to CommonJS.

      npx ts-node -r tsconfig-paths/register -P tsconfig.json -O '{"module":"commonjs"}' -e "\
          import {add} from '~/your-library';
          console.log('1+2=' + add(1,2));";# 1+2=3
    7. Setting up and running unit tests.

      Create unit test configuration file.

      touch jest.config.js;

      Add content:

      const { pathsToModuleNameMapper } = require('ts-jest/utils');
      const { compilerOptions } = require('./tsconfig.json');
      module.exports = {
        roots: [
          '<rootDir>/src',
          '<rootDir>/tests/'
        ],
        transform: {
          '^.+\\.tsx?$': 'ts-jest'
        },
        testRegex: '(/tests/.*|(\\.|/)(test|spec))\\.tsx?$',
        moduleFileExtensions: [
          'ts',
          'js'
        ],
        moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths , { prefix: '<rootDir>/' })
        // moduleNameMapper: {
        //   '^~/(.+)': '<rootDir>/src/$1'
        // }
      }
      Name Description
      roots A list of paths to directories that Jest should use to search for files in.
      Specify the directory path where the source code (./src) and test code (./tests) files are located.
      transform Instruct Jest to transpile TypeScript code with ts-jest.
      testRegex Specify the file and directory to be teste.
      moduleFileExtensions Specifies the extension of the file to be tested.
      moduleNameMapper Apply alias setting of actual path set in "baseUrl" and "paths" of tsconfig.json.

      Create a tests directory to store test code at the root of the project.

      mkdir tests;

      Then, Create add.test.ts and sub.test.ts files in the tests directory.
      This will contain our actual test.

      // tests/add.test.ts
      import {add} from '~/your-library';
      test('Add 1 + 2 to equal 3', () => {
        expect(add(1, 2)).toBe(3);
      });    
      // tests/sub.test.ts
      import {sub} from '~/your-library';
      test('Subtract 1 - 2 to equal -1', () => {
        expect(sub(1, 2)).toBe(-1);
      });

      Open your package.json and add the following script.

      ...
      "scripts": {
        "test": "jest"
      ...

      Run the test.

      npm run test;

      Jest will print this message.
      You just successfully wrote your first test.

      PASS  tests/add.test.ts
      PASS  tests/sub.test.ts
       
      Test Suites: 2 passed, 2 total
      Tests:       2 passed, 2 total
      Snapshots:   0 total
      Time:        1.332s, estimated 3s
      Ran all test suites.
    8. Run the build.
      There is one caveat.
      Convert UMD library names in global namespace from snake case to camel case. In the case of e.g.your-library, it will be window.yourLibrary.

      Create a build configuration file.

      touch rollup.config.js;

      Add content:

      import typescript from 'rollup-plugin-typescript2';
      import { terser } from "rollup-plugin-terser";
      import pkg from './package.json';
      export default {
        external: Object.keys(pkg['dependencies'] || []),
        input: './src/your-library.ts',
        plugins: [
          typescript({
            tsconfigDefaults: { compilerOptions: {} },
            tsconfig: "tsconfig.json",
            tsconfigOverride: { compilerOptions: {} },
            useTsconfigDeclarationDir: true
          }),
          terser()
        ],
        output: [
          // ES module (for bundlers) build.
          {
            format: 'esm',
            file: pkg.module
          },
          // CommonJS (for Node) build.
          {
            format: 'cjs',
            file: pkg.main
          },
          // browser-friendly UMD build
          {
            format: 'umd',
            file: pkg.browser,
            name: pkg.browser
              .replace(/^.*\/|\.js$/g, '')
              .replace(/([-_][a-z])/g, (group) => group.toUpperCase().replace('-', '').replace('_', ''))
          }
        ]
      }
      Name Description
      external Comma-separate list of module IDs to exclude.
      input The bundle's entry point(s) (e.g. your main.js or app.js or index.js).
      plugins Plugins allow you to customise Rollup's behaviour by, for example,
      transpiling code before bundling, or finding third-party modules in your node_modules folder.
      Use rollup-plugin-typescript2 and rollup-plugin-terser.
      rollup-plugin-typescript2 is a TypeScript loader, and this plugin reads "tsconfig.json" by default.
      rollup-plugin-terser compresses source code.
      output The output destination of the bundle.
      Three types of libraries, ES Modules, CommonJS, and UMD, are output.

      Open your package.json and add the following script.

      ...
      "scripts": {
        "build": "rollup -c"
      }
      ...

      Run the build.

      npm run build;

      The library compilation result and declaration file are output to the project root.
      You just built successfully.

      .
          -- dist/
              -- your-library.esm.js
              -- your-library.common.js
              -- your-library.js
          -- types/
              -- your-library.d.ts
              -- add.d.ts
              -- sub.d.ts
      

    How to publish a npm package

    1. Create an NPM user locally.
      When the command is executed, a '~/.npmrc' file is created and the entered information is stored.

      npm set init.author.name 'Your name';
      npm set init.author.email 'your@email.com';
      npm set init.author.url 'https://your-url.com';
      npm set init.license 'MIT';
      npm set init.version '1.0.0';
    2. Create a user on npm.
      If the user is not registered yet, enter the new user information to be registered in npm.
      If an npm user has already been created, enter the user information and log in.

      npm adduser;
    3. Create a repository on GitHub and clone.

      git clone https://github.com/your-user/your-repository.git;
    4. Setting files to be excluded from publishing

      Create an .npmignore file at the root of the project.

      .npmignore
      

      Add node_modules and package-lock.json to .npmignore not to publish.

      node_modules/
      package-lock.json
      
    5. Create v1.0.0 tag on GitHub.

      git tag -a v1.0.0 -m 'My first version v1.0.0';
      git push origin v1.0.0;
    6. Publish to npm

      npm publish;

    How to upgrade NPM packages

    1. Push program changes to github

      git commit -am 'Update something';
      git push;
    2. Increase version

      npm version patch -m "Update something";
    3. Create a new version tag on Github

      git push --tags;
    4. Publish to npm

      npm publish;

    Try this library

    1. Create project.

      mkdir myapp && cd $_;
    2. Create project configuration file.

      npm init -y;
    3. Install this library.

      npm i -S esm-and-other-format-libraries-starter;
    4. Create HTML.

      touch index.html;
    5. Try the library.

      • For ES Modules:

        The ES Modules library can be run in the browser immediately without compiling.

        Add the following code to myapp/index.html and check with your browser.

        <script type="module">
        import { add } from './node_modules/esm-and-other-format-libraries-starter/dist/mylib.esm.js';
        console.log(`1+2=${add(1,2)}`);// 1+2=3
        </script>
      • For CommonJS:

        The CommonJS library cannot be executed in the browser as it is, so it must be compiled into a format that can be executed in the browser.

        Install webpack for build.

        npm i -D webpack webpack-cli;

        Create a module that runs the library.
        Prepare myapp/app.js and add the following code.

        import {add} from 'esm-and-other-format-libraries-starter';
        console.log(`1+2=${add(1,2)}`);// 1+2=3

        Compile "myapp/app.js" into a format that can be executed by a browser.
        The compilation result is output to "myapp/app.budle.js".

        npx webpack app.js -o bundle.js;

        Add the following code to myapp/index.html and check with your browser.

        <script src="bundle.js"></script>
      • For UMD:

        The UMD library can be executed globally. It's very easy, but I don't like it because it makes module dependencies unclear.

        Add the following code to myapp/index.html and check with your browser.

        <script src="node_modules/esm-and-other-format-libraries-starter/dist/mylib.js"></script>
        <script>
        console.log(`1+2=${mylib.add(1,2)}`);// 1+2=3
        </script> 

    Difference in tscofig module output results.

    Check what JavaScript code is generated according to the setting value of module of tsconfig.

    1. The following is a module written in TypeScript used in the experiment.

      Main module.

      // ./src/app.ts
      import add from './add';
      const result = add(1, 2);

      Sub module.

      // ./src/add.ts
      export default function (a:number, b:number):number {
        return a + b;
      }
    2. Experimental results

      • 'target' is 'ESNext' and 'module' is 'es2015' or 'ESNext':

        // ./dist/app.js
        import add from './add';
        const result = add(1, 2);
        // ./dist/add.js
        export default function (a, b) {
            return a + b;
        }
      • 'target' is 'ESNext' and 'module' is 'none' or 'commonjs':

        // ./dist/app.js
        "use strict";
        var __importDefault = (this && this.__importDefault) || function (mod) {
            return (mod && mod.__esModule) ? mod : { "default": mod };
        };
        Object.defineProperty(exports, "__esModule", { value: true });
        const add_1 = __importDefault(require("./add"));
        const result = add_1.default(1, 2);
        // ./dist/add.js
        "use strict";
        Object.defineProperty(exports, "__esModule", { value: true });
        function default_1(a, b) {
            return a + b;
        }
        exports.default = default_1;
      • 'target' is 'ESNext' and 'module' is 'amd':

        ./dist/app.js
        var __importDefault = (this && this.__importDefault) || function (mod) {
            return (mod && mod.__esModule) ? mod : { "default": mod };
        };
        define(["require", "exports", "./add"], function (require, exports, add_1) {
            "use strict";
            Object.defineProperty(exports, "__esModule", { value: true });
            add_1 = __importDefault(add_1);
            const result = add_1.default(1, 2);
        });
        // ./dist/add.js
        define(["require", "exports"], function (require, exports) {
            "use strict";
            Object.defineProperty(exports, "__esModule", { value: true });
            function default_1(a, b) {
                return a + b;
            }
            exports.default = default_1;
        });
      • 'target' is 'ESNext' and 'module' is 'system':

        // ./dist/app.js
        System.register(["./add"], function (exports_1, context_1) {
            "use strict";
            var add_1, result;
            var __moduleName = context_1 && context_1.id;
            return {
                setters: [
                    function (add_1_1) {
                        add_1 = add_1_1;
                    }
                ],
                execute: function () {
                    result = add_1.default(1, 2);
                }
            };
        });
        // ./dist/add.js
        System.register([], function (exports_1, context_1) {
            "use strict";
            var __moduleName = context_1 && context_1.id;
            function default_1(a, b) {
                return a + b;
            }
            exports_1("default", default_1);
            return {
                setters: [],
                execute: function () {
                }
            };
        });
      • 'target' is 'ESNext' and 'module' is 'umd':

        // ./dist/app.js
        var __importDefault = (this && this.__importDefault) || function (mod) {
            return (mod && mod.__esModule) ? mod : { "default": mod };
        };
        (function (factory) {
            if (typeof module === "object" && typeof module.exports === "object") {
                var v = factory(require, exports);
                if (!== undefined) module.exports = v;
            }
            else if (typeof define === "function" && define.amd) {
                define(["require", "exports", "./add"], factory);
            }
        })(function (require, exports) {
            "use strict";
            Object.defineProperty(exports, "__esModule", { value: true });
            const add_1 = __importDefault(require("./add"));
            const result = add_1.default(1, 2);
        });
        // ./dist/add.js
        (function (factory) {
            if (typeof module === "object" && typeof module.exports === "object") {
                var v = factory(require, exports);
                if (!== undefined) module.exports = v;
            }
            else if (typeof define === "function" && define.amd) {
                define(["require", "exports"], factory);
            }
        })(function (require, exports) {
            "use strict";
            Object.defineProperty(exports, "__esModule", { value: true });
            function default_1(a, b) {
                return a + b;
            }
            exports.default = default_1;
        });

    Reference

    License

    MIT

    Author

    Install

    npm i esm-and-other-format-libraries-starter

    DownloadsWeekly Downloads

    4

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    16.7 MB

    Total Files

    3208

    Last publish

    Collaborators

    • takuya-motoshima