Подключение в проект на CommonJS

Использование CommonJS-модулей для интеграции библиотеки localForage характерно для проектов, построенных на Node.js-инструментах сборки, таких как Webpack, Browserify или Parcel. Несмотря на то что localForage предназначена для работы в браузере и опирается на Web APIs (IndexedDB, WebSQL, localStorage), её корректное подключение через CommonJS остаётся стандартным сценарием в современных фронтенд-пайплайнах.

Основы CommonJS-импорта localForage

В проектах, где используется система модулей CommonJS, подключение библиотеки осуществляется через require:

const localForage = require('localforage');

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

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

Установка библиотеки перед подключением

Перед использованием CommonJS-импорта библиотека должна быть установлена через npm или yarn:

npm install localforage

или

yarn add localforage

После установки пакет попадает в node_modules, откуда и резолвится через require.

Особенности работы в сборщиках модулей

Webpack

Webpack корректно обрабатывает CommonJS-модули и преобразует их в формат, пригодный для браузера. При подключении localForage через require происходит следующее:

  • модуль попадает в dependency graph;
  • Webpack включает его в бандл;
  • браузер получает уже транспилированный код без необходимости поддержки CommonJS.

Пример использования в Webpack-проекте:

const localForage = require('localforage');

localForage.setItem('token', 'abc123')
  .then(() => console.log('Сохранено'));

Browserify

Browserify исторически ориентирован на CommonJS, поэтому localForage подключается без дополнительных настроек:

var localForage = require('localforage');

localForage.getItem('token').then(function (value) {
  console.log(value);
});

Parcel

Parcel автоматически определяет модульную систему и также поддерживает CommonJS без дополнительной конфигурации:

const localForage = require('localforage');

Внутренняя совместимость CommonJS и ES Modules

localForage распространяется как пакет, совместимый одновременно с CommonJS и ES Modules. Это означает, что:

  • require('localforage') работает без дополнительных транспиляций;
  • import localForage from 'localforage' является альтернативным синтаксисом;
  • оба подхода приводят к одному и тому же экспортируемому объекту.

В средах сборки часто происходит интероп между форматами модулей, обеспечиваемый транспайлерами (Babel, TypeScript).

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

После подключения через CommonJS доступен полный API библиотеки:

const localForage = require('localforage');

localForage.setItem('user', { id: 1, name: 'Alex' });

localForage.getItem('user').then((value) => {
  console.log(value);
});

Методы возвращают Promise, что делает возможным построение цепочек обработки данных:

localForage.setItem('settings', { theme: 'dark' })
  .then(() => localForage.getItem('settings'))
  .then((value) => {
    console.log(value.theme);
  });

Конфигурация после подключения

CommonJS-подключение не влияет на возможность конфигурирования библиотеки. Настройки применяются сразу после импорта:

const localForage = require('localforage');

localForage.config({
  name: 'myApp',
  storeName: 'keyValueStore',
  driver: localForage.INDEXEDDB
});

Параметры конфигурации:

  • name — имя базы данных;
  • storeName — имя хранилища;
  • driver — выбор backend-хранилища.

Выбор драйвера в CommonJS-среде

После подключения через require доступен полный контроль над драйверами:

const localForage = require('localforage');

localForage.setDriver([
  localForage.INDEXEDDB,
  localForage.WEBSQL,
  localForage.LOCALSTORAGE
]);

Механизм выбора драйвера остаётся идентичным вне зависимости от системы модулей.

Использование в SSR и Node.js окружении

Несмотря на возможность импорта через CommonJS, localForage не предназначен для прямого выполнения в Node.js, поскольку зависит от браузерных API.

При использовании SSR (например, Next.js или Nuxt в режиме серверного рендеринга) требуется учитывать:

  • window и IndexedDB отсутствуют на сервере;
  • вызовы localForage должны выполняться только на клиенте;
  • импорт через require допустим, но обращение к API — условное.

Пример безопасного использования:

let localForage;

if (typeof window !== 'undefined') {
  localForage = require('localforage');
}

Ленивая инициализация через CommonJS

В некоторых архитектурах применяется динамическая загрузка:

function getStorage() {
  return require('localforage');
}

const storage = getStorage();

storage.setItem('cache', 'data');

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

Типичные ошибки при подключении

1. Использование до загрузки DOM

const localForage = require('localforage');

localForage.setItem('key', 'value');

Ошибка возникает только в окружениях, где IndexedDB недоступен до полной инициализации браузера.

2. Конфликт сборщика с ESM/CJS интеропом

При неправильной настройке Babel или Webpack возможны ситуации:

  • localForage.default is undefined;
  • двойная обёртка экспортов.

Решается настройкой esModuleInterop или корректным импортом:

const localForage = require('localforage').default || require('localforage');

3. Использование в Node.js без полифиллов

Отсутствие Web APIs приводит к ошибкам выполнения, поскольку localForage не содержит серверной реализации хранилища.

Архитектурное место CommonJS-подключения

В современных фронтенд-приложениях CommonJS часто выступает промежуточным слоем:

  • исходный код может быть написан в ESM;
  • сборщик преобразует модули в CommonJS или обратно;
  • localForage включается в финальный бандл как универсальная зависимость.

Такой подход обеспечивает совместимость с legacy-кодом и старыми инструментами сборки.

Поведение экспорта в CommonJS

Экспорт localForage представляет собой единый объект, содержащий:

  • методы управления хранилищем;
  • константы драйверов;
  • конфигурационные функции.

При импорте через require отсутствует необходимость деструктуризации:

const localForage = require('localforage');

localForage.clear();

Однако при желании возможно точечное извлечение:

const { setItem, getItem } = require('localforage');

Такой вариант используется реже, поскольку нарушает единообразие API-объекта.

Итоговая модель подключения в CommonJS-проектах

CommonJS-использование localForage строится на трёх базовых шагах:

  1. установка пакета через npm;
  2. импорт через require;
  3. использование асинхронного API с Promise.

Эта модель остаётся стабильной независимо от сборщика и масштаба приложения, сохраняя совместимость с современными и устаревшими фронтенд-архитектурами.

Оглавление