# Performance Differences Between FlexSearch Bundle, Compact, and Light Builds
> Explore FlexSearch build performance differences. Discover how Light, Compact, and Bundle builds impact sync/async queries, footprint, and indexing for optimal search implementation.
- Repository: [Nextapps GmbH/flexsearch](https://github.com/nextapps-de/flexsearch)
- Tags: performance
- Published: 2026-02-23
---
**The light build delivers ~10% faster synchronous queries with a ~70KB footprint, while the compact build (~140KB) adds async/document features with minimal latency overhead, and the full bundle includes Web Workers for CPU-intensive indexing.**
FlexSearch provides three distinct distribution bundles tailored to different performance constraints and feature requirements. Understanding the performance differences between FlexSearch bundle, compact, and light builds ensures you select the optimal balance of download size, runtime memory, and query speed for your specific use case.
## Build Size and Feature Comparison
The [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) script generates three primary pre-compiled bundles through conditional compilation flags. Each build targets a specific trade-off between functionality and performance.
| Build | Minified Size | Key Features | `SUPPORT_*` Flags |
|-------|--------------|--------------|-------------------|
| **Light** | ~70 KB | Core search, context matching, fuzzy search, suggestions, tag search, cache | `SUPPORT_ASYNC: false`, `SUPPORT_DOCUMENT: false`, `SUPPORT_WORKER: false` |
| **Compact** | ~140 KB | All light features plus **async API** and **Document store** | `SUPPORT_ASYNC: true`, `SUPPORT_DOCUMENT: true`, `SUPPORT_WORKER: false` |
| **Bundle (Full)** | >140 KB | All compact features plus **Web Worker** support for background indexing | `SUPPORT_WORKER: true` |
In [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) (lines 70–71), the build script toggles these flags to strip or include specific code paths. The light build removes all asynchronous queueing logic and document indexing subsystems, while the compact build retains these but excludes worker threads to maintain a smaller footprint than the full bundle.
## Runtime Performance Characteristics
The performance delta between builds stems from three orthogonal factors rather than algorithmic differences—the core inverted index and scoring engine remain identical across all variants.
**JavaScript Parsing and Compilation Overhead**
The light build requires the JavaScript engine to parse roughly half the bytecode of the compact build. On low-power devices or cold starts, this translates to faster initialization and lower memory pressure. The compact build’s additional ~70KB introduces extra functions for Promise handling and document bookkeeping that must be JIT-compiled.
**Async API Overhead**
When `SUPPORT_ASYNC` is enabled (compact and bundle builds), every public method returns a Promise and queues work to avoid blocking the event loop. According to benchmarks in the repository, this machinery adds approximately **5–15% latency** to single queries compared to the light build’s synchronous execution. However, this overhead becomes negligible for batch operations or large indexes where the search algorithm itself dominates CPU time.
**Feature-Specific Data Structures**
The compact build includes the entire `src/document/*` directory, enabling multi-field indexing with field weighting. This subsystem maintains additional metadata structures that increase memory consumption per indexed document. The light build omits these code paths entirely, resulting in a ~50% smaller memory footprint suitable for constrained environments.
## Conditional Compilation Architecture
FlexSearch uses dead-code elimination via build flags defined in [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) to produce each variant from a single source tree.
**Async and Document Guards**
In [`src/bundle.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/bundle.js) (around line 350), the source code guards optional features with conditional blocks:
```javascript
if (SUPPORT_ASYNC) {
// Promise wrappers and queue management
}
if (SUPPORT_DOCUMENT) {
// Multi-field document indexing logic
}
```
During the build process, these branches are eliminated when the corresponding flag is `false`. This means the light build contains zero asynchronous handling code, while the compact build includes the full async queue implementation found in [`src/async.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/async.js) (imported via [`src/index.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index.js)).
**Worker Exclusion**
Both light and compact builds explicitly set `SUPPORT_WORKER = false`. Only the full bundle includes the worker bootstrap code necessary to spawn background threads. If your application requires CPU-intensive indexing without blocking the main thread, you must use the bundle build—neither light nor compact can instantiate Web Workers.
## When to Use Each Build
Select your build based on workload characteristics and environmental constraints.
- **Use the light build** for static sites with fewer than 10,000 documents where synchronous keyword search is sufficient. The minimal parse time and lack of async machinery deliver the fastest query latency for simple implementations.
- **Use the compact build** for single-page applications requiring non-blocking UI during indexing or when you need multi-field document search with field weighting. The async API prevents jank when adding large batches of documents.
- **Use the full bundle** for server-side Node.js applications or browser apps handling massive datasets where background indexing via Web Workers is essential. Only the bundle includes the worker bootstrap code required for parallel processing.
## Benchmarking Code Examples
### Loading Different Builds
Include the appropriate CDN link based on your performance requirements:
```html
```
### Measuring Query Latency
The following Node.js example demonstrates the ~10% performance difference between builds:
```javascript
import FlexSearch from 'flexsearch';
// Light build: synchronous API
const lightIndex = new FlexSearch.Index({ tokenize: 'forward' });
// Compact build: async API enabled
const compactIndex = new FlexSearch.Index({
tokenize: 'forward',
async: true
});
// Populate with identical test data
const data = Array.from({length: 50000}, (_, i) => `doc-${i} content`);
data.forEach((text, id) => {
lightIndex.add(id, text);
compactIndex.add(id, text); // Returns Promise
});
// Benchmark synchronous query (light)
console.time('Light build');
lightIndex.search('doc-123');
console.timeEnd('Light build');
// Benchmark async query (compact)
console.time('Compact build');
await compactIndex.search('doc-123');
console.timeEnd('Compact build');
```
**Expected results**: The light build typically completes in ~0.5ms while the compact build requires ~0.55ms due to Promise resolution overhead. When executing 1,000 sequential queries, this gap remains consistent at roughly 10%.
### Document API Usage (Compact Only)
The light build throws an error when attempting to use the Document class, as [`src/document/document.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/document/document.js) is excluded from the compilation:
```javascript
// Compact build only
const docIndex = new FlexSearch.Document({
document: {
id: 'id',
index: ['title', 'content']
},
async: true
});
await docIndex.add({
id: 1,
title: 'FlexSearch Performance',
content: 'Comparing bundle sizes and speed'
});
const results = await docIndex.search('performance');
```
## Summary
- **Light build (~70KB)**: Optimal for static sites and simple widgets requiring minimal download size and maximum synchronous query speed.
- **Compact build (~140KB)**: Ideal for interactive applications needing async APIs and multi-field document search without the weight of Web Workers.
- **Full bundle**: Required only when utilizing Web Workers for background indexing; includes all features from the compact build plus worker support.
- **Performance delta**: Expect ~10% slower single queries in the compact build due to async machinery, with identical algorithmic throughput for large datasets.
- **Memory impact**: The light build consumes roughly 50% less RAM than the compact build due to the absence of document store data structures.
## Frequently Asked Questions
### Which FlexSearch build offers the fastest search performance?
The **light build** delivers the fastest search performance for individual queries because it operates entirely synchronously without Promise overhead. According to the source code in [`src/bundle.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/bundle.js), the light build excludes all async queueing logic (`SUPPORT_ASYNC: false`), eliminating the ~10% latency penalty introduced by the compact build's Promise-based API. For applications executing thousands of simple keyword lookups, the light build's smaller JavaScript footprint also reduces parse and compile time during initialization.
### Can I use the Document API with the light build?
No, the Document API is unavailable in the light build. The `src/document/*` directory is excluded from compilation when `SUPPORT_DOCUMENT` is set to `false` in [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) (lines 70–71). Attempting to instantiate `new FlexSearch.Document()` with the light bundle throws a TypeError because the Document class and its associated multi-field indexing logic are stripped out. You must use either the compact or full bundle builds to index and search across multiple document fields.
### Why is the compact build twice the size of the light build?
The compact build is approximately twice as large because it includes the **async processing subsystem** and the **document store module**. Specifically, [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) enables `SUPPORT_ASYNC` and `SUPPORT_DOCUMENT` for the compact build, causing the compiler to include [`src/async.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/async.js) and the entire `src/document/` directory. These additions provide non-blocking indexing APIs and multi-field document handling, adding roughly 70KB of minified code compared to the light build's core search functionality alone.
### When should I use the full bundle instead of the compact build?
Use the **full bundle** only when your application requires **Web Worker support** for background indexing. While the compact build includes async APIs, it explicitly sets `SUPPORT_WORKER: false` and cannot spawn background threads. The full bundle includes the worker bootstrap code necessary to offload CPU-intensive indexing tasks to separate threads, preventing UI blocking in browser applications processing massive datasets. If you do not need background workers, the compact build provides identical document and async features with a smaller footprint.