Package Management

When used properly, npm simplifies dependency management while making your code more modular.

This isn't documentation for npm. All web engineers - FE/BE - should be familiar with npm install - read the docs on npmjs.org.

Note: We used to use bower for Web package management but are now doing everything with npm. For info on bower see the prior version of this file.

Where do packages come from????

npm can install from multiple locations, including:

• GitHub URLs, like npm install github:vokal/vokal-engineering
• The npm registry, like npm install express
• From another location on your machine, like npm install ../something or npm install . -g to install a local directory globally

See this link for more

Specific versions are referenced in different ways depending on the install source. On GitHub you can install any specific tag or sha, and the npm registry supports installing by semver.

With any install command include --save or --save-dev as needed to write the dependency into the local package.json.

OK, so what can I do besides install stuff?

You can create modular dependencies that live on GitHub and npm. All forks of OSS, public repos that never made it to npm, and your own module code should be kept as separate repos, out of your main project source code, and referenced as a package.

Writing modular self-contained code is important for our internal code reuse, and when appropriately released as OSS, is important to Vokal's reputation. It is preferable that all modules are forked properly so they have the potential to be merged back into master or mutate into some other awesome thing.

For clients that have multiple repos, never copy/paste functional code or styles between repos, always choose a location on one of the existing repos or on a new repo to store that shared content.

So don't download a zip file and extract it into your project. You are fooling yourself if you do that thinking you might get around to patching the upstream eventually, don't do it.

Forks of OSS should generally maintain the coding standards of the upstream version unless you want to create a fork that you clearly know will never be merged back upstream. If you are not sure, use the upstream coding standards.

Publishing to npm

Vokal has an account at npm that should be the owner of any projects that are also owned by Vokal on GitHub and need to be published to npm. The same pattern of allowing project maintainers to publish directly can be granted via the Vokal account making engineer accounts contributors on npm. When publishing to npm, be mindful of keeping the correct version in package.json. If you are on Windows, be aware that npm doesn't currently normalize line endings, so watch not to publish anything in /bin with CRLF line endings.

What about Git Submodules or some other scary git thing?

Web projects should not use them.