Home

Awesome

<p align="center"> <img src="https://cloud.githubusercontent.com/assets/1016365/9864650/93a5660a-5b00-11e5-8716-a0d538d12913.png" alt="ng6-starter" width="480px;" > <!-- old img url: http://res.cloudinary.com/angularclass/image/upload/v1431802814/ng6_vrmd60.png --> </p>

NG6 Join Slack Join the chat at https://gitter.im/angularclass/NG6-starter

The de facto starter repo for building scalable apps with Angular, ES6, and Webpack

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:

Check out the JSPM version--an alternative to Webpack as an ES6 build system.

If you're looking for a preliminary Angular 2 build, please use the angular2-webpack-starter.


Table of Contents

Walkthrough

Build System

NG6 uses NPM scripts, 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:

Gulp is the orchestrator:

Check out the JSPM version--an alternative to Webpack as an ES6 build system.

File Structure

We use a componentized approach with NG6. This will be the eventual standard (and particularly helpful, if using Angular's new router) as well as a great way to ensure a tasteful transition to Angular 2, when the time is ripe. Everything--or mostly everything, as we'll explore (below)--is a component. A component is a self-contained concern--may it be a feature or strictly-defined, ever-present element of the UI (such as a header, sidebar, or footer). Also characteristic of a component is that it harnesses its own stylesheets, templates, controllers, routes, services, and specs. This encapsulation allows us the comfort of isolation and structural locality. Here's how it looks:

client
⋅⋅app/
⋅⋅⋅⋅app.js * app entry file
⋅⋅⋅⋅app.html * app template
⋅⋅⋅⋅common/ * functionality pertinent to several components propagate into this directory
⋅⋅⋅⋅components/ * where components live
⋅⋅⋅⋅⋅⋅components.js * components entry file
⋅⋅⋅⋅⋅⋅home/ * home component
⋅⋅⋅⋅⋅⋅⋅⋅home.js * home entry file (routes, configurations, and declarations occur here)
⋅⋅⋅⋅⋅⋅⋅⋅home.component.js * home "directive"
⋅⋅⋅⋅⋅⋅⋅⋅home.controller.js * home controller
⋅⋅⋅⋅⋅⋅⋅⋅home.scss * home styles
⋅⋅⋅⋅⋅⋅⋅⋅home.html * home template
⋅⋅⋅⋅⋅⋅⋅⋅home.spec.js * home specs (for entry, component, and controller)

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:

To run tests, type npm test in the terminal. Read more about testing below.

Getting Started

Dependencies

Tools needed to run this app:

Installing

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 npm start will bundle the app with webpack, launch a development server, and watch all files. The port will be displayed in the terminal.

Tasks

Here's a list of available tasks:

Testing

To run the tests, run npm test.

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. Mocha is the testing suite and Chai is the assertion library. If you would like to change this, see karma.conf.js.

Examples

It's always easier to learn something if you have an examples. Here is a list of repos which based on this starter:

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.scss // 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 npm run 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 npm run component -- --name signup --parent auth will create a signup component at client/app/components/auth/signup.

Running npm run 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.

Starter Kit Support and Questions

Contact us, anytime, regarding anything about this project.


enjoy — PatrickJS