|
| 1 | +# Angular 2 QuickStart Source |
| 2 | + |
| 3 | +This repository holds the TypeScript source code of the [angular.io quickstart](https://angular.io/docs/ts/latest/quickstart.html), |
| 4 | +the foundation for most of the documentation samples and potentially a good starting point for your application. |
| 5 | + |
| 6 | +It's been extended with testing support so you can start writing tests immediately. |
| 7 | + |
| 8 | +**This is not the perfect arrangement for your application. It is not designed for production. |
| 9 | +It exists primarily to get you started quickly with learning and prototyping in Angular 2** |
| 10 | + |
| 11 | +We are unlikely to accept suggestions about how to grow this QuickStart into something it is not. |
| 12 | +Please keep that in mind before posting issues and PRs. |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + |
| 16 | +Node.js and npm are essential to Angular 2 development. |
| 17 | + |
| 18 | +<a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm"> |
| 19 | +Get it now</a> if it's not already installed on your machine. |
| 20 | + |
| 21 | +**Verify that you are running at least node `v5.x.x` and npm `3.x.x`** |
| 22 | +by running `node -v` and `npm -v` in a terminal/console window. |
| 23 | +Older versions produce errors. |
| 24 | + |
| 25 | +We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm. |
| 26 | + |
| 27 | +## Create a new project based on the QuickStart |
| 28 | + |
| 29 | +Clone this repo into new project folder (e.g., `my-proj`). |
| 30 | +```bash |
| 31 | +git clone https://github.com/angular/quickstart my-proj |
| 32 | +cd my-proj |
| 33 | +``` |
| 34 | + |
| 35 | +We have no intention of updating the source on `angular/quickstart`. |
| 36 | +Discard everything "git-like" by deleting the `.git` folder. |
| 37 | +```bash |
| 38 | +rm -rf .git // non-Windows |
| 39 | +rd .git /S/Q // windows |
| 40 | +``` |
| 41 | + |
| 42 | +### Create a new git repo |
| 43 | +You could [start writing code](#start-development) now and throw it all away when you're done. |
| 44 | +If you'd rather preserve your work under source control, consider taking the following steps. |
| 45 | + |
| 46 | +Initialize this project as a *local git repo* and make the first commit: |
| 47 | +```bash |
| 48 | +git init |
| 49 | +git add . |
| 50 | +git commit -m "Initial commit" |
| 51 | +``` |
| 52 | + |
| 53 | +Create a *remote repository* for this project on the service of your choice. |
| 54 | + |
| 55 | +Grab its address (e.g. *`https://github.com/<my-org>/my-proj.git`*) and push the *local repo* to the *remote*. |
| 56 | +```bash |
| 57 | +git remote add origin <repo-address> |
| 58 | +git push -u origin master |
| 59 | +``` |
| 60 | +## Install npm packages |
| 61 | + |
| 62 | +> See npm and nvm version notes above |
| 63 | +
|
| 64 | +Install the npm packages described in the `package.json` and verify that it works: |
| 65 | + |
| 66 | +**Attention Windows Developers: You must run all of these commands in administrator mode**. |
| 67 | + |
| 68 | +```bash |
| 69 | +npm install |
| 70 | +npm start |
| 71 | +``` |
| 72 | + |
| 73 | +> If the `typings` folder doesn't show up after `npm install` please install them manually with: |
| 74 | +
|
| 75 | +> `npm run typings -- install` |
| 76 | +
|
| 77 | +The `npm start` command first compiles the application, |
| 78 | +then simultaneously re-compiles and runs the `lite-server`. |
| 79 | +Both the compiler and the server watch for file changes. |
| 80 | + |
| 81 | +Shut it down manually with Ctrl-C. |
| 82 | + |
| 83 | +You're ready to write your application. |
| 84 | + |
| 85 | +### npm scripts |
| 86 | + |
| 87 | +We've captured many of the most useful commands in npm scripts defined in the `package.json`: |
| 88 | + |
| 89 | +* `npm start` - runs the compiler and a server at the same time, both in "watch mode". |
| 90 | +* `npm run tsc` - runs the TypeScript compiler once. |
| 91 | +* `npm run tsc:w` - runs the TypeScript compiler in watch mode; the process keeps running, awaiting changes to TypeScript files and re-compiling when it sees them. |
| 92 | +* `npm run lite` - runs the [lite-server](https://www.npmjs.com/package/lite-server), a light-weight, static file server, written and maintained by |
| 93 | +[John Papa](https://github.com/johnpapa) and |
| 94 | +[Christopher Martin](https://github.com/cgmartin) |
| 95 | +with excellent support for Angular apps that use routing. |
| 96 | +* `npm run typings` - runs the typings tool. |
| 97 | +* `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation. This script installs the TypeScript definition files this app requires. |
| 98 | +Here are the test related scripts: |
| 99 | +* `npm test` - compiles, runs and watches the karma unit tests |
| 100 | +* `npm run e2e` - run protractor e2e tests, written in JavaScript (*e2e-spec.js) |
| 101 | + |
| 102 | +## Testing |
| 103 | + |
| 104 | +The QuickStart documentation doesn't discuss testing. |
| 105 | +This repo adds both karma/jasmine unit test and protractor end-to-end testing support. |
| 106 | + |
| 107 | +These tools are configured for specific conventions described below. |
| 108 | + |
| 109 | +*It is unwise and rarely possible to run the application, the unit tests, and the e2e tests at the same time. |
| 110 | +We recommend that you shut down one before starting another.* |
| 111 | + |
| 112 | +### Unit Tests |
| 113 | +TypeScript unit-tests are usually in the `app` folder. Their filenames must end in `.spec`. |
| 114 | + |
| 115 | +Look for the example `app/app.component.spec.ts`. |
| 116 | +Add more `.spec.ts` files as you wish; we configured karma to find them. |
| 117 | + |
| 118 | +Run it with `npm test` |
| 119 | + |
| 120 | +That command first compiles the application, then simultaneously re-compiles and runs the karma test-runner. |
| 121 | +Both the compiler and the karma watch for (different) file changes. |
| 122 | + |
| 123 | +Shut it down manually with Ctrl-C. |
| 124 | + |
| 125 | +Test-runner output appears in the terminal window. |
| 126 | +We can update our app and our tests in real-time, keeping a weather eye on the console for broken tests. |
| 127 | +Karma is occasionally confused and it is often necessary to shut down its browser or even shut the command down (Ctrl-C) and |
| 128 | +restart it. No worries; it's pretty quick. |
| 129 | + |
| 130 | +The `HTML-Reporter` is also wired in. That produces a prettier output; look for it in `~_test-output/tests.html`. |
| 131 | + |
| 132 | +### End-to-end (E2E) Tests |
| 133 | + |
| 134 | +E2E tests are in the `e2e` directory, side by side with the `app` folder. |
| 135 | +Their filenames must end in `.e2e-spec.ts`. |
| 136 | + |
| 137 | +Look for the example `e2e/app.e2e-spec.ts`. |
| 138 | +Add more `.e2e-spec.js` files as you wish (although one usually suffices for small projects); |
| 139 | +we configured protractor to find them. |
| 140 | + |
| 141 | +Thereafter, run them with `npm run e2e`. |
| 142 | + |
| 143 | +That command first compiles, then simultaneously starts the Http-Server at `localhost:8080` |
| 144 | +and launches protractor. |
| 145 | + |
| 146 | +The pass/fail test results appear at the bottom of the terminal window. |
| 147 | +A custom reporter (see `protractor.config.js`) generates a `./_test-output/protractor-results.txt` file |
| 148 | +which is easier to read; this file is excluded from source control. |
| 149 | + |
| 150 | +Shut it down manually with Ctrl-C. |
0 commit comments