Service Worker

As noted in a Google primer:

Rich offline experiences, periodic background syncs, push notifications—functionality that would normally require a native application—are coming to the web. Service workers provide the technical foundation that all these features rely on.

Only one service worker can be controlling a page at a time. This has prevented themes and plugins from each introducing their own service workers because only one wins. So the first step at adding support for service workers in core is to provide an API for themes and plugins to register scripts and then have them concatenated into a script that is installed as the service worker. There are two such concatenated service worker scripts that are made available: one for the frontend and one for the admin. The frontend service worker is installed under the home('/') scope and the admin service worker is installed under the admin_url('/') scope.

The API is implemented using the same interface as WordPress uses for registering scripts; in fact WP_Service_Worker_Scripts is a subclass of WP_Scripts. The instance of this class is accessible via wp_service_workers()->get_registry(). Instead of using wp_register_script() the service worker scripts are registered using wp_register_service_worker_script(). This function accepts two parameters:

• $handle: The service worker script handle which can be used to mark the script as a dependency for other scripts.
• $args: An array of additional service worker script arguments as $key => $value pairs:
  • $src: Required. The URL to the service worker on the local filesystem or a callback function which returns the script to include in the service worker.
  • $deps: An array of service worker script handles that a script depends on.

Note that there is no $ver (version) parameter because browsers do not cache service workers so there is no need to cache bust them.

Service worker scripts should be registered on the wp_front_service_worker and/or wp_admin_service_worker action hooks, depending on whether they should be active for the frontend service worker, the admin service worker, or both of them. The hooks are passed the WP_Service_Worker_Scripts instance, so you can optionally access its register() method directly, which wp_register_service_worker_script() is a simple wrapper of.

Here are some examples:

function register_foo_service_worker_script( $scripts ) {
	// $scripts->register() is the same as wp_register_service_worker_script().
	$scripts->register(
		'foo', // Handle.
		array(
			'src'  => plugin_dir_url( __FILE__ ) . 'foo.js', // Source.
			'deps' => array( 'app-shell' ), // Dependency.
		)
	);
}
// Register for the frontend service worker.
add_action( 'wp_front_service_worker', 'register_foo_service_worker_script' );

function register_bar_service_worker_script( $scripts ) {
	$scripts->register(
		'bar',
		array(
			// Use a script render callback instead of a source file.
			'src'  => function() {
				return 'console.info( "Hello admin!" );';
			},
			'deps' => array(), // No dependencies (can also be omitted).
		)
	);
}
// Register for the admin service worker.
add_action( 'wp_admin_service_worker', 'register_bar_service_worker_script' );

function register_baz_service_worker_script( $scripts ) {
	$scripts->register( 'baz', array( 'src' => plugin_dir_url( __FILE__ ) . 'baz.js' ) );
}
// Register for both the frontend and admin service worker.
add_action( 'wp_front_service_worker', 'register_baz_service_worker_script' );
add_action( 'wp_admin_service_worker', 'register_baz_service_worker_script' );

See labeled GitHub issues and see WordPress core tracking ticket #36995.

Caching

Service Workers in the feature plugin are using Workbox to power a higher-level PHP abstraction for themes and plugins to indicate the routes and the caching strategies in a declarative way. Since only one handler can be used per one route then conflicts are also detected and reported in console when using debug mode.

The API abstraction allows registering routes for caching and urls for precaching using the following two functions:

1. wp_register_service_worker_caching_route(): accepts the following two parameters:

