ws-directivesAngular directives shared between our UIs.
installationinstall it locally with npm
npm install --save @wealthsimple/angular-directives
or with yarn
yarn add @wealthsimple/angular-directives
make sure you also have the following installed:
package.jsonfor specific versions.
usageCheckout out our fancy Github page!
yarn installto install dev dependencies
yarn start:devo watch & build files, and serve up the examples page.
- open http://localhost:8080 in your browser to preview your changes.
As you make changes, the output will be rebuilt and the browser will re-load your changes automatically.
hooking your local copy into another projectUse
yarn linkif you'd like to reference this library locally from another ng project
yarn linkin root of this library
yarn link @wealthsimple/angular-directivesin the root of the other ng project to refer to your local version of this library.
publishingIf you have merge rights, you should also have the ability to release new versions (you know who to ask for access).
We currently publish on the
Once you merge a change to master, follow the steps below to issue a new release of this package:
Please follow semantic versioning. Seriously, this is super important. If you don't and downstream users are careless with their shrinkwrapping strategy, you may break them.
- prepare a PR with a new version number.
Once you've picked a new version number, update the
package.jsonto that version. This is what NPM will use. Also run this command locally:
npm run prepublishOnly
This will regenerate the github-pages content in
Before making a PR, make sure to run
yarn installto update the
Get this PRed up and approved, then merge it.
At this point gh-pages is using the new code
- prepare a new release
- Go to the 'releases' tab in github.
- Hit the 'draft new release button'. Use the
masterbranch only please. This will prompt
npmyou need to manually publish. Go to your terminal, rebase latest master, and run:
npm login npm publish
This runs the unit tests and uploads the source to
npm's registry. Note that as of 5.0.0 we don't distribute transpiled ES5/CSS any more. Consumers are expected to transpile the ES6/SCSS using their own toolchain.
In the consumer (e.g. Terminal), update your
package.jsonto the newest version of
"@wealthsimple/angular-directives": "^7.X.X"and run
yarn installto ensure your
My awesome new feature requires me to use amazing-3rdparty-lib.js. Can I add it as a dependency?Sure, make a PR. Get someone from #web-tech-maintenance to review it though, so we can check that the license is in line with policies, etc. Be aware that this is the start of the conversation though. Pulling in new libs requires a little extra diligence from the broader team.
Also think about whether it should be a dependency or a peerDependency.
Dependencies:These are for things that you don't expect consumers to also be using. So, really specific libs that are implementation details of a component for example.
Generally it should be pretty rare to add new dependencies.
PeerDependencies:Peer dependencies are for things that you expect consumers to also be using directly. We expect consumers to install them alongside ws-directives (npm will give them an error if they don't).
So for example, AngularJS is a peer dependency.
Most of the time, new deps will be peer dependencies.
To add a peerDependency, do three things:
1) add it to
package.json: specify a version range that we'll commit to working with. Our webpack config loads the list of
peerDependenciesand marks them as
external, meaning if you
importthem in code, webpack won't include them in our bundle. 2) also add a specific version to
devDependenciesso you can develop against it 3) but since it's not in the bundle, you'll have to edit
index.htmlto pull the lib in from a CDN. I recommend http://unpkg.com, which is a thin wrapper over the npm registry exposed as a CDN.
Can I use underscore/lodash/ramda? Pleaaase?My default stance is: yes in consuming projects, but probably not in ws-directives. Those libs are pretty big and I don't want to force consumers to include them.
Array.prototype.forEach, etc. That should cover most of your underscore needs. If it doesn't, post in #web-tech-maintenance and we'll discuss it.
How can I check that I got it right?1) Run the unit tests to make sure the new lib is available to the test setup:
yarn run test. 2) Run the example page in devmode to make sure you got any CDN additions right:
open http://localhost:8080. 3) Look at the bundle stats report to make sure the dep is included or not included as appropriate:
yarn build:docs && open docs/report.html