BloatSlayer Documentation

Overview

BloatSlayer is a WordPress performance plugin designed to help you improve your Core Web Vitals by identifying and removing unused CSS and JavaScript files from your pages. Most WordPress sites load dozens of stylesheets and scripts on every page, even when those assets are only needed on specific pages or not at all. This unnecessary loading directly impacts Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS).

BloatSlayer works by scanning your site's frontend, cataloging every enqueued asset, and giving each one a smart verdict based on its origin, dependencies, and usage patterns. You can then selectively disable the assets you do not need, reducing page weight and improving load times without touching any code.

The free version provides full scanning, verdicts, and global asset toggling. BloatSlayer Pro adds Safe Mode, per-page rules, and a visual dependency map for advanced users who want granular control.

Installation

There are two ways to install BloatSlayer on your WordPress site. You can install it via the WordPress admin dashboard or by uploading the ZIP file manually.

Install via WordPress Dashboard

1. Download the bloatslayer.zip file from your Boulley Technology account or the product page.
2. In your WordPress admin, navigate to Plugins > Add New > Upload Plugin.
3. Click Choose File, select the ZIP file, and click Install Now.
4. After installation completes, click Activate Plugin.

Install via FTP

1. Unzip the bloatslayer.zip file on your computer.
2. Upload the bloatslayer folder to /wp-content/plugins/ on your server.
3. In your WordPress admin, go to Plugins and click Activate next to BloatSlayer.

Once activated, BloatSlayer appears under Tools > BloatSlayer in your WordPress admin sidebar.

Getting Started

After activating BloatSlayer, navigate to Tools > BloatSlayer. You will see an empty dashboard prompting you to run your first scan. Click the "Scan Assets" button to begin.

When you click Scan Assets, BloatSlayer opens your site's homepage in the background, captures a snapshot of every CSS and JavaScript file that WordPress enqueues, and analyzes each one. This process typically takes a few seconds. When the scan completes, the page will reload automatically and display your results.

You can re-scan at any time to pick up new assets after installing or removing plugins and themes. It is a good practice to re-scan whenever you make significant changes to your site's plugin or theme lineup.

Dashboard

After a successful scan, the BloatSlayer dashboard displays a stats bar at the top with five key metrics that give you a quick overview of your site's asset health:

• Total Assets — The total number of CSS and JS files enqueued on your site's frontend.
• Safe to Disable — How many assets BloatSlayer has identified as safe to remove without affecting core functionality.
• Critical — Assets that are essential to your site's operation and should not be disabled.
• Disabled — How many assets you have currently toggled off.
• Size Saved — The approximate total file size of all disabled assets, showing how much bandwidth you are saving per page load.

These numbers update in real time as you toggle assets on and off. The stats bar is your primary indicator of how much optimization you have applied and how much more room there is to improve.

Asset Table

Below the stats bar, the asset table lists every CSS and JavaScript file found during the scan. Each row displays the following columns:

• Handle Name — The WordPress handle used to register and enqueue the asset (e.g., contact-form-7, jquery-core). This is the internal identifier WordPress uses.
• File Size — The file size in kilobytes. Larger files have a bigger impact on load time.
• Origin — Where the asset comes from: a plugin, your active theme, or WordPress core. This helps you understand which plugin is responsible for loading it.
• Verdict — BloatSlayer's recommendation for the asset, displayed as a color-coded badge. See the Verdicts section below for details.
• Enqueued — Whether the asset is currently loaded on your frontend.
• Disable Toggle — A switch to disable or re-enable the asset. Toggling this off prevents WordPress from loading the file on the frontend.

You can sort the table by any column and use the search box to filter assets by handle name. This makes it easy to find specific plugin assets when you have many rows.

Verdicts Explained

BloatSlayer assigns a verdict to each asset based on its source, dependencies, and known usage patterns. Each verdict is displayed as a color-coded badge:

• Safe to Disable — The asset is not used on the current page and has no dependencies that require it. You can disable it with confidence. Examples include plugin stylesheets loading on pages where the plugin's shortcode or widget is not present.
• Likely Safe — The asset is probably not needed, but BloatSlayer cannot fully confirm. It may be loaded conditionally by a plugin. Disable it and test your site's frontend to verify nothing breaks.
• Review — BloatSlayer does not have enough information to make a recommendation. You should manually check whether the asset is needed on the pages where it loads.
• Caution — The asset may be required for visible functionality. Disabling it could cause layout shifts, broken forms, or missing styles. Proceed carefully and test thoroughly if you choose to disable it.
• Critical — The asset is essential. It belongs to WordPress core, your active theme's primary stylesheet, or a critical dependency chain. Disabling it will almost certainly break your site. Do not disable unless you are certain you know what you are doing.

Safe Mode (Pro)

Safe Mode is a BloatSlayer Pro feature that provides a safety net while you experiment with disabling assets. When Safe Mode is active, your disabled asset changes only take effect for logged-in administrators. Regular visitors continue to see your full site with all assets loaded normally.

