WordPress Speculative Loading

WordPress emits a browser speculationrules script in the frontend footer. Core enables it by default only for logged-out requests with pretty permalinks, then applies safe defaults and exclusions. Plugins should usually exclude sensitive plugin URLs, not replace Core's entire rule set.

Configuration contract

wp_get_speculation_rules_configuration() returns:

• null when disabled; or
• array( 'mode' => 'prefetch|prerender', 'eagerness' => 'conservative|moderate|eager' ).

Filter the policy only when the plugin truly owns the site-wide decision:

add_filter( 'wp_speculation_rules_configuration', static function ( $config ) {
    if ( is_page( 'member-dashboard' ) ) {
        return null;
    }
    return $config;
} );

The input may be null. Returning invalid data does not fail closed; Core sanitizes it back to defaults. Return null explicitly to disable.

Exclude plugin-owned routes

Use root-relative path patterns and * wildcards:

add_filter(
    'wp_speculation_rules_href_exclude_paths',
    static function ( array $paths, string $mode ): array {
        $paths[] = '/checkout/*';
        $paths[] = '/account/*';
        $paths[] = '/my-plugin/action/*';
        return $paths;
    },
    10,
    2
);

Core's own exclusions cannot be removed through this filter. Core excludes admin/login/content paths, query-string URLs on pretty-permalink sites, rel="nofollow", and elements opted out by class.

For one link or subtree:

<a class="no-prefetch no-prerender" href="/account/sign-out/">Sign out</a>

Under prerender, .no-prefetch also opts out because prerender includes fetching.

Add a custom rule carefully

Use wp_load_speculation_rules and the passed rule collection. Its concrete class is Core-internal, so depend on the documented hook and add_rule() behavior rather than constructing or persisting the class yourself.

add_action( 'wp_load_speculation_rules', static function ( $rules ): void {
    $rules->add_rule(
        'prefetch',
        'acme-next-page',
        array(
            'source'    => 'list',
            'urls'      => array( home_url( '/docs/next/' ) ),
            'eagerness' => 'moderate',
        )
    );
} );

Rule IDs must contain at least two characters: a lowercase letter followed by one or more lowercase letters, digits, _, or -. A rule uses either where (document source) or urls (list source), never both. immediate is permitted only for list rules, not document-level rules.

WordPress 7.1 host defaults

Core still defaults auto to prefetch + conservative. In 7.1, hosting operators can change what auto resolves to using either constants or same-named environment variables:

define( 'WP_SPECULATIVE_LOADING_DEFAULT_MODE', 'prerender' );
define( 'WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS', 'moderate' );

The constant wins over the environment variable. Invalid values fall back to Core defaults, and immediate is not accepted as the site-wide default. Plugins should not define these operator-level constants. An explicit wp_speculation_rules_configuration filter value still takes precedence over the host's auto default.

Safety model

Prefetch/prerender may issue a GET before the user intentionally navigates.

• GET routes must never mutate data, consume a one-time operation, log out a user, place an order, or trigger billing.
• Exclude carts, checkout, account actions, nonce-bearing actions, and highly personalized/session-sensitive pages.
• Ensure prerendered responses have correct cache headers and cannot be served across users.
• Do not add cross-origin URLs without reviewing privacy, authentication, and browser behavior.
• Do not assume unsupported browsers execute the rules; navigation must work normally without them.
• Keep rule sets small. Aggressive eagerness can waste bandwidth and backend capacity.

Read references/rules-and-test-matrix.md for Core exclusions, validation, and test cases.

Verification

1. Test logged-out pretty-permalink HTML and inspect the footer's script[type="speculationrules"] JSON.
2. Confirm logged-in and plain-permalink defaults are disabled unless another filter intentionally enables them.
3. Assert every state-changing GET is fixed or excluded; exclusion is defense-in-depth, not permission control.
4. Exercise configuration with null, malformed arrays, and valid explicit values.
5. Test host constants separately from plugin filters.
6. Observe requests and cache/session behavior in a browser that implements Speculation Rules.

Related skills

• plugin-scaffold/wp-plugin-assets-loading for general frontend loading strategy.
• wordpress/wp-security-audit for state-changing GET and authorization review.

References

• Read references/rules-and-test-matrix.md for the rule shape, exclusion patterns and the verification matrix.
• WordPress 7.1 Field Guide: https://make.wordpress.org/core/2026/08/05/wordpress-7-1-field-guide/