Esta página foi traduzida pela API Cloud Translation.

Migrar do sw-precache ou do sw-toolkit

Os desenvolvedores que já usaram sw-precache e/ou sw-toolbox têm um caminho de upgrade direto para a família de bibliotecas do Workbox. O upgrade para o Workbox vai proporcionar uma experiência moderna e extensível de service worker com melhor depuração e ergonomia do desenvolvedor.

Modificações na configuração atual

Se você estiver usando sw-precache configurado com qualquer uma das opções a seguir, precisará considerar as seguintes mudanças ao migrar para o Workbox.

Opções renomeadas

O parâmetro de configuração dynamicUrlToDependencies foi renomeado como templatedURLs.

O parâmetro de configuração staticFileGlobs foi renomeado como globPatterns.

O parâmetro de configuração runtimeCaching usa um conjunto atualizado de opções, correspondente aos nomes usados nos módulos do Workbox. Para ilustrar o que foi renomeado, esta configuração sw-precache:

runtimeCaching: [{
  urlPattern: /api/,
  handler: 'fastest',
  options: {
    cache: {
      name: 'my-api-cache',
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

é equivalente a esta configuração do Workbox:

runtimeCaching: [{
  urlPattern: /api/,
  // 'fastest' is now 'StaleWhileRevalidate'
  handler: 'StaleWhileRevalidate',
  options: {
    // options.cache.name is now options.cacheName
    cacheName: 'my-api-cache',
    // options.cache is now options.expiration
    expiration: {
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

Opções obsoletas

Não há mais suporte para rotas curinga do estilo expresso. Se você usava rotas curinga no estilo do Express na configuração runtimeCaching ou diretamente em sw-toolbox, migre para uma rota de expressão regular equivalente ao usar o Workbox.

Migrações de sw-precache

Da CLI sw-precache para a workbox-cli

Os desenvolvedores que usam a interface de linha de comando sw-precache, executando o comando manualmente ou como parte de um processo de build baseado em npm scripts, vão descobrir que o uso do módulo workbox-cli é a maneira mais fácil de migrar. A instalação de workbox-cli vai dar acesso a um binário chamado workbox.

Embora a CLI sw-precache suporte a configuração usando flags de linha de comando ou um arquivo de configuração, a CLI workbox exige que todas as opções de configuração sejam fornecidas em um arquivo de configuração usando CommonJS module.exports.

A CLI workbox é compatível com vários modos diferentes. Use workbox --help para ver todas. Mas o modo que mais se aproxima da funcionalidade de sw-precache é generateSW. Uma chamada para

$ sw-precache --config='sw-precache-config.js'

pode ser expressa como

$ workbox generateSW workbox-config.js

Do módulo de nó sw-precache para o módulo de nó workbox-build

Os desenvolvedores que usam a node API para sw-precache como parte de um fluxo de trabalho gulp/Grunt ou apenas em um script de compilação node personalizado podem migrar para o workbox-build node.

A função generateSW() do módulo workbox-build corresponde mais à função write() do módulo sw-precache. Uma diferença importante é que generateSW() sempre retorna uma promessa, enquanto a antiga função write() oferece suporte a um callback e a uma interface baseada em promessas.

Uso de gulp, por exemplo:

const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
  return swPrecache.write('service-worker.js', {
    // Config options.
  });
});

pode ser alterado para

const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
  return workboxBuild.generateSW({
    // Config options.
  });
});

Do sw-precache-webpack-plugin para o plug-in Workbox webpack

Os desenvolvedores que usam o sw-precache-webpack-plugin como parte do processo de build do webpack podem migrar para a classe GenerateSW no módulo workbox-webpack-plugin.

A workbox-webpack-plugin se integra diretamente ao processo de build do Webpack e "conhece" todos os recursos gerados por uma determinada compilação. Isso significa que, para muitos casos de uso, você pode confiar no comportamento padrão de workbox-webpack-plugin sem configuração adicional e receber um service worker equivalente ao que sw-precache-webpack-plugin oferece.

const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new SWPrecacheWebpackPlugin({
      dontCacheBustUrlsMatching: /\.\w{8}\./,
      filename: 'service-worker.js',
    }),
  ],
};

pode ser alterado para

const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new GenerateSW({
      // Config options, if needed.
    }),
  ],
};

migrações de sw-toolbox

Migrar de sw-toolbox manual para workbox-sw

Se você estava usando sw-toolbox diretamente (em vez de usar implicitamente pela opção runtimeCaching do sw-precache), a migração para o Workbox exige alguns ajustes manuais para ter o comportamento equivalente. Para mais contexto, leia a documentação dos módulos workbox-routing e workbox-strategies.

Aqui estão alguns snippets de código para ajudar a orientar a migração. Esse código sw-toolbox:

importScripts('path/to/sw-toolbox.js');

// Set up a route that matches HTTP 'GET' requests.
toolbox.router.get(
  // Match any URL that contains 'ytimg.com', regardless of
  // where in the URL that match occurs.
  /\.ytimg\.com\//,

  // Apply a cache-first strategy to anything that matches.
  toolbox.cacheFirst,

  {
    // Configure a custom cache name and expiration policy.
    cache: {
      name: 'youtube-thumbnails',
      maxEntries: 10,
      maxAgeSeconds: 30,
    },
  }
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
toolbox.router.default = toolbox.networkFirst;

é equivalente a este código do Workbox:

importScripts('path/to/workbox-sw.js');

workbox.routing.registerRoute(
  // Match any URL that contains 'ytimg.com'.
  // Unlike in sw-toolbox, in Workbox, a RegExp that matches
  // a cross-origin URL needs to include the initial 'https://'
  // as part of the match.
  new RegExp('^https://.*.ytimg.com'),

  // Apply a cache-first strategy to anything that matches.
  new workbox.strategies.CacheFirst({
    // Configuration options are passed in to the strategy.
    cacheName: 'youtube-thumbnails',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 10,
        maxAgeSeconds: 30,
      }),
      // In Workbox, you must explicitly opt-in to caching
      // responses with a status of 0 when using the
      // cache-first strategy.
      new workbox.cacheableResponse.CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
workbox.routing.setDefaultHandler(new workbox.strategies.NetworkFirst());

Receber ajuda

A maioria das migrações para o Workbox deve ser simples. Se você tiver problemas que não foram abordados neste guia, abra um problema (link em inglês) no GitHub.

Migrar do sw-precache ou do sw-toolkit Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.