Skip to main content

Performance

Best practices for optimal performance with Apex.

Build Optimization

Apex automatically purges unused styles in production builds.

File Size

The full Apex build is approximately 15KB minified and gzipped. With purging enabled, your CSS bundle will only include the utilities you actually use.

PurgeCSS

Apex uses PurgeCSS to remove unused styles. Configure your purge options in the configuration file.

What is PurgeCSS?

PurgeCSS analyzes your content files (HTML, JSX, Vue, etc.) and removes unused CSS rules. This can reduce your CSS bundle size by 80-95%.

Configuration

Create a purgecss.config.js file in your project root to configure PurgeCSS.

JS
// purgecss.config.js
export default {
  content: [
    './src/**/*.html',
    './src/**/*.js',
    './src/**/*.jsx',
    './src/**/*.ts',
    './src/**/*.tsx',
    './src/**/*.vue',
  ],
  safelist: [
    // State variants
    /-(hover|focus|active|disabled|visited|before|after)$/,
    // Screen reader utilities
    /^sr-only/,
    /^not-sr-only/,
    // RTL variants
    /^rtl-/,
    // Dark mode variants
    /^dark:/,
    // Animation classes
    /^animate-/,
    // Focus utilities
    /^focus-visible/,
    /^focus-within/
  ],
  extractors: [
    {
      extractor: (content) => {
        const matches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || [];
        return [...new Set(matches)];
      },
      extensions: ['html', 'js', 'jsx', 'ts', 'tsx', 'vue']
    }
  ]
};

Installation

Install PurgeCSS as a PostCSS plugin or standalone tool.

Bash
# Install PurgeCSS
npm install -D @fullhuman/postcss-purgecss

# Or with yarn
yarn add -D @fullhuman/postcss-purgecss

PostCSS Integration

Integrate PurgeCSS with your PostCSS build pipeline.

JS
// postcss.config.js
import purgecss from '@fullhuman/postcss-purgecss';

export default {
  plugins: [
    // Other PostCSS plugins...
    purgecss({
      content: ['./src/**/*.{html,js,jsx,ts,tsx,vue}'],
      safelist: {
        standard: ['sr-only', 'not-sr-only'],
        deep: [/focus-visible/, /focus-within/, /dark:/, /animate-/],
        greedy: [/^rtl-/]
      }
    })
  ]
};

Safelist Configuration

Define patterns for classes that should never be removed, even if they appear unused. This is important for dynamic classes and JavaScript-generated content.

JS
// Example: Safelist patterns for dynamic classes
const purgeCssPlugin = purgecss({
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  safelist: {
    // Standard classes to keep
    standard: [
      'sr-only',
      'not-sr-only',
      'skip-link'
    ],
    // Keep classes matching these patterns
    deep: [
      /focus-visible/,      // Keep all focus-visible utilities
      /focus-within/,       // Keep all focus-within utilities
      /dark:/,              // Keep dark mode variants
      /motion-reduce:/,     // Keep motion reduce utilities
      /contrast-/,          // Keep contrast utilities
      /rtl-/,               // Keep RTL utilities
      /animate-/            // Keep animation classes
    ],
    // Greedy patterns (more permissive)
    greedy: [
      /^theme-/,             // Keep theme classes
      /^data-theme/         // Keep data-theme attributes
    ]
  }
});

Build Tool Integration

PurgeCSS can be integrated with popular build tools like Vite, webpack, and Rollup.

JS
// vite.config.js
import { defineConfig } from 'vite';
import purgecss from 'vite-plugin-purgecss';

export default defineConfig({
  plugins: [
    purgecss({
      content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
      safelist: ['sr-only', 'not-sr-only']
    })
  ]
});

// webpack.config.js
const PurgeCSSPlugin = require('purgecss-webpack-plugin');
const glob = require('glob');

module.exports = {
  plugins: [
    new PurgeCSSPlugin({
      paths: glob.sync(`${PATHS.src}/**/*`, { nodir: true }),
      safelist: ['sr-only', 'not-sr-only']
    })
  ]
};

CLI Usage

Use the PurgeCSS CLI to process CSS files directly from the command line.

Bash
# Using PurgeCSS CLI
npx purgecss --css css/style.css --content src/index.html src/**/*.js --output css/

# With a config file
npx purgecss --config purgecss.config.js

PurgeCSS Best Practices

  • Always safelist accessibility utilities like sr-only and focus-visible
  • Safelist dynamic classes that are added via JavaScript
  • Include all template files in the content array
  • Test your site thoroughly after purging to ensure no styles are missing
  • Use regex patterns for safelist to match multiple variants

Best Practices

  • Use the CDN for prototyping, npm for production
  • Enable purge in production
  • Disable utilities you do not need
  • Use custom components for repeated patterns