<commit_before># shrinkpack

[![NPM version](http://img.shields.io/npm/v/shrinkpack.svg?style=flat-square)](https://www.npmjs.com/package/shrinkpack)
[![NPM downloads](http://img.shields.io/npm/dm/shrinkpack.svg?style=flat-square)](https://www.npmjs.com/package/shrinkpack)
[![Build Status](http://img.shields.io/travis/JamieMason/shrinkpack/master.svg?style=flat-square)](https://travis-ci.org/JamieMason/shrinkpack)
[![Dependency Status](http://img.shields.io/david/JamieMason/shrinkpack.svg?style=flat-square)](https://david-dm.org/JamieMason/shrinkpack)
[![Join the chat at https://gitter.im/JamieMason/shrinkpack](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JamieMason/shrinkpack)
[![Analytics](https://ga-beacon.appspot.com/UA-45466560-5/shrinkpack?flat&useReferer)](https://github.com/igrigorik/ga-beacon)

Shrinkpack complements the [npm shrinkwrap](https://docs.npmjs.com/cli/shrinkwrap) command by
maintaining a `node_shrinkwrap` directory in your project, containing the exact same tarballs that
`npm install` downloads from [https://registry.npmjs.org](https://registry.npmjs.org).

The rest of the `npm install` process is exactly the same. The only difference is that no network
activity is necessary when installing and building your project. The `node_shrinkwrap` directory can
be ignored in your editor (much like is done with the `node_modules` directory) but is instead
checked into source control.

> For context, please see the [target problem](#target-problem) and [justification](#justification)
> sections of this README.

## Contents

* [Installation](#installation)
* [Usage](#usage)
  * [Command Line](#command-line)
  * [Node.js](#nodejs)
* [Target Problem](#target-problem)
* [Justification](#justification)
  * [npm shrinkwrap](#npm-shrinkwrap)
  * [shrinkpack](#shrinkpack-1)
* [Suitability to your project](#suitability-to-your-project)
* [Tutorial](#tutorial)
  * [Create a new project](#create-a-new-project)
  * [Set some sensible npm defaults](#set-some-sensible-npm-defaults)
  * [Install dependencies](#install-dependencies)
  * [Shrinkwrap dependencies](#shrinkwrap-dependencies)
  * [Create a project-specific cache (optional)](#create-a-project-specific-cache-optional)
  * [Shrinkpack dependencies](#shrinkpack-dependencies)
  * [Check into Git](#check-into-git)
  * [Clean install](#clean-install)
  * [Update Dependencies](#update-dependencies)
  * [Toggle Compression](#toggle-compression)
  * [Remove Optional Dependencies](#remove-optional-dependencies)

## Installation

```
npm install --global shrinkpack
```

> **Note:** npm had a [regression affecting shrinkwrap](https://github.com/npm/npm/pull/13214) in
> versions 3.8.8 to 3.10.3.<br>
> Please ensure your version of `npm` is 3.10.4 or newer, or 3.8.7 or older.

## Usage

### Command Line

```
Usage: shrinkpack [options] [directory]

Options:

  -h, --help           output usage information
  -V, --version        output the version number
  -c, --compress       use compressed .tgz tarballs instead of .tar
  -o, --keep-optional  do not exclude optional dependencies

Icons:

  + Added
  ↓ Downloaded
  → Imported from Cache
  i Information
  - Removed
  ✓ Resolved
  12:34 Time Taken

Compression:

  Although compressed .tgz files have lower filesizes, storing binary files in
  Git can result in a gradual increase in the time it takes to push to your
  repository. Shrinkpack uses uncompressed, plain text .tar files by default,
  which are handled optimally by Git in the same way that .md, .js, and .css
  files are for example.
```

### Node.js

Shrinkpack works in 2 phases;

1. Analyse the project and gather all the diffing information between the file system and the shrinkwrap.
2. Use the diffing information to bring the file system in sync with the shrinkwrap.

```js
var shrinkpack = require('shrinkpack');

shrinkpack.analyse({ compress: false, directory: process.cwd(), keepOptional: false })
  .then(data => shrinkpack.update(data));
```

Or to run `shrinkpack` in full, including all the additional logging that you see when using the CLI.

```js
var cli = require('shrinkpack');

shrinkpack.run({ compress: false, directory: process.cwd(), keepOptional: false })
  .then(() => {});
```

## Target Problem

On most projects I've worked on we've had a [Jenkins](http://jenkins-ci.org/) (or similiar)
continuous integration environment, where we would run tests, analyse code, gather metrics, and
create deployment packages.

Each time code was pushed to our `develop` and `master` branches, a repeatable process was carried
out where a clean workspace was created, the latest version of the project was installed and
configured, then testing and code analysis took place.

We were all very happy with this process and the convenience of npm in particular, but the phase of
our builds where `npm install` listed a huge amount of network traffic would always raise the same<commit_msg>docs(readme): make correction to node.js api example<commit_after># shrinkpack

[![NPM version](http://img.shields.io/npm/v/shrinkpack.svg?style=flat-square)](https://www.npmjs.com/package/shrinkpack)
[![NPM downloads](http://img.shields.io/npm/dm/shrinkpack.svg?style=flat-square)](https://www.npmjs.com/package/shrinkpack)
[![Build Status](http://img.shields.io/travis/JamieMason/shrinkpack/master.svg?style=flat-square)](https://travis-ci.org/JamieMason/shrinkpack)
[![Dependency Status](http://img.shields.io/david/JamieMason/shrinkpack.svg?style=flat-square)](https://david-dm.org/JamieMason/shrinkpack)
[![Join the chat at https://gitter.im/JamieMason/shrinkpack](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/JamieMason/shrinkpack)
[![Analytics](https://ga-beacon.appspot.com/UA-45466560-5/shrinkpack?flat&useReferer)](https://github.com/igrigorik/ga-beacon)

Shrinkpack complements the [npm shrinkwrap](https://docs.npmjs.com/cli/shrinkwrap) command by
maintaining a `node_shrinkwrap` directory in your project, containing the exact same tarballs that
`npm install` downloads from [https://registry.npmjs.org](https://registry.npmjs.org).

The rest of the `npm install` process is exactly the same. The only difference is that no network
activity is necessary when installing and building your project. The `node_shrinkwrap` directory can
be ignored in your editor (much like is done with the `node_modules` directory) but is instead
checked into source control.

> For context, please see the [target problem](#target-problem) and [justification](#justification)
> sections of this README.

## Contents

* [Installation](#installation)
* [Usage](#usage)
  * [Command Line](#command-line)
  * [Node.js](#nodejs)
* [Target Problem](#target-problem)
* [Justification](#justification)
  * [npm shrinkwrap](#npm-shrinkwrap)
  * [shrinkpack](#shrinkpack-1)
* [Suitability to your project](#suitability-to-your-project)
* [Tutorial](#tutorial)
  * [Create a new project](#create-a-new-project)
  * [Set some sensible npm defaults](#set-some-sensible-npm-defaults)
  * [Install dependencies](#install-dependencies)
  * [Shrinkwrap dependencies](#shrinkwrap-dependencies)
  * [Create a project-specific cache (optional)](#create-a-project-specific-cache-optional)
  * [Shrinkpack dependencies](#shrinkpack-dependencies)
  * [Check into Git](#check-into-git)
  * [Clean install](#clean-install)
  * [Update Dependencies](#update-dependencies)
  * [Toggle Compression](#toggle-compression)
  * [Remove Optional Dependencies](#remove-optional-dependencies)

## Installation

```
npm install --global shrinkpack
```

> **Note:** npm had a [regression affecting shrinkwrap](https://github.com/npm/npm/pull/13214) in
> versions 3.8.8 to 3.10.3.<br>
> Please ensure your version of `npm` is 3.10.4 or newer, or 3.8.7 or older.

## Usage

### Command Line

```
Usage: shrinkpack [options] [directory]

Options:

  -h, --help           output usage information
  -V, --version        output the version number
  -c, --compress       use compressed .tgz tarballs instead of .tar
  -o, --keep-optional  do not exclude optional dependencies

Icons:

  + Added
  ↓ Downloaded
  → Imported from Cache
  i Information
  - Removed
  ✓ Resolved
  12:34 Time Taken

Compression:

  Although compressed .tgz files have lower filesizes, storing binary files in
  Git can result in a gradual increase in the time it takes to push to your
  repository. Shrinkpack uses uncompressed, plain text .tar files by default,
  which are handled optimally by Git in the same way that .md, .js, and .css
  files are for example.
```

### Node.js

Shrinkpack works in 2 phases;

1. Analyse the project and gather all the diffing information between the file system and the shrinkwrap.
2. Use the diffing information to bring the file system in sync with the shrinkwrap.

```js
var shrinkpack = require('shrinkpack');

shrinkpack.analyse({ compress: false, directory: process.cwd(), keepOptional: false })
  .then(data => shrinkpack.update(data));
```

Or to run `shrinkpack` in full, including all the additional logging that you see when using the CLI.

```js
var shrinkpack = require('shrinkpack');

shrinkpack.cli({ compress: false, directory: process.cwd(), keepOptional: false })
  .then(() => {});
```

## Target Problem

On most projects I've worked on we've had a [Jenkins](http://jenkins-ci.org/) (or similiar)
continuous integration environment, where we would run tests, analyse code, gather metrics, and
create deployment packages.

Each time code was pushed to our `develop` and `master` branches, a repeatable process was carried
out where a clean workspace was created, the latest version of the project was installed and
configured, then testing and code analysis took place.

We were all very happy with this process and the convenience of npm in particular, but the phase of
our builds where `npm install` listed a huge amount of network traffic would always raise the same
{'fraction_non_alphanumeric': 0.12303030303030303, 'fraction_numerical': 0.007676767676767677, 'mean_word_length': 4.7900584795321635, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 19, 'https://': 26, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3447905', 'n_tokens_mistral': 3246, 'n_tokens_neox': 2922, 'n_words': 965}