Creates a production preview of a package
Last updated 10 months ago by zkochan .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install package-preview 
SYNC missed versions from official npm registry.


Creates a production preview of a package

npm version Status Windows build status

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? This is because what you test locally is not what gets published to the npm registry. With package-preview you'll always test exactly the same version of the package that is going to be installed as a dependency.


There are many ways a package can work locally but break after it's been published.

  • a file needed by the package is not added to the files field of package.json.
  • prod dependencies are accidentally installed as dev dependencies
  • packages are required in code but not declared in package.json
  • installation lifecycle scripts fail
  • bins are incorrectly declared
  • the main file is not specified correctly

These issues are mostly missed during development and testing because the content of the local package differs from the one that is packed and published. package-preview packs your project and installs it the way it's going to be installed as a dependency, so you can test the exact same package content that is going to be installed by Node.js package managers.

However, some issues can be missed even when a package is published. From version 3, npm creates a flat node_modules structure, as a result, your project has access to packages that are not declared in its package.json. Luckily, there is an alternative package manager which is more strict - pnpm. pnpm creates a strict, nested node_modules structure and package-preview uses it for installing dependencies for the preview. You can read more about pnpm's strictness and how it helps to avoid silly bugs in this article.


Install package-preview:

npm install -D package-preview
# or
pnpm install -D package-preview

package-preview uses pnpm for installing dependencies for the preview. If you don't have it installed, package-preview will install it on first run. Though you can also install manually if you want:

npm install -g pnpm
# or
curl -L | node


Lets' say your package is called awesome. In its package.json, run preview before running your tests:

  "name": "awesome",
  "version": "1.0.0",
  "scripts": {
    "test": "preview && tape test.js"

package-preview is going to create the preview version of your package and link it into your project's node_modules. So in your tests, you can require awesome and test the production version of your package:

// Instead of require('.')
const awesome = require('awesome')

assert(awesome() === 'Awesome stuff!')

Pro tips

Frequently packages run their tests before publish:

  "scripts": {
    "prepublishOnly": "npm test"

However, if package-preview is executed before tests, it will result in an infinite loop:

publish -> prepublishOnly -> npm test -> package-preview -> publish

To avoid this loop, use package-preview with the --skip-prepublishOnly flag:

  "scripts": {
    "test": "preview --skip-prepublishOnly && tape test.js",
    "prepublishOnly": "npm test"

There are similar flags for skipping other lifecycle events: --skip-prepublish, --skip-prepare, --skip-prepack.


  Usage: preview [what] [where] {OPTIONS}

        --skip-prepublish  Skips running `prepublish` script before publishing preview
           --skip-prepare  Skips running `prepare` script before publishing preview
    --skip-prepublishOnly  Skips running `prepublishOnly` script before publishing preview
           --skip-prepack  Skips running `prepack` script before publishing preview


MIT © Zoltan Kochan

Current Tags

  • 2.0.0                                ...           latest (10 months ago)
  • 2.0.0                                ...           next (10 months ago)

20 Versions

  • 2.0.0                                ...           10 months ago
  • 1.0.6                                ...           a year ago
  • 1.0.5                                ...           2 years ago
  • 1.0.4                                ...           2 years ago
  • 1.0.3                                ...           2 years ago
  • 1.0.2                                ...           2 years ago
  • 1.0.1                                ...           2 years ago
  • 1.0.0                                ...           2 years ago
  • 0.2.3                                ...           2 years ago
  • 0.2.2                                ...           2 years ago
  • 0.2.1                                ...           2 years ago
  • 0.2.0                                ...           2 years ago
  • 0.1.3                                ...           2 years ago
  • 0.1.2                                ...           2 years ago
  • 0.1.1                                ...           2 years ago
  • 0.1.0                                ...           2 years ago
  • 0.0.3                                ...           2 years ago
  • 0.0.2                                ...           2 years ago
  • 0.0.1                                ...           2 years ago
  • 0.0.0                                ...           2 years ago
Maintainers (1)
Today 0
This Week 0
This Month 2
Last Day 0
Last Week 0
Last Month 5
Dependencies (14)
Dev Dependencies (10)

Copyright 2014 - 2017 © |