npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

publishr

v1.0.0

Published

A tool for harmonious publishing of git and npm packages.

Downloads

162

Readme

Travis Status Coverage Status NPM Package

Publishr

A tool for harmonious publishing of git and npm packages.

Publishr allows you to consistently publish different files in git and npm using an npm version workflow, which enables efficient installation from both types of repository.

Motivation

It can be troublesome to enable package installation from both npm and git repositories, especially when a project includes build steps. One inefficient publishing solution entails saving both source and compiled files to git and npm. Another less than ideal solution requires installing heavy build dependencies in production. Depending on the size of your repository, these solutions can be a burden for both development and production. Ideally, the git repository only contains source code and the npm repository contains compiled code. Furthermore, the npm repository should not contain any large build dependencies. Publishr solves these problems by tapping into npm's version/publish lifecycle scripts.

Installation

$ npm install publishr

Setup

  1. Save all build dependencies to package.json as dependencies.
  2. Save placeholder (ex. .someconfig.publishr) files that should be replaced in the npm repo.
  3. Add a publishr config to package.json.
  4. Use publishr.dependencies to describe which build dependencies to replace in the npm repo.
  5. Use publishr.files to describe files to replace/create in the npm repo.
  6. Use publishr.scripts to describe scripts to add/replace/remove in the npm repo.
  7. Add publishr postversion to npm's postversion script.
  8. Add publishr postpublish to npm's postpublish script.

Configuration

  1. publishr.dependencies - Describes build dependencies to replace in the npm repo.
  • Takes an array of regular expression strings
    • ["^babel$"] matches only babel
    • ["^babel"] matches babel, babel-core
    • ["babel"] matches babel, babel-core, is-babel
  1. publishr.files - Describes files to replace/create in the npm repo.
  • Takes an object of oldFile keys to newFile values
    • {".npmignore": ".npmignore.publishr"} replaces/creates .npmignore with .npmignore.publishr
  1. publishr.scripts - Describes files to add/replace/remove in the npm repo.
  • Takes an object of script name keys to command values.
    • {"hello": "echo hello"} adds/replaces the test script hello with the command echo hello
    • {"postinstall": ""} removes the postinstall script.

Publishing

  1. Run publishr dry-run to test your configuration.
  2. If the dry run fails, fix all errors and go back to 1.
  3. Run your version command.
  4. Run your publish command.

Example

An example package.json file will look something like this:

  {
    "name": "some-neat-project",
    "version": "0.0.1",
    "dependencies": {
      "lodash": "^4.0.0",
      "babel-core": "^6.0.0"
    },
    "devDependencies": {
      "eslint": "^1.0.0"
    },
    "scripts": {
      "build": "gulp build",
      "postinstall": "npm run build",
      "postpublish": "publishr postpublish",
      "postversion": "publishr postversion"
    },
    "publishr": {
      "dependencies": ["^babel"],
      "files": {
        ".npmignore": ".npmignore.publishr",
        ".someconfig": ".someconfig.publishr"
      },
      "scripts": {
        "build": "echo 'No Build Needed'",
        "extra": "echo 'Extra Script'",
        "postinstall": ""
      }
    }
  }

The above configuration tells publishr to do a few things:

  1. Move all dependencies matching the regular expression ^babel to devDependencies before publishing to npm.
  2. Replace .npmignore with the contents of .npmignore.publishr before publishing to npm.
  3. Replace .someconfig with the contents of .someconfig.publishr before publishing to npm.
  4. Replace the build script with echo 'No Build Needed' before publishing to npm.
  5. Add the extra script before publishing to npm.
  6. Remove the postinstall script before publishing to npm.

The version command will look something like this:

$ npm version patch

Result:

v0.0.2

> [email protected] postversion /some/path
> publishr postversion

The publish command will look something like this:

$ npm publish

Result:

+ [email protected]

> [email protected] postpublish /some/path
> publishr postpublish

When all is said and done, the git and npm repo will have different versions of package.json, .npmignore, and .someconfig. Your npm package will install as quickly as possible and you still support installing from a git repo.

Usage

Usage: publishr <command> [options]

Commands:
  dry-run      Perform a dry run of postversion and postpublish
  postpublish  Clean up any actions taken by postversion
  postversion  Create and overwrite files for publishing

Options:
  -h, --help     Show help                                             [boolean]
  -V, --verbose  Log each step during postversion/postpublish          [boolean]
  -v, --version  Show version number                                   [boolean]