Подключение в проект на ES-модулях

Установка через пакетный менеджер

Базовый способ интеграции в современный JavaScript-проект — установка через npm или yarn:

npm install localforage

или

yarn add localforage

После установки пакет становится доступным как ES-модуль и может быть импортирован напрямую из кода приложения без дополнительных обёрток.

Прямой импорт ES-модуля

localForage поставляется с поддержкой ESM, поэтому основной сценарий использования строится вокруг стандартного синтаксиса import.

import localforage from "localforage";

После импорта доступен экземпляр API с предустановленными настройками и набором методов для работы с асинхронным хранилищем браузера.

Базовая инициализация через ES-модули

Конфигурация выполняется сразу после импорта. Это позволяет задать отдельное пространство хранения для конкретного приложения или модуля.

import localforage from "localforage";

localforage.config({
  name: "MyApp",
  storeName: "keyvalue_pairs",
  description: "Основное хранилище приложения"
});

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

  • name — логическое имя базы данных в IndexedDB
  • storeName — имя object store (используется в IndexedDB)
  • version — версия базы данных (опционально)
  • driver — приоритет драйверов хранения

Импорт в модульной архитектуре проекта

В ES-модульной архитектуре рекомендуется выносить работу с хранилищем в отдельный модуль:

// storage.js
import localforage from "localforage";

localforage.config({
  name: "AppStorage"
});

export default localforage;

Использование в других частях приложения:

import storage from "./storage.js";

await storage.setItem("token", "abc123");
const token = await storage.getItem("token");

Такой подход обеспечивает единый слой абстракции над хранилищем и упрощает замену конфигурации.

Использование именованных экземпляров

localForage поддерживает создание независимых экземпляров через createInstance. В ES-модулях это особенно полезно для разделения доменных областей данных.

import localforage from "localforage";

const authStorage = localforage.createInstance({
  name: "AuthDB",
  storeName: "auth"
});

const cacheStorage = localforage.createInstance({
  name: "CacheDB",
  storeName: "cache"
});

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

Динамический импорт (lazy loading)

В ES-модулях возможно отложенное подключение библиотеки, что снижает начальный размер бандла:

const localforage = await import("localforage");

await localforage.default.setItem("theme", "dark");

Особенность динамического импорта заключается в необходимости обращения к default, так как модуль экспортируется как default export.

Использование с bundler-сборщиками

При работе с Vite, Webpack или Rollup ES-импорт обрабатывается автоматически:

import localforage from "localforage";

async function saveData() {
  await localforage.setItem("profile", { id: 1, name: "Alex" });
}

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

Подключение через ES-модули в браузере без сборщика

При использовании native ES modules в браузере возможна загрузка через CDN:

import localforage from "https://cdn.jsdelivr.net/npm/localforage/+esm";

await localforage.setItem("session", "active");

Такой способ позволяет использовать библиотеку без этапа сборки, но требует поддержки ES-modules в целевом окружении.

Типовая структура ESM-интеграции

Модульная организация проекта с использованием localForage часто включает отдельные слои:

src/
  storage/
    index.js        // конфигурация и экспорт localforage
    auth.js         // работа с авторизацией
    cache.js        // кэширование данных
  services/
    api.js          // бизнес-логика
  main.js           // точка входа

Каждый слой работает через единый экземпляр или через набор специализированных экземпляров, созданных на основе createInstance.

Особенности работы в строгом ES-module режиме

ES-модули предполагают статический граф импортов, что влияет на архитектуру хранения:

  • импорт выполняется один раз на модуль
  • конфигурация хранилища должна выполняться до первых операций
  • повторный импорт не создаёт новых экземпляров
  • состояние сохраняется в рамках singleton-экземпляра при default import

localForage использует это поведение для обеспечения консистентного доступа к IndexedDB и fallback-драйверам (WebSQL и localStorage).

Интеграция с TypeScript в ES-модулях

При использовании TypeScript импорт сохраняет стандартный ESM-формат:

import localforage from "localforage";

interface User {
  id: number;
  name: string;
}

await localforage.setItem<User>("user", {
  id: 1,
  name: "Alex"
});

Типизация усиливает контроль над данными, сохраняя асинхронную модель API библиотеки.

Особенности загрузки и инициализации в ESM среде

При работе в ES-модулях важно учитывать порядок выполнения:

  1. Импорт модуля
  2. Конфигурация storage
  3. Использование методов API

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

Изоляция окружений в многомодульных приложениях

В ES-архитектуре каждый модуль имеет собственный scope, но singleton-поведение библиотеки может приводить к общей конфигурации. Для предотвращения конфликтов используется createInstance:

import localforage from "localforage";

const moduleStorage = localforage.createInstance({
  name: "ModuleA"
});

Это обеспечивает независимость между частями приложения и предотвращает перезапись настроек глобального экземпляра.

Оглавление