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, наприклад:

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

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

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

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

bar = foo as any; // Okay!

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

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

Suppressed:

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. Ми рекомендуємо переглянути там, перш ніж створювати власні визначення, як ми наводимо тут. Тим не менш, цей швидкий і брудний спосіб є життєво важливим знанням, щоб зменшити початкове тертя з TypeScript**.

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

declare var $: any;

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

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

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

Знову ж таки, високоякісний jquery.d.ts існує на DefinitelyTyped. Але тепер ви знаєте, як швидко подолати будь-яке протиріччя JavaScript -> TypeScript під час використання стороннього JavaScript. Далі ми детально розглянемо декларації середовища.

Third Party NPM modules

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

declare module "jquery";

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

import * as $ from "jquery";

Знову ж таки, високоякісний jquery.d.ts існує на DefinitelyTyped, який забезпечує набагато вищу якість оголошення модуля jquery. Але він може не існувати для вашої бібліотеки, тож тепер у вас є швидкий спосіб продовжити міграцію з низьким рівнем тертя 🌹

External non js resources

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

declare module "*.css";

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

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

declare module "*.html";

More

Якщо ви хочете приховати своє оновлення, оскільки ви не змогли залучити команду для переходу на TypeScript, TypeScript has a blog post on upgrading silently without having to convince your team up front.