apexcss-cli

ApexCSS CLI

ApexCSS CLI - A powerful build tool with automatic framework detection and seamless integration.

What is ApexCSS CLI?

ApexCSS CLI helps you build and customize your own CSS utility framework. It provides:

• Automatic Framework Detection - Detects your project setup (React, Vue, Next.js, etc.) and configures accordingly
• Layered CSS Generation - Build only what you need (base, utilities, themes)
• Watch Mode - Automatically rebuild on configuration changes
• Smart Configuration - TypeScript/JavaScript config files with validation
• Framework Integration - Automatically adds CSS imports to your framework's entry file

Installation

npm install -g apexcss-cli

This installs the apex command globally.

# or use without installing
(recommended) npx apexcss-cli <command>

Quick Start

# 1. Initialize with automatic framework detection
apex init

# 2. Build your CSS
apex build

# 3. During development, watch for changes
apex watch

Automatic Framework Detection

ApexCSS CLI automatically detects your project framework and configures the integration:

Framework	Detection Method	Auto-Import
Next.js	next in dependencies	Added to globals.css
React	react in dependencies	Added to main entry file
Vue	vue in dependencies	Added to main.ts/js
Angular	@angular/core in dependencies	Added to styles.css
Svelte	svelte in dependencies	Added to main entry file
Astro	astro in dependencies	Added to Layout.astro
Nuxt	nuxt in dependencies	Instructions for nuxt.config.ts
Vanilla	Default fallback	Added to main.js/ts

Run apex doctor to see what was detected in your project.

Usage

Initialize Configuration

# Interactive mode with prompts (default)
apex init

# Specify framework explicitly
apex init --framework=react

# Custom output directory
apex init --output=./src/styles

# Skip adding imports to entry files
apex init --no-import

Build CSS

# Build complete CSS (base + utilities + themes)
apex build

# Build specific layers only
apex build --layer base
apex build --layer utilities
apex build --layer themes
apex build --layer base,themes

# Production build with minification
apex build --minify

# Generate source maps
apex build --sourcemap

# Output as SCSS instead of CSS
apex build --format=scss

# Production build: compile, then tree-shake the result in one step
apex build --purge

--purge scans your project's source files and tree-shakes the freshly built CSS in place, in a single non-interactive command — equivalent to running apex build followed by apex purge --yes. Unlike apex purge, it never modifies apex.config.js; it only prunes the compiled CSS output.

Watch Mode

# Watch config file for changes and auto-rebuild
apex watch

# Watch with custom config path
apex watch --config=./custom.config.js

Diagnostics

# Run system diagnostics
apex doctor

Purge (Optimize Bundle Size)

The purge command analyzes your project's source files, disables unused ApexCSS features in your config, and by default tree-shakes your compiled CSS in node_modules/apexcss/dist down to only the rules your project actually uses.

# Analyze project, disable unused features, and tree-shake compiled CSS
apex purge

# Dry run - show changes without applying
apex purge --dry-run

# Auto-apply changes without confirmation
apex purge --yes

# Scan specific directories
apex purge --src=./src,./components

# Create backup before modifying
apex purge --backup

# Show detailed class usage statistics
apex purge --verbose

# Only adjust feature flags in apex.config.js, skip CSS tree-shaking
apex purge --no-prune-css

# Tree-shake CSS from/to a custom location
apex purge --css-dir=./dist/css --css-out=./dist/css-pruned

How it works:

1. Scans your HTML, JSX, Vue, Svelte, and Astro files
2. Extracts all CSS class names used in your project
3. Maps detected classes to ApexCSS features
4. Identifies features that are enabled but not used
5. Shows you which features can be safely disabled
6. Updates your apex.config.js to disable unused features
7. Tree-shakes your compiled CSS (apex build output) down to the classes actually in use, unless --no-prune-css is passed

Run apex build before apex purge so there's compiled CSS to tree-shake. If none is found, purge still updates your config and prints a reminder instead of failing.

Example output:

╔══════════════════════════════════════════════════════════════╗
║              Proposed Configuration Changes                   ║
╚══════════════════════════════════════════════════════════════╝

📦 Features to DISABLE (not detected in codebase):

   • transforms3d     (~12KB)
   • filters          (~8KB)
   • typographyExtended (~15KB)

📊 Estimated bundle size reduction: ~35KB

Apply these changes to apex.config.js? (Y/n)

Warning: Always test your application after purging. If styles are missing, you can restore the backup:

cp apex.config.js.backup apex.config.js

CLI Options

Option	Description	Default
-c, --config <path>	Config file path	./apex.config.js
-o, --output <dir>	Output directory	node_modules/apexcss/dist
--minify	Minify output CSS	false
--sourcemap	Generate source maps	false

Command-Specific Options

init command:

Option	Description
-f, --framework <name>	Specify framework (react, vue, angular, svelte, astro, next, nuxt, vanilla)
--no-import	Skip adding imports to entry files

build command:

