or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cache-management.mdcompilation.mdindex.mdinstrumentation.mdmodule-analysis.mdoptimization.mdpath-utils.mdsource-maps.mdurl-processing.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tailwindcss/node@4.1.x

To install, run

npx @tessl/cli install tessl/npm-tailwindcss--node@4.1.0

index.mddocs/

@tailwindcss/node

@tailwindcss/node provides Node.js-specific utilities and runtime functionality for Tailwind CSS v4, including compilation tools, module dependency analysis, source map handling, path normalization, and optimization utilities. It serves as the core Node.js integration layer for Tailwind CSS, enabling server-side processing of styles, hot module reloading support, and seamless integration with Node.js build tools and development workflows.

Package Information

  • Package Name: @tailwindcss/node
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @tailwindcss/node

Core Imports

import { 
  compile, 
  compileAst, 
  Instrumentation, 
  optimize, 
  normalizePath, 
  toSourceMap,
  env 
} from "@tailwindcss/node";

For CommonJS:

const { 
  compile, 
  compileAst, 
  Instrumentation, 
  optimize, 
  normalizePath, 
  toSourceMap,
  env 
} = require("@tailwindcss/node");

Specialized imports:

// Require cache management
import { clearRequireCache } from "@tailwindcss/node/require-cache";

// ESM cache loader (used internally by Node.js module system)
// Note: This is registered automatically when importing the main module

Basic Usage

import { compile, CompileOptions, optimize } from "@tailwindcss/node";

// Compile Tailwind CSS with Node.js-specific features
const options: CompileOptions = {
  base: "/path/to/project",
  onDependency: (path: string) => {
    console.log("Dependency:", path);
  },
  shouldRewriteUrls: true,
};

const compiler = await compile(`
  @tailwind base;
  @tailwind components; 
  @tailwind utilities;
`, options);

// Get the compiled CSS
const css = compiler.build();

// Optimize the CSS for production
const optimized = optimize(css, {
  minify: true,
  file: "styles.css"
});

console.log(optimized.code);

Architecture

@tailwindcss/node is built around several key components:

  • Compilation System: Core CSS compilation with Tailwind processing, module loading, and dependency tracking
  • Module Resolution: Enhanced module resolution supporting TypeScript, ESM, and CommonJS with custom resolvers
  • Performance Instrumentation: Built-in profiling and timing tools for development and debugging
  • CSS Optimization: Lightning CSS-based optimization with source maps and browser compatibility
  • Path Normalization: Cross-platform path handling for Windows and Unix systems
  • Source Map Support: Full source map generation and manipulation with inline embedding
  • Hot Module Reloading: ESM cache busting and require cache management for development workflows

Capabilities

CSS Compilation

Core Tailwind CSS compilation functionality with Node.js-specific module loading, dependency tracking, and file system integration.

function compile(css: string, options: CompileOptions): Promise<Compiler>;
function compileAst(ast: AstNode[], options: CompileOptions): Promise<Compiler>;

interface CompileOptions {
  base: string;
  from?: string;
  onDependency: (path: string) => void;
  shouldRewriteUrls?: boolean;
  polyfills?: Polyfills;
  customCssResolver?: Resolver;
  customJsResolver?: Resolver;
}

type Resolver = (id: string, base: string) => Promise<string | false | undefined>;

CSS Compilation

Performance Instrumentation

Built-in performance monitoring and profiling tools with timer support and automatic reporting for development workflows.

class Instrumentation implements Disposable {
  constructor(defaultFlush?: (message: string) => void);
  hit(label: string): void;
  start(label: string): void;
  end(label: string): void;
  reset(): void;
  report(flush?: (message: string) => void): void;
  [Symbol.dispose](): void;
}

Performance Instrumentation

CSS Optimization

Lightning CSS-based optimization with minification, nesting, media query processing, and browser compatibility transformations.

function optimize(input: string, options?: OptimizeOptions): TransformResult;

interface OptimizeOptions {
  file?: string;
  minify?: boolean;
  map?: string;
}

interface TransformResult {
  code: string;
  map: string | undefined;
}

CSS Optimization

Source Map Support

Comprehensive source map generation, manipulation, and serialization with inline embedding support for debugging workflows.

function toSourceMap(map: DecodedSourceMap | string): SourceMap;

interface SourceMap {
  readonly raw: string;
  readonly inline: string;
}

type DecodedSource = {
  url: string;
  content: string;
};

type DecodedSourceMap = {
  mappings: Array<{
    generatedPosition: { line: number; column: number };
    originalPosition?: { line: number; column: number; source: DecodedSource };
    name?: string;
  }>;
};

Source Map Support

Path Normalization

Cross-platform path normalization utilities for consistent file path handling across Windows and Unix systems.

function normalizePath(originalPath: string): string;

Path Normalization

Module Dependency Analysis

Recursive module dependency analysis with support for TypeScript, ESM, and CommonJS import patterns.

function getModuleDependencies(absoluteFilePath: string): Promise<string[]>;

Module Dependencies

URL Processing

CSS URL rewriting functionality for asset path management and relative URL transformation in build processes.

function rewriteUrls(options: {
  css: string;
  base: string;
  root: string;
}): Promise<string>;

URL Processing

Cache Management

Node.js module cache management for hot module reloading and development workflows.

function clearRequireCache(files: string[]): void;

Cache Management

Environment Variables

The package supports several environment configurations:

const env: {
  readonly DEBUG: boolean;
};

The DEBUG environment variable supports various patterns:

  • DEBUG=true or DEBUG=1 - Enable debugging
  • DEBUG=false or DEBUG=0 - Disable debugging
  • DEBUG=* - Enable all debug modes
  • DEBUG=tailwindcss - Enable Tailwind CSS debugging
  • DEBUG=-tailwindcss - Explicitly disable Tailwind CSS debugging

Types

Core types used throughout the package:

// Re-exported from tailwindcss
enum Features {
  // CSS feature flags for compilation
}

interface Polyfills {
  // CSS polyfill configuration
}

// Internal types
interface AstNode {
  // AST node structure (from tailwindcss)
}

interface Compiler {
  // Compilation result with build methods
  build(): string;
  root?: { pattern: string } | 'none';
}