TypeScript Build Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• tsconfig.json
• tsconfig.eslint.json
• package.json
• biome.json
• src/index.ts

The TypeScript build configuration in cheerio-select is designed to support a hybrid module system, producing both CommonJS and ECMAScript Module (ESM) outputs. This dual-build strategy ensures compatibility with a wide range of Node.js environments while leveraging modern TypeScript features for type safety and development efficiency. The project uses a central tsconfig.json for core compiler settings, extended by specific configurations for linting and testing environments.

Sources: package.json:34-40, tsconfig.json

Build Pipeline Architecture

The build process is managed through npm scripts that orchestrate the TypeScript compiler (tsc) to generate multiple distribution formats. The primary goal is to populate the lib/ directory with compiled JavaScript and type definitions.

Orchestration Flow

The following diagram illustrates how npm scripts trigger the various stages of the TypeScript compilation process:

The build process ensures that ESM consumers receive a proper package.json with {"type":"module"} within the ESM sub-directory to ensure correct Node.js resolution.

Sources: package.json:34-37

Core Compiler Options

The project defines strict type-checking and module resolution rules in the base configuration file.

Base Configuration (tsconfig.json)

The base configuration targets es5 compatibility for the main CommonJS build while maintaining strict type safety.

Option	Value	Description
target	es5	Sets the JavaScript language version for emitted JavaScript.
module	commonjs	Specifies the module code generation method.
lib	["ES2015.Core"]	Library files to be included in the compilation.
rootDir	src	Specifies the root folder within source files.
outDir	lib	Redirects output structure to the directory.
strict	true	Enables all strict type-checking options.
declaration	true	Generates corresponding .d.ts files.

Sources: tsconfig.json:3-23

Strictness and Quality Checks

Beyond standard strict mode, the configuration enables several additional checks to prevent common coding errors:

• noUnusedLocals: Reports errors on unused local variables.
• noUnusedParameters: Reports errors on unused parameters.
• exactOptionalPropertyTypes: Ensures optional properties are handled precisely.
• noImplicitOverride: Ensures that overrides in subclasses are explicitly marked.

Sources: tsconfig.json:25-33

Environment-Specific Configurations

The build system utilizes configuration inheritance to handle different toolchains without duplicating base settings.

ESLint Configuration (tsconfig.eslint.json)

This configuration extends the base tsconfig.json to include the test directory, which is normally excluded from the production build. This allows the ESLint engine and typescript-eslint to have full type information for both source and test files.

{
    "extends": "./tsconfig.json",
    "include": ["src", "test"],
    "exclude": []
}

Sources: tsconfig.eslint.json:1-5

Distribution and Entry Points

The package.json defines how different environments access the compiled output:

• Main: lib/index.js (CommonJS)
• Module: lib/esm/index.js (ESM)
• Types: lib/index.d.ts (Type Definitions)
• Exports: Conditional exports mapping import to ESM and require to CJS.

Sources: package.json:23-31

Linting and Formatting Integration

The TypeScript configuration is complemented by Biome and ESLint to maintain code quality. The biome.json file is configured to include TypeScript files while ignoring build artifacts and dependencies.

File Inclusion Rules

The project explicitly defines which files are subject to linting and formatting:

• Includes: **/*.{ts,md,json,yml}
• Ignores: node_modules, coverage, lib, and hidden files.

Sources: biome.json:8-16

Specialized Rules

For test files (**/*.{test,spec}.ts), the linter is configured with specific globals like jest, describe, and it to prevent "undefined variable" errors during analysis.

Sources: biome.json:68-80

Summary

The cheerio-select TypeScript build configuration provides a robust foundation for high-performance CSS selector processing. By utilizing a dual-output build pipeline and strict compiler flags, the project ensures cross-environment compatibility and high internal code quality. The use of configuration inheritance allows for a clean separation between production build logic, testing requirements, and linting rules.

Sources: tsconfig.json, package.json, biome.json