I recently prepared and published a small CLI tool called Repository-Context-Packager to the npm registry. I used npm as my package registry and the standard npm publish for releasing.
The release process started with preparing my package.json file. I set the version to 1.0.0 and added a files array to control what gets published. I also added a bin field for the CLI command, set the engines requirement, and created a prepublishOnly script to run tests and linting automatically before publishing.
Next, I created a .npmignore file to exclude test files, GitHub workflows, and dev documentation. This kept the package size small—only about 27 KB with 11 files. I used npm pack --dry-run to preview the package contents before actually publishing.
Before publishing, I made sure all 76 tests passed with npm test and verified the code quality with npm run lint. Then I committed the package.json changes and created a git tag using git tag -a v1.0.0 -m "Release v1.0.0". After pushing both the commit and tag to GitHub, I ran npm publish to upload the package to the npm registry. Finally, I verified everything by checking the npm package page and testing the installation with npm install -g repository-context-packager.
I was realizing that git tags and npm package versions are completely separate systems. npm reads the version from package.json, not from git tags. I initially created a git tag v1.0.0 and expected npm to automatically show that version, but npm still showed 0.9.0 because that's what was in package.json. The correct workflow is to update package.json first, commit that change, create the git tag, push everything, and then publish.
I also learned how to handle git push conflicts. When I tried to push my tag, it was rejected because the remote had new commits. I used git pull --rebase origin main to update my branch and resolved the conflicts. Another issue was that I had created a tag before updating package.json, so I had to delete it with git tag -d v1.0.0 and git push origin --delete v1.0.0, then recreate it on the correct commit.
Adding a prepublishOnly script that runs npm test && npm run lint was really valuable. It prevents me from accidentally publishing broken code because the publish command stops if tests fail.
The changes I made were minimal and focused on packaging rather than source code. I updated package.json with the new version, added a files array, bin field, engines requirement, prepublishOnly script, and keywords for discoverability. I created a .npmignore file to exclude tests, CI files, and dev documentation. I also updated the README.md with npm installation instructions and version history. The actual source code in the src/ and bin/ directories didn't need any changes.
When my partner tested the release process, they got stuck on two main issues. First, they were confused about the version mismatch—they saw the git tag v1.0.0 but npm showed 0.9.0. I explained that git tags and npm versions are separate systems and that npm reads from package.json. Second, they encountered a git push rejection because of remote commits they didn't have. I showed them how to use git pull --rebase origin main to handle this situation.
The testing session revealed that I needed better documentation explaining the relationship between git tags and package versions. What seemed obvious to me after going through the process wasn't clear to someone doing it for the first time.
Now that the package is published, users can install it globally with npm install -g repository-context-packager. After installation, they can use the repomaster command from anywhere. Common commands include repomaster --version to check the version, repomaster --help to see available options, repomaster . to package the current directory, and repomaster . -o output.txt to save the output to a file.
Top comments (0)