# JS Migration Guide

Припускаючи:

* ви знаєте JavaScript.
* ви знаєте шаблони та інструменти створення (наприклад, webpack), які використовуються в проекті.

Відкинувши це припущення, загалом процес складається з таких кроків:

* Додайте `tsconfig.json`.
* Змініть розширення файлу вихідного коду з `.js` на `.ts`. Почніть _suppressing_ помилки за допомогою `any`.
* Напишіть новий код на TypeScript і якомога менше використовуйте `any`.
* Поверніться до старого коду та почніть додавати анотації типів і виправляйте виявлені помилки.
* Використовуйте визначення навколишнього середовища для стороннього коду JavaScript.

Давайте обговоримо деякі з цих пунктів далі.

Зауважте, що весь JavaScript є _valid_ TypeScript. Тобто якщо ви надасте компілятору TypeScript деякий JavaScript -> JavaScript, створений компілятором TypeScript, поводитиметься точно так само, як оригінальний JavaScript. Це означає, що зміна розширення з `.js` на `.ts` не вплине негативно на вашу кодову базу.

## Suppressing Errors

TypeScript негайно почне перевірку типу вашого коду, і ваш вихідний код JavaScript _може бути не таким охайним, як ви думали_, і, отже, ви отримуєте діагностичні помилки. Багато з цих помилок можна придушити за допомогою `any`, наприклад:

```ts
var foo = 123;
var bar = 'hey';

bar = foo; // ERROR: не може призначити number в string
```

Незважаючи на те, що **error is valid** (і в більшості випадків отримана інформація буде кращою, ніж те, що уявляли оригінальні автори різних частин бази коду), ви, ймовірно, зосередитеся на написанні нового коду на TypeScript, поступово оновлюючи стару кодову базу. Тут ви можете придушити цю помилку за допомогою твердження типу, як показано нижче:

```ts
var foo = 123;
var bar = 'hey';

bar = foo as any; // Okay!
```

В інших місцях ви можете позначити щось як `any`, наприклад:

```ts
function foo() {
    return 1;
}
var bar = 'hey';
bar = foo(); // ERROR: не може призначити number в string
```

Suppressed:

```ts
function foo(): any { // Added `any`
    return 1;
}
var bar = 'hey';
bar = foo(); // Okay!
```

> Примітка: придушення помилок небезпечно, але це дозволяє вам помічати помилки у вашому _new_ коді TypeScript. Ви можете залишати коментарі `// TODO:` під час роботи.\*\*

## Third Party JavaScript

Ви можете змінити свій JavaScript на TypeScript, але ви не можете змінити весь світ на використання TypeScript. Ось тут і з’являється підтримка навколишнього визначення TypeScript. На початку ми рекомендуємо вам створити `vendor.d.ts` (розширення `.d.ts` вказує на те, що це _declaration file_) і почати додавати брудні речі до нього. Крім того, можна створити спеціальний файл для бібліотеки, наприклад. `jquery.d.ts` для jquery.

> Примітка: добре підтримувані та чітко типізовані визначення для майже 90% найпопулярніших бібліотек JavaScript існують у репозиторії OSS під назвою[DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped). Ми рекомендуємо переглянути там, перш ніж створювати власні визначення, як ми наводимо тут. Тим не менш, цей швидкий і брудний спосіб є життєво важливим знанням, щоб зменшити початкове тертя з TypeScript\*\*.

Розглянемо випадок `jquery`, ви можете легко створити _trivial_ визначення для нього:

```ts
declare var $: any;
```

Іноді ви можете додати явну анотацію до чогось (наприклад, `JQuery`), і вам потрібно щось у _type declaration space_. Ви можете зробити це досить легко, використовуючи ключове слово `type`:

```ts
declare type JQuery = any;
declare var $: JQuery;
```

Це спрощує шлях оновлення в майбутньому.

Знову ж таки, високоякісний `jquery.d.ts` існує на [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped). Але тепер ви знаєте, як _швидко_ подолати будь-яке протиріччя JavaScript -> TypeScript під час використання стороннього JavaScript. Далі ми детально розглянемо декларації середовища.

**Third Party NPM modules**

Подібно до оголошення глобальної змінної, ви можете легко оголосити глобальний модуль. наприклад для `jquery`, якщо ви хочете використовувати його як модуль ([https://www.npmjs.com/package/jquery](https://www.npmjs.com/package/jquery)), ви можете написати наступне самостійно:

```ts
declare module "jquery";
```

А потім ви можете імпортувати його у свій файл за потреби:

```ts
import * as $ from "jquery";
```

> Знову ж таки, високоякісний `jquery.d.ts` існує на [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped), який забезпечує набагато вищу якість оголошення модуля jquery. Але він може не існувати для вашої бібліотеки, тож тепер у вас є швидкий спосіб продовжити міграцію з низьким рівнем тертя 🌹

**External non js resources**

Ви навіть можете дозволити імпорт будь-якого файлу, напр. Файли `.css` (якщо ви використовуєте щось на кшталт завантажувачів стилю webpack або модулів css) із простою декларацією стилю `*` (ідеально у файлі[`global.d.ts` file](../project/modules/globals)):

```ts
declare module "*.css";
```

Тепер люди можуть `імпортувати * як foo з "./some/file.css";`

Так само, якщо ви використовуєте шаблони html (наприклад, angular), ви можете:

```ts
declare module "*.html";
```

**More**

Якщо ви хочете приховати своє оновлення, оскільки ви не змогли залучити команду для переходу на TypeScript, [TypeScript has a blog post on upgrading silently without having to convince your team up front](https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/).
