@lucio/example

TypeScript library recipe for Node.js and the browser

This is a tutorial on how to write a library in TypeScript and publish it in a way that it can be used both in Node.js and the browser.

The repository can be used as a template for new TypeScript libraries. Just bear in mind that some files will need to be manually changed. I don't have the full list of changes needed, but you'll want to look for luciopaiva throughout the project, also read package.json carefully and don't forget to update LICENSE.md with your name and the current year.

With a single build, the goal is to be able to generate scripts that will let you:

• import {Foo} from "example"; in both Node.js and the browser
• const {Foo} = require("example"); in Node.js
• <script src="/path/to/example" /><script>const {Foo} = Example;</script> in the browser

For that we are going to use Webpack.

Webpack

npm i -D webpack

Run:

npx webpack init

It will guide you in creating the basic setup, installing webpack-cli and etc. This is the sequence of questions I was presented to while running it myself (and my answers):

? Which of the following JS solutions do you want to use? Typescript
? Do you want to use webpack-dev-server? No
? Do you want to simplify the creation of HTML files for your bundle? No
? Do you want to add PWA support? No
? Which of the following CSS solutions do you want to use? none
? Do you like to install prettier to format generated configuration? No
[webpack-cli] ℹ INFO  Initialising project...
   create package.json
   create src/index.ts
 conflict README.md
? Overwrite README.md? do not overwrite
     skip README.md
   create index.html
   create webpack.config.js
   create tsconfig.json

We can delete index.html as it won't be used. src/index.ts will be your code entry point (see this repository's code for an example). Of course, you could change the entry point to something else if you prefer so.

webpack.config.js needs to be considerably changed to achieve what we want. We need to tell Webpack to generate 3 different targets: one for Node.js, one for the browser via import statements and one for the browser via script tags. Webpack config is able to output multiple configuration objects, so that's what we do (see file). There is a function to generate configurations, and it works by making minor adjustments to a template object according to the desired target.

A plugin is added to fork TypeScript-related tasks to a parallel process, thus speeding up things (see ForkTsCheckerWebpackPlugin in webpack.config.js). This plugin will also be responsible for generating .d.ts files.

At this point npx webpack -w is already able to generate the output scripts.

Integration tests

Here I added some integration tests unders /tests/integration to verify that client projects will be able to import our library in every possible way.

Linting

ESLint is used as a linter for TypeScript. It is triggered by Webpack during the build pipeline. Custom rules can be added to .eslintrc.json and files can be ignored in .eslintignore.

Next steps

• npm publish (with script to generate /dist)
• automate integration testing
• coverage
• beautifier (with prettier)
• count lines of code
• benchmarks

Default imports

What if we want to export a default class? What would need to be changed?