ws-directives
Angular directives shared between our UIs.
installation
install 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:
- angularjs
- wealthsimple-fabric
- angular-animate
- angular-ui-router
- angular-translate
Check peerDependencies
in package.json
for specific versions.
usage
Checkout out our fancy Github page!
local development
- run
yarn install
to install dev dependencies - run
yarn start:dev
o 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 project
Use yarn link
if you'd like to reference this library locally from another ng project
- run
yarn link
in root of this library - run
yarn link @wealthsimple/angular-directives
in the root of the other ng project to refer to your local version of this library.
publishing
If 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 npm
package registry.
Once you merge a change to master, follow the steps below to issue a new release of this package:
1. prepare a PR with a new version number.
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.
Once you've picked a new version number, update the version
field in package.json
to that version. This is what NPM will use. Also run this command locally:
npm run prepublishOnly
This will regenerate the github-pages content in docs
.
Before making a PR, make sure to run yarn install
to update the package-lock.json
file
Get this PRed up and approved, then merge it.
At this point gh-pages is using the new code
2. prepare a new release
- Go to the 'releases' tab in github.
- Hit the 'draft new release button'. Use the
master
branch only please. This will prompt you to enter some info about what's in the new release. Be descriptive! This serves as our changelog, and your colleagues will thank you. Screenshots of new controls/features are handy too.
3. publish
For npm
you 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.
3. consume
In the consumer (e.g. Terminal), update your package.json
to the newest version of "@wealthsimple/angular-directives": "^7.X.X"
and run yarn install
to ensure your package-lock.json
is synced.
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:
- add it to
peerDependencies
inpackage.json
: specify a version range that we'll commit to working with. Our webpack config loads the list ofpeerDependencies
and marks them asexternal
, meaning if youimport
them in code, webpack won't include them in our bundle. - also add a specific version to
devDependencies
so you can develop against it - but since it's not in the bundle, you'll have to edit
index.html
to 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.
The good news is we do expect consumers to target modern JavaScript runtimes, with polyfills as necessary (e.g. core-js). Which means you can use array.map
, array.prototype.includes
, array.prototype.reduce
, array.prototype.filter
, 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?
- Run the unit tests to make sure the new lib is available to the test setup:
yarn run test
. - Run the example page in devmode to make sure you got any CDN additions right:
yarn start:dev
,open http://localhost:8080
. - 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