Have ideas to improve npm?Join in the discussion! »


    0.3.3 • Public • Published


    GitHub last commit

    Like gh-pages but for packages!

    Publish your optimized packages to NPM with one command: gh-packages

    gh-packages: How It Works

    Table of Contents

    How Does It Work?

    gh-packages will automatically create a new branch gh-packages with a copy of you project and publish it on NPM.

    You can execute a custom command before publishing your package by using the -c or --command flag: gh-packages -c "<custom bash command>"


    npm i -g gh-packages

    Note: It is also possible install gh-packages locally or to use it with npx. For more information: how to install gh-packages?


    To publish your package to NPM simply run gh-packages inside your package's directory:

    cd your-package

    Note: If you don't have an NPM account yet, you can create one here: create NPM account

    Note 2: Make sure you run npm login, npm init and git init in your-package's directory. For more information, please read the documentation: Getting Started


    gh-packages [patch|minor|major] [-c|--command]

    Version Number Update:

    Patch Update (0.0.X): gh-packages or gh-packages patch

    Minor Update (0.X.0): gh-packages minor

    Major Update (X.0.0): gh-packages major

    You can read about semantic versioning here: semver.org

    User Command:

    It is possible to define a bash command by using the --command or -c flag that will be executed on the gh-packages branch.

    gh-packages -c "<custom bash command>"

    This command will be run on the gh-packages branch before the package's publication.

    Package.JSON Configuration

    After you are done experimenting with the command line, it is good to parameter permanently your options in the package.json file.

    "scripts": {
      "package": "gh-packages ${VERSION-patch} --command \"echo 'custom command'\""

    Note: Don't forget to add a comma , at the end of the previous line. It is a common cause of error when editing package.json files.

    You can run the command in two ways:

    npm run package

    This will run your custom command and publish your package on NPM with as a patch update.

    VERSION=major npm run package

    This command, on top of running you custom command will publish you package to NPM as a major update. You can swap the word major with minor or patch as needed.

    Note: You can also change the ${VERSION-patch} to ${VERSION-minor} to change the default package publication from patch to minor.


    For more information and advanced examples, please visit the documentation page.

    Feature Request & Improvement

    Found a bug? Would you like a new feature? Open an issue here!

    Found a typo or would like to improve the docs? Open a PR here!


    Thanks to Rubens Mariuzzo for his Guide to creating a NodeJS command-line package.

    Thanks to Dominik Kundel for his Three Things You Didn't Know You Could Do with npm Scripts blog post.

    Thanks to Nate Fischer for his ShellJS package.

    Thanks to the people working on the yargs project.


    • [x] include things learned @ https://github.com/npm/feedback/discussions/112#discussioncomment-164829 in the install section of the documentation
    • [ ] create a wiki to explain all aspects of the project
    • [ ] add example page to wiki (mv, rm, rm -r, rm all but specified files...)
    • [ ] merge wiki usage and options pages together
    • [ ] check all the wiki links
    • [ ] test code. get at least 80% code coverage.
    • [ ] do one-line commit in package.json of the "version" line, complete with version number
    • [ ] add --platform and -p option to choose to publish on NPM or on GitHub
    • [ ] publish to other platforms as well. ex: docker, maven, nuget, rubygems, pypi...
    • [ ] name branches differently in case user wants to upload his package on multiple platforms. ex: gh-packages-npm, gh-packages-pypi...
    • [ ] check how does NPM parse/updates files
    • [ ] convert project to TypeScript
    • [ ] add Rollup bundler
    • [ ] run gh-packages to reduce bundle size
    • [ ] add an interactive message to the user before publishing the package "Are you sure you want to publish [package-name] vesion [new-package-version]? Y/n" with a -y or --yes flag to force the publcation without any messages
    • [ ] remove the preferGlobal flag in package.json https://github.com/npm/feedback/discussions/112#discussioncomment-162264
    • [ ] add package script in package.json to push with latest cli.js


    npm i gh-packages

    DownloadsWeekly Downloads






    Unpacked Size

    127 kB

    Total Files


    Last publish


    • avatar