solarssk/wp-critical-css repository overview

⁠WP Critical CSS

Self-hosted critical CSS generator for WordPress. No metered quota. No SaaS. Your own container, your own control.

Full documentation, source, and issue tracker live on GitHub: github.com/solarssk/wp-critical-css⁠.

⁠What it does

WP Rocket's Remove Unused CSS and QUIC.cloud's free tier both solve the same problem - shipping only the CSS a page actually needs above the fold - behind a paid plan or a metered quota. This image does the same job with a container you run yourself: a real headless Chrome renders each URL and extracts the above-the-fold CSS for mobile and desktop separately, and a small companion WordPress plugin inlines it and defers the rest.

⁠How it works

1. Trigger - a post is saved/published (save_post hook), or the daily sitemap sweep picks it up.
2. Queue - both paths feed one generation queue, bounded so it can't grow without limit.
3. Render - headless Chrome extracts critical CSS for mobile and desktop viewports separately.
4. Deliver - the result is POSTed back to WordPress and stored (per-post, or as site options for the homepage).
5. Inject - critical CSS is inlined in <style id="wpcc-critical-css">; the theme's regular stylesheets defer via the standard media="print" swap.

⁠Features

⁠Stack

⁠Quick start

Add to your existing WordPress docker-compose.yml:

services:
  critical-css-service:
    image: solarssk/wp-critical-css:latest
    restart: always
    init: true
    cap_drop: [ALL]
    read_only: true
    tmpfs:
      - /tmp
      - /home/pptruser/.cache/puppeteer/tmp
    env_file:
      - .env
    networks:
      - your_wordpress_network

.env needs (see .env.example⁠):

• SHARED_SECRET - generate with openssl rand -hex 32
• WP_RECEIVER_URL - your WordPress REST endpoint
• ALLOWED_HOSTNAME - your site's hostname (only this hostname is ever rendered)
• SITE_SITEMAP_URL - your sitemap index URL

Add the same secret to wp-config.php:

define( 'WPCC_SHARED_SECRET', '<same value as SHARED_SECRET above>' );

Then install the companion WP Critical CSS plugin from a GitHub release⁠ - upload the zip via Plugins > Add New Plugin > Upload Plugin, no server file access needed. Full walkthrough: docs/DEPLOYMENT.md⁠.

⁠Image tags

solarssk/wp-critical-css:X.Y.Z      # pinned release, e.g. 0.2.2
solarssk/wp-critical-css:X.Y        # rolling minor line, e.g. 0.2
solarssk/wp-critical-css:latest

Built from ghcr.io/puppeteer/puppeteer, pinned by digest. Every image passes a Trivy CRITICAL-vulnerability gate before it's pushed, and the same digest is also published to ghcr.io/solarssk/wp-critical-css if you prefer GHCR. Single-architecture (linux/amd64) - not a multi-arch manifest.

⁠Links

• Architecture⁠
• Deployment guide⁠
• Security controls⁠
• Security policy⁠
• Changelog⁠

⁠License

MIT⁠