Publish your npm package to a Git branch. Useful for testing packages in production-like environments before publishing to npm.
To test a package without publishing to the npm registry.
Publishing to npm just for testing has major downsides:
- Versioning overhead: You must bump the version, even for throwaway builds.
- Permanent: npm's strict unpublish policy makes removing test releases difficult.
- Hard to inspect: npm doesn't make it easy to view the contents of a published package.
- Risky: You could accidentally publish test code as a stable release.
- Skips npm lifecycle scripts
- Links the entire project (including source, tests, configs)
- Doesn't install dependencies automatically
- No versioning required: Uses Git branches instead of package versions.
- Easy cleanup: Delete the branch when you're done.
- Browsable: View and verify the published package on GitHub.
- Safe: Keeps test builds out of npm.
- Realistic simulation: Runs
prepareandprepack, and includes only publishable files.
Publish your npm package to a Git branch:
npx git-publishThis publishes the current package to the branch npm/<current branch> on the remote origin.
npm install -g git-publishThen run with:
git-publish| Flag | Description |
|---|---|
-b, --branch <name> |
Target branch name. Defaults to npm/<current branch or tag> |
-r, --remote <remote> |
Git remote to push to (default: origin) |
-o, --fresh |
Create a fresh single-commit branch. Force-pushes to remote |
-d, --dry |
Simulate the process. Does not commit or push |
-h, --help |
Show CLI help |
--version |
Show CLI version |
- Testing a package before it's ready for npm
- Contributing to a repo where you don't have publish access
- Testing in a CI/CD or remote environment where
npm linkdoesn't work - Avoiding symlink issues from
npm link
Add your build command to the prepack script in package.json:
{
// ...
"scripts": {
"prepack": "npm run build",
},
}This mirrors the same behavior as npm publish.
- Checks out or creates the publish branch
- Runs the
prepareandprepacknpm scripts - Uses npm-packlist to determine publishable files
- Commits only those files
- Pushes the branch to the Git remote
- Prints the command to install the package via Git
When installing from Git, npm uses commit hashes—not branch names. If the commit is "detached" (i.e., unreachable from history), it may be garbage-collected, breaking installs.
To avoid this, git-publish preserves history by default.
If you prefer a single clean commit and understand the risks, use the --fresh flag to force-push a one-commit branch.
Manual commits often:
- Miss important files (e.g., those not in
dist/) - Include irrelevant files (e.g., tests, source, configs)
- Skip npm lifecycle scripts
git-publish avoids these pitfalls by using npm-packlist (same as npm publish) and running prepare and prepack.
Yes. Run git-publish from inside the specific package directory (e.g., packages/my-lib).
It will detect and publish only that package's contents to the root of the Git branch.
Important
Currently does not support resolving workspace: protocol dependencies. Avoid using those or pre-bundle them before publishing.
Yes—if your Git client (e.g., local dev, CI, etc.) is authorized to access the repo.
If that's not possible, you can push the branch to a public repo using the --remote flag.
Warning
Minify or obfuscate private code before publishing to a public repo.
Say you're testing changes in Repo A, but your GitHub Actions workflow in Repo B can't access private repos. You can push the publish branch to Repo B instead:
npx git-publish --remote git@github.com:repo-b.git --branch test-pkgResult:
✔ Successfully published branch! Install with command:
→ npm i 'repo-b#test-pkg'
