README
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.
Create project.
mkdir your-library && cd $_;
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.|
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.|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.|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};
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
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?