Как импортировать библиотеку JavaScript на фронтенде без сборщика

Современные JavaScript-библиотеки часто ориентированы на работу в проектах с системой сборки (Webpack, Vite, esbuild и т.п.). Но что если вы хотите использовать библиотеку без сборщика, прямо в браузере? Эта статья подробно объясняет, какие варианты существуют, как определить тип файлов, которые предоставляет библиотека, и как их подключить без сборки.

Какие бывают файлы в библиотеке

Существует три основных типа файлов, которые могут быть в сборке JavaScript-библиотеки:

1. Классические файлы, которые определяют глобальные переменные. Такие можно просто добавить через <script src="...">

2. ES модули - современные модули с import/export, которые браузеры поддерживают напрямую

3. CommonJS-модули - старая система модулей, которая предназначена для Node.js и не работает в браузере без сборщика

Где искать файлы библиотеки: NPM-сборка

Даже если вы не хотите использовать Node или сборщик, полезно установить библиотеку через npm install в временной директории. Так можно посмотреть весь набор скомпилированных файлов на диске. Файлы, которые вы затем указываете в CDN-ссылках (например, jsDelivr или Cloudflare), фактически изначально берутся из сборки на NPM.

Пример 1: Chart.js

Рассмотрим библиотеку визуализации графиков Chart.js:

$ npm install chart.js
$ cd node_modules/chart.js/dist
$ ls *.*js
chart.cjs  chart.js  chart.umd.js  helpers.cjs  helpers.js

Здесь есть три варианта файлов:

• chart.cjs: файл формата CommonJS, который не может работать в браузере без сборщика

• chart.js: содержит import '@kurkle/color' - значит это ES модуль

• chart.umd.js: UMD-файл - универсальный модуль, который можно подключить через <script> и он создаст глобальную переменную Chart

Как использовать UMD-файл

Самый простой вариант это взять UMD-сборку и подключить её напрямую:

<script src="./chart.umd.js"></script>

После этого библиотека будет доступна в глобальной переменной Chart, и её можно использовать прямо в браузере.

Где находятся файлы: package.json

Иногда библиотека не кладёт файлы в стандартную папку dist. Местоположение сборки определяется в её package.json. Например, в Chart.js есть такие поля:

"jsdelivr": "./dist/chart.umd.js",
"unpkg": "./dist/chart.umd.js",
"main": "./dist/chart.cjs",
"module": "./dist/chart.js"

Это показывает, какие файлы используются разными системами: CDN, Node.js, ES модулями и т.п.

Пример 2: ES модуль - @atcute/oauth-browser-client

Некоторые библиотеки предоставляют только ES модули. В примере с @atcute/oauth-browser-client все файлы выглядят как стандартные ES модули (используют export). Это значит, что их можно подключить в браузере без сборщика, но потребуется importmap.

Что такое importmap

Importmap - это специальная таблица в HTML, которая говорит браузеру, где искать модули в виде путей:

<script type="importmap">
{
  "imports": {
    "@atcute/oauth-browser-client": "./node_modules/@atcute/oauth-browser-client/dist/index.js",
    "nanoid": "./node_modules/nanoid/bin/dist/index.js"
    …
  }
}
</script>

Затем в вашем модуле можно писать обычные импорты:

import { configureOAuth } from "@atcute/oauth-browser-client";

И запускать через:

<script type="module" src="YOURSCRIPT.js"></script>

Но importmap работает только в современных браузерах и иногда вызывает сложности (например, много файлов для загрузки).

ES модули без importmap

Если модуль не имеет зависимостей, importmap не нужен и можно подключить модуль напрямую через:

<script type="module" src="main.js"></script>

и внутри main.js писать:

import { foo } from "https://example.com/foo.js";

Это работает для простых ES модулей, которые не зависят от других файлов.

Альтернатива: CDN-трансформация

Если библиотека написана в формате CommonJS и у вас нет сборщика, её можно взять через CDN-транслятор вроде esm.sh или skypack.dev. Эти сервисы динамически преобразуют CommonJS в ES модули, и браузер сможет загрузить их:

<script type="module" src="script.js"></script>

где в script.js:

import { BrowserOAuthClient } from "https://esm.sh/@atproto/oauth-client-browser@0.3.0";

Это работает, но означает, что вы фактически используете сторонний сервис, который выполняет сборку за вас.

Краткая сводка

Вот как отличить и использовать различные типы файлов:

Обратите внимание, что обычное расширение .js само по себе ничего не говорит о формате и нужно смотреть внутри файла.