Go to file
2016-08-31 13:02:18 +02:00
assets ready for primetime 2016-07-01 04:50:23 +02:00
dist fix project cleaning 2016-08-30 17:57:51 +02:00
docs update npmpage creation 2016-08-31 12:04:14 +02:00
ts fix project cleaning 2016-08-30 17:57:51 +02:00
.gitignore update npmpage creation 2016-08-31 12:04:14 +02:00
.gitlab-ci.yml fixed .gitlab-ci.yml 2016-08-31 13:02:10 +02:00
.npmignore add .npmignore 2016-05-27 00:59:17 +02:00
.travis.yml now completeley hiding git console output 2016-02-23 18:58:44 +01:00
appveyor.yml Update appveyor.yml 2016-05-18 02:33:05 +02:00
CHANGELOG Add changelog 2016-05-29 19:23:11 +00:00
CONTRIBUTING.md Add contribution guide 2016-05-29 19:24:59 +00:00
LICENSE Initial commit 2016-01-13 19:21:20 +01:00
package.json 5.4.17 2016-08-31 13:02:18 +02:00
README.md update npmpage creation 2016-08-31 12:04:14 +02:00
tsconfig.json integrate tsn and clean up 2016-07-01 02:28:34 +02:00

npmts

Write npm modules with TypeScript without hassle. TypeScript ready. Fully ES6.

Status

build status coverage report Dependency Status bitHound Dependencies bitHound Code TypeScript node

What is NPMTS?

NPMTS is your friend when it comes to write, test, publish and document NPM modules written in TypeScript. By default NPMTS will bundle declaration files. As a result npm module code completion in editors like Visual Studio Code works.

There is a docker image available that includes npmts to make CI a breeze:
hosttoday/ht-docker-node:npmts on Dockerhub

Install

First install npmts globally, then install the npmts-g locally.

*npmts-g checks if the global version of npmts suffices the modules requirements. If not it installs npmts locally in the right version during npm install.

npm install npmts -g # installs npmts globally
npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency

Then add it to your package.json's script section to trigger a build:

"scripts": {
    "test": "(npmts)"
}

Default task execution order

  1. Config: Check config in ./npmextra.json (Check out npmextra)
  2. Clean: Clean up from any previous builds (old js files)
  3. Check: Check project for typings declaration in package.json, unused dependencies and missing dependencies
  4. Transpile: Transpile TypeScript with inline sourcemaps and declaration files to ES target
  5. Documentation: Create TypeDoc Documentation from TypeScript files
  6. Test: Babelify ES6 to ES5 on the fly, instrumentalize ES5 JavaScript with istanbul and run tests with Mocha.

npmextra.json

the npmts section in npmextra.json can be used to configure npmts.

Default

Note: When you are using "mode":"default" it'll cause npmts to override any other settings you may have made except for tsOptions (ES target etc.) with default behaviour.

{
  "npmts":{
    "mode":"default"
  }
}

Custom settings

{
  "mode":"custom",
  "docs":false,
  "test":true,
  "npmts":{
    "ts":{
      "./customdir/*.ts":"./"
    },
    "tsOptions":{
      "declaration":false,
      "target":"ES6"
    },
    "cli":true
  }
}
key default value description
"mode" "default" "default" will do default stuff and override , "custom" only does what you specify
"docs" true create docs for your module
"test" true test your module
"ts" {"./ts/*.ts":"./","./test/test.ts":"./test/"} allows you to define multiple ts portions
"tsOptions" {"target":"ES5", "declaration":"true"} specify options for tsc
"cli" "false" some modules are designed to be used from cli. If set to true NPMTS will create a cli.js that wires you dist files up for cli use.

TypeScript

by default npmts looks for ./ts/*.ts and ./test/test.ts that will compile to ./dist/*.js and ./test/test.js

Use commonjs module system for wiring up files.

Declaration files

npmts also creates declaration files like ./dist/index.d.ts by default. You can reference it in your package.json like this.

"main": "dist/index.js",
"typings": ".dist/index.d.ts",

This is in line with the latest TypeScript best practices. You can then import plugins via the TypeScript import Syntax and tsc will pick up the declaration file automatically.

TypeDoc

By default TypeDoc will create docs for your module in ./pages/api/ directory.

Note: Use npmpage to build a website for the module. It also allows you to integrate api docs with a gitbook located in ./docs/

Some notes:

Typings for third party modules that do not bundle declaration files

NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope.

Instrumentalize Code

npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report.

Tests

Any errors will be shown with reference to their originating source in TypeScript thanks to autogenerated source maps.

Example Usage in modules:

We will add more options over time.

Tips and tricks:

  • Use npmts-g to use globally installed npmts and install npmts locally if no global npmts is available.
  • Use npmpage to create a webpage from coverage reports and TypeDoc for the module
  • Use hosttoday/ht-docker-node:npmts for speedy CI builds
  • Use npmdocker for running tests consistently with docker.

Future Scope:

  • automatically manage badges in README
  • manage tslint to enforce code best practices
  • tear down any differences between local and CI environments by using brand new npmdocker

About the authors:

Project Phase

PayPal