• $route: Route regular expression, without delimiters.
• $args: An array of additional route arguments as $key => $value pairs:
  • $strategy: Required. Strategy, can be WP_Service_Worker_Caching_Routes::STRATEGY_NETWORK_FIRST, WP_Service_Worker_Caching_Routes::STRATEGY_CACHE_FIRST, WP_Service_Worker_Caching_Routes::STRATEGY_STALE_WHILE_REVALIDATE, WP_Service_Worker_Caching_Routes::STRATEGY_CACHE_ONLY, WP_Service_Worker_Caching_Routes::STRATEGY_NETWORK_ONLY.
  • For more information about the behavior of the strategies, please see Workbox Strategies.
  • ℹ️ Typically navigation requests and theme/plugin assets should use the network-first strategy; uploaded files may use the cache-first strategy. It is not currently recommended to use the stale-while-revalidate strategy for navigation requests because there is no mechanism in place yet to inform the user that an update is available (see #217).
  • $cache_name: Name to use for the cache.
  • $plugins: Array of plugins with configuration. The key of each plugin in the array must match the plugin's name. See https://developers.google.com/web/tools/workbox/guides/using-plugins#workbox_plugins.

2. wp_register_service_worker_precaching_route(): accepts the following two parameters:

• $url: URL to cache.
• $args: An array of additional route arguments as $key => $value pairs:
  • $revision: Revision, optional.

Examples of using the API:

add_action( 'wp_front_service_worker', function( \WP_Service_Worker_Scripts $scripts ) {
	$scripts->caching_routes()->register(
		'/wp-content/.*\.(?:png|gif|jpg|jpeg|svg|webp)(\?.*)?$',
		array(
			'strategy'  => WP_Service_Worker_Caching_Routes::STRATEGY_CACHE_FIRST,
			'cacheName' => 'images',
			'plugins'   => array(
				'expiration' => array(
					'maxEntries'    => 60,
					'maxAgeSeconds' => 60 * 60 * 24,
				),
			),
		)
	);
} );

add_action( 'wp_front_service_worker', function( \WP_Service_Worker_Scripts $scripts ) {
	$scripts->precaching_routes()->register(
		'https://example.com/wp-content/themes/my-theme/my-theme-image.png',
		array(
			'revision' => get_bloginfo( 'version' ),
		)
	);
} );

If you would like to opt-in to a caching strategy for navigation requests, you can do:

add_filter( 'wp_service_worker_navigation_caching_strategy', function() {
	return WP_Service_Worker_Caching_Routes::STRATEGY_NETWORK_FIRST;
} );

add_filter( 'wp_service_worker_navigation_caching_strategy_args', function( $args ) {
	$args['cacheName'] = 'pages';
	$args['plugins']['expiration']['maxEntries'] = 50;
	return $args;
} );

Please note that if you are using the stale-while-revalidate strategy, it is important that you set the cache entries to expire the same time as the logged-in user nonce. For example:

add_filter(
	'wp_service_worker_navigation_caching_strategy',
	function() {
		return WP_Service_Worker_Caching_Routes::STRATEGY_STALE_WHILE_REVALIDATE;
	}
);
add_filter(
	'wp_service_worker_navigation_caching_strategy_args',
	function( $args ) {
		$args['cacheName']                           = 'pages';
		$args['plugins']['expiration']['maxEntries'] = 20;

		/** This filter is documented in wp-includes/pluggable.php */
		$max_age_seconds = apply_filters( 'nonce_life', DAY_IN_SECONDS );
		$args['plugins']['expiration']['maxAgeSeconds'] = $max_age_seconds;

		return $args;
	}
);

As noted above, the stale-while-revalidate strategy is not currently recommended.

(If you previously added a wp_service_worker_navigation_preload filter to disable navigation preload, you should probably remove it. This was originally needed to work around an issue with ensuring the offline page would work when using a navigation caching strategy, but it is no longer needed and it should be removed improved performance. Disabling navigation preload is only relevant when you are developing an app shell.)

Offline / 500 error handling

The feature plugins offers improved offline experience by displaying a custom template when user is offline instead of the default message in browser. Same goes for 500 errors -- a template is displayed together with error details.

Themes can override the default template by using error.php, offline.php, and 500.php in you theme folder. error.php is a general template for both offline and 500 error pages and it is overridden by offline.php and 500.php if they exist.

Note that the templates should use wp_service_worker_error_message_placeholder() for displaying the offline / error messages. Additionally, on the 500 error template the details of the error can be displayed using the function wp_service_worker_error_details_template( $output ).

For development purposes the offline and 500 error templates are visible on the following URLs on your site:

• https://your-site-name.com/?wp_error_template=offline;
• https://your-site-name.com/?wp_error_template=500

Default value for $output is the following: <details id="error-details"><summary>' . esc_html__( 'More Details', 'pwa' ) . '</summary>{{{error_details_iframe}}}</details> where {{{error_details_iframe}}} will be replaced by the iframe.

In case of using the <iframe> within the template {{{iframe_src}}} and {{{iframe_srcdoc}}} are available as well.

For example this could be done:

wp_service_worker_error_details_template(
    '<details id="error-details"><summary>' . esc_html__( 'More Details', 'pwa' ) . '</summary><iframe style="width:100%" src="{{{iframe_src}}}" data-srcdoc="{{{iframe_srcdoc}}}"></iframe></details>'
);

Offline Commenting

Another feature improving the offline experience is Offline Commenting implemented leveraging Workbox Background Sync API.

In case of submitting a comment and being offline (failing to fetch) the request is added to a queue and once the browsers "thinks" the connectivity is back then Sync is triggered and all the commenting requests in the queue are replayed. This meas that the comment will be resubmitted once the connection is back.

Available actions and filters

Here is a list of all available actions and filters added by the feature plugin.

Filters

• wp_service_worker_skip_waiting: Filters whether the service worker should update automatically when a new version is available.
  • Has one boolean argument which defaults to true.
• wp_service_worker_clients_claim: Filters whether the service worker should use clientsClaim() after skipWaiting().
  • Has one boolean argument which defaults to false;
• wp_service_worker_navigation_preload: Filters whether navigation preload is enabled. Has two arguments:
  • boolean which defaults to true;
  • $current_scope, either 1 (WP_Service_Workers::SCOPE_FRONT) or 2 (WP_Service_Workers::SCOPE_ADMIN);
• wp_offline_error_precache_entry: Filters what is precached to serve as the offline error response on the frontend.
  • Has one parameter $entry which is an array:
    • $url URL to page that shows the offline error template.
    • $revision Revision for the template. This defaults to the template and stylesheet names, with their respective theme versions.
• wp_server_error_precache_entry: Filters what is precached to serve as the internal server error response on the frontend.
  • Has one parameter $entry which is an array:
    • $url URL to page that shows the server error template.
    • $revision Revision for the template. This defaults to the template and stylesheet names, with their respective theme versions.
• wp_service_worker_error_messages: Filters the offline error messages displayed on the offline template by default and in case of offline commenting.
  • Has one argument with array of messages:
    • $default The message to display on the default offline template;
    • $comment The message to display on the offline template in case of commenting;

Actions

• wp_front_service_worker: Fires before serving the frontend service worker, when its scripts should be registered, caching routes established, and assets precached.
  • Has one argument $scripts WP_Service_Worker_Scripts Instance to register service worker behavior with.
• wp_admin_service_worker: Fires before serving the wp-admin service worker, when its scripts should be registered, caching routes established, and assets precached.
  • Has one argument $scripts WP_Service_Worker_Scripts Instance to register service worker behavior with.
• wp_default_service_workers: Fires when the WP_Service_Worker_Scripts instance is initialized.
  • Has one argument $scripts WP_Service_Worker_Scripts Instance to register service worker behavior with.

Integrations

The plugin bundles several experimental integrations that are kept separate from the service worker core code. These integrations act as examples and proof-of-concept to achieve certain goals. While all of them are generally applicable and recommended to truly benefit from service workers, they are not crucial for the core API.

All these integrations are hidden behind a feature flag. To enable them, you can add service_worker theme support:

add_theme_support( 'service_worker', true );

Alternatively, you can selectively enable specific integrations by providing an array when adding theme support:

add_theme_support(
	'service_worker',
	array(
		'wp-site-icon'         => false,
		'wp-custom-logo'       => true,
		'wp-custom-background' => true,
		'wp-fonts'             => true,
	)
);

Most of the integrations involve precaching assets when the service worker is first installed. This ensures that all of the assets will be available when the user goes offline, but it has a couple downsides:

1. Many more resources may be downloaded and cached than are actually needed. For example, the wp-custom-logo integration will precache all image sizes that are included in the srcset for the Custom Logo. When on a mobile device, this may mean downloading a large logo image size that is never used.
2. Precached resources are served with a cache-first strategy. When the service worker is installed, each precached resource gets a corresponding revision. When a resource is changed, this necessitates a service worker update to download the new resource before it will be served. This will mean that the user may have to reload the page (after first closing other windows for that site) to see this update. This is particularly annoying during development, but it also makes

For these reasons, precaching resources should be done very sparingly. (The only two resources which are always precached are the offline page and the error page.) Instead, runtime caching should be used with a network-first caching strategy so that the latest version of a resource will be used whenever it is changed and then fallback to a previously-cached resource.

⚠️ The following integrations are experimental and not necessarily recommended and they may be deprecated/removed!

The available integrations are as follows:

• wp-site-icon: Add the various site icon sizes to the precache.
• wp-custom-logo: Add the full size custom logo image(s) to the precache.
• wp-custom-header: Add the theme's custom header image(s) to the precache.
• wp-custom-background: Add the theme's custom background image to the precache.
• wp-scripts: Add scripts with the precache data flag set to the precache. Also included is the emoji script. The precache flag is added like so: wp_script_add_data( $handle, 'precache', true ).
• wp-styles: Add styles with the precache data flag set to the precache. The precache flag is added like so: wp_style_add_data( $handle, 'precache', true ).
• wp-fonts: Add assets used by Google Fonts to the runtime cache.
• wp-admin-assets: Add all scripts, styles, and fonts used in the admin to the precache. This only applies to the service worker used in the admin.