Example Typescript Module for Node.js
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
Jörn Franke 39b950fe48 feat: add codeberg 3 months ago
.github/workflows feat: use npm ci instead of npm install 6 months ago
spec add code formatting 9 months ago
src added some exmaple typedoc documentation 8 months ago
.eslintrc.json add code formatting 9 months ago
.gitignore added typedoc 9 months ago
.nycrc.json add code formatting 9 months ago
.prettierignore added typedoc 9 months ago
.prettierrc.json add code formatting 9 months ago
LICENSE Initial commit 9 months ago
README.md feat: add codeberg 3 months ago
SECURITY.md add security.md 9 months ago
package-lock.json feat: bump up versions 3 months ago
package.json feat: bump up versions 3 months ago
tsconfig.dev.json cleanup 9 months ago
tsconfig.json cleanup 9 months ago
tsconfig.prod.json added declarations 9 months ago

README.md

Introduction

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:

This package is available on:

Clean

In order to clean all build outputs (dist, coverage etc.) you need to run

npm run clean

Code formatting

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.

Code Documentation

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.

Build

To build the module run

npm run build

You will will find all built code in the dist folder

Build for production

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

Code analysis

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

Test

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.

Continuous Integration Pipeline

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.

License

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.