Fixing CSS view transitions when developing with Local

I’ve been running into an issue where CSS view transitions would sometimes work, sometimes not when using Local by Flywheel. It’s a little tricky to troubleshoot legitimate view transition issues (like mismatched classes and elements) when the transition would fail for other mysterious reasons. It turns out the culprit is WordPress’s speculative loading rules coupled with Flywheel’s nginx configuration.

Starting with WordPress 6.8, speculative loading is enabled by default, prefetching pages that users are likely to navigate to. As a result, using navigation:auto within @view-transition{} in CSS sometimes leads to an issue in Chrome (and likely other Chromium based browsers), where pages load so fast the view transition is skipped and the browser console reports a general view transition error.

Local by Flywheel compounds this using Cache-Control: no-store on all responses, which seems to conflict with Chrome’s prefetch cache.

WordPress exposes a wp_speculation_rules_configuration filter to control speculation behavior. Switching from prefetch mode to prerender resolves the conflict. I wrap this with a local conditional check, allowing the defaults be used in other environments.

add_filter( 'wp_speculation_rules_configuration', 'apm_configure_speculation_rules' );

function apm_configure_speculation_rules( $config ) {

    if ( wp_get_environment_type() === 'local' ) {
        $config['mode'] = 'prerender';
        $config['eagerness'] = 'conservative';
    }

    return $config;

}