Creating NPM Package
There are a few simple steps that you have to take when creating a NPM package.
Github
Setup repo
- First create a new github repo
- In the github repo go to settings -> Collaborator & Team
- In the section add a team select eCommerce
Clone repo
Clone the repo the way you like either command line tool or use the github app.
Setup Project
Setup Package.json
- First create a new package.json file
- Take the example code on the right as a base
- Add the json to your package.json
- Change [PACKAGE_NAME] for your package name. Leave the @od/ in there this is the scope of all packages
- Change the [PACKAGE_DESCRIPTION] change the description to your liking, make sure it makes sense for other people
- Change the [NAME_AND_EMAIL] block to the author of the package so we can relate back to that person if we have questions
- Change the [GITHUB_URL] to the url of the repo
- Leave the rest of the settings untouched
- Add .gitignore file to your project (if you already did overwrite the contents with the example on the right)
Setup .npmrc
- Create a file called .npmrc in the root (these are going to be the NPM Settings for this project)
- Copy the contents from the right example into the file and change the email address to yours
Readme File
It's important to create a README.md file in the root of the project, use this file to write a short description of the project. If you project needs certain steps while making changes to it e.g.: your projects requires a build.
Then please describe all steps in the readme in how to get the project running and how to make any changes.
Linking Package
Setup Project Link with WWW
When you are coding in your local you don't want to constantly have to publish your package before you can see the changes in your www page show up. There is a solution for this called NPM Link.
First if you have run in to trouble with EACCESS codes if you don't use sudo when installing a package it's important to first follow these steps: (this is a one time thing)
Make sure you follow option 2 from the following guide (don't use the NPM_CONFIG_PREFIX option!):
Fix NPM Permissions
To set this up follow the steps in the example on the right of the screen.
Full NPM Docs
To read more in detail about NPM Linking see the official docs down below:
NPM Docs
Publishing Package
NPM Version
When you are done coding and you feel confident with your code it's time to "release" and "publish" your code. We do this by running npm version.
Few things to note:
- Always make sure your git repo is clean. this means push all your changes to the git repo otherwise this command will fail
- Normally publishing happens by running npm publish but if you look at the package.json we linked it to npm version in the preversion and postversion scripts.
When you are ready to publish and version your package it's as simple as running npm version [new_version] on your command line.
the new_version string has to be a valid semver string. the options for semver you can find below.
Our versioning system is going to be simple, we will only be using patch, minor or major. Read further for more details on versioning strategy.
- patch
- minor
- major
- prepatch
- preminor
- premajor
- prerelease
Versioning Strategy
Whenever you have first release or a major update select the major tag.
For a new feature or small update use the minor tag
For a non intrusive bug fix use patch tag
Full NPM Docs
To read more in detail about NPM Linking see the official docs down below:
NPM Version
package.json
{
"version": "0.0.1",
"name": "@od/[PACKAGE_NAME]",
"description": "[PACKAGE_DESCRIPTION]",
"scripts": {
"preversion": "git add -A && git push && git push --tags",
"postversion": "npm publish"
},
"author": "[NAME_AND_EMAIL e.g.: Mick Feller <mick.feller@officedepot.com>]",
"license": "UNLICENSED",
"repository": {
"type": "git",
"url": "[GITHUB_URL]"
},
"publishConfig": {
"registry": "http://nexus.uschecomrnd.net:8081/repository/npm-repo/"
}
}
.gitignore
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Runtime data
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# nyc test coverage
.nyc_output
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Bower dependency directory (https://bower.io/)
bower_components
# node-waf configuration
.lock-wscript
# Compiled binary addons (http://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules/
jspm_packages/
# Typescript v1 declaration files
typings/
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL history
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variables file
.env
# General
.DS_Store
.AppleDouble
.LSOverride
# Icon must end with two \r
Icon
# Thumbnails
._*
# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent
# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk# See https://help.github.com/ignore-files/ for more about ignoring files.
# dependencies
/node_modules
# testing
/coverage
# production
/build
# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.npmrc
cache=/app/npm-cache
registry=http://nexus.uschecomrnd.net:8081/repository/npm-group/
_auth=YWRtaW46a0hYIzFsUU4=
email=[YOUR_EMAIL]
NPM Link
cd ~/Sites/workspaces/frontend_global_resources # go into the package directory
npm link # creates global link
cd ~/Sites/workspaces/WWW-Trunk/globalWeb # go into some other package directory.
npm link @od/global-resources # link-install the package (this is the package name from package.json NOT the folder name)