Option	Description	Default
--format <format>	Output format (css, scss)	css
-l, --layer <layers>	Build specific layers (base, utilities, themes, all)	all
--no-cache	Skip build cache and force recompilation	-
--purge	Tree-shake compiled CSS immediately after building	false

purge command:

Option	Description	Default
--src <dirs>	Comma-separated source directories to scan	Auto-detect
--exclude <dirs>	Comma-separated directories to exclude from scanning	-
--dry-run	Show changes without applying	false
-y, --yes	Skip confirmation prompt	false
--backup	Create backup before modifying config	false
--verbose-stats	Show detailed class usage statistics	false
--report <path>	Write a JSON analysis report to the given path	-
--no-prune-css	Skip CSS tree-shaking; only adjust feature flags	prune-css runs by default
--css-dir <dir>	Directory containing compiled CSS to prune	node_modules/apexcss/dist
--css-out <dir>	Directory for pruned CSS output	Same as --css-dir

Configuration

Create an apex.config.js file in your project root:

export default {
  // Feature toggles - enable/disable utility categories
  features: {
    display: true,
    flexbox: true,
    grid: true,
    positioning: true,
    visibility: true,
    spacing: true,
    typography: true,
    colors: true,
    backgrounds: true,
    borders: true,
    shadows: true,
    opacity: true,
    transitions: true,
    transforms: true,
    animations: true
  },

  // Breakpoints
  breakpoints: {
    sm: '320px',
    md: '768px',
    lg: '1024px',
    xl: '1280px'
  },

  // Custom colors using OKLCH color space
  colors: {
    primary: {
      hue: 250,
      chroma: 0.2,
      lightnessScale: {
        50: 96, 100: 90, 200: 85, 300: 78, 400: 70,
        500: 65, 600: 55, 700: 45, 800: 35, 900: 25, 950: 18
      }
    },
    secondary: {
      hue: 180,
      chroma: 0.15,
      lightnessScale: {
        50: 96, 100: 90, 200: 85, 300: 78, 400: 70,
        500: 65, 600: 55, 700: 45, 800: 35, 900: 25, 950: 18
      }
    }
  },

  // Spacing scale
  spacing: {
    '0': '0px',
    '1': '0.25rem',
    '2': '0.5rem',
    '4': '1rem',
    '8': '2rem',
    '16': '4rem'
  }
};

Dependencies

Required

• apexcss - The core CSS framework (peer dependency)

Bundled

• chalk - Terminal styling
• commander - CLI framework
• sass - Sass compiler (embedded)

Optional

• chokidar - File watching (for watch command)
• inquirer - Interactive prompts (for init command)

# Install the CLI
npm install -g apexcss-cli

# Or install locally with the core framework
npm install apexcss apexcss-cli

Development

Setup

# Clone the repository
git clone https://github.com/chris-briddock/apex-cli.git
cd apex-cli

# Install dependencies
npm install

Testing

# Run all tests
npm test

# Run tests with coverage (LCOV report)
npm run test:coverage

# View coverage as text in terminal
npm run test:coverage:text

# Generate HTML coverage report
npm run test:coverage:html
# Then open coverage/index.html in your browser

# Run tests in watch mode
npm run test:watch

# Run unit tests only
npm run test:unit

Code Quality

# Run Biome linter
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Run Biome formatter
npm run format

# Fix formatting
npm run format:fix

# Run all checks (lint + format)
npm run check

# Fix all auto-fixable issues
npm run check:fix

Coverage Summary

Current test coverage:

Module	Statements	Branches	Functions	Lines
cli/utils/config-loader.js	99%	95%	100%	99%
cli/utils/logger.js	100%	100%	100%	100%
cli/utils/framework-detector.js	95%	94%	100%	95%
cli/commands/doctor.js	82%	79%	100%	82%
cli/commands/watch.js	67%	100%	83%	67%
cli/commands/build.js	54%	100%	67%	54%
cli/commands/init.js	41%	96%	50%	41%

Total: 76% statements, 92% branches, 86% functions

How It Works

1. Initialization (apex init):

   • Detects your project framework from package.json
   • Creates a starter config file (apex.config.js)
   • Optionally adds CSS import to your framework's entry file
   • Sets up .gitignore for output directory

2. Build Process (apex build):

   • Reads your configuration
   • Generates SCSS based on enabled features
   • Uses the embedded Sass compiler to build CSS
   • Outputs minified CSS (with optional source maps)

3. Watch Mode (apex watch):

   • Monitors your config file for changes
   • Automatically rebuilds on change
   • Handles concurrent changes gracefully

4. Purge/Optimization (apex purge):

   • Scans your project's source files (HTML, JSX, Vue, etc.)
   • Extracts all CSS class names used
   • Maps classes to ApexCSS feature categories
   • Identifies enabled features with zero usage
   • Generates a diff showing potential savings
   • Updates config file to disable unused features
   • Creates backup if requested
   • Shows summary of changes and next steps

License

MIT