If you want to create a new web interface or web interface component, and you don't want to have to
manually install all the dependencies to get the project going (grunt
, karma
, webpack
, etc.), this is for you.
These steps work best on an empty repository (a new project) but are safe to do in an existing project, you just may not get the best of everything because we won't overwrite or extend files that already exist.
Make sure you have Node.js and npm installed in your development environment. Use nvm it will make your life much easier.
Make sure lib-curl is installed. On Ubuntu, you can do the following:
sudo apt-get install libcurl4-openssl-dev
If you want to be able to run the e2e-test
target that uses webdriverio
and webdrivercss
, you need to install
the following dependencies as well: graphicsmagick
and cairo
brew install Caskroom/cask/xquartz # <- if you don't have X11
brew install graphicsmagick cairo
sudo apt-get install raphicsmagick cairo
Run the following command in your project directory to install this package and all of its dependencies:
npm install beaker
You should now have all of the beaker dependencies added to your project in the directory node_modules
.
Now that we have the npm dependencies installed lets setup our initial project environment. Run the following command at the root of your project.
./node_modules/.bin/beaker init --type webpack
The --type
flag specifies what
kind of project you are creating. Possible values are currently
node
- an npm module intended for consumption in a nodejs environmentwebpack
- a webpack bundle projectapp
- a webpack app project
This will populate your project root with a few initial files/folders. For a listing of what will be created you can use:
./node_modules/.bin/beaker help init
If you are unfamiliar with Grunt you may want to head over to Grunt's getting started page and learn more about it.
We should now have our basic project setup. Try running the following command to see if everything works:
source env.sh
grunt
If the command works and you see a message along the lines of:
Running "webpack-dev-server:start" (webpack-dev-server) task
If you're a vim
(with syntastic
) user (and you should be ๐), you may also want to configure
your .vimrc
to be able to properly reference the extra eslint-rules
directory we have in the beaker
directory. An example of what to add to your .vimrc
can be found
here
The following grunt
tasks and make
targets have been provided to allow for rapid development
The default grunt
task will launch the webpack-dev-server
in
hot mode this allows you to point your browser at
the following URLs:
- http://localhost:8080/ - view demo (refresh after changing files)
- http://localhost:8080/webpack-dev-server/ - same as above, but with status banner and hot-reloading
The dev
task will build your app and then watch files and re-build whenever you change something. This is not quite
as fast as using the webpack-dev-server
, since it has to write everything to disk and doesn't cache anything.
However, it has the added beneifit of being able to be served by any static file web server.
The build
task will build your component demo (or your app for production). It will optimize your bundle by using
UglifyJS to minify your code, and the dedupe plugin to remove duplicate modules.
Checks your code for lint.
A CI-friendly test that executes tests once and exits
This is a simple make target that does a grunt karma:unit watch:karma
. This will cause the karma
server to
start and a watcher to be placed on all the files in src/
. So, when any file is changed, all your karma tests
will be run. It's still a little slow because of the source-maps being generated.
This just starts the karma server, without any watchers, in case you wanna run scoped specs (see below).
This translates to doing a karma run
with the --grep=<pattern>
option given to karma-jasmine
. This will
effectively xit()
any specs that don't match the pattern, so that you can run just a subset of specs, without
having to manually change it()
to xit()
in your source code.
Currently, this only works with simple text (no-whitespace) patterns. Such as:
make foo-bar.test
If you wanna play with more advanced patterns, you can use the karma command directly:
karma run node_modules/beaker/config/karma/config.js -- --grep=<pattern>
If you are going to be adding functionality to beaker
keep in mind the following regarding dependencies.
The package.json
for beaker
has three different dependency sections, each with their own specific purpose.
These are dependencies that are required outside of beaker
things like karma
, grunt
, eslint
etc.
All packages defined in peerDependencies
get installed alongside beaker
my-project/
node_moudles/
beaker/
karma/
grunt/
eslint/
NOTE Since, they're installed alongside the package in question
peerDependencies
are not installed when runningnpm install
from within the project that contains them. If you need access to the package within the project as well, seedevDependencies
below.
These are dependencies that beaker
requires to function, but are not needed outside of beaker
.
Some examples would be internal libraries needed for beaker
to function, like http-sync
, which is used
to make synchronous http requests to GitHub.
All packages defined in dependencies
get installed within beaker
my-project/
node_modules/
beaker/
node_modules/
http-sync/
NOTE Since, they're installed within the package in question
dependencies
are installed both when someone else installs the package, and whennpm install
is called from within the project. Because they are both installed when someone else installsbeaker
you never want the same package in bothdependencies
andpeerDependencies
. Otherwise you can end up with something like:
my-project/
node_modules/
beaker/
node_modules/
http-sync/
http-sync/
If beaker
needs something that it defines in it's peerDependencies
like, for example, eslint
(I mean, we want to lint the code in beaker
too, right?) then, we need to include that dep in both
peerDependencies
and devDependencies
.
All packages defined in devDependencies
get installed within beaker
but only when npm install
is run
from within the beaker
project, not when another project installs beaker
. So, it also doesn't make any
sense to have the same package in both dependencies
and devDependencies
, since they're both installed with a local
npm install
.
When you install this npm package it will include all of the following npm packages as dependencies:
- grunt-karma
- grunt-eslint
- grunt-filenames
- karma
- karma-chrome-launcher
- karma-cli
- karma-js-coverage
- karma-jasmine
- karma-spec-reporter
We also include code from the following sources.
- nodeca (some eslint rules)