CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-typescript-plugin-css-modules

CSS modules support for TypeScript language service providing intelligent type information and auto-completion for CSS module imports

—

Pending
Overview
Eval results
Files

css-processing.mddocs/

CSS Processing

CSS file compilation and processing system supporting multiple preprocessors, PostCSS integration, and custom rendering pipelines.

Capabilities

File Type Detection

Automatic detection of CSS file types based on file extensions.

/**
 * Supported CSS file types
 */
enum FileType {
  css = 'css',
  less = 'less',
  sass = 'sass',
  scss = 'scss',
  styl = 'styl'
}

/**
 * Determines CSS file type from filename extension
 * @param fileName - Path to the CSS file
 * @returns FileType enum value
 */
function getFileType(fileName: string): FileType;

Usage Examples:

// The plugin automatically detects file types:
// component.module.css -> FileType.css
// styles.module.scss -> FileType.scss
// theme.module.sass -> FileType.sass
// layout.module.less -> FileType.less
// animations.module.styl -> FileType.styl

Custom Renderer System

Extensible system for implementing custom CSS processing pipelines.

/**
 * Custom renderer function type
 */
type CustomRenderer = (
  css: string,
  options: CustomRendererOptions
) => string | {
  css: string;
  sourceMap?: RawSourceMap;
};

/**
 * Options passed to custom renderer functions
 */
interface CustomRendererOptions {
  /** Current file being processed */
  fileName: string;
  /** Logger instance for debugging */
  logger: Logger;
  /** TypeScript compiler options */
  compilerOptions: tsModule.CompilerOptions;
}

Custom Renderer Implementation:

// customRenderer.js
module.exports = (css, { fileName, logger }) => {
  try {
    // Custom processing logic
    const processedCss = css.replace(/\$primary-color/g, '#007bff');
    
    return {
      css: processedCss,
      sourceMap: null // Optional source map
    };
  } catch (error) {
    logger.error(error.message);
    return css; // Return original on error
  }
};

Configuration:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          "customRenderer": "./customRenderer.js"
        }
      }
    ]
  }
}

PostCSS Integration

Built-in PostCSS processor for handling CSS transformations and plugin execution.

/**
 * Creates PostCSS processor instance
 * @param userPlugins - Array of PostCSS plugins
 * @returns PostCSS Processor instance
 */
function getProcessor(userPlugins: AcceptedPlugin[]): Processor;

/**
 * Filters PostCSS plugins based on exclusion rules
 * @param config - Plugin filtering configuration
 * @returns Filtered plugins array
 */
function filterPlugins(config: {
  plugins: AcceptedPlugin[];
  exclude?: string[];
}): AcceptedPlugin[];

Usage Examples:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          "postcssOptions": {
            "useConfig": true,
            "excludePlugins": ["postcss-mixins"]
          }
        }
      }
    ]
  }
}

With a postcss.config.js:

module.exports = {
  plugins: [
    require('postcss-nested'),
    require('postcss-preset-env'),
    require('postcss-mixins') // Will be excluded
  ]
};

CSS Export Extraction

System for extracting CSS class names and generating TypeScript-compatible exports.

/**
 * CSS exports extraction configuration
 */
interface CSSExportConfig {
  /** CSS content to process */
  css: string;
  /** Source file name */
  fileName: string;
  /** Logger instance */
  logger: Logger;
  /** Plugin options */
  options: Options;
  /** PostCSS processor */
  processor: Processor;
  /** TypeScript compiler options */
  compilerOptions: tsModule.CompilerOptions;
  /** Project directory */
  directory: string;
}

/**
 * CSS exports with optional source map
 */
interface CSSExportsWithSourceMap {
  /** Extracted CSS class names */
  classes: CSSExports;
  /** Optional source map */
  sourceMap?: RawSourceMap;
}

Sass Tilde Importer

Custom Sass importer for resolving Webpack-style tilde imports from node_modules.

/**
 * Resolves tilde-prefixed URLs to node_modules paths
 * @param url - Import URL starting with ~
 * @param extensions - File extensions to try (default: ['scss', 'sass', 'css'])
 * @returns Array of possible file paths to try
 */
function resolveUrls(url: string, extensions?: string[]): string[];

/**
 * Sass file importer for tilde imports
 */
const sassTildeImporter: sass.FileImporter<'sync'>;

Usage Examples:

In Sass files, you can now use:

// These imports are resolved by the tilde importer
@import '~bootstrap/scss/variables';
@import '~@fortawesome/fontawesome-free/scss/fontawesome';
@import '~some-package/styles/theme';

The importer resolves these to:

// Actual resolved paths
@import 'node_modules/bootstrap/scss/variables';
@import 'node_modules/@fortawesome/fontawesome-free/scss/fontawesome';
@import 'node_modules/some-package/styles/theme';

Class Name Transformations

System for transforming CSS class names to match different naming conventions.

/**
 * Creates class name transformation function
 * @param camelCaseOption - Transformation mode
 * @returns Function that transforms a class name to an array of variants
 */
function transformClasses(
  camelCaseOption?: ClassnameTransformOptions
): (classname: string) => string[];

Usage Examples:

// With classnameTransform: "camelCase"
// CSS: .my-component-header
// Available as: styles['my-component-header'] and styles.myComponentHeader

// With classnameTransform: "camelCaseOnly"  
// CSS: .my-component-header
// Available as: styles.myComponentHeader only

// With classnameTransform: "dashes"
// CSS: .my_component_header  
// Available as: styles['my_component_header'] and styles.myComponentHeader

Error Handling

The CSS processing system includes comprehensive error handling for common issues:

  • File not found: Graceful handling when CSS files are missing
  • Compilation errors: Detailed error reporting for preprocessor compilation failures
  • Invalid syntax: Clear error messages for malformed CSS
  • Plugin errors: Isolated error handling for PostCSS plugin failures
  • Custom renderer errors: Error boundary for custom renderer exceptions

All errors are logged through the integrated logging system with context information including file names and error details.

Install with Tessl CLI

npx tessl i tessl/npm-typescript-plugin-css-modules

docs

css-processing.md

file-matching.md

index.md

plugin-configuration.md

type-generation.md

tile.json