Documentation

Everything WP Shipyard does fits on this page. Current release: 1.0.0, tested with WordPress 7.1.

Install

1. Download wp-shipyard.zip.
2. In wp-admin go to Plugins, Add New, Upload Plugin, choose the zip, then Install Now.
3. Activate the plugin. WP Shipyard appears under Appearance.

With WP-CLI:

wp plugin install https://github.com/WPShipyard/wp-shipyard/releases/latest/download/wp-shipyard.zip --activate

Requirements: WordPress 6.2 or newer, PHP 7.4 or newer, and an administrator account. Multisite is supported: the switch is per site and per browser, and a theme must be enabled for the site. Tested with WordPress 7.1, block and classic themes, child themes, WooCommerce and Elementor.

Enter the shipyard

Go to Appearance, then WP Shipyard. Every installed theme is listed with its screenshot, version, whether it is a block or classic theme, and its parent if it is a child theme. The live theme is tagged Live. Choose Switch to on the one you want to work in. The page reloads and, for your browser only, the site now renders with that theme. With many themes installed, a filter box narrows the list.

A theme that cannot be switched into says why in place of the button: it has errors, it is not enabled for this site on multisite, or it needs a newer WordPress or PHP than the site has. The same rules apply to the API, so a bad theme never reaches your browser.

While you are switched, the admin bar shows a yellow badge with the theme's name. Its menu holds Exit WP Shipyard, Customize or Edit site, a one-click switch to every other installed theme, and a link back to the page. So you can hop between themes from any page, front or back. The page header gains View site and Customize or Edit site buttons, and Appearance, Themes, Menus and Widgets show a reminder that they are working on the shipyard theme rather than the live one.

Fit out a theme

While switched, WordPress believes the shipyard theme is the current theme for your requests. That means:

• The Customizer opens on the shipyard theme and saves to its own theme_mods.
• Appearance, Menus lets you assign menus to the shipyard theme's locations.
• Widget areas belong to the shipyard theme's registered sidebars.
• Block themes open the Site Editor for the shipyard theme's templates.
• Front-end pages, archives and single posts render with the shipyard templates against the live content.

Everything else is shared with the live site: posts, pages, media, users, plugin settings and custom fields. If a new template expects a field that does not exist yet, add it now and the content is ready on launch day.

Exit and launch

Exit WP Shipyard, in the admin bar or on the Tools page, clears the cookie and sends you back to the live theme. Nothing you configured in the shipyard theme is lost; it is stored against that theme and waits.

Launch, on the Tools page, makes the theme you are in the live theme for everyone. A confirmation spells out what happens: visitors get the new theme right away, the menus, widgets and Customizer settings you saved in the shipyard are kept, and your browser leaves the shipyard. Under the hood it is the same theme activation Appearance, Themes performs, so it needs the switch_themes capability, and activating the theme there instead works just as well.

How it works

The plugin filters pre_option_stylesheet and pre_option_template. When the request carries a wp_shipyard_theme cookie naming an installed theme and a valid login cookie for a user with the manage_options capability, both filters return that theme (and, for a child theme, its parent) instead of the database value. Every other request falls through to the real options. The check reads the auth cookie directly rather than loading the current user, because these filters fire before init.

The cookie is set for one year, scoped to the site path, HttpOnly, Secure on HTTPS and SameSite Lax. On multisite its name carries the site id, so a switch on one site never follows you to another. Switch, Exit and Launch are available two ways: a small REST API under wp-shipyard/v1 (themes, switch, exit, launch) that the page uses, and nonce-protected admin-post.php handlers that the admin bar links and the no-JavaScript page use. Both require the capability. A stale admin bar link sends you to the page with a note rather than an error.

Every switched response is sent with Cache-Control no-store, the DONOTCACHEPAGE constant that WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed Cache and most host caches honour, and an X-WP-Shipyard header naming the theme. Nothing rendered in the shipyard is ever stored for another visitor.

Escape hatch: add ?wp_shipyard=exit to any URL of the site and the switch is cleared before WordPress loads any theme code, then the parameter is removed from the address. Site Health, Info has a WP Shipyard section listing the live theme, what this browser is switched into, the cookie and the capability.

Themes and plugins can ask where a request is:

wp_shipyard()->current();   // slug the browser is switched into, or "" when it is not
wp_shipyard()->live();      // the live theme's slug

add_filter( 'wp_shipyard_capability', fn() => 'edit_theme_options' );   // let editors preview too

// Force or veto the theme for a request. Runs before init; $user_id is 0 for a visitor.
add_filter( 'wp_shipyard_current', function ( $slug, $user_id ) {
    return isset( $_GET['preview_theme'] ) && $user_id ? 'twentytwentyfour' : $slug;
}, 10, 2 );

Whatever the filter returns is sent with the same no-store headers, so it is safe with caches; keeping visitors out of half-built themes is up to you.

Two constants change behaviour:

FAQ

Uninstall

Deactivate, then delete. The plugin creates no database tables and no options. A leftover cookie is ignored once the plugin is inactive and expires on its own after a year. A theme you launched stays active, because launching was an ordinary activation.