Разработка

На этапе разработки проектов, когда вы пишете компоненты Lit, повысить продуктивность помогут следующие инструменты:

• Сервер разработки для просмотра кода без этапа сборки.
• TypeScript для написания кода с проверкой типов.
• Линтер для выявления ошибок JavaScript.
• Форматтер кода для единообразного форматирования.
• Плагины IDE для Lit для линтинга и подсветки синтаксиса шаблонов Lit.

Ознакомьтесь с документацией по стартовым наборам, чтобы легко настроить среду разработки со всеми этими предварительно настроенными функциями.

Все пакеты Lit публикуются со сборками для разработки и производства, использующими поддержку условий экспорта в Node.

Производственная сборка оптимизирована с помощью очень агрессивных настроек минификации. Сборка для разработки не минифицирована, что упрощает отладку, и включает дополнительные проверки и предупреждения. Сборка по умолчанию является производственной, чтобы проекты случайно не развертывали более крупную сборку для разработки.

Чтобы использовать сборку для разработки, необходимо указать условие экспорта "development" в инструментах, поддерживающих условия экспорта, таких как Rollup, Webpack и Web Dev Server. Для каждого инструмента это делается по-разному.

Например, в Rollup с помощью плагина @rollup/node-resolve можно выбрать сборку для разработки, используя параметр exportConditions:

import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  // ...
  plugins: [nodeResolve({
    exportConditions: ['development']
  })]
};

Сборки для разработки ReactiveElement и LitElement поддерживают дополнительные предупреждения во время выполнения, которые помогают выявлять проблемы, проверка которых в производственных сборках обходилась бы дорого.

Некоторые предупреждения отображаются всегда. Также есть две категории необязательных предупреждений, которые можно включать и отключать:

• 'migration'. Предупреждения, связанные с переходом с LitElement 2.x. По умолчанию отключены.
• 'change-in-update'. Предупреждения, связанные с изменением реактивного состояния во время обновления. По умолчанию включены.

Управлять необязательными предупреждениями можно с помощью методов ReactiveElement.disableWarning() и ReactiveElement.enableWarning(). Их можно вызывать для любого подкласса ReactiveElement, включая LitElement и ваши собственные классы. Вызов этих методов для класса включает или отключает предупреждения для этого класса и всех его подклассов. Например, можно отключить категорию предупреждений для всех классов ReactiveElement, всех классов LitElement или определённого подкласса LitElement.

Эти методы доступны только в сборках для разработки, поэтому обязательно проверяйте возможность их вызова. Рекомендуем использовать опциональную цепочку.

Примеры:

import {LitElement, ReactiveElement} from 'lit';

// Turn off migration warnings on all ReactiveElements,
// including LitElements
ReactiveElement.disableWarning?.('migration');

// Turn off update warnings on all LitElements
LitElement.disableWarning?.('change-in-update');

// Turn off update warnings on one element
MyElement.disableWarning?.('change-in-update');

Управлять предупреждениями в рамках одного класса можно также, определив свойство static enabledWarnings:

class MyElement extends LitElement {
  static enabledWarnings = ['migration'];
}

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

Предупреждение, отображаемое только в режиме разработки, возникает при обнаружении нескольких версий или даже нескольких копий одной версии любого из основных пакетов Lit — lit-html, lit-element, @lit/reactive-element.

Если Lit используется как внутренняя зависимость элементов, элементы могут использовать разные версии Lit и при этом полностью взаимодействовать друг с другом. Мы также позаботились о том, чтобы Lit 2 и Lit 3 были в основном совместимы друг с другом. Например, можно передать шаблон Lit 2 в функцию рендеринга Lit 3 и наоборот.

Почему же тогда появляется предупреждение? Lit иногда сравнивают с фреймворками, которые часто перестают работать, если смешать компоненты, использующие разные версии фреймворка. Поэтому несколько дублирующихся версий Lit можно установить случайно и не заметить.

Загрузка нескольких совместимых версий Lit не оптимальна, поскольку пользователю приходится передавать дополнительные дублирующиеся байты.

Если вы публикуете библиотеку, использующую Lit, следуйте нашим рекомендациям по публикации, чтобы пользователи вашей библиотеки могли устранять дубликаты Lit в своих проектах.

Устранение дубликатов версий Lit

Возможно, что даже после выполнения приведённых ниже шагов устранить дубликаты Lit не получится. Например, библиотека, от которой вы зависите, может включать в себя определённую версию Lit. В таких случаях предупреждение можно игнорировать.

Если вы видите предупреждение Multiple versions of Lit loaded в режиме разработки, попробуйте сделать следующее:

1. Узнайте, у каких библиотек Lit загружено несколько версий, проверив в консоли браузера следующие переменные: window.litElementVersions, window.reactiveElementVersions и window.litHtmlVersions.

2. Используйте npm ls (можно указать конкретные библиотеки для поиска, например npm ls @lit/reactive-element), чтобы определить, какие зависимости загружают несколько разных версий Lit.

3. Попробуйте использовать npm dedupe для устранения дубликатов Lit. Используйте npm ls, чтобы проверить, удалось ли устранить дубликаты пакета Lit.

4. Можно подсказать npm, какие версии основных пакетов Lit нужно поместить в корневой каталог зависимостей. Для этого установите их как прямые зависимости проекта с помощью npm i @lit/reactive-element@latest lit-element@latest lit-html@latest. Замените latest версией, для которой нужно устранить дубликаты.

5. Если дубликаты всё ещё есть, возможно, потребуется удалить файл блокировки пакетов и node_modules. Затем явно установите нужную версию lit, а после неё — зависимости.

Lit поставляется в виде модулей JavaScript и использует неполные спецификаторы модулей, которые пока не поддерживаются нативно в большинстве браузеров. Неполные спецификаторы широко используются, и вы можете использовать их и в собственном коде. Например:

import {LitElement, html, css} from 'lit';

Чтобы выполнить этот код в браузере, неполный спецификатор ('lit') необходимо преобразовать в URL, который браузер сможет загрузить (например, '/node_modules/lit/lit.js').

Существует множество серверов разработки, которые умеют обрабатывать спецификаторы модулей. Если у вас уже есть сервер разработки, который это делает и интегрирован в процесс сборки, этого должно быть достаточно.

Если вам нужен сервер разработки, рекомендуем Web Dev Server.

Web Dev Server — это сервер разработки с открытым исходным кодом, позволяющий разрабатывать без этапа сборки.

Он преобразует неполные спецификаторы модулей в допустимые URL, необходимые браузерам.

Установите Web Dev Server:

npm i @web/dev-server --save-dev

Добавьте команду в файл package.json:

"scripts": {
  "start": "web-dev-server"
}

И файл web-dev-server.config.js:

export default {
  open: true,
  watch: true,
  appIndex: 'index.html',
  nodeResolve: {
    exportConditions: ['development'],
  },
};

Запустите сервер разработки:

npm run start

Для старых браузеров, таких как IE11, Web Dev Server может преобразовывать модули JavaScript для использования обратно совместимого загрузчика модулей SystemJS и автоматически подключать полифилы веб-компонентов. Чтобы обеспечить поддержку старых браузеров, необходимо настроить пакет @web/dev-server-legacy.

Установите пакет Web Dev Server для поддержки устаревших браузеров:

npm i @web/dev-server-legacy --save-dev

Настройте web-dev-server.config.js:

import { legacyPlugin } from '@web/dev-server-legacy';

export default {
  // ...
  plugins: [
    // Make sure this plugin is always last
    legacyPlugin({
      polyfills: {
        webcomponents: true,
        // Inject lit's polyfill-support module into test files, which is required
        // for interfacing with the webcomponents polyfills
        custom: [
          {
            name: 'lit-polyfill-support',
            path: 'node_modules/lit/polyfill-support.js',
            test: "!('attachShadow' in Element.prototype)",
            module: false,
          },
        ],
      },
    }),
  ],
};

Полные инструкции по установке и использованию см. в документации Web Dev Server.

Lit поддерживает разработку компонентов на TypeScript, включая полные объявления типов для API Lit, стандартные и экспериментальные декораторы, а также инструменты сообщества для проверки типов шаблонов и линтинга.

Поскольку Lit — это просто библиотека, не требующая компилятора и нестандартного синтаксиса языка, для неё не нужны какие-либо специальные инструменты TypeScript. Lit работает с официальным компилятором TypeScript, tsc, оболочками TypeScript, такими как оболочки для Rollup, Vite или Webpack, а также с альтернативными компиляторами, например esbuild.

Основные требования к проекту TypeScript:

• Включить современный уровень языка JavaScript, например с помощью "ES2021" в параметре lib.
• Включить типы DOM с помощью "DOM" в параметре lib.
• При желании включить экспериментальные декораторы и отключить семантику «define» для полей классов, если вы решили использовать экспериментальные декораторы TypeScript.

Как правило, эти параметры задаются в файле tsconfig проекта.

Чтобы установить TypeScript в проект:

npm i -D typescript

Чтобы собрать код:

npx tsc --watch

Полные инструкции по установке и использованию см. на сайте TypeScript. Для начала особенно полезны разделы об установке TypeScript и использовании его возможностей.

TypeScript поддерживает две версии декораторов: экспериментальные и стандартные. Дополнительную информацию см. в документации по декораторам.

Линтинг помогает выявлять ошибки в коде. Для линтинга кода Lit рекомендуем использовать ESLint.

Чтобы установить ESLint в проект:

npm install eslint --save-dev
npx eslint --init

Чтобы запустить его:

npx eslint yourfile.js

Или добавьте его в npm-скрипты:

{
  "scripts": {
    "lint": "eslint \"**/*.{js,ts}\"",
  }
}

Полные инструкции по установке и использованию см. в документации ESLint.

Также рекомендуем eslint-plugin-lit для ESLint, который обеспечивает линтинг HTML-шаблонов Lit, включая распространённые проверки HTML и специальные правила для Lit.

Интеграция линтинга в рабочий процесс IDE помогает выявлять ошибки как можно раньше. Инструкции по настройке IDE для работы с Lit см. в разделе Плагины IDE для Lit.

Форматтер кода помогает поддерживать единообразие и удобочитаемость кода. Интеграция выбранного форматтера с IDE гарантирует, что код всегда будет чистым и аккуратным.

Вот несколько популярных вариантов:

• Prettier: плагин для VS Code
• Beautifier: плагин для VS Code
• Clang: плагин для VS Code

При разработке с Lit могут быть полезны различные плагины IDE. В частности, рекомендуем использовать подсветку синтаксиса, совместимую с шаблонами Lit.

lit-plugin обеспечивает подсветку синтаксиса, проверку типов и другие возможности для шаблонов Lit. Он доступен для VS Code. Также можно использовать плагин компилятора TypeScript ts-lit-plugin, совместимый с Sublime Text и Atom.

lit-plugin и ts-lit-plugin обеспечивают:

• Подсветку синтаксиса
• Проверку типов
• Автодополнение кода
• Документацию при наведении курсора
• Переход к определению
• Линтинг
• Быстрые исправления

ESLint поддерживает интеграцию со многими редакторами кода. Если в конфигурации ESLint установлен eslint-plugin-lit для ESLint, IDE будет показывать ошибки и предупреждения, связанные с Lit.

Другие плагины IDE, а также дополнительные инструменты и сведения см. в репозитории awesome-lit-html.

Редактировать эту страницу