PurifyCSS WordPress Plugin: Getting started

1. Get a license (if you don’t have one yet)

The license key gives you acces to the PurifyCSS API, that is used to generate the optimized CSS files.

After the registration, you will find the license key on the dashboard in your user account.

2. Activate your license

In order to connect your domain with your license key, you need to enter the key in the field on the plugin settings page and press “Activate”.

If you want to remove a domain you activated previously, you can manage your domains in your user account dashboard.

3. Generate the optimized CSS files

You can optimize your CSS files in two ways: by crawling all pages at once or one-by-one for a single URL.

Process multiple pages in a bulk job

You can have the API automatically crawl your site and detect the unused CSS for each crawled page in a batch as a bulk job. Depending on the number of URLs, this can take several minutes, meanwhile you can monitor the progress in an overview of the pages already found.

PurifyCSS Plugin – Running job with multiple URLs and different states for subtasks: done, enqueued & processing

Process a single page

If you just want to do a quick test instead of scanning the whole site, you can also run the optimization process for a single URL. For this, you need to go to a page of your choice, while still logged in as administrator, in the admin bar select PurifyCSS / “Run for this URL” (or “Re-run”, if there is already generated data for the current page).

While working, you will see a loading indicator, near the PurifyCSS admin bar menu. When that disappears, the processing is finished, and you can reload the page, to view the changes.
(I know… that is not the user-friendliest and most intuitive way, but it’s on my to-do list to improve that)

4. Test your site with the generated CSS files

Make sure to test your pages thoroughly.
Note that the plugin might have deleted some parts of your code that are actually necessary, e.g. some CSS classes that were inserted after page load. There is no way for the plugin to detect all edge cases with high accuracy, so manual testing is important.

There are two ways to view the changes before releasing it to the public.

Add the parameter purifycss=true to any URL of your site

By using the parameter purifycss with “true” or “false”, you can directly compare the original styles with the optimized ones. Just open your URL with &purify=true in one tab and the same URL with &purify=false in another. By switching between those tabs (I recommend using the keyboard shortcut Ctrl+Tab), you will immediately see if there is any visual difference between the two versions.

Choose “test mode” on the settings page

By enabling test mode, only you (as a logged in admin user) will see the pages using the optimized css files. Your visitors will still see the original styles. This enables you to browse through your site and look for any errors that might be caused by PurifyCSS. You can still append &purify=false to any URL if you want to compare a page to the original one.

Some tips regarding what to pay attention to:

  • Hover over and click on elements
  • Try submitting your forms with incomplete or invalid data
  • Also test pages that are not linked from your home page or through your main navigation
  • Test on different screen sizes – not just by resizing your window, but also on different physical devices
  • Test in different browsers!

If you run into other cases, that might be helpful to other users, please let me know, so that I can add them to the list above. Thank you!

5. Adjust your settings where necessary

If you run into cases where style rules were removed by mistake, it is very likely that the problem is due to asynchronously added classes or HTML. You can tell the plugin which HTML snippets to consider in the next run by adding them on the settings page under “PurifyCSS options”

Custom HTML Code – in this case for a Contact Form 7 validation message

If you find it difficult to fix a specific page, you can also exclude it by adding the URL to the “Exclude URLs” list. Add one URL per line. The excluded pages will still use the original styles, even when the plugin is active.

6. Publish the optimized CSS files

When you are confident that you found and fixed all style issues, you can release your optimized files to the public by pressing the “Live” button:

Note that if you re-run Purifycss while it is in “Live” mode, it will automatically switch back to “Off”. This happens because of two main reasons: 1) the API that crawls your public-facing site would otherwise get the already truncated files, so it is disabled to be able to access the original styles and 2) after re-generating the optimized files, you should manually test your site with the new styles before enabling them again on the public site.