diff --git a/README.md b/README.md index f7f01a9c8bcd..9050471c72c2 100644 --- a/README.md +++ b/README.md @@ -37,23 +37,9 @@ with NPM 3 or higher. * [Usage](#usage) * [Generating a New Project](#generating-and-serving-an-angular2-project-via-a-development-server) * [Generating Components, Directives, Pipes and Services](#generating-components-directives-pipes-and-services) -* [Generating a Route](#generating-a-route) -* [Creating a Build](#creating-a-build) -* [Build Targets and Environment Files](#build-targets-and-environment-files) -* [Base tag handling in index.html](#base-tag-handling-in-indexhtml) -* [Bundling](#bundling) -* [Running Unit Tests](#running-unit-tests) -* [Running End-to-End Tests](#running-end-to-end-tests) -* [Proxy To Backend](#proxy-to-backend) -* [Linting code](#linting-code) -* [Commands autocompletion](#commands-autocompletion) -* [Project assets](#project-assets) -* [Global styles](#global-styles) -* [CSS preprocessor integration](#css-preprocessor-integration) -* [3rd Party Library Installation](#3rd-party-library-installation) -* [Global Library Installation](#global-library-installation) * [Updating Angular CLI](#updating-angular-cli) * [Development Hints for hacking on Angular CLI](#development-hints-for-hacking-on-angular-cli) +* [License](#license) ## Installation @@ -112,284 +98,6 @@ Interface | `ng g interface my-new-interface` Enum | `ng g enum my-new-enum` Module | `ng g module my-module` -### Generating a route - -The CLI supports routing in several ways: - -- We include the `@angular/router` NPM package when creating or initializing a project. - -- When you generate a module, you can use the `--routing` option like `ng g module my-module --routing` to create a separate file `my-module-routing.module.ts` to store the module routes. - - The file includes an empty `Routes` object that you can fill with routes to different components and/or modules. - - The `--routing` option also generates a default component with the same name as the module. - -- You can use the `--routing` option with `ng new` to create a `app-routing.module.ts` file when you create or initialize a project. - - -### Creating a build - -```bash -ng build -``` - -The build artifacts will be stored in the `dist/` directory. - -### Build Targets and Environment Files - -`ng build` can specify both a build target (`--target=production` or `--target=development`) and an -environment file to be used with that build (`--environment=dev` or `--environment=prod`). -By default, the development build target and environment are used. - -The mapping used to determine which environment file is used can be found in `angular-cli.json`: - -```json -"environments": { - "source": "environments/environment.ts", - "dev": "environments/environment.ts", - "prod": "environments/environment.prod.ts" -} -``` - -These options also apply to the serve command. If you do not pass a value for `environment`, -it will default to `dev` for `development` and `prod` for `production`. - -```bash -# these are equivalent -ng build --target=production --environment=prod -ng build --prod --env=prod -ng build --prod -# and so are these -ng build --target=development --environment=dev -ng build --dev --e=dev -ng build --dev -ng build -``` - -You can also add your own env files other than `dev` and `prod` by doing the following: -- create a `src/environments/environment.NAME.ts` -- add `{ "NAME": 'src/environments/environment.NAME.ts' }` to the `apps[0].environments` object in `angular-cli.json` -- use them via the `--env=NAME` flag on the build/serve commands. - -### Base tag handling in index.html - -When building you can modify base tag (``) in your index.html with `--base-href your-url` option. - -```bash -# Sets base tag href to /myUrl/ in your index.html -ng build --base-href /myUrl/ -ng build --bh /myUrl/ -``` - -### Bundling - -All builds make use of bundling, and using the `--prod` flag in `ng build --prod` -or `ng serve --prod` will also make use of uglifying and tree-shaking functionality. - -### Running unit tests - -```bash -ng test -``` - -Tests will execute after a build is executed via [Karma](http://karma-runner.github.io/0.13/index.html), and it will automatically watch your files for changes. You can run tests a single time via `--watch=false` or `--single-run`. - -You can run tests with coverage via `--code-coverage`. The coverage report will be in the `coverage/` directory. - -### Running end-to-end tests - -```bash -ng e2e -``` - -Before running the tests make sure you are serving the app via `ng serve`. - -End-to-end tests are run via [Protractor](https://angular.github.io/protractor/). - -### Proxy To Backend -Using the proxying support in webpack's dev server we can highjack certain urls and send them to a backend server. -We do this by passing a file to `--proxy-config` - -Say we have a server running on `http://localhost:3000/api` and we want all calls to `http://localhost:4200/api` to go to that server. - -We create a file next to projects `package.json` called `proxy.conf.json` -with the content - -```json -{ - "/api": { - "target": "http://localhost:3000", - "secure": false - } -} -``` - -You can read more about what options are available here [webpack-dev-server proxy settings](https://webpack.github.io/docs/webpack-dev-server.html#proxy) - -and then we edit the `package.json` file's start script to be - -```json -"start": "ng serve --proxy-config proxy.conf.json", -``` - -now run it with `npm start` - - -### Linting code - -You can lint your app code by running `ng lint`. -This will use the `lint` npm script that in generated projects uses `tslint`. - -You can modify the these scripts in `package.json` to run whatever tool you prefer. - - - - -### Commands autocompletion - -To turn on auto completion use the following commands: - -For bash: -```bash -ng completion --bash >> ~/.bashrc -source ~/.bashrc -``` - -For zsh: -```bash -ng completion --zsh >> ~/.zshrc -source ~/.zshrc -``` - -Windows users using gitbash: -```bash -ng completion --bash >> ~/.bash_profile -source ~/.bash_profile -``` - -### Project assets - -You use the `assets` array in `angular-cli.json` to list files or folders you want to copy as-is when building your project: -```json -"assets": [ - "assets", - "favicon.ico" -] -``` - - -### Global styles - -The `styles.css` file allows users to add global styles and supports -[CSS imports](https://developer.mozilla.org/en/docs/Web/CSS/@import). - -If the project is created with the `--style=sass` option, this will be a `.sass` -file instead, and the same applies to `scss/less/styl`. - -You can add more global styles via the `apps[0].styles` property in `angular-cli.json`. - -### CSS Preprocessor integration - -Angular CLI supports all major CSS preprocessors: -- sass/scss ([http://sass-lang.com/](http://sass-lang.com/)) -- less ([http://lesscss.org/](http://lesscss.org/)) -- stylus ([http://stylus-lang.com/](http://stylus-lang.com/)) - -To use these preprocessors simply add the file to your component's `styleUrls`: - -```javascript -@Component({ - selector: 'app-root', - templateUrl: './app.component.html', - styleUrls: ['./app.component.scss'] -}) -export class AppComponent { - title = 'app works!'; -} -``` - -When generating a new project you can also define which extension you want for -style files: - -```bash -ng new sassy-project --style=sass -``` - -Or set the default style on an existing project: - -```bash -ng set defaults.styleExt scss -``` - -### 3rd Party Library Installation - -Simply install your library via `npm install lib-name --save` and import it in your code. - -If the library does not include typings, you can install them using npm: - -```bash -npm install d3 --save -npm install @types/d3 --save-dev -``` - -If the library doesn't have typings available at `@types/`, you can still use it by -manually adding typings for it: - -1. First, create a `typings.d.ts` file in your `src/` folder. This file will be automatically included as global type definition. - -2. Then, in `src/typings.d.ts`, add the following code: - - ```typescript - declare module 'typeless-package'; - ``` - -3. Finally, in the component or file that uses the library, add the following code: - - ```typescript - import * as typelessPackage from 'typeless-package'; - typelessPackage.method(); - ``` - -Done. Note: you might need or find useful to define more typings for the library that you're trying to use. - -### Global Library Installation - -Some javascript libraries need to be added to the global scope, and loaded as if -they were in a script tag. We can do this using the `apps[0].scripts` and -`apps[0].styles` properties of `angular-cli.json`. - -As an example, to use [Bootstrap 4](http://v4-alpha.getbootstrap.com/) this is -what you need to do: - -First install Bootstrap from `npm`: - -```bash -npm install bootstrap@next -``` - -Then add the needed script files to `apps[0].scripts`: - -```json -"scripts": [ - "../node_modules/jquery/dist/jquery.js", - "../node_modules/tether/dist/js/tether.js", - "../node_modules/bootstrap/dist/js/bootstrap.js" -], -``` - -Finally add the Bootstrap CSS to the `apps[0].styles` array: -```json -"styles": [ - "../node_modules/bootstrap/dist/css/bootstrap.css", - "styles.css" -], -``` - -Restart `ng serve` if you're running it, and Bootstrap 4 should be working on -your app. - - - ### Updating Angular CLI To update Angular CLI to a new version, you must update both the global package and your project's local package. diff --git a/docs/documentation/stories/asset-configuration.md b/docs/documentation/stories/asset-configuration.md new file mode 100644 index 000000000000..1c7d319d4090 --- /dev/null +++ b/docs/documentation/stories/asset-configuration.md @@ -0,0 +1,9 @@ +# Project assets + +You use the `assets` array in `angular-cli.json` to list files or folders you want to copy as-is when building your project: +```json +"assets": [ + "assets", + "favicon.ico" +] +``` \ No newline at end of file diff --git a/docs/documentation/stories/autocompletion.md b/docs/documentation/stories/autocompletion.md new file mode 100644 index 000000000000..324d6a2faa58 --- /dev/null +++ b/docs/documentation/stories/autocompletion.md @@ -0,0 +1,21 @@ +# Autocompletion + +To turn on auto completion use the following commands: + +For bash: +```bash +ng completion --bash >> ~/.bashrc +source ~/.bashrc +``` + +For zsh: +```bash +ng completion --zsh >> ~/.zshrc +source ~/.zshrc +``` + +Windows users using gitbash: +```bash +ng completion --bash >> ~/.bash_profile +source ~/.bash_profile +``` \ No newline at end of file diff --git a/docs/documentation/stories/routing.md b/docs/documentation/stories/routing.md new file mode 100644 index 000000000000..5d5b3b0c7239 --- /dev/null +++ b/docs/documentation/stories/routing.md @@ -0,0 +1,13 @@ +# Generating a route + +The CLI supports routing in several ways: + +- We include the `@angular/router` NPM package when creating or initializing a project. + +- When you generate a module, you can use the `--routing` option like `ng g module my-module --routing` to create a separate file `my-module-routing.module.ts` to store the module routes. + + The file includes an empty `Routes` object that you can fill with routes to different components and/or modules. + + The `--routing` option also generates a default component with the same name as the module. + +- You can use the `--routing` option with `ng new` to create a `app-routing.module.ts` file when you create or initialize a project. \ No newline at end of file