CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-eslint-import-resolver-typescript

TypeScript resolver plugin for eslint-plugin-import that enables TypeScript module resolution with path mapping and @types/* support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration.mddocs/

Configuration Management

Option normalization and TypeScript project configuration management for handling various project structures and settings.

Capabilities

Normalize Options

Normalizes and validates TypeScript resolver options, handles project detection, and manages configuration caching.

/**
 * Normalizes TypeScript resolver options and handles project detection
 * @param options - Raw TypeScript resolver options
 * @param cwd - Current working directory (defaults to process.cwd())
 * @returns Normalized and validated options
 */
function normalizeOptions(
  options?: TypeScriptResolverOptions | null,
  cwd?: string
): TypeScriptResolverOptions;

Usage Examples:

import { normalizeOptions } from "eslint-import-resolver-typescript";

// Basic normalization
const normalized = normalizeOptions({
  project: "./tsconfig.json",
  alwaysTryTypes: true
});

// With custom working directory
const normalizedWithCwd = normalizeOptions(
  { project: "configs/tsconfig.json" },
  "/path/to/project"
);

// Normalize empty options (uses defaults)
const defaults = normalizeOptions();
console.log(defaults.extensions); // ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json', '.node']

Option Normalization Features

The normalization process handles several complex scenarios:

  • Project Path Resolution: Converts relative paths to absolute paths
  • Glob Pattern Expansion: Expands glob patterns to actual configuration files
  • Default Detection: Automatically finds tsconfig.json or jsconfig.json files
  • Multi-Project Handling: Manages multiple TypeScript configurations
  • Caching: Caches normalized options for performance
  • Validation: Validates configuration file existence and accessibility

Configuration Types

interface TypeScriptResolverOptions extends NapiResolveOptions {
  /** TypeScript project configuration paths (file path, directory, or glob patterns) */
  project?: string[] | string;
  /** Whether to always try to resolve @types packages (default: true) */
  alwaysTryTypes?: boolean;
  /** Whether Bun core modules should be accounted for */
  bun?: boolean;
  /** Suppress multiple projects warning */
  noWarnOnMultipleProjects?: boolean;
  
  // Configuration object for TypeScript compiler
  tsconfig?: {
    /** Path to TypeScript configuration file */
    configFile?: string;
    /** TypeScript project references handling */
    references?: 'auto' | boolean;
  };
}

Project Configuration Patterns

Single Configuration File:

const options = normalizeOptions({
  project: "./tsconfig.json"
});

Directory-based Configuration:

const options = normalizeOptions({
  project: "path/to/folder" // Will look for tsconfig.json or jsconfig.json
});

Multiple Configurations:

const options = normalizeOptions({
  project: [
    "packages/module-a/tsconfig.json",
    "packages/module-b/jsconfig.json"
  ]
});

Glob Pattern Configurations:

// Single glob pattern
const globOptions = normalizeOptions({
  project: "packages/*/tsconfig.json"
});

// Multiple glob patterns
const multiGlobOptions = normalizeOptions({
  project: [
    "packages/*/tsconfig.json",
    "other-packages/*/jsconfig.json"
  ]
});

// Complex glob pattern
const complexGlobOptions = normalizeOptions({
  project: "packages/*/{ts,js}config.json"
});

Default Values

The normalization process applies these default values:

// Mutable variable holding the default configuration file path
declare let defaultConfigFile: string;

// Default condition names for package.json exports
declare const defaultConditionNames: string[];
// ['types', 'import', 'esm2020', 'es2020', 'es2015', 'require', 'node', 'node-addons', 'browser', 'default']

// Default file extensions to resolve
declare const defaultExtensions: string[];
// ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.json', '.node']

// Default extension aliases for TypeScript compilation
declare const defaultExtensionAlias: Record<string, string[]>;
/* {
  '.js': ['.ts', '.tsx', '.d.ts', '.js'],
  '.ts': ['.ts', '.d.ts', '.js'],
  '.jsx': ['.tsx', '.d.ts', '.jsx'],
  '.tsx': ['.tsx', '.d.ts', '.jsx', '.js'],
  '.cjs': ['.cts', '.d.cts', '.cjs'],
  '.cts': ['.cts', '.d.cts', '.cjs'],
  '.mjs': ['.mts', '.d.mts', '.mjs'],
  '.mts': ['.mts', '.d.mts', '.mjs']
} */

// Default package.json main fields priority
declare const defaultMainFields: string[];
// ['types', 'typings', 'fesm2020', 'fesm2015', 'esm2020', 'es2020', 'module', 'jsnext:main', 'main']

Configuration File Detection

The normalization process follows this detection algorithm:

  1. Explicit Configuration: If project is specified, use those paths
  2. Directory Scanning: If project points to directories, scan for config files
  3. Glob Expansion: Expand glob patterns to actual configuration files
  4. Default Detection: Fall back to root tsconfig.json or jsconfig.json
  5. Validation: Verify that configuration files exist and are readable
// Detection priority order:
const DEFAULT_CONFIGS = ['tsconfig.json', 'jsconfig.json'];
const DEFAULT_TRY_PATHS = ['', ...DEFAULT_CONFIGS];

Multi-Project Handling

For projects with multiple TypeScript configurations:

const options = normalizeOptions({
  project: [
    "frontend/tsconfig.json",
    "backend/tsconfig.json",
    "shared/tsconfig.json"
  ],
  noWarnOnMultipleProjects: true // Suppress warning about multiple projects
});

Without noWarnOnMultipleProjects, the resolver will warn:

"Multiple projects found, consider using a single tsconfig with references to speed up"

Caching Behavior

The normalization process implements intelligent caching:

  • Configuration Caching: Caches normalized options by configuration file and options hash
  • File System Caching: Caches file existence checks and directory scans
  • Glob Result Caching: Caches glob pattern expansion results

Cache keys are generated using stable hashing of the configuration:

import { stableHash } from 'stable-hash-x';

const optionsHash = stableHash(options);
const cacheKey = `${configFile}\0${optionsHash}`;

Error Handling

The normalization process handles various error conditions:

  • Missing Configuration Files: Continues with default behavior if optional configs are missing
  • Invalid Glob Patterns: Throws descriptive errors for malformed patterns
  • Permission Issues: Handles file system permission problems gracefully
  • Circular References: Detects and prevents circular configuration references

Performance Optimization

Several optimizations improve normalization performance:

  • Lazy Evaluation: Defers expensive operations until needed
  • Path Caching: Caches resolved file paths
  • Pattern Matching: Uses efficient glob matching algorithms
  • Memory Management: Implements bounded caches to prevent memory leaks

Install with Tessl CLI

npx tessl i tessl/npm-eslint-import-resolver-typescript

docs

configuration.md

core-resolution.md

index.md

resolver-factory.md

utilities.md

tile.json