Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
cheerio-select is a CSS selector engine built to provide jQuery-like positional pseudo-selector support on top of the css-select library. It acts as a specialized wrapper designed for environments like Cheerio where complex DOM querying, including non-standard positional selectors like :first, :eq(), and :even, is required.
The installation and setup process involves integrating the library into a Node.js environment, configuring the TypeScript compiler for those using strongly typed workflows, and utilizing the provided API to query DOM structures generated by parsers such as htmlparser2.
Sources: README.md:1-12, package.json:3-5
Installation
The package is distributed via npm and is designed for Node.js environments. It supports both CommonJS and ECMAScript Modules (ESM) formats through its dual-build architecture.
Package Manager
To install the library, use the standard npm installation command:
npm install cheerio-select
Sources: README.md:27-31, package.json:17-21
Core Dependencies
cheerio-select relies on several low-level DOM and CSS utility libraries. These are automatically installed as dependencies:
| Dependency | Purpose |
|---|---|
css-select | The underlying standard CSS selector engine. |
css-what | Used for parsing CSS selectors into tokens. |
domutils | Utilities for manipulating and traversing the DOM. |
domhandler | Provides the node and element types used in the DOM tree. |
boolbase | Simple boolean functions for selection logic. |
Sources: package.json:42-49
Development Environment Setup
For contributors or developers building the project from source, the environment is configured with TypeScript and the Biome toolchain for linting and formatting.
Build Scripts
The project uses tsc (TypeScript Compiler) to generate both CommonJS and ESM outputs located in the lib/ directory.
The diagram shows the build flow from the source files to the dual-output distribution directories.
Sources: package.json:28-32, tsconfig.json:1-12
Linting and Formatting
The project utilizes Biome for code quality and formatting. Rules are strictly enforced, including the requirement for consistent member accessibility and no unused locals.
- Linting:
npm run lint(runs ESLint and Biome check) - Formatting:
npm run format(runs Biome check with--write)
Sources: package.json:33-37, biome.json:1-83
Project Configuration
TypeScript Integration
The tsconfig.json specifies an es5 target with commonjs modules for compatibility, while the build process overrides these for the ESM build. Key settings include:
- rootDir:
src - outDir:
lib - strict:
true(Enables all strict type-checking options) - esModuleInterop:
true(Ensures compatibility between CommonJS and ES modules)
Sources: tsconfig.json:3-35
Testing Infrastructure
The library uses Jest with ts-jest for unit testing. The test environment is set to node.
The sequence shows the testing workflow where TypeScript test files are processed through ts-jest before execution.
Sources: package.json:39-41, 62-71
Basic Implementation Setup
To use cheerio-select in a project, it must be paired with a DOM parser. The typical setup involves htmlparser2.
Initialization Example
import { parseDocument } from "htmlparser2";
import { select } from "cheerio-select";
// 1. Parse HTML into a DOM structure
const dom = parseDocument("<div><p>Item 1</p><p>Item 2</p></div>");
// 2. Use cheerio-select to query the DOM
const firstP = select("p:first", dom);
Sources: README.md:35-46, src/index.spec.ts:6-10
Configuration Options
When calling selection functions, an Options object can be provided to customize behavior.
| Option | Type | Description |
|---|---|---|
root | Document | Optional reference to the root of the document for absolute selectors. |
xmlMode | boolean | Whether to treat the DOM as XML (case-sensitive tags, etc.). |
context | `AnyNode | AnyNode[]` |
Sources: src/index.ts:35-39, src/index.spec.ts:74-80
Summary
Setting up cheerio-select requires installing the package via npm and ensuring a compatible DOM provider (like domhandler via htmlparser2) is available. The library's architecture facilitates high-performance CSS querying with extended jQuery positional pseudo-selectors by wrapping the standard css-select engine. Development is supported by a strict TypeScript and Biome environment to ensure code reliability and consistency across the build outputs.