Настройка TypeScript

Установка и базовая конфигурация

Для работы с FAST Element на TypeScript необходима корректная настройка проекта с использованием Node.js и npm или Yarn. Основной пакет для TypeScript — typescript, а для сборки модулей и разработки компонентов FAST рекомендуется использовать esbuild, vite или webpack.

Установка TypeScript и FAST Element выполняется командой:

npm install typescript @microsoft/fast-element @microsoft/fast-foundation

После установки создаётся файл tsconfig.json, который задаёт правила компиляции TypeScript. Минимальная конфигурация для FAST Element может выглядеть так:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "lib": ["DOM", "ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

Ключевые моменты конфигурации:

  • "target": "ES2020" — позволяет использовать современные возможности JavaScript, включая async/await и динамический импорт.
  • "module": "ESNext" — обеспечивает поддержку нативных ECMAScript-модулей.
  • "strict": true — включает строгую типизацию для повышения безопасности кода.
  • "lib": ["DOM", "ES2020"] — подключает типы для браузерного окружения и современных стандартов ECMAScript.
  • "declaration": true — создаёт .d.ts файлы для дальнейшего использования компонентов в других проектах.

Структура проекта

Стандартная структура проекта с FAST Element и TypeScript может выглядеть следующим образом:

project/
├─ src/
│  ├─ components/
│  │  ├─ button.ts
│  │  └─ card.ts
│  └─ index.ts
├─ dist/
├─ tsconfig.json
├─ package.json
└─ vite.config.ts
  • Папка components содержит отдельные компоненты FAST Element.
  • Файл index.ts агрегирует все компоненты для экспорта.
  • dist — директория с собранными результатами.

Создание первого компонента на TypeScript

FAST Element использует декораторы @customElement и реактивные свойства @attr. Пример простого компонента кнопки:

import { FASTElement, html, css, customElement, attr } from "@microsoft/fast-element";

const template = html<Button>`<button part="button">${x => x.label}</button>`;

const styles = css`
  button {
    padding: 0.5rem 1rem;
    background-color: #0078d4;
    color: white;
    border: none;
    border-radius: 4px;
    cursor: pointer;
  }
  button:hover {
    background-color: #005a9e;
  }
`;

@customElement({ name: "fast-button", template, styles })
export class Button extends FASTElement {
  @attr label: string = "Кнопка";
}

Особенности TypeScript при работе с FAST Element:

  • @attr позволяет автоматически синхронизировать свойства компонента с атрибутами HTML.
  • Типизация свойства гарантирует корректность данных.
  • CSS оформляется через объект css, что поддерживает encapsulation для компонентов.

Подключение TypeScript к сборщику

Для сборки проекта с TypeScript используется Vite или Webpack. Пример конфигурации Vite (vite.config.ts):

import { defineConfig } from "vite";

export default defineConfig({
  build: {
    target: "es2020",
    outDir: "dist",
  },
  esbuild: {
    jsxFactory: "FASTElement.html",
    jsxFragment: "FASTElement.html``",
  }
});

Vite автоматически интегрирует TypeScript, компилирует файлы в dist и поддерживает горячую перезагрузку компонентов.

Настройка строгой типизации для реактивных данных

FAST Element поддерживает реактивные свойства через @observable и @attr. Чтобы TypeScript корректно отслеживал изменения, рекомендуется включить строгие правила:

"strict": true,
"strictPropertyInitialization": false
  • strictPropertyInitialization: false отключает ошибку о неинициализированных свойствах, что важно для реактивных атрибутов, которые могут быть установлены через HTML.

Подключение типов для шаблонов

FAST Element использует функции-шаблоны html и css. Для корректной типизации следует импортировать их напрямую из пакета:

import { html, css, FASTElement } from "@microsoft/fast-element";

Это позволяет TypeScript понимать возвращаемые значения и проверять совместимость с компонентами.

Интеграция с ESLint и Prettier

Для поддержания качества кода TypeScript рекомендуется подключить ESLint с плагинами для FAST Element:

npm install eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --save-dev

Пример конфигурации .eslintrc.json:

{
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "env": {
    "browser": true,
    "es2020": true
  }
}

Это обеспечивает строгую проверку типов и предотвращает ошибки при разработке сложных компонентов.

Работа с модульной архитектурой

FAST Element поддерживает модульную структуру компонентов. TypeScript позволяет импортировать и экспортировать их безопасно:

// src/index.ts
export { Button } from "./components/button";
export { Card } from "./components/card";

Импорт в приложении:

import { Button } from "./index";

Такой подход облегчает поддержку большого количества компонентов и интеграцию в другие проекты.

Выводы по настройке

Правильная конфигурация TypeScript для FAST Element обеспечивает:

  • строгую типизацию реактивных компонентов,
  • корректное создание .d.ts файлов,
  • интеграцию с современными сборщиками и инструментами разработки,
  • поддержку модульной структуры и масштабируемости проекта.

Типизация компонентов и использование @attr и @observable делают FAST Element безопасным и удобным инструментом для построения веб-компонентов с высокой производительностью и предсказуемым поведением.

Оглавление