CtrlK

Community Documentation Log in Get started

tessl/npm-tailwindcss--node

Node.js-specific utilities and runtime functionality for Tailwind CSS v4, providing compilation tools, module dependency analysis, source map handling, path normalization, and optimization utilities.

43%

Overall

Evaluation — 43%

↑ 1.16x

Agent success when using this tile

Overview

Eval results

Files

CSS Optimization

Name: tessl/npm-tailwindcss--node
Author: tessl

Lightning CSS-based optimization with minification, nesting, media query processing, and browser compatibility transformations. Provides comprehensive CSS optimization including source map preservation and custom media query handling.

Capabilities

Optimize Function

Optimizes CSS using Lightning CSS with advanced transformations and browser compatibility.

/**
 * Optimizes CSS using Lightning CSS with custom transformations
 * @param input - CSS string to optimize
 * @param options - Optimization configuration options
 * @returns Optimization result with code and source map
 */
function optimize(
  input: string, 
  options?: OptimizeOptions
): TransformResult;

interface OptimizeOptions {
  /** The file being transformed (for source maps and error reporting) */
  file?: string;
  /** Enable minified output */
  minify?: boolean;
  /** Input source map string for source map chaining */
  map?: string;
}

interface TransformResult {
  /** Optimized CSS code */
  code: string;
  /** Output source map (undefined if no input map provided) */
  map: string | undefined;
}

Usage Examples:

import { optimize } from "@tailwindcss/node";

// Basic optimization
const result = optimize(`
  .container {
    display: flex;
    flex-direction: column;
  }
  
  @media (min-width: 768px) {
    .container {
      flex-direction: row;
    }
  }
`);

console.log(result.code);

// Production optimization with minification
const minified = optimize(css, {
  minify: true,
  file: "styles.css"
});

console.log(minified.code); // Minified output

Source Map Support

The optimization function supports source map chaining for debugging:

import { optimize } from "@tailwindcss/node";

// With existing source map
const previousMap = JSON.stringify({
  version: 3,
  sources: ["input.css"],
  mappings: "AAAA,UAAU",
  // ... other source map properties
});

const result = optimize(css, {
  file: "styles.css",
  map: previousMap
});

// Result includes chained source map
if (result.map) {
  console.log("Source map preserved:", result.map);
}

Advanced Configuration

The optimization process uses Lightning CSS with specific configurations:

import { optimize } from "@tailwindcss/node";

// The optimize function internally uses these Lightning CSS features:
// - CSS Nesting support
// - Media Query range syntax handling  
// - Custom media queries (draft support)
// - Deep selector combinator (non-standard)
// - Error recovery for malformed CSS

const result = optimize(`
  .card {
    &:hover {
      transform: scale(1.05);
    }
    
    @media (width >= 768px) {
      padding: 2rem;
    }
  }
  
  @custom-media --desktop (min-width: 1024px);
  
  @media (--desktop) {
    .card {
      max-width: 800px;
    }
  }
`, {
  minify: true,
  file: "components.css"
});

console.log(result.code);

Browser Compatibility

The optimization process targets specific browser versions:

// Internal browser targets (for reference):
const targets = {
  safari: "16.4",      // Safari 16.4+
  ios_saf: "16.4",     // iOS Safari 16.4+
  firefox: "128",      // Firefox 128+
  chrome: "111"        // Chrome 111+
};

CSS Features

The optimization process includes and excludes specific CSS features:

Included Features

CSS Nesting: Native CSS nesting syntax
Media Queries: Including range syntax and custom media

Excluded Features

Logical Properties: CSS logical properties are not transformed
Dir Selector: Direction pseudo-classes are not processed
Light-Dark Function: CSS light-dark() function is not processed

Special Handling

The optimizer includes special handling for media query compatibility:

// Media query range syntax is transformed for compatibility
// Input:  @media not (width < 768px)
// Output: @media not all and (width < 768px)

const result = optimize(`
  @media not (width < 768px) {
    .responsive {
      display: block;
    }
  }
`);

Double Optimization

The function performs optimization in two passes for maximum efficiency:

import { optimize } from "@tailwindcss/node";

// The optimize function internally:
// 1. First pass: Apply CSS nesting and basic transformations
// 2. Second pass: Merge adjacent rules and final optimizations

const css = `
  .button {
    padding: 0.5rem;
  }
  .button {
    margin: 0.25rem;
  }
`;

const result = optimize(css, { minify: true });
// Adjacent rules are merged: .button{padding:.5rem;margin:.25rem}

Error Recovery

The optimization process includes error recovery for malformed CSS:

import { optimize } from "@tailwindcss/node";

// Handles malformed CSS gracefully
const malformedCSS = `
  .valid { color: red; }
  .broken { color: ; }  /* Missing value */
  .also-valid { color: blue; }
`;

const result = optimize(malformedCSS);
// Valid rules are preserved, broken rules are handled gracefully
console.log(result.code);

Performance Considerations

Uses Lightning CSS for maximum performance
Two-pass optimization ensures optimal output size
Source maps are efficiently chained when provided
Error recovery prevents optimization failures on malformed input
Memory-efficient processing suitable for large CSS files

tessl i tessl/npm-tailwindcss--node@4.1.0