Import maps

Import maps — это механизм, который позволяет управлять модулями в браузере, указывая, откуда загружать конкретные пакеты без необходимости использования сборщиков вроде Webpack или Rollup. В контексте фреймворка Fresh они играют ключевую роль, так как Fresh использует нативный ESM в Deno для выполнения JavaScript и TypeScript-кода, что упрощает импорт сторонних библиотек.

Основы import maps

Import map представляет собой JSON-структуру с двумя основными полями:

{
  "imports": {},
  "scopes": {}
}
  • imports — отображение имени модуля на конкретный URL или локальный путь.
  • scopes — область видимости, позволяющая переопределять импорты для определённых URL-путей.

Пример базового import map для Fresh:

{
  "imports": {
    "preact/": "https://esm.sh/preact@10.15.1/",
    "preact/hooks": "https://esm.sh/preact@10.15.1/hooks"
  }
}

Такой конфиг позволяет использовать:

import { h } from "preact";
import { useState } from "preact/hooks";

без указания полного URL для каждого импорта.

Подключение import map в Fresh

Fresh использует Deno, поэтому import map указывается через флаг при запуске проекта:

deno run -A --import-map=import_map.json main.ts
  • -A — полный доступ к разрешениям.
  • --import-map — путь к файлу import map.

В процессе разработки это гарантирует, что все импорты будут разрешены через указанные URL или локальные пакеты.

Работа с локальными пакетами

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

{
  "imports": {
    "lodash": "./vendor/lodash.js"
  }
}

Теперь:

import _ from "lodash";

будет ссылаться на локальный файл ./vendor/lodash.js, а не на внешний CDN.

Scopes и управление версиями

Scopes позволяют задать разные версии библиотек для разных частей приложения:

{
  "scopes": {
    "./admin/": {
      "preact": "https://esm.sh/preact@10.15.1/"
    },
    "./user/": {
      "preact": "https://esm.sh/preact@10.14.0/"
    }
  }
}
  • Для файлов в папке ./admin/ будет использоваться версия 10.15.1.
  • Для файлов в папке ./user/ — версия 10.14.0.

Это удобно при постепенном обновлении зависимостей.

Использование с TypeScript

Deno и Fresh полностью поддерживают TypeScript, а import map помогает избежать конфликтов типов. Для корректной работы рекомендуется создавать отдельный import_map.d.ts с типами для локальных модулей. Пример:

declare module "lodash" {
  export function debounce(fn: Function, wait: number): Function;
}

Работа с внешними CDN

Fresh активно использует CDN для управления зависимостями. Самый популярный вариант — esm.sh, который автоматически транспилирует пакеты из npm в ESM, совместимый с Deno:

{
  "imports": {
    "axios": "https://esm.sh/axios@1.6.0"
  }
}

Импорт в проекте:

import axios from "axios";

Все зависимости будут подтягиваться по URL без необходимости установки через npm.

Интеграция с компонентами Fresh

Компоненты Fresh строятся на Preact. Import map обеспечивает согласованность версий Preact и хуков, предотвращая конфликты между компонентами и сторонними библиотеками. Пример:

{
  "imports": {
    "preact": "https://esm.sh/preact@10.15.1",
    "preact/hooks": "https://esm.sh/preact@10.15.1/hooks",
    "tailwindcss": "https://esm.sh/tailwindcss@3.3.0"
  }
}

Теперь компоненты могут использовать Preact и Tailwind без проблем с версиями.

Автоматизация и обновление

Для проектов Fresh рекомендуется хранить import map под контролем версий, чтобы все участники проекта использовали одинаковые версии библиотек. Обновление URL через CDN позволяет быстро переключаться на новые версии без изменения кода.

Важные моменты

  • Import map работает только с ESM.
  • URL библиотек должен поддерживать ESM; иначе импорт будет невозможен.
  • Scopes позволяют управлять версионированием модулей в разных частях проекта.
  • В Deno import map является стандартным способом управления зависимостями, что делает Fresh lean и независимым от npm.

Использование import maps делает Fresh лёгким, модульным и полностью совместимым с нативными возможностями JavaScript и Deno. Правильная организация import map ускоряет разработку, упрощает обновление библиотек и предотвращает конфликты версий.

Оглавление