Skip to content

Latest commit

 

History

History
107 lines (74 loc) · 5.06 KB

README.md

File metadata and controls

107 lines (74 loc) · 5.06 KB
Raw

build-this-branch

Script to automate creating built branches for testing npm packages without publishing them to npm.

Support this project by ⭐️ starring and sharing it. Follow me to see what other cool projects I'm working on! ❤️

Usage

Run in your Git repository from the branch you want to build:

npx build-this-branch

⚠️ Warning: This command will force-push to the remote branch built/<current branch>. Make sure there are no unsaved changes there. You can configure the built branch name with --built-branch <branch name>.

Global install

If you use this command often, make sure to install it globally so it's on disk:

npm install -g build-this-branch

Flags

Flag Description
-c, --build-command <command> The command to build the branch. (default: npm run build)
-b, --built-branch <branch name> The name of the built branch. Defaults to prefixing "built/" to the current branch or tag name.
-r, --remote <remote> The remote to push to. (default: origin)
-d, --dry Dry run mode. Will not build, commit, or push to the remote.
-h, --help Show help
-v, --version Show version

FAQ

What's a built branch?

A built branch is a Git branch that contains published assets so it can be installed with npm from GitHub:

# Installs from github.com/organization/repository/tree/built-branch
npm install 'organization/repository#built-branch'

Built branches are useful for quickly testing changes and can be preferrable over permanently publishing a prerelease to npm.

When would I use this?

When you want to test install an in-development npm package by publishing it to a GitHub branch instead of npm.

But you can prepublish private test packages on npm too!

Personally, I prefer to use GitHub + Git over npm for testing packages because I'll have more control with better UI/UX.

A built branch is innately impermanent because it constantly gets force-pushed, and the branch can be easily deleted via commandline or GitHub UI. On top of that, it's easily sharable by link—to install or to look at the source. npm requires version bumping every test package, has a strict Unpublish policy, and does not make it easy to view the code before installing.

Use-cases:

  • When you want to test a new package that isn't ready to be published on npm.
  • When you're contributing to an open source project, and you want to test the changes.
  • When you want to avoid using npm link because of symlink complexities.
  • When you can't install locally via npm install <project path> or npm pack + npm install <tarball> (eg. testing in remote environment or providing a shareable test package).

How is this different from simply committing distribution files to a branch?

You can accomplish something similar by manually running the following commands:

$ npm run build
$ git add --force dist
$ git commit -nam built
$ git push

However, this will not yield the same exact output as npm publish because:

  • There can be missing distribution files (eg. multiple files at the package root). build-this-branch uses npm-packlist —the same library npm publish uses—to detect publish files specified via package.json#files and .npmignore.
  • Irrelevant files are committed (eg. source files). This can slow down installation or even interfere with the library behavior. For example, if your project has development configuration files, they can accidentally be read by the dependent.

What does this script do?

This script does the following to make a built branch:

  1. Run build script (eg. npm run build)
  2. Create a new branch with the built/ namespace
  3. Detects and only commits npm publish files to the new branch
  4. Force pushes up to remote
  5. Deletes local built branch
  6. Prints the installation command for the built branch

Can I install from a built branch hosted on a private repository?

Yes, if it's being installed from a Git client that's authorized to access the private repository.

However, if you're comfortable publishing the built assets to a public repository (given it's minified, mangled), you can use the --remote <remote> flag to push to another repository that the client has access to (eg. public repository).

User story

You want to test a built branch hosted on a private repository Repo A, but GitHub Actions on the consuming project Repo B doesn't have access to the private repository so npm install fails.

To work around this, you push the built branch to Repo B to install it from there:

$ npx build-this-branch --remote git@github.com:repo-b.git --branch test-pkg

✔ Successfully built branch! Install with command:
  → npm i 'repo-b#test-pkg'