gh-packages

Like gh-pages but for packages!

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

Table of Contents

• How Does It Work?
• Installation
• Usage
• Options
  • Version Number Update
  • User Command
• Package.JSON Configuration
• Documentation
• Feature Request & Improvement
• Thanks
• Todo

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>"

Installation

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?

Usage

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

cd your-package
gh-packages

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

Options

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.

Documentation

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

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.

Todo

• [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