docs(typescript-config): copy edits applying guidelines (#3383)
This commit is contained in:
parent
557200be4f
commit
a8540b01d3
|
@ -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.
|
||||||
|
|
Loading…
Reference in New Issue