This example is about a simple Typescript nodejs module that can be published to npmjs.org or other NPM registries. It should help you to quickly start a new Typescript project for a resuable module with all important aspects of a project, such as testing, coverage and code analysis.
If you want to start a new nodejs module based on Typescript without a graphical user interface (GUI) then you can simply use this one. It uses:
- Typescript to write more secure and maintainable Javascript code
- Typedoc - to create HTML documentation out of your source code comments
- Prettier to make your code more readable using code formatting
- Eslint to analyse your code for inconsistencies, bad practices or security issues using static code analysis
- Jasmine to write unit tests for your module
- Istanbul NYC to calculate how much of your module code is covered by unit tests
This package is available on:
- Codeberg (a non-commercial European hosted Git for Open Source): https://codeberg.org/ZuInnoTe/example-typescript-nodejs-module
- Github (an US hosted commercial Git platform): https://github.com/ZuInnoTe/example-typescript-nodejs-module
In order to clean all build outputs (dist, coverage etc.) you need to run
npm run clean
It is important to have readable code and ensure a consisting read experience accross the code base - even if written by different team members. You can automatically format all your code by running
npm run fmt
You can define which files should be ignored by this in .prettierignore. It is often very similar to your .gitignore.
You can configure the code formatting in .prettierrc.json.
Documenting your core APIs of your module is crucial for its reuse and maintainability. You can generate the code documentation as follows:
npm run typedoc
You will then find in the folder docs/code/ the documentation which can be openend using index.html and browser.
See here how to add useful comments to your source code so they make a great documentation: https://typedoc.org/guides/doccomments/
Ideally you make the code documentation in a versioned manner available with your release or in a dedicated versioned git repository. Furthermore, you should make them browsable so that the users of your module can access the documentation without barriers. For example, Github Pages can be used for this.
To build the module run
npm run build
You will will find all built code in the dist folder
Production builds are more compact and do not contain unnecessary files. You can build a production build using
npm run build-prod
You will will find all built code in the dist folder
Analysis of the code can be run via
npm run codeanalysis
If there are issues with your code it will prompt them to you include the line of code and the issue. You can configure it via the configuration file .eslintrc.json
Testing can be run via
npm run test
It will produce a table that shows you a summary of your test coverage of your module. Additionally it will report the following outputs:
- A HTML report in the folder coverage/index.html. You can browse through all code files and see where coverage is still missing
- A lcov report that can integrated in various code reporting tools, such as Sonarqube
It is recommended to store the test results in a versioned manner with your release files, so people can check them.
You can specify your own tests by adding a *.spec.ts file in the folder spec. See spec/index.spec.ts for an example.
You can configure testing via spec/support/jasmin.json.
You can configure coverage via .nycrc.json.
We provide a continuous integration pipeline using Github Actions. This is crucial to create reproducible builds of your package that do not only work on your developer workstation, but everywhere.
The workflow is defined in .github/workflows/build.yml.
You may also look at other continuous integration alternatives, such as Travis-CI.
Copyright 2021 ZuInnoTe (Jörn Franke)
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.