This repostory is a template for npm packages using typescript.
There are a few things you need to change when you make use of this repo, so please full-text search for every <TODO> you can find. Replace those with what you actually want it to say.
This template has the whole setup needed to make typescript npm libraries.
It comes with a few utilities pre-loaded, to make development easier.
The package.json provides a few utility-commands:
...
"scripts": {
"lint": "eslint 'src/**/*.ts'",
"fix-lint": "eslint 'src/**/*.ts' --fix",
"prepare": "husky",
"build": "npm run build:compile && npm run build:fix",
"build:fix": "fix-esm-import-path out/*.js",
"build:compile": "tsc",
"build:clean": "rm -rf out",
"test": "jest --coverage",
"develop": "npx tsc --watch --outDir out/"
},
...All will be explained in the next chapters
For publishing to work you need to generate an npm Access Token:
- Navigate to npmjs.com
- Go to Settings > Access Tokens
- Press Generate New Token > Classic Token
- As the type you should define "Automation"
- Copy your new access token
Then you need to apply it:
- Navigate to your repository
- Go to Settings > Secrets and variables > Actions
- Click New repository secret and name it
NPM_TOKEN. In the Secret paste your npmjs token
Development should always be done with a second terminal session using:
npm run developThis ensures that all written typescript code gets transpiled into the /out directory. It automatically creates map files, type files and the javascript files.
Linting is also pre-configured using eslint and tslint. They can be run using:
npm run lintThis will show where eslint/tslint found errors.
To autofix simply run:
npm run fix-lintA pre-commit hook is defined using husky. It automatically gets initialized and run before every commit. In case it finds anything (using the npm run lint command), it aborts the commit.
The test environment is set up with jest and ts-jest, meanings it's very easy to write tests.
All tests must follow following pattern in order to be run:
/tests/**/*.test.tsThe package.json provides
After running tests using npm test a coverage file will be created unter /coverage, showing which lines got ran by the tester.
To build the project you can use:
npm run buildCI/CD is all done automatically on GitHub using the defined workflows under .github/workflows:
.github/
workflows/
publish.yml
tests.yml
As the naming makes obvious one file runs tests and the other publishes.
The tests get run on every push to any branch. They check the code with our linters first and then run tests. If the tests pass or not will be displayed using a green check or a red cross next to the commit message.
Publishing automatically gets done when a new tag is pushed to main.
First, the automation checks if the version in your package.json matches the tag you just pushed. In case that doesn't match it fails the publish instantly.
At the same time it runs the whole test CI once more to make sure everything is okay.
In case all of that comes true, it publishes the package to npmjs.
This repository makes use of typedoc to automatically display all jsdocs in html. It also takes all Markdown Files under docs/ and adds those.
It pushes that website to github pages automatically whenever publishing to the npm registry is done.
Important: For it to work you need to enable GitHub Pages. Navigate to your GitHub repository > Settings > Pages and set Source to GitHub Actions.
For an example of the working typedocs, see the adt.ts library.
If you want to run it manually just to update the website (which I would disencourage) you can do so. For that navigate to Your Repository > Actions and then select Manually publish docs to gh pages in the left sidebar. You can manually trigger that workflow.
While there are a few other commands namespaced under build:* they are just used inside the build. In case you are interested in understanding those, just read them.
== Links below are to be used! Change the credits! ==
This template was written and published by Anes Hodza