2016-01-16 13:09:33 +00:00
# npmts
2016-07-18 22:25:31 +00:00
Write npm modules with TypeScript without hassle. TypeScript ready. Fully ES6.
2016-01-16 13:09:33 +00:00
2016-02-09 16:19:27 +00:00
## Status
2016-05-27 12:44:15 +00:00
[![build status ](https://gitlab.com/pushrocks/npmts/badges/master/build.svg )](https://gitlab.com/pushrocks/npmts/commits/master)
2016-08-20 03:03:32 +00:00
[![coverage report ](https://gitlab.com/pushrocks/npmts/badges/master/coverage.svg )](https://gitlab.com/pushrocks/npmts/commits/master)
2016-02-14 02:19:54 +00:00
[![Dependency Status ](https://david-dm.org/pushrocks/npmts.svg )](https://david-dm.org/pushrocks/npmts)
[![bitHound Dependencies ](https://www.bithound.io/github/pushrocks/npmts/badges/dependencies.svg )](https://www.bithound.io/github/pushrocks/npmts/master/dependencies/npm)
[![bitHound Code ](https://www.bithound.io/github/pushrocks/npmts/badges/code.svg )](https://www.bithound.io/github/pushrocks/npmts)
2016-08-20 03:03:32 +00:00
[![TypeScript ](https://img.shields.io/badge/TypeScript-2.x-blue.svg )](https://nodejs.org/dist/latest-v6.x/docs/api/)
2016-07-28 02:10:32 +00:00
[![node ](https://img.shields.io/badge/node->=%206.x.x-blue.svg )](https://nodejs.org/dist/latest-v6.x/docs/api/)
2016-02-09 16:19:27 +00:00
2016-03-27 10:32:55 +00:00
## What is NPMTS?
NPMTS is your friend when it comes to write, test, publish and document NPM modules written in TypeScript.
2016-05-01 19:15:52 +00:00
By default NPMTS will **bundle declaration files** . As a result npm module **code completion in editors like Visual Studio Code** works.
2016-01-16 13:09:33 +00:00
2016-04-30 09:55:42 +00:00
There is a docker image available that includes npmts to make CI a breeze:
2016-07-11 12:46:31 +00:00
[hosttoday/ht-docker-node:npmts on Dockerhub ](https://hub.docker.com/r/hosttoday/ht-docker-node/ )
2016-04-30 09:55:42 +00:00
2016-01-16 13:09:33 +00:00
### Install
2016-07-11 11:46:44 +00:00
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.
2016-01-16 13:09:33 +00:00
```sh
2016-06-12 02:31:43 +00:00
npm install npmts -g # installs npmts globally
npm install npmts-g --save-dev # installs npmts-g checking tool as devDependency
2016-01-16 13:09:33 +00:00
```
2016-06-12 02:31:43 +00:00
Then add it to your package.json's script section to trigger a build:
2016-01-16 13:09:33 +00:00
```json
"scripts": {
2016-07-11 11:46:44 +00:00
"test": "(npmts)"
2016-01-16 13:09:33 +00:00
}
```
2016-05-01 19:15:52 +00:00
### Default task execution order
2016-02-14 02:12:02 +00:00
2016-07-18 22:25:31 +00:00
1. **Config:** Check config in ./npmextra.json (Check out [npmextra ](https://www.npmjs.com/package/npmextra ))
1. **Clean:** Clean up from any previous builds (old js files)
2016-07-28 02:08:46 +00:00
1. **Check:** Check project for typings declaration in package.json, unused dependencies and missing dependencies
2016-07-28 02:10:32 +00:00
1. **Transpile:** Transpile TypeScript with **inline sourcemaps** and **declaration files** to ES target
2016-07-18 22:25:31 +00:00
1. **Documentation:** Create TypeDoc Documentation from TypeScript files
1. **Test:** Babelify ES6 to ES5 on the fly, instrumentalize ES5 JavaScript with istanbul and run tests with Mocha.
2016-03-27 10:32:55 +00:00
2016-07-18 22:25:31 +00:00
### npmextra.json
2016-07-28 02:06:20 +00:00
the npmts section in npmextra.json can be used to configure npmts.
2016-02-14 02:12:02 +00:00
2016-08-19 07:46:36 +00:00
**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.
```json
{
"npmts":{
"mode":"default"
}
}
```
**Custom settings**
2016-04-30 03:49:53 +00:00
```json
{
2016-08-19 07:46:36 +00:00
"mode":"custom",
"docs":false,
"test":true,
2016-07-16 21:33:10 +00:00
"npmts":{
"ts":{
"./customdir/*.ts":"./"
},
"tsOptions":{
"declaration":false,
"target":"ES6"
},
"cli":true
}
2016-04-30 03:49:53 +00:00
}
```
2016-05-01 19:15:52 +00:00
| key | default value | description |
| --- | --- | --- |
2016-08-19 07:46:36 +00:00
| `"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 |
2016-07-28 02:28:28 +00:00
| `"ts"` | `{"./ts/*.ts":"./","./test/test.ts":"./test/"}` | allows you to define multiple ts portions |
2016-05-01 19:15:52 +00:00
| `"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. |
2016-04-30 03:49:53 +00:00
2016-07-18 22:25:31 +00:00
### TypeScript
2016-02-17 04:45:42 +00:00
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.
2016-01-16 13:20:14 +00:00
2016-07-18 22:25:31 +00:00
### Declaration files
2016-07-28 02:28:28 +00:00
**npmts** also creates declaration files like `./dist/index.d.ts` by default.
2016-04-30 09:55:42 +00:00
You can reference it in your package.json like this.
2016-01-18 14:20:23 +00:00
```json
2016-04-30 09:55:42 +00:00
"main": "dist/index.js",
"typings": ".dist/index.d.ts",
2016-01-18 14:20:23 +00:00
```
2016-04-30 09:55:42 +00:00
This is in line with the latest TypeScript best practices.
2016-03-27 10:32:55 +00:00
You can then import plugins via the TypeScript `import` Syntax
and tsc will pick up the declaration file automatically.
2016-07-18 22:25:31 +00:00
## Some notes:
2016-07-11 12:42:36 +00:00
#### Typings for third party modules that do not bundle declaration files
2016-07-28 02:28:28 +00:00
NPMTS no longer supports typings.json. Instead use the new TypeScript 2.x approach to typings using the @types/ npm scope.
2016-04-30 10:34:32 +00:00
2016-02-14 02:13:03 +00:00
#### Instrumentalize Code
2016-03-27 10:32:55 +00:00
npmts instrumentalizes (using istanbul) the created JavaScript code to create a coverage report.
2016-02-14 02:12:02 +00:00
2016-02-14 02:13:03 +00:00
#### Tests
2016-03-27 10:32:55 +00:00
Any errors will be shown with reference to their originating source in TypeScript
thanks to autogenerated source maps.
2016-01-18 14:35:44 +00:00
2016-04-30 10:38:16 +00:00
## Example Usage in modules:
2016-07-18 22:25:31 +00:00
* [gulp-browser ](https://www.npmjs.com/package/gulp-browser )
2016-01-16 13:42:30 +00:00
2016-04-01 23:25:01 +00:00
> We will add more options over time.
2016-06-12 02:31:43 +00:00
## Tips and tricks:
* Use [npmts-g ](https://www.npmjs.com/package/npmts-g ) to use globally installed npmts and install npmts locally if no global npmts is available.
2016-07-18 22:25:31 +00:00
* Use [npmpage ](https://www.npmjs.com/package/npmpage ) to create a webpage from coverage reports and TypeDoc for the module
2016-06-12 02:31:43 +00:00
* Use [hosttoday/ht-docker-node:npmts ](https://hub.docker.com/r/hosttoday/ht-docker-node/ ) for speedy CI builds
2016-07-18 22:25:31 +00:00
* Use [npmdocker ](https://www.npmjs.com/package/npmdocker ) for running tests consistently with docker.
2016-06-12 02:31:43 +00:00
2016-07-28 02:06:20 +00:00
## 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
2016-04-30 10:38:16 +00:00
## About the authors:
2016-04-01 23:25:01 +00:00
[![Project Phase ](https://mediaserve.lossless.digital/lossless.com/img/createdby_github.svg )](https://lossless.com/)
2016-05-17 18:13:30 +00:00
[![PayPal ](https://img.shields.io/badge/Support%20us-PayPal-blue.svg )](https://paypal.me/lossless)