docs(typescript-config): copy edits applying guidelines (#3383)

This commit is contained in:
Kapunahele Wong 2017-03-17 18:24:18 -04:00 committed by Jules Kremer
parent 557200be4f
commit a8540b01d3
1 changed files with 19 additions and 15 deletions

View File

@ -1,7 +1,8 @@
include ../_util-fns include ../_util-fns
:marked :marked
TypeScript is a primary language for Angular application development. It is a dialect of JavaScript with design-time support for type-safety and tooling. TypeScript is a primary language for Angular application development.
It is a superset of JavaScript with design-time support for type safety and tooling.
Browsers can't execute TypeScript directly. Typescript must be "transpiled" into JavaScript using the *tsc* compiler, Browsers can't execute TypeScript directly. Typescript must be "transpiled" into JavaScript using the *tsc* compiler,
which requires some configuration. which requires some configuration.
@ -9,21 +10,21 @@ include ../_util-fns
This page covers some aspects of TypeScript configuration and the TypeScript environment This page covers some aspects of TypeScript configuration and the TypeScript environment
that are important to Angular developers, including details about the following files: that are important to Angular developers, including details about the following files:
* [tsconfig.json](#tsconfig) - TypeScript compiler configuration. * [tsconfig.json](#tsconfig)—TypeScript compiler configuration.
* [typings](#typings) - TypesScript declaration files. * [typings](#typings)—TypesScript declaration files.
a(id="tsconfig") a(id="tsconfig")
.l-main-section .l-main-section
:marked :marked
## *tsconfig.json* ## *tsconfig.json*
Typically, you add a TypeScript configuration file (`tsconfig.json`) to your project to Typically, you add a TypeScript configuration file called `tsconfig.json` to your project to
guide the compiler as it generates JavaScript files. guide the compiler as it generates JavaScript files.
.l-sub-section .l-sub-section
:marked :marked
For details about `tsconfig.json`, see the official For details about `tsconfig.json`, see the official
[TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html). [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
:marked :marked
We created the following `tsconfig.json` during [Setup](setup.html): The [Setup](setup.html) guide uses the following `tsconfig.json`:
+makeJson('quickstart/ts/src/tsconfig.1.json', null, 'tsconfig.json')(format=".") +makeJson('quickstart/ts/src/tsconfig.1.json', null, 'tsconfig.json')(format=".")
:marked :marked
This file contains options and flags that are essential for Angular applications. This file contains options and flags that are essential for Angular applications.
@ -73,39 +74,42 @@ a(id="typings")
can find them. Angular is one such library. can find them. Angular is one such library.
The `node_modules/@angular/core/` folder of any Angular application contains several `d.ts` files that describe parts of Angular. The `node_modules/@angular/core/` folder of any Angular application contains several `d.ts` files that describe parts of Angular.
**You need do nothing to get *typings* files for library packages that include `d.ts` files—as all Angular packages do.** **You need do nothing to get *typings* files for library packages that include `d.ts` files.
Angular packages include them already.**
### lib.d.ts ### lib.d.ts
TypeScript includes a special declaration file called `lib.d.ts`. This file contains the ambient declarations for various common JavaScript constructs present in JavaScript runtimes and the DOM. TypeScript includes a special declaration file called `lib.d.ts`. This file contains the ambient declarations for various common JavaScript constructs present in JavaScript runtimes and the DOM.
Based on the `--target`, TypeScript adds _additional_ ambient declarations like `Promise` if our target is `es6`. Based on the `--target`, TypeScript adds _additional_ ambient declarations
like `Promise` if the target is `es6`.
Since the QuickStart is targeting `es5`, we can override the list of declaration files to be included: Since the QuickStart is targeting `es5`, you can override the
list of declaration files to be included:
code-example(format=".") code-example(format=".")
"lib": ["es2015", "dom"] "lib": ["es2015", "dom"]
:marked :marked
Thanks to that, we have all the `es6` typings even when targeting `es5`. Thanks to that, you have all the `es6` typings even when targeting `es5`.
### Installable typings files ### Installable typings files
Many libraries—jQuery, Jasmine, and Lodash among them—do *not* include `d.ts` files in their npm packages. Many libraries—jQuery, Jasmine, and Lodash among them—do *not* include `d.ts` files in their npm packages.
Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and
published them in well-known locations. published them in well-known locations.
We can install these typings via `npm` using the You can install these typings via `npm` using the
[`@types/*` scoped package](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html) [`@types/*` scoped package](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html)
and Typescript (starting at 2.0) will automatically recognize them. and Typescript, starting at 2.0, automatically recognizes them.
For instance, to install typings for `jasmine` we could do `npm install @types/jasmine --save-dev`. For instance, to install typings for `jasmine` you could do `npm install @types/jasmine --save-dev`.
:marked :marked
QuickStart identified two *typings* (`d.ts`) files: QuickStart identifies two *typings*, or `d.ts`, files:
* [jasmine](http://jasmine.github.io/) typings for the Jasmine test framework * [jasmine](http://jasmine.github.io/) typings for the Jasmine test framework.
* [node](https://www.npmjs.com/package/@types/node) for code that references objects in the *nodejs* environment; * [node](https://www.npmjs.com/package/@types/node) for code that references objects in the *nodejs* environment;
You can view an example in the [webpack](./webpack.html) page. you can view an example in the [webpack](./webpack.html) page.
QuickStart doesn't require these typings but many of the samples do. QuickStart doesn't require these typings but many of the samples do.