Параметр replacePrefix

Библиотека sw-precache используется для генерации сервис-воркеров, которые автоматически кэшируют статические ресурсы веб-приложения и обеспечивают оффлайн-доступ. Одним из ключевых инструментов настройки путей к ресурсам является параметр replacePrefix. Он предназначен для модификации URL-адресов кэшируемых файлов перед их записью в манифест сервис-воркера.

Назначение `replacePrefix`

replacePrefix позволяет заменять часть пути к файлу на другой префикс, что особенно важно при деплое проекта на сервер с другой структурой каталогов или при использовании CDN. Это обеспечивает корректное разрешение URL в момент запроса к кэшированным ресурсам.

Например, если локально файлы находятся в папке /dist/, а на сервере они доступны по пути /static/, параметр replacePrefix позволяет указать соответствие:

replacePrefix: {
  'dist/': 'static/'
}

После генерации сервис-воркера все пути в манифесте, начинающиеся с dist/, будут заменены на static/, что гарантирует правильную работу кэша в продакшн-среде.

Синтаксис и поддерживаемые типы

replacePrefix может быть указан в виде:

Объекта, где ключ — исходный префикс, а значение — префикс замены:

replacePrefix: {
  'src/': '/assets/',
  'lib/': '/vendor/'
}

Функции, которая принимает путь к файлу и возвращает новый путь:

replacePrefix: function(filePath) {
  return filePath.replace(/^dist\//, 'static/');
}

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

Влияние на кэширование

Параметр replacePrefix не изменяет структуру файловой системы, а только модифицирует пути в манифесте сервис-воркера. Это значит, что:

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

Важно учитывать, что replacePrefix применяется до сериализации манифеста, то есть изменения касаются исключительно URL, которые будут использоваться в precacheConfig.

Примеры использования

1. Простой префикс для продакшн-сборки

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'dist/**/*.js',
    'dist/**/*.css',
    'dist/**/*.html'
  ],
  replacePrefix: {
    'dist/': '/static/'
  }
});

В этом случае все файлы из локальной папки dist/ будут кэшироваться с префиксом /static/.

2. Использование функции для динамической замены

swPrecache.write('service-worker.js', {
  staticFileGlobs: [
    'build/**/*.js',
    'build/**/*.css'
  ],
  replacePrefix: function(filePath) {
    if (filePath.endsWith('.js')) {
      return '/scripts/' + filePath.replace(/^build\//, '');
    }
    return '/styles/' + filePath.replace(/^build\//, '');
  }
});

Здесь для JavaScript-файлов создается префикс /scripts/, а для CSS — /styles/, что позволяет разделять ресурсы по категориям в кэше.

Особенности и ограничения

replacePrefix работает только с файлами, указанными в staticFileGlobs. Файлы, добавленные динамически через runtime caching, не затрагиваются.
При использовании объекта с ключами, важно, чтобы ключи точно соответствовали началу пути. Любые несовпадения приведут к тому, что префикс не будет заменён.
Функциональный подход предпочтителен при необходимости сложной логики преобразования или при наличии нескольких условий.