@paulmarshall/bitbucket-npm-public
v1.0.1
Published
Public guide on deployment from Bitbucket to npm registry for public and private packages
Downloads
5
Readme
Getting Started
You're pushing to Bitbucket, which will then pipe the code out to the NPM registry.
Make sure you have setup your repo first and you're on it so it can be included in the package details
You can trigger the pipe code with a push to master, this would mean only stable builds should be pushed to master, everything else on develop. Usual hotfix and feature gitflow rules apply.
As we use Beanstalk to deploy,
it would make sense to deploy to npm with a similar deployment-to-production option.
You can find the Deployments option under Pipelines in the repository menu on Bitbucket.
However, restricted deployments are
premium only
and so normal non manual deployments can get triggered with a push to develop,
which is not what we want,
so stick with a push to master as the trigger for now.
Normal start is with initialising node.js:
npm init
Use the following flag to add the scope into package.json.
npm init --scope=the-name-of-your-package
When working with private packages for either your username or organisation, you should scope from the init
npm init --scope=@my-org
or
npm init --scope=@my-username
Be aware, if you switch your account to be paid, your original username becomes the org to maintain its status, so you'll need to logout and login again or you'll get a build fail.
You'll be able to set 'Collaborators' on your private package page, they themselves will need to be paid members of npmjs to access the package.
Give the package a name with hyphens.
If you're working with scope, your package name should be @username/package-name.
Set the version number to 1.0.0. Always follow the standard NPM versioning setup.
|Code status | Stage | Rule | Example version|
|:---:|---|---|---:|
|First release | New product | Start with 1.0.0 | 1.0.0 |
|Backward compatible bug fixes | Patch release | Increment the third digit | 1.0.1 |
|Backward compatible new features | Minor release | Increment the middle digit and reset last digit to zero | 1.1.0|
|Changes that break backward compatibility | Major release | Increment the first digit and reset middle and last digits to zero | 2.0.0|
You can bump your version with npm before each push/merge to master, but don't.
npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
'npm [-v | --version]' to print npm version
'npm view <pkg> version' to view a package's published version
'npm ls' to inspect current package/dependency versions
And with a commit message, but don't do that either.
npm version patch -m "Upgrade to %s for reasons"
The pipe we'll use itself has
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
which works really well, but you have to remember to let it do the work and fetch the resulting tags. Update major/minor/patch there if need be. Note the push --tags flag, which can lead to a few merge issues where you need to pull the authored change from the bitbucket-pipelines.
Try commit on develop, move to master, merge in develop, push to master, wait for the pipeline to execute, then do a fetch including all tags.
You could do manual, as the package will be rejected if you fail to bump manually anyway. Either way, fetch all tags as well to make sure that any Bitbucket changes get pulled.
Include a brief description, remember to include what the package actually does and any things to look out for
Leave the entry point as index.js
Check git repository is correct
Add keywords
Add author
Add license (default is usually fine)
Log in to NPM
npm login
Enter your Username, you set this when you signed up for NPM, this is not your email address
Enter your Password, same as the one that logs you in to NPM
Enter your Email address
Push to NPM
If you have a private (paid) account
npm publish
npm assumes any package published without the --access=public flag is meant to be private, so if you don't have a paid account you'll get an error, private = paid.
If you only have a public account or you want to publish a public package on a paid account
npm publish --access=public
This puts the package on the registry and should be the only time you use that method preferring to move to CI via BitBucket.
Create token
You need to create a custom token to give to Bitbucket to allow it to pipe it through to your npm account
npm token create
You can then add this to your Bitbucket account by clicking on your profile in Bitbucket and then on Bitbucket settings
On the menu on the left at the bottom is PIPELINES > Account variables
In there you can specify NPM_TOKEN, which you generated above in Create token which can be used in your bitbucket-pipelines.yml file, which should be created in the root.
e.g. NPM_TOKEN: $NPM_TOKEN
You can mask and encrypt the variable for the token by clicking the padlock icon. See Variables in pipelines for more on this and variables in general for Bitbucket
If you change an account from normal to paid, this will most likely invalidate any tokens and they should be deleted and replaced.
Bitbucket pipeline
You can setup the bitbucket-pipelines.yml, a file which should live in the root of your project, using the Available pipes, ours is based on NPM publish
Here are some generic examples, we could push to the npm registry when we update the master branch, it would be safer and more familiar to use the manual deployment-to-production option, but that is a premium option.
Default example (don't use this)
# This is a sample build configuration for JavaScript.
# Check our guides at https://confluence.atlassian.com/x/14UWN for more examples.
# Only use spaces to indent your .yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:6.9.4
pipelines:
default:
- step:
caches:
- node
script: # Modify the commands below to build your repository.
- npm install
- npm test
Basic example (don't use this)
image: node:8.15.1
script:
- pipe: atlassian/npm-publish:0.2.2
variables:
NPM_TOKEN: $NPM_TOKEN
Advanced example (don't use this)
image: node:8.15.1
script:
- pipe: atlassian/npm-publish:0.2.2
variables:
NPM_TOKEN: $NPM_TOKEN
FOLDER: 'package1'
Master branch example (you can USE THIS ONE for both public & private packages)
image: node:8.15.1
pipelines:
branches:
master:
- step:
script:
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
- pipe: atlassian/npm-publish:0.2.2
variables:
NPM_TOKEN: $NPM_TOKEN
# FOLDER: '<string>' # Optional.
# EXTRA_ARGS: '<string>' # Optional.
# DEBUG: '<boolean>' # Optional.
- npm install
Deployment example (don't use this)
image: node:8.15.1
pipelines:
default:
- step:
name: Publish to npm
deployment: production
script:
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
- pipe: atlassian/npm-publish:0.2.0
variables:
NPM_TOKEN: $NPM_TOKEN
# FOLDER: '<string>' # Optional.
# EXTRA_ARGS: '<string>' # Optional.
# DEBUG: '<boolean>' # Optional.
- npm install
Manual deployment example (this would be better to use, but doesn't show up without Premium only option )
image: node:8.15.1
pipelines:
default:
- step:
name: Default step before push to npm
script:
- npm install
- step:
name: Deploy to npm
deployment: production
trigger: manual
script:
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
- pipe: atlassian/npm-publish:0.2.0
variables:
NPM_TOKEN: $NPM_TOKEN
# FOLDER: '<string>' # Optional.
# EXTRA_ARGS: '<string>' # Optional.
# DEBUG: '<boolean>' # Optional.
- npm install
Private example (don't use this)
image: node:8.15.1
pipelines:
default:
- step:
script:
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
# Generates a .npmrc file configured for installing private modules:
#
# NPM_REGISTRY_URL: the full URL of your private registry
# defaults to registry.npmjs.org.
# NPM_TOKEN: secret token for installing private modules. This
# this token can be found in your .npmrc, after logging in.
- printf "//`node -p \"require('url').parse(process.env.NPM_REGISTRY_URL || 'https://registry.npmjs.org').host\"`/:_authToken=${NPM_TOKEN}\nregistry=${NPM_REGISTRY_URL:-https://registry.npmjs.org}\n" >> ~/.npmrc
# installs public and private modules.
- npm install
Private branch example for enterprise (don't use this)
image: node:8.15.1
pipelines:
branches:
master:
- step:
script:
- npm version patch -m "Upgrade to %s [skip ci]"
- git push && git push --tags
# Generates a .npmrc file configured for installing private modules:
#
# NPM_REGISTRY_URL: the full URL of your private registry
# defaults to registry.npmjs.org.
# NPM_TOKEN: secret token for installing private modules. This
# this token can be found in your .npmrc, after logging in.
- printf "//`node -p \"require('url').parse(process.env.NPM_REGISTRY_URL || 'https://registry.npmjs.org').host\"`/:_authToken=${NPM_TOKEN}\nregistry=${NPM_REGISTRY_URL:-https://registry.npmjs.org}\n" >> ~/.npmrc
# installs public and private modules.
- npm install
These follow a few basics structures to get you up and running but you can be more specific if required just remember to use spaces and not tabs!
You can validate your code in the bitbucket-pipelines.yml, which should help clear any issues
Here's the structure if you want to do anything else:
pipelines:marks the beginning of all your pipeline definitions.
default: contains the steps that will run on every push.
step : each step starts a new Docker container that includes a clone of your repository, and then runs the contents of your script section inside it.
script : a list of commands that are executed in sequence.
Which looks like:
pipelines:
default:
- step:
script:
- echo 'I made a pipeline!'
If you want to push to npm using branches,
when you commit to master,
the bitbucket-pipelines.yml automatically updates the registry.
You need to go into Pipelines to commit the file,
but make sure you have a copy of your files in master before otherwise the build will fail,
as it won't be able to find the package.json file.
You can see the progess of the pipeline under 'Pipelines' in your repo menu.
https://bitbucket.org/(your-bitbucket-username)/(your-repo-name)/addon/pipelines/home#!/
This will show your commit history and success/failure statuses.
If successful, you should get an email from the npm registry informing you of the update successfully deploying.
##Using the package Ensure you setup npm in your project
npm init
Then run the install
npm i @username/package-name
The last script in the pipe is npm install, but you should check the dependencies of the package and manually install if this doesn't work
cd the-package-directory
npm install
##npm Unpublish Policy What to do if your package was published less than 72 hours ago If the package is still within the first 72 hours, you should use one of the following from your command line:
npm unpublish <package_name> -f to remove the entire package thanks to the -f or force flag
npm unpublish <package_name>@ to remove a specific version
Some considerations:
Once package@version has been used, you can never use it again.
You must publish a new version even if you unpublished the old one
If you entirely unpublish a package, nobody else (even you) will be able to publish a package of that name for 24 hours.