@paulmarshall/bitbucket-npm-public

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.