| 1 | # package-preview
|
| 2 |
|
| 3 | > Creates a production preview of a package
|
| 4 |
|
| 5 | [](https://www.npmjs.com/package/package-preview)
|
| 6 | [](https://travis-ci.org/zkochan/package-preview "See test builds")
|
| 7 |
|
| 8 | How many times have you published version `1.0.0` of your new fancy package and it didn't work when you installed it as a dependency?
|
| 9 | This is because what you test locally is not what gets published to the npm registry.
|
| 10 | With `package-preview` you'll always test exactly the same version of the package that is going to be installed as a dependency.
|
| 11 |
|
| 12 | ## Background
|
| 13 |
|
| 14 | There are many ways a package can work locally but break after it's been published.
|
| 15 |
|
| 16 | * a file needed by the package is not added to the [files](https://docs.npmjs.com/files/package.json#files) field of `package.json`.
|
| 17 | * prod dependencies are accidentally installed as dev dependencies
|
| 18 | * packages are required in code but not declared in `package.json`
|
| 19 | * installation lifecycle scripts fail
|
| 20 | * bins are incorrectly declared
|
| 21 | * the main file is not specified correctly
|
| 22 |
|
| 23 | These issues are mostly missed during development and testing because the content of the local package differs from the one
|
| 24 | that is packed and published. `package-preview` packs your project and installs it the way it's going to be installed
|
| 25 | as a dependency, so you can test the exact same package content that is going to be installed by Node.js package managers.
|
| 26 |
|
| 27 | However, some issues can be missed even when a package is published. From version 3, npm creates a flat `node_modules` structure,
|
| 28 | as a result, your project has access to packages that are not declared in its `package.json`. Luckily, there is an alternative
|
| 29 | package manager which is more strict - [pnpm](https://github.com/pnpm/pnpm). `pnpm` creates a strict, nested `node_modules` structure
|
| 30 | and `package-preview` uses it for installing dependencies for the preview.
|
| 31 | You can read more about pnpm's strictness and how it helps to avoid silly bugs in [this](https://www.kochan.io/nodejs/pnpms-strictness-helps-to-avoid-silly-bugs.html) article.
|
| 32 |
|
| 33 | ## Install
|
| 34 |
|
| 35 | `package-preview` uses [pnpm](https://github.com/pnpm/pnpm) for installing dependencies for the preview. Install `pnpm`:
|
| 36 |
|
| 37 | ```bash
|
| 38 | npm install -g pnpm
|
| 39 | # or
|
| 40 | curl -L https://unpkg.com/@pnpm/self-installer | node
|
| 41 | ```
|
| 42 |
|
| 43 | Install `package-preview`:
|
| 44 |
|
| 45 | ```bash
|
| 46 | npm install -D package-preview
|
| 47 | # or
|
| 48 | pnpm install -D package-preview
|
| 49 | ```
|
| 50 |
|
| 51 | ## Usage
|
| 52 |
|
| 53 | Lets' say your package is called `awesome`. In its `package.json`, run `preview` before running your tests:
|
| 54 |
|
| 55 | ```json
|
| 56 | {
|
| 57 | "name": "awesome",
|
| 58 | "version": "1.0.0",
|
| 59 | "scripts": {
|
| 60 | "test": "preview && tape test.js"
|
| 61 | }
|
| 62 | }
|
| 63 | ```
|
| 64 |
|
| 65 | `package-preview` is going to create the preview version of your package and link it into your project's `node_modules`.
|
| 66 | So in your tests, you can require `awesome` and test the production version of your package:
|
| 67 |
|
| 68 | ```js
|
| 69 | // Instead of require('.')
|
| 70 | const awesome = require('awesome')
|
| 71 |
|
| 72 | assert(awesome() === 'Awesome stuff!')
|
| 73 | ```
|
| 74 |
|
| 75 | ## License
|
| 76 |
|
| 77 | [MIT](LICENSE) © [Zoltan Kochan](https://www.kochan.io)
|