|
| 1 | +[](https://twitter.com/SwiftOnSecurity) |
| 2 | +[](https://github.com/auchenberg/volkswagen) [](https://badge.fury.io/gh/angularclass%2Fangular2-webpack-starter) [](https://david-dm.org/angularclass/angular2-webpack-starter) |
| 3 | +[](http://issuestats.com/github/angularclass/angular2-webpack-starter) |
| 4 | +[](http://issuestats.com/github/angularclass/angular2-webpack-starter) [](http://stackshare.io/angularclass/angular-2-webpack-starter) |
| 5 | + |
| 6 | +<p align="center"> |
| 7 | + <a href="https://angularclass.com" target="_blank"> |
| 8 | + <img src="https://cloud.githubusercontent.com/assets/1016365/9863762/a84fed4a-5af7-11e5-9dde-d5da01e797e7.png" alt="Webpack and Angular 2" width="500" height="320"/> |
| 9 | + </a> |
| 10 | +</p> |
| 11 | + |
| 12 | +# Angular2 Webpack Starter [](https://angularclass.com/slack-join) [](https://gitter.im/angularclass/angular2-webpack-starter?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 13 | + |
| 14 | + |
| 15 | +> An Angular 2 starter kit featuring [Angular 2](https://angular.io) ([Router](https://angular.io/docs/js/latest/api/router/), [Forms](https://angular.io/docs/js/latest/api/forms/), |
| 16 | +[Http](https://angular.io/docs/js/latest/api/http/), |
| 17 | +[Services](https://gist.github.com/gdi2290/634101fec1671ee12b3e#_follow_@AngularClass_on_twitter), |
| 18 | +[Tests](https://angular.io/docs/js/latest/api/test/), [E2E](https://angular.github.io/protractor/#/faq#what-s-the-difference-between-karma-and-protractor-when-do-i-use-which-)), [Karma](https://karma-runner.github.io/), [Protractor](https://angular.github.io/protractor/), [Jasmine](https://github.com/jasmine/jasmine), [Istanbul](https://github.com/gotwarlost/istanbul), [TypeScript](http://www.typescriptlang.org/), [Typings](https://github.com/typings/typings), [TsLint](http://palantir.github.io/tslint/), and [Webpack](http://webpack.github.io/) by [AngularClass](https://angularclass.com). |
| 19 | + |
| 20 | +> If you're looking for Angular 1.x please use [NG6-starter](https://github.com/angularclass/NG6-starter) |
| 21 | +> If you're looking to learn about Webpack and ES6 Build Tools check out [ES6-build-tools](https://github.com/AngularClass/ES6-build-tools) |
| 22 | +> If you're looking to learn TypeScript see [TypeStrong/learn-typescript](https://github.com/TypeStrong/learn-typescript) |
| 23 | +
|
| 24 | +This seed repo serves as an Angular 2 starter for anyone looking to get up and running with Angular 2 and TypeScript fast. Using a [Webpack](http://webpack.github.io/) for building our files and assisting with boilerplate. We're also using Protractor for our end-to-end story and Karma for our unit tests. |
| 25 | +* Best practices in file and application organization for Angular 2. |
| 26 | +* Ready to go build system using Webpack for working with TypeScript. |
| 27 | +* Angular 2 examples that are ready to go when experimenting with Angular 2. |
| 28 | +* A great Angular 2 seed repo for anyone who wants to start their project. |
| 29 | +* Testing Angular 2 code with Jasmine and Karma. |
| 30 | +* Coverage with Istanbul and Karma |
| 31 | +* End-to-end Angular 2 code using Protractor. |
| 32 | +* Type manager with Typings |
| 33 | + |
| 34 | +### Quick start |
| 35 | +> Clone/Download the repo then edit `app.ts` inside [`/src/app/app.ts`](/src/app/app.ts) |
| 36 | +
|
| 37 | +```bash |
| 38 | +# clone our repo |
| 39 | +# --depth 1 removes all but one .git commit history |
| 40 | +git clone --depth 1 https://github.com/angularclass/angular2-webpack-starter.git |
| 41 | + |
| 42 | +# change directory to our repo |
| 43 | +cd angular2-webpack-starter |
| 44 | + |
| 45 | +# install the repo with npm |
| 46 | +npm install |
| 47 | + |
| 48 | +# start the server |
| 49 | +npm start |
| 50 | +``` |
| 51 | +go to [http://0.0.0.0:3000](http://0.0.0.0:3000) or [http://localhost:3000](http://localhost:3000) in your browser |
| 52 | + |
| 53 | +# Table of Contents |
| 54 | +* [File Structure](#file-structure) |
| 55 | +* [Getting Started](#getting-started) |
| 56 | + * [Dependencies](#dependencies) |
| 57 | + * [Installing](#installing) |
| 58 | + * [Running the app](#running-the-app) |
| 59 | +* [Contributing](#contributing) |
| 60 | +* [TypeScript](#typescript) |
| 61 | +* [Typings](#typings) |
| 62 | +* [Frequently asked questions](#frequently-asked-questions) |
| 63 | +* [Support, Questions, or Feedback](#support-questions-or-feedback) |
| 64 | +* [License](#license) |
| 65 | + |
| 66 | + |
| 67 | +## File Structure |
| 68 | +We use the component approach in our starter. This is the new standard for developing Angular apps and a great way to ensure maintainable code by encapsulation of our behavior logic. A component is basically a self contained app usually in a single file or a folder with each concern as a file: style, template, specs, e2e, and component class. Here's how it looks: |
| 69 | +``` |
| 70 | +angular2-webpack-starter/ |
| 71 | + ├──src/ * our source files that will be compiled to javascript |
| 72 | + | ├──main.ts * our entry file for our browser environment |
| 73 | + │ │ |
| 74 | + | ├──index.html * Index.html: where we generate our index page |
| 75 | + │ │ |
| 76 | + | ├──polyfills.ts * our polyfills file |
| 77 | + │ │ |
| 78 | + │ ├──app/ * WebApp: folder |
| 79 | + │ │ ├──app.spec.ts * a simple test of components in app.ts |
| 80 | + │ │ ├──app.e2e.ts * a simple end-to-end test for / |
| 81 | + │ │ └──app.ts * App.ts: a simple version of our App component components |
| 82 | + │ │ |
| 83 | + │ └──assets/ * static assets are served here |
| 84 | + │ ├──icon/ * our list of icons from www.favicon-generator.org |
| 85 | + │ ├──service-worker.js * ignore this. Web App service worker that's not complete yet |
| 86 | + │ ├──robots.txt * for search engines to crawl your website |
| 87 | + │ └──human.txt * for humans to know who the developers are |
| 88 | + │ |
| 89 | + ├──spec-bundle.js * ignore this magic that sets up our angular 2 testing environment |
| 90 | + ├──karma.config.js * karma config for our unit tests |
| 91 | + ├──protractor.config.js * protractor config for our end-to-end tests |
| 92 | + │ |
| 93 | + ├──tsconfig.json * config that webpack uses for typescript |
| 94 | + ├──typings.json * our typings manager |
| 95 | + ├──package.json * what npm uses to manage it's dependencies |
| 96 | + │ |
| 97 | + ├──webpack.config.js * our development webpack config |
| 98 | + ├──webpack.test.config.js * our testing webpack config |
| 99 | + └──webpack.prod.config.js * our production webpack config |
| 100 | +``` |
| 101 | + |
| 102 | +# Getting Started |
| 103 | +## Dependencies |
| 104 | +What you need to run this app: |
| 105 | +* `node` and `npm` (`brew install node`) |
| 106 | +* Ensure you're running the latest versions Node `v4.1.x`+ and NPM `2.14.x`+ |
| 107 | + |
| 108 | +Once you have those, you should install these globals with `npm install --global`: |
| 109 | +* `webpack` (`npm install --global webpack`) |
| 110 | +* `webpack-dev-server` (`npm install --global webpack-dev-server`) |
| 111 | +* `karma` (`npm install --global karma-cli`) |
| 112 | +* `protractor` (`npm install --global protractor`) |
| 113 | +* `typings` (`npm install --global typings`) |
| 114 | +* `typescript` (`npm install --global typescript`) |
| 115 | + |
| 116 | +## Installing |
| 117 | +* `fork` this repo |
| 118 | +* `clone` your fork |
| 119 | +* `npm install` to install all dependencies |
| 120 | +* `typings install` to install necessary typings |
| 121 | +* `npm run server` to start the dev server in another tab |
| 122 | + |
| 123 | +## Running the app |
| 124 | +After you have installed all dependencies you can now run the app. Run `npm run server` to 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://0.0.0.0:3000` (or if you prefer IPv6, if you're using `express` server, then it's `http://[::1]:3000/`). |
| 125 | + |
| 126 | +### server |
| 127 | +```bash |
| 128 | +# development |
| 129 | +npm run server |
| 130 | +# production |
| 131 | +npm run build:prod |
| 132 | +npm run server:prod |
| 133 | +``` |
| 134 | + |
| 135 | +## Other commands |
| 136 | + |
| 137 | +### build files |
| 138 | +```bash |
| 139 | +# development |
| 140 | +npm run build:dev |
| 141 | +# production |
| 142 | +npm run build:prod |
| 143 | +``` |
| 144 | + |
| 145 | +### watch and build files |
| 146 | +```bash |
| 147 | +npm run watch |
| 148 | +``` |
| 149 | + |
| 150 | +### run tests |
| 151 | +```bash |
| 152 | +npm run test |
| 153 | +``` |
| 154 | + |
| 155 | +### watch and run our tests |
| 156 | +```bash |
| 157 | +npm run watch:test |
| 158 | +``` |
| 159 | + |
| 160 | +### run end-to-end tests |
| 161 | +```bash |
| 162 | +# make sure you have your server running in another terminal |
| 163 | +npm run e2e |
| 164 | +``` |
| 165 | + |
| 166 | +### run webdriver (for end-to-end) |
| 167 | +```bash |
| 168 | +npm run webdriver:update |
| 169 | +npm run webdriver:start |
| 170 | +``` |
| 171 | + |
| 172 | +### run Protractor's elementExplorer (for end-to-end) |
| 173 | +```bash |
| 174 | +npm run webdriver:start |
| 175 | +# in another terminal |
| 176 | +npm run e2e:live |
| 177 | +``` |
| 178 | + |
| 179 | + |
| 180 | +# Contributing |
| 181 | +You can include more examples as components but they must introduce a new concept such as `Home` component (separate folders), and Todo (services). I'll accept pretty much everything so feel free to open a Pull-Request |
| 182 | + |
| 183 | +# TypeScript |
| 184 | +> To take full advantage of TypeScript with autocomplete you would have to install it globally and use an editor with the correct TypeScript plugins. |
| 185 | +
|
| 186 | +## Use latest TypeScript compiler |
| 187 | +TypeScript 1.7.x includes everything you need. Make sure to upgrade, even if you installed TypeScript previously. |
| 188 | + |
| 189 | +``` |
| 190 | +npm install --global typescript |
| 191 | +``` |
| 192 | + |
| 193 | +## Use a TypeScript-aware editor |
| 194 | +We have good experience using these editors: |
| 195 | + |
| 196 | +* [Visual Studio Code](https://code.visualstudio.com/) |
| 197 | +* [Webstorm 10](https://www.jetbrains.com/webstorm/download/) |
| 198 | +* [Atom](https://atom.io/) with [TypeScript plugin](https://atom.io/packages/atom-typescript) |
| 199 | +* [Sublime Text](http://www.sublimetext.com/3) with [Typescript-Sublime-Plugin](https://github.com/Microsoft/Typescript-Sublime-plugin#installation) |
| 200 | + |
| 201 | +# Typings |
| 202 | +> When you include a module that doesn't include Type Definitions inside of the module you need to include external Type Definitions with Typings |
| 203 | +
|
| 204 | +## Use latest Typings module |
| 205 | +``` |
| 206 | +npm install --global typings |
| 207 | +``` |
| 208 | + |
| 209 | +## Custom Type Definitions |
| 210 | +When including 3rd party modules you also need to include the type definition for the module |
| 211 | +if they don't provide one within the module. You can try to install it with typings |
| 212 | + |
| 213 | +``` |
| 214 | +typings install node --save |
| 215 | +``` |
| 216 | + |
| 217 | +If you can't find the type definition in the registry we can make an ambient definition in |
| 218 | +this file for now. For example |
| 219 | + |
| 220 | +```typescript |
| 221 | +declare module "my-module" { |
| 222 | + export function doesSomething(value: string): string; |
| 223 | +} |
| 224 | +``` |
| 225 | + |
| 226 | + |
| 227 | +If you're prototyping and you will fix the types later you can also declare it as type any |
| 228 | + |
| 229 | +```typescript |
| 230 | +declare var assert: any; |
| 231 | +``` |
| 232 | + |
| 233 | +If you're importing a module that uses Node.js modules which are CommonJS you need to import as |
| 234 | + |
| 235 | +```typescript |
| 236 | +import * as _ from 'lodash'; |
| 237 | +``` |
| 238 | + |
| 239 | +You can include your type definitions in this file until you create one for the typings registry |
| 240 | +see [typings/registry](https://github.com/typings/registry) |
| 241 | + |
| 242 | +# Frequently asked questions |
| 243 | +* What's the current browser support for Angular 2 Beta? |
| 244 | + * Please view the updated list of [browser support for Angular 2](https://github.com/angularclass/awesome-angular2#current-browser-support-for-angular-2) |
| 245 | +* Why is my service, aka provider, is not injecting parameter correctly? |
| 246 | + * Please use `@Injectable()` for your service for typescript to correctly attach the metadata (this is a TypeScript problem) |
| 247 | +* How do I run protractor with node 0.12.x? |
| 248 | + * please check out this repo to use the old version of protractor [#146](https://github.com/AngularClass/angular2-webpack-starter/pull/146/files) |
| 249 | +* Where do I write my tests? |
| 250 | + * You can write your tests next to your component files. See [`/src/app/home/home.spec.ts`](/src/app/home/home.spec.ts) |
| 251 | +* How do I start the app when I get `EACCES` and `EADDRINUSE` errors? |
| 252 | + * The `EADDRINUSE` error means the port `3000` is currently being used and `EACCES` is lack of permission for webpack to build files to `./dist/` |
| 253 | +* How to use `sass` for css? |
| 254 | + * `loaders: ['raw-loader','sass-loader']` and `@Component({ styles: [ require('./filename.scss') ] })` see issue [#136](https://github.com/AngularClass/angular2-webpack-starter/issues/136) |
| 255 | +* How do I test a Service? |
| 256 | + * See issue [#130](https://github.com/AngularClass/angular2-webpack-starter/issues/130#issuecomment-158872648) |
| 257 | +* How do I add `vscode-chrome-debug` support? |
| 258 | + * The VS Code chrome debug extension support can be done via `launch.json` see issue [#144](https://github.com/AngularClass/angular2-webpack-starter/issues/144#issuecomment-164063790) |
| 259 | +* How do I make the repo work in a virtual machine? |
| 260 | + * You need to use `0.0.0.0` so revert these changes [#205](https://github.com/AngularClass/angular2-webpack-starter/pull/205/files) |
| 261 | +* What are the naming conventions for Angular 2? |
| 262 | + * please see issue [#185](https://github.com/AngularClass/angular2-webpack-starter/issues/185) and PR [196](https://github.com/AngularClass/angular2-webpack-starter/pull/196) |
| 263 | +* How do I include bootstrap or jQuery? |
| 264 | + * please see issue [#215](https://github.com/AngularClass/angular2-webpack-starter/issues/215) and [#214](https://github.com/AngularClass/angular2-webpack-starter/issues/214#event-511768416) |
| 265 | +* I'm getting an error about not finding my module that I installed? |
| 266 | + * please see [How to include or create custom type definitions](https://github.com/AngularClass/angular2-webpack-starter/wiki/How-to-include-or-create-custom-type-definitions) and [custom_typings.d.ts](https://github.com/AngularClass/angular2-webpack-starter/blob/master/src/custom_typings.d.ts) |
| 267 | +* How do I async load a component? |
| 268 | + * the component must have `.async.ts` and require using webpack `loader: () => require('./about/about')('About')` |
| 269 | + |
| 270 | +# Support, Questions, or Feedback |
| 271 | +> Contact us anytime for anything about this repo or Angular 2 |
| 272 | +
|
| 273 | +* [Chat: AngularClass.slack](http://angularclass.com/member-join/) |
| 274 | +* [Twitter: @AngularClass](https://twitter.com/AngularClass) |
| 275 | +* [Gitter: AngularClass/angular2-webpack-starter](https://gitter.im/angularclass/angular2-webpack-starter) |
| 276 | + |
| 277 | +___ |
| 278 | + |
| 279 | +enjoy — **AngularClass** |
| 280 | + |
| 281 | +<br><br> |
| 282 | + |
| 283 | +[](https://angularclass.com) |
| 284 | +##[AngularClass](https://angularclass.com) |
| 285 | +> Learn AngularJS, Angular 2, and Modern Web Development from the best. |
| 286 | +> Looking for corporate Angular training, want to host us, or Angular consulting? [email protected] |
| 287 | +
|
| 288 | +# License |
| 289 | + [MIT](/LICENSE) |
0 commit comments