ng6-exportable-seed
This repo serves as a minimal starter for those looking to get up-and-running with Angular and ES6, using Gulp and Webpack for the build process. This seed is not a Yeoman generator. It's a minimal starter with tasks for building the boilerplate. These are its features:
- The best practice in directory/file organization for Angular (allowing for infinite horizontal app scaling)
- A ready-to-go build system for working with ES6
- Tasks for generating additional boilerplate Angular components
- A full testing system in place
- Pre-configured linting tasks
- Support for stylus, less, sass and plain-old css
- An optional exportable project
Table of Contents
Walkthrough
Build System
NG6 uses Gulp and Webpack together for its build system. Yes, you don't need Gulp if you're using Webpack. This is true if your build system is only responsible for file manipulation. However, ours is not.
Webpack
handles all file-related concerns:
- Transpiling from ES6 to ES5 with
Babel
- Explicitly define dependencies using ngInject
- Loading HTML files as modules
- Load fonts and icons as Data-Uris
- Transpiling stylesheets and appending them to the DOM
- Refreshing the browser and rebuilding on file changes
- Hot module replacement for transpiled stylesheets
- Bundling the app
- Loading all modules
- Doing all of the above for
*.spec.js
files as well
Gulp
is the orchestrator:
- Starting and calling Webpack
- Starting a development server (yes, Webpack can do this too)
- Generating boilerplate for the Angular app
Testing Setup
All tests are also written in ES6. We use Webpack to take care of the logistics of getting those files to run in the various browsers, just like with our client files. This is our testing stack:
- Karma
- Webpack + Babel
- Jasmine
To run tests, type npm test
or karma start
in the terminal. Read more about testing below.
Getting Started
Dependencies
Tools needed to run this app:
-
node
andnpm
Once you have these, install the following as globals:
npm install -g gulp karma karma-cli webpack
Installing
-
fork
this repo -
clone
your fork -
npm install -g gulp karma karma-cli webpack
install global cli dependencies -
npm install
to install dependencies
Running the App
NG6 uses Gulp to build and launch the development environment. After you have installed all dependencies, you may run the app. Running gulp
will bundle the app with webpack
, launch a development server, and watch all files. The port will be displayed in the terminal.
Gulp Tasks
Here's a list of available tasks:
export
serve
-
watch
- alias of
serve
- alias of
-
default
(which is the default task that runs when typinggulp
without providing an argument)- runs
serve
.
- runs
-
component
- scaffolds a new Angular component. Read below for usage details.
Testing
To run the tests, run npm test
or karma start
.
Karma
combined with Webpack runs all files matching *.spec.js
inside the
app
folder. This allows us to keep test files local to the component--which
keeps us in good faith with continuing to build our app modularly. The file
spec.bundle.js
is the bundle file for all our spec files that Karma will
run.
Be sure to define your *.spec.js
files within their corresponding component
directory. You must name the spec file like so, [name].spec.js
. If you don't
want to use the .spec.js
suffix, you must change the regex
in
spec.bundle.js
to look for whatever file(s) you want.
Generating Components
Following a consistent directory structure between components offers us the certainty of predictability. We can take advantage of this certainty by creating a gulp task to automate the "instantiation" of our components. The component boilerplate task generates this:
componentName/
componentName.js // entry file where all its dependencies load
componentName.component.js
componentName.controller.js
componentName.html
componentName.styl // scoped to affect only its own template
componentName.spec.js // contains passing demonstration tests
You may, of course, create these files manually, every time a new module is needed, but that gets quickly tedious.
To generate a component, run gulp component --name componentName
.
The parameter following the --name
flag is the name of the component to be
created. Ensure that it is unique or it will overwrite the preexisting
identically-named component.
The component will be created, by default, inside client/app/components
. To
change this, apply the --parent
flag, followed by a path relative to
client/app/components/
.
For example, running gulp component --name signup --parent auth
will create a signup
component at client/app/components/auth/signup
.
Running gulp component --name footer --parent ../common
creates a footer
component at client/app/common/footer
.
Because the argument to --name
applies to the folder name and the actual component name, make sure to camelcase the component names.