This allows you to browse your site as an admin, verify that everything looks and works correctly with the assets disabled, and only then commit the changes for all visitors. Safe Mode eliminates the risk of accidentally breaking your live site while optimizing.

To enable Safe Mode, toggle the Safe Mode switch at the top of the BloatSlayer dashboard. The switch is clearly labeled and turns blue when active. When you are satisfied that your changes are safe, turn Safe Mode off to apply the asset removals globally.

Per-Page Rules (Pro)

By default, BloatSlayer applies asset toggles globally across your entire site. With Per-Page Rules in BloatSlayer Pro, you can set different rules for individual pages and posts. For example, you might keep Contact Form 7's CSS enabled only on your Contact page and disable it everywhere else.

To set per-page rules, edit any page or post in WordPress and look for the BloatSlayer meta box in the sidebar. It shows a simplified version of the asset table with toggles specific to that page. Any per-page rule you set overrides the global setting for that particular asset on that particular page.

Per-page rules are the most effective way to optimize your site because they let you load only the assets each page actually needs. A typical site can reduce its CSS payload by 60-80% on most pages using per-page rules.

Dependency Map (Pro)

The Dependency Map is a visual tree that shows how your assets relate to each other. Some scripts depend on other scripts (for example, many plugins depend on jQuery), and disabling a dependency can break multiple assets downstream.

The map displays each asset as a node, with lines connecting assets to their dependencies. Assets with many dependents are highlighted so you can see which ones are critical load-bearing files. Hovering over a node reveals its full file path, size, and the list of assets that depend on it.

Use the Dependency Map before disabling assets with a "Review" or "Caution" verdict. If an asset has no dependents and is not part of a dependency chain, it is generally safer to remove. If it has multiple dependents, disabling it will also effectively break the assets that rely on it.

License Activation

BloatSlayer Pro features require an active license key. After purchasing a Pro license from Boulley Technology, you can activate it directly within the plugin.

1. Navigate to Tools > BloatSlayer in your WordPress admin.
2. Click the License tab or look for the license activation field at the bottom of the dashboard.
3. Enter your license key exactly as it appears in your purchase confirmation email or your Boulley Technology account dashboard.
4. Click Activate License. The page will confirm activation and unlock Pro features immediately.

Each license key is valid for one site. If you need to move your license to a different site, deactivate it first from the current site, then activate it on the new one. You can manage your licenses at any time from your Boulley Technology account.

Troubleshooting

My site looks broken after disabling assets

Go back to Tools > BloatSlayer and re-enable the assets you most recently disabled. If you are unsure which asset caused the issue, re-enable all assets and then disable them one at a time, checking your frontend after each change. Using Safe Mode (Pro) prevents this scenario by limiting changes to admin views first.

The scan is not finding any assets

Make sure your site is accessible from the server. BloatSlayer loads your homepage to detect assets. If you have a maintenance mode plugin active, an HTTP authentication prompt, or a firewall blocking local requests, the scan will not be able to reach your frontend. Temporarily disable these protections, run the scan, then re-enable them.

Scan completes but results seem incomplete

Clear any caching layers (plugin cache, server cache, CDN cache) before scanning. Cached pages may serve stale HTML that does not reflect the current set of enqueued assets. After clearing caches, run the scan again.

Assets keep coming back after I disable them

Some plugins forcefully enqueue their assets in ways that bypass the standard WordPress dequeue mechanism. BloatSlayer handles the vast majority of cases, but if a plugin uses aggressive late-loading techniques, the asset may re-appear. Contact our support team with the asset handle name and the plugin responsible, and we will investigate.

Pro features are not showing up

Verify that your license key is activated under the License tab. If the key shows as active but Pro features are still hidden, try deactivating and reactivating the plugin. If the issue persists, check that you are running the latest version of BloatSlayer.

Frequently Asked Questions

Will BloatSlayer break my site?

BloatSlayer does not modify any files. It simply prevents WordPress from loading selected assets on the frontend. If you disable something that causes a problem, re-enabling it instantly restores normal behavior. With Safe Mode (Pro), you can test changes as an admin before they affect visitors.

Does it work with page builders like Elementor or Divi?

Yes. BloatSlayer scans all enqueued assets regardless of which page builder you use. It is particularly effective on page builder sites because these builders tend to load many assets globally. Per-page rules let you keep builder assets only on the pages that use them.

How much faster will my site be?

Results vary depending on how many unnecessary assets your site loads. A typical WordPress site with 10-15 plugins can often eliminate 40-70% of its CSS and JS payload, which translates to measurable improvements in load time and Core Web Vitals scores.

Does BloatSlayer work with caching plugins?

Yes. BloatSlayer operates at the WordPress enqueue level, which runs before any caching plugin generates its cached files. After changing your BloatSlayer settings, clear your cache so the caching plugin generates new cached pages that reflect the updated asset list.

Can I use BloatSlayer on a multisite network?

BloatSlayer can be activated on individual sites within a multisite network. Each sub-site maintains its own asset list and settings. Network-wide activation with shared settings is not currently supported but is planned for a future release.