A template to assist you in creating and publishing TypeScript modules on NPM

✅ NEW: The workflow is now fully portable.
✅ NEW: Only one secret has to be defined: NPM_TOKEN (to enable publishing on your behalf on NPM).
✅ NEW: yarn support You are now free to use yarn instead of npm if you'd like to.
✅ NEW: React ready ( tsconfig.json configured to transpile .tsx files).

Presentation

This template automates the boring and tedious tasks of:

• Filling up the package.json
• Setting up Typescript.
• Writing a README.md with decent presentation and instructions on how to install/import your module.
• Testing on multiple Node version running on Ubuntu and Windows before publishing.
• Maintaining a CHANGELOG.
• Publishing on NPM and creating corresponding GitHub releases.

Besides, good stuff that comes with using this template: <<<<<<< HEAD

• The dist/ directory is not tracked on the main branch.
• Shorter specific file import path.
  import {...} from "my_module/theFile" instead of the usual import {...} from "my_module/dist/theFile"
• CDN distribution for importing from an .html file with a <script> tag. (Optional, you can disable this feature for node projects)
• ESlint and Prettier are automatically run against files staged for commit. (Optional, you can disable this feature)

If you want your module to support Deno as well checkout denoify_ci.

Examples of project using this template

• denoify
• keycloak-react-theming
• tss-react
• EVT (uses denoify_ci )

Table of content

• Presentation
• Examples of project using this template
• Table of content
• How to use
  • Fork it ( click use the template )
  • Enable automatic publishing
• Few things you need to be aware of before getting started
• Customization:
  • Changing the directories structure
  • Swipe the image in the README.md
  • Disable linting and formatting
    • Disable Eslint and Prettier altogether
    • Disable only Prettier
  • Disable CDN build
    • Completely disable
    • Only disable ES Module build ( dist/zz_esm/* )
  • Remove unwanted dev dependencies
  • Customizing the Badges
• Accessing files outside the dist/ directory
• The automatically updated CHANGELOG.md
• Video demo
• Examples of auto-generated readme
• Creating a documentation website for your project
• Creating a landing page for your project

How to use

Fork it ( click use the template )

• Click on
• The repo name you will choose will be used as a module name for NPM so:
  • Be sure it makes for a valid NPM module name.
  • Check if there is not already a NPM module named like that.
• The description you provide will be the one used on NPM and in package.json ( you can change it later )

Once you've done that a GitHub action workflow will set up the README.md and the package.json for you, wait a couple of minutes for it to complete ( a bot will push ). You can follow the job advancement in the "Action" tab.

Each time you will push changes npm test will be run on remote docker containers against multiple node versions if everything passes you will get a green ci badges in your readme.

Enable automatic publishing

Once you are ready to make your package available on NPM you will need to provide your NPM token so that the workflow can publish on your behalf:

Go to repository Settings tab, then Secrets you will need to add a new secret: NPM_TOKEN, you NPM authorization token.

To trigger publishing edit the package.json version field ( 0.0.0-> 0.0.1 for example) then push changes... that's all ! The publishing will actually be performed only if npm test passes.

Few things you need to be aware of before getting started

• The files to include in the NPM bundle are cherry-picked using the package.json files field.
  If you don't want to bother and includes everything just remove the files field from the package.json.
• If you are going to programmatically load files outside of the dist/ directory ( like the package.json or files inside res/ ) be mindful that the paths might not be the one you expect. Details.
• The template does not support .npmignore ( it use the safer package.json files instead ).
• The template does not support .npmrc.

Customization:

Changing the directories structure

Swipe the image in the README.md

Disable linting and formatting

Disable Eslint and Prettier altogether

Disable only Prettier

Disable CDN build

Completely disable

Only disable ES Module build ( dist/zz_esm/* )

{
  "cdn:bundle:.js": "simplifyify dist/index.js -s #{REPO_NAME}# -o dist/bundle.js --debug --bundle",
  "cdn:bundle:.min.js": "terser dist/bundle.js -cmo dist/bundle.min.js",
  "cdn:bundle": "npm run cdn:bundle:.js && npm run cdn:bundle:.min.js",
  "cdn:esm": "tsc -p tsconfig.esm.json",
  "cdn": "npm run cdn:bundle && npm run cdn:esm",
}

{
  "cdn:.js": "simplifyify dist/index.js -s #{REPO_NAME}# -o dist/bundle.js --debug --bundle",
  "cdn:.min.js": "terser dist/bundle.js -cmo dist/bundle.min.js",
  "cdn": "npm run cdn:.js && npm run cdn:.min.js",
}

Remove unwanted dev dependencies

Customizing the Badges

Accessing files outside the dist/ directory

import * as fs from "fs";
import * as path from "path";

const str = fs.readFileSync(
    path.join(__dirname,"..", "package.json")
).toString("utf8");

import * as fs from "fs";
import * as path from "path";
import { getProjectRoot } from "./tools/getProjectRoot";

const str = fs.readFileSync(
    path.join(getProjectRoot(),"package.json")
).toString("utf8");

The automatically updated CHANGELOG.md

Starting from the second release, a CHANGELOG.md will be created at the root of the repo.

Example:

The CHANGELOG.md is built from the commits messages since last release.

Are NOT included in the CHANGELOG.md:

• The commit messages that includes the word "changelog" ( non-case sensitive ).
• The commit messages that start with "Merge branch ".
• The commit messages that with "GitBook: "

The GitHub release will point to a freezed version of the CHANGELOG.md:

Video demo

Examples of auto-generated readme

Creating a documentation website for your project

I recommend GitBook, It enables you to write your documentation in markdown from their website and get the markdown files synchronized with your repo. They will provide you with a nice website for which you can customize the domain name.
All this is covered by their free tier.

Example:

• repo
• GitBook documentation website

I advise you to have a special directory at the root of your project where the markdown documentation files are stored. It is configured by placing a .gitbook.yaml file at the root of the repo containing, for example: root: ./docs/

Do not hesitate to request free access to premium features. Open source projects are eligible!

PS: I am not affiliated with GitBook in any way.

Creating a landing page for your project

Beside the documentation website, you might want to have a catchy landing page to share on social networks.
You can use GitHub pages to host it.

If you like the landing page of EVT, evt.land, you can fork the repo and adapt it for your module.

To produce high quality GIF from screen recording that remain relatively small checkout the wonderful Gifski from Sindre Sorhus.

Once your page is ready you'll just have to go to settings and enable Pages yo put it online.

And update your DNS:

I personally use Hurricane Electric free DNS servers because they support a lot of record types. However, if your DNS provider does not support ALIAS, you can use A records and manually enter the IP of GitHub servers. I let you consult the GitHub Pages Documentation.