Merge pull request #318 from iRoachie/typescript

docs(static type checking): Improved TypeScript docs
7 years ago · 8c8a876995
1 changed files with 131 additions and 2 deletions
--- a/content/docs/static-type-checking.md
+++ b/content/docs/static-type-checking.md
@ -146,9 +146,132 @@ Now you're all set! We recommend to check out the following resources to learn m

 ## TypeScript

-[TypeScript](https://www.typescriptlang.org/) is a programming language developed by Microsoft. It is a typed superset of JavaScript, and includes its own compiler.
+[TypeScript](https://www.typescriptlang.org/) is a programming language developed by Microsoft. It is a typed superset of JavaScript, and includes its own compiler. Being a typed language, Typescript can catch errors and bugs at build time, long before your app goes live. You can learn more about using TypeScript with React [here](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter).

-You can learn more about using TypeScript with React [here](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter).
+To use TypeScript, you need to:
+* Add Typescript as a dependency to your project
+* Configure the TypeScript compiler options
+* Use the right file extensions
+* Add definitions for libraries you use
+
+Let's go over these in detail.
+
+### Adding TypeScript to a Project
+It all begins with running one command in your terminal.
+
+If you use [Yarn](https://yarnpkg.com/), run:
+
+```bash
+yarn add --dev typescript
+```
+
+If you use [npm](https://www.npmjs.com/), run:
+
+```bash
+npm install --save-dev typescript
+```
+
+Congrats! You've installed the latest version of TypeScript into your project. Installing TypeScript gives us access to the `tsc` command. Before configuration, let's add `tsc` to the "scripts" section in our `package.json`:
+
+```js{4}
+{
+  // ...
+  "scripts": {
+    "build": "tsc",
+    // ...
+  },
+  // ...
+}
+```
+
+### Configuring the TypeScript Compiler
+The compiler is of no help to us until we tell it what to do. In TypeScript, these rules are defined in a special file called `tsconfig.json`. To generate this file run:
+
+```bash
+tsc --init
+```
+
+Looking at the now generated `tsconfig.json`, you can see that there are many options you can use to configure the compiler. For a detailed description of all the options, check [here](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+
+Of the many options, we'll look at `rootDir` and `outDir`. In its true fashion, the compiler will take in typescript files and generate javascript files. However we don't want to get confused with our source files and the generated output.
+
+We'll address this in two steps:
+* Firstly, let's arrange our project structure like this. We'll place all our source code in the `src` directory.
+
+```
+├── package.json
+├── src
+│   └── index.ts
+└── tsconfig.json
+```
+
+* Next, we'll tell the compiler where our source code is and where the output should go.
+
+```js{6,7}
+// tsconfig.json
+
+{
+  "compilerOptions": {
+    // ...
+    "rootDir": "src",
+    "outDir": "build"
+    // ...
+  },
+}
+```
+
+Great! Now when we run our build script the compiler will output the generated javascript to the `build` folder. The [TypeScript React Starter](https://github.com/Microsoft/TypeScript-React-Starter/blob/master/tsconfig.json) provides a `tsconfig.json` with a good set of rules to get you started.
+
+Generally, you don't want to keep the generated javascript in your source control, so be sure to add the build folder to your `.gitignore`.
+
+### File extensions
+In React, you most likely write your components in a `.js` file. In TypeScript we have 2 file extensions:
+
+`.ts` is the default file extension while `.tsx` is a special extension used for files which contain `JSX`.
+
+### Running TypeScript
+
+If you followed the instructions above, you should be able to run TypeScript for the first time.
+
+```bash
+yarn build
+```
+
+If you use npm, run:
+
+```bash
+npm run build
+```
+
+If you see no output, it mean's that it completed successfully.
+
+
+### Type Definitions
+To be able to show errors and hints from other packages, the compiler relies on declaration files. A declaration file provides all the type information about a library. This enables us to use javascript libraries like those on npm in our project. 
+
+There are two main ways to get declarations for a library:
+
+__Bundled__ - The library bundles it's own declaration file. This is great for us, since all we need to do is install the library, and we can use it right away. To check if a library has bundled types, look for an `index.d.ts` file in the project. Some libraries will have it specified in teir `package.json` under the `typings` or `types` field.
+
+__[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped)__ - DefinitelyTyped is a huge repository of declarations for libraries that don't bundle a declaration file. The declarations are crowd-sourced and managed by Microsoft and open source contributors. React for example doesn't bundle it's own declaration file. Instead we can get it from DefintelyTyped. To do so enter this command in your terminal.
+
+```bash
+# yarn
+yarn add --dev @types/react
+
+# npm
+npm i --save-dev @types/react
+```
+
+__Local Declarations__
+Sometimes the package that you want to use doesn't bundle declarations nor is it available on DefinitelyTyped. In that case, we can have a local declaration file. To do this, create a `declarations.d.ts` file in the root of your source directory. A simple declaration could look like this:
+
+```typescript
+declare module 'querystring' {
+  export function stringify(val: object): string
+  export function parse(val: string): object
+}
+```

 ### Using TypeScript with Create React App

@ -162,6 +285,12 @@ Note that it is a **third party** project, and is not a part of Create React App

 You can also try [typescript-react-starter](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter).

+You are now ready to code! We recommend to check out the following resources to learn more about Typescript:
+
+* [TypeScript Documentation: Basic Types](https://www.typescriptlang.org/docs/handbook/basic-types.html)
+* [TypeScript Documentation: Migrating from Javascript](http://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
+* [TypeScript Documentation: React and Webpack](http://www.typescriptlang.org/docs/handbook/react-&-webpack.html)
+
 ## Reason

 [Reason](https://reasonml.github.io/) is not a new language; it's a new syntax and toolchain powered by the battle-tested language, [OCaml](http://ocaml.org/). Reason gives OCaml a familiar syntax geared toward JavaScript programmers, and caters to the existing NPM/Yarn workflow folks already know.