cmelion/generator-ng2-webpack repository overview

Now that Angular2 has moved to Webpack, the need for this generator is less of a priority for me. I'm working on a new one⁠ based on Redux-Observable⁠ that will support either Angular2 or React as well as a seamless mixture of the two. Work on this repo will be limited to bug-fixes and pull-requests.

⁠generator-ng2-webpack

An opinionated BYOBE⁠ tool (Yeoman⁠ generator) for scaffolding an app using angular2 and webpack

We like React too! So if you have some react components you want to use in your Angular 2 apps we will be adding a sub-generator very soon! For now check out the about component in the generated app⁠ for a taste of what you can do.

⁠Credits

This generator was inspired by:

• https://github.com/preboot/angular-webpack⁠
• https://github.com/AngularClass/angular2-webpack-starter⁠
• https://github.com/mcfly-io/generator-ng2-webpack⁠
• http://www.syntaxsuccess.com/viewarticle/integrating-react-with-angular-2.0⁠

Sample generator output⁠

⁠Installation

First, install Yeoman⁠ and generator-ng2-webpack using npm⁠. If you don't already have node.js/npm installed, we recommend using nvm⁠ (windows users may want to consult the wiki⁠).

npm install -g yo
npm install -g generator-ng2-webpack

Then generate your new project:

# create an application directory
$mkdir my-app

# change directory to your app
$ cd my-app

yo ng2-webpack [project-name]

You then have access to the following sub generators:

• yo ng2-webpack:service (Creates a service)
• yo ng2-webpack:pipe (Creates a pipe)
• yo ng2-webpack:component (Creates a component)
• yo ng2-webpack:directive (Creates a directive)
• yo ng2-webpack:interface (Creates an interface)

Resulting in a complete, yet simple, starter for Angular using Webpack.

You may prefer to use npm to run your sub-generators. For a complete list of available commands and to add tab auto-completion, run the following commands in a terminal:

$ npm completion >> ~/.bashrc
$ source ~/.bashrc
$ npm run <tab><tab>

which will produce the following output

build                 docker-open-terminal  e2e-live              new-service           watch
ci                    docker-server         lint                  postinstall           webdriver-start
clean                 docker-start          new-component         server                webdriver-update
clean-install         docker-stop           new-directive         start                 
clean-start           docs                  new-interface         test                  
delayed-open          e2e                   new-pipe              test-watch  
 

This workflow serves as a starting point for building component based Angular 2.0 applications using Webpack.

• Heavily commented webpack configuration with reasonable defaults.
• ES6, and ES7 support with babel.
• Source maps included in all builds.
• Development server with live reload.
• Production builds with cache busting.
• Testing environment using karma to run tests and jasmine as the framework.
• Code coverage when tests are run.
• No gulp and no grunt, just npm scripts.

⁠Quick start

# change directory to your app
$ cd my-app

# start the server
$ npm start

go to http://localhost:2368⁠ in your browser.

⁠Table of Contents

• Getting Started⁠
  • File Structure⁠
  • Dependencies⁠
  • Installing⁠
  • Running the app⁠
  • Developing⁠
  • Testing⁠
  • Roadmap⁠
  • FAQ⁠
• License⁠

⁠Getting Started

⁠File Structure

├── app/                            * top level web app component folder
│   ├── components/                 * subcomponents
│   │   ├── about/                  * example page level component folder
│   │   │   ├── index.async.ts      * .async indicates that the component will be asychronously loaded
│   │   │   ├── spec.ts             * unit test
│   │   │   ├── style.scss          * css styles, could be css, less or sass
│   │   │   └── template.html       * component's html template
│   │   └── home/                   * example main page level component
│   │       ├── e2e.js              * end-to-end test for home
│   │       ├── index.ts            * a simple synchronous component
│   │       ├── spec.ts             * 
│   │       ├── style.scss          * 
│   │       └── template.html       * 
│   ├── e2e.js                      * end-to-end test for the app component
│   ├── index.ts                    * the app component
│   ├── root.spec.ts                * the main entry point for hierarchically nested tests.
│   ├── services/                   * app level service folder
│   │   └── api/                    * example application level service folder
│   │       ├── index.ts            * example service
│   │       └── spec.ts             * unit test associated with example service
│   ├── style.scss                  * application component specific styles
│   └── template.html               * application component html template
├── bootstrap.ts                    * application entry point (bootstrap)
├── public/                         * static public facing resources
│   ├── img/                        * global/top level icons and images
│   └── index.html                  * the html index page where it all starts
├── shims/                          * shims an polyfills for non-compliant browsers
│   └── shims_for_IE.js             * sample shim
├── style/                          * 
│   └── app.scss                    * styles required by the index page
└── vendor.ts                       * this is where we import shims/polyfills and core third party libraries

⁠Dependencies

What you need to run this app:

• node and npm (Use NVM⁠)
• Ensure you're running Node (v4.1.x+) and NPM (2.14.x+)

⁠Installing

# create an application directory
$mkdir my-app

# change directory to your app
$ cd my-app

yo ng2-webpack [project-name]

That's it!

⁠Running the app

After you have installed all dependencies you can now run the app with:

npm start

or (if you want to automatically open a browser window)

npm delayed-open

It will start a local server using webpack-dev-server which will watch, build (in-memory), and reload for you. The port will be displayed to you as http://localhost:2368.

⁠Developing

⁠Build files

• single run: npm run build
• build files and watch: npm run watch

⁠Testing

⁠1. Unit Tests

• single run: npm test
• live mode (TDD style): npm run test-watch

⁠Roadmap

• Mocking with JSON Server⁠ - see working example⁠
• Docker⁠ integration
• Support for Eclipse Che⁠

⁠Frequently asked questions

• How do I async load a component?
  • see wiki How-do-I-async-load-a-component-with-AsyncRoute⁠
• I hate that all the files are named index.ts, style.scss and template.html and what happened to my.controller.ts, etc?
  • While it's mostly personal preference, there are several good reasons for standardized filenames, see filename conventions⁠
  • In a component based architecture almost everything is a component, checkout what happened to my .controller. ?⁠
• Why should I use a generator?⁠
• How do I run docker commands from the npm tool window?
  • Install docker run: npm install -g docker-run
  • see wiki Docker Workflow explained⁠
• How do I import third party/vendor libs⁠?
• How do I add Material-Design-Lite(MDL) to a project?
  • see wiki Working with MDL⁠

⁠License

MIT⁠