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