Slim vs Full Builds

Relevant source files

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

• package.json
• src/index.ts
• src/slim.ts
• website/src/content/blog/2024-08-07-version-1.md
• src/parse.spec.ts
• src/tests/xml.spec.ts
• Readme.md

Introduction

Cheerio provides two distinct entry points for developers: a Full Build and a Slim Build. The primary purpose of this separation is to offer a choice between a feature-rich, "batteries-included" experience and a lightweight, dependency-minimized version. Starting with version 1.0, these builds are explicitly defined in the project structure to support various environment requirements, such as browser compatibility and reduced bundle sizes.

The Full Build is the default entry point and includes all available parsers and convenience methods, whereas the Slim Build requires explicit selection and excludes heavy dependencies like the parse5 HTML parser.

Sources: package.json:67-93, website/src/content/blog/2024-08-07-version-1.md:59-62, Readme.md:46-51

Build Architecture and Export Logic

The project utilizes the tshy build tool to manage CommonJS and ESM distributions across different platforms. The package.json configuration defines how consumers access these builds through the exports field.

Package Entry Points

Entry Path	Type	File Target	Description
.	Full	src/index.ts	The default build containing all features.
./slim	Slim	src/slim.ts	The lightweight build without parse5.
./utils	Utility	src/utils.ts	Internal and shared utility functions.

Sources: package.json:67-93, package.json:151-156

Dependency Distribution

The following diagram illustrates how components and external dependencies are distributed between the two builds.

The Full Build acts as a superset, incorporating parse5 for robust HTML5-compliant parsing, while the Slim Build relies exclusively on htmlparser2.

Sources: package.json:124-134, src/parse.spec.ts:8-12, website/src/content/blog/2024-08-07-version-1.md:73-77

Functional Differences

Parser Availability

The most significant difference between the builds is the underlying parser. Cheerio's default build uses parse5 by default for HTML parsing, which provides high fidelity to browser parsing behavior. The Slim Build omits parse5, defaulting to the more forgiving but less spec-strict htmlparser2.

• Full Build: Supports both parse5 (HTML) and htmlparser2 (XML/HTML).
• Slim Build: Supports only htmlparser2.

Sources: src/parse.spec.ts:8-12, src/tests/xml.spec.ts:21-48, Readme.md:46-51

Browser Support

The project distinguishes between Node.js and Browser environments. Both the Full and Slim builds have specific sub-exports for the browser environment, typically mapping to ESM distributions.

Implementation Details

The Slim build is implemented by exporting a restricted set of functionalities from src/slim.ts. While the Full build in src/index.ts re-exports everything from the core and includes the parse5 adapter, the Slim entry point intentionally bypasses these heavier modules.

Usage in Code

To use the Slim build, the import path must be explicitly changed:

// Full Build (Default)
import * as cheerio from 'cheerio';

// Slim Build
import * as cheerio from 'cheerio/slim';

Sources: website/src/content/blog/2024-08-07-version-1.md:60-62, package.json:79-88

Summary

The distinction between Slim and Full builds in Cheerio allows developers to balance features against package weight. The Full build provides the "batteries-included" experience with parse5 support, making it suitable for server-side scraping where accuracy is paramount. The Slim build provides a lightweight alternative suitable for browser environments or applications where htmlparser2 is sufficient for parsing needs.