# How to Create Custom Builds of FlexSearch to Reduce Bundle Size for Specific Use Cases

> Learn to create custom FlexSearch builds with feature flags and Google Closure Compiler. Reduce bundle size by stripping unused functionality for your specific use cases.

- Repository: [Nextapps GmbH/flexsearch](https://github.com/nextapps-de/flexsearch)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can create custom FlexSearch builds by running `npm run build:custom` with feature flags (like `SUPPORT_DOCUMENT` or `SUPPORT_TAGS`) to strip unused functionality, generating a minimal bundle via Google Closure Compiler.**

The open-source FlexSearch library (nextapps-de/flexsearch) provides a sophisticated build system that lets you compile only the features you need. By leveraging the build script in [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) and configuration flags defined in [`src/config.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/config.js), you can drastically reduce your final bundle size for production deployments.

## Understanding the FlexSearch Build Architecture

The custom build system relies on three core components working together to eliminate dead code before compilation.

### The Build Script (task/build.js)

The heart of the system is [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js), which orchestrates the entire process. It parses command-line arguments (lines 29-60) to build an `options` object mapping flag names to values, then rewrites [`src/config.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/config.js) with your selected flags (lines 77-99). Finally, it invokes Google Closure Compiler with optimizations to strip unreachable code paths.

### Configuration Flags (src/config.js)

The [`src/config.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/config.js) file exports default constants for all feature flags (prefixed with `SUPPORT_`). During the build process, the script overwrites these exports with your CLI values, allowing Closure Compiler to perform dead code elimination on features marked as `false`.

## Available Feature Flags for Custom Builds

FlexSearch exposes several boolean flags that control which modules are included in your final bundle:

- **SUPPORT_DOCUMENT** – Enables document indexing capabilities for searching across structured data
- **SUPPORT_TAGS** – Adds tag-based filtering and search functionality
- **SUPPORT_WORKER** – Includes Web Worker support for offloading search operations to background threads
- **SUPPORT_CACHE** – Enables result caching mechanisms for repeated queries
- **SUPPORT_ASYNC** – Adds asynchronous search operation support
- **SUPPORT_SERIALIZE** – Includes index serialization and deserialization capabilities

Additional build options include `LANGUAGE_OUT` (e.g., `ECMASCRIPT5` or `ECMASCRIPT_2015`) and `POLYFILL` (boolean) for legacy browser support.

## Step-by-Step Guide to Creating Custom Builds

### Full-Featured Document and Tag Search Build

To create a build supporting document indexing, tag filtering, and ECMAScript 5 compatibility with polyfills:

```bash
npm run build:custom \
  SUPPORT_DOCUMENT=true \
  SUPPORT_TAGS=true \
  LANGUAGE_OUT=ECMASCRIPT5 \
  POLYFILL=true

```

This generates `dist/flexsearch.custom.<hash>.min.js` containing only the core engine, document index, tag search, and necessary ES5 polyfills.

### Minimal Bundle-Only Build

For the smallest possible footprint with no optional features:

```bash
npm run build:custom

```

Running the command without flags disables all optional features, producing a minimal bundle containing only the essential search engine core. The output filename includes a hash representing the empty configuration state.

### ESM Module Build with Worker Support

To generate an ES module version with Web Worker capabilities:

```bash
npm run build:custom RELEASE=custom.module \
  SUPPORT_DOCUMENT=true \
  SUPPORT_WORKER=true

```

Setting `RELEASE=custom.module` instructs the build script to output `dist/flexsearch.custom.module.<hash>.min.js` as an ES module rather than UMD format.

## Integrating Custom Builds Into Your Project

Add a custom build script to your project's [`package.json`](https://github.com/nextapps-de/flexsearch/blob/main/package.json) to automate bundle generation:

```json
{
  "scripts": {
    "flexsearch:light": "npm run build:custom SUPPORT_DOCUMENT=false SUPPORT_TAGS=false SUPPORT_WORKER=false",
    "flexsearch:full": "npm run build:custom SUPPORT_DOCUMENT=true SUPPORT_TAGS=true SUPPORT_CACHE=true"
  }
}

```

Now `npm run flexsearch:light` produces a tiny bundle optimized for simple in-memory searches, while `npm run flexsearch:full` includes document indexing and caching for complex applications.

## Summary

- **FlexSearch uses Google Closure Compiler** via [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) to eliminate dead code based on feature flags defined in [`src/config.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/config.js).
- **Feature flags** like `SUPPORT_DOCUMENT`, `SUPPORT_TAGS`, and `SUPPORT_WORKER` control which modules are included in your bundle.
- **Run `npm run build:custom`** with your desired flags to generate optimized bundles in `dist/` with hashed filenames indicating the configuration.
- **ESM and UMD formats** are supported via the `RELEASE` flag, allowing integration with modern module systems or legacy environments.

## Frequently Asked Questions

### How much bundle size can I save with custom builds?

Custom builds can reduce the final bundle size by 50-80% depending on which features you disable. A minimal build with only core search functionality typically weighs under 10KB minified and gzipped, compared to the full-featured bundle which includes document indexing, worker support, and serialization capabilities.

### Can I use custom builds with npm or only by cloning the repository?

While the build script requires cloning the repository to access [`task/build.js`](https://github.com/nextapps-de/flexsearch/blob/main/task/build.js) and the source files in `src/`, you can integrate the build process into your CI/CD pipeline by adding the repository as a dev dependency or by pre-building custom bundles and committing them to your project's `vendor` directory.

### What happens if I enable a feature flag but don't use that feature in my code?

Even if you don't import or call specific methods, enabling a feature flag includes that module's code in the final bundle. The build system performs dead code elimination based on the flags, not your usage patterns, so only disable flags for features you definitely don't need to achieve maximum size reduction.

### Does the custom build system support TypeScript definitions?

The custom build process generates JavaScript bundles only. However, the main FlexSearch repository includes TypeScript definition files that cover all possible feature combinations. When using a custom build with reduced features, you can still use the standard type definitions, though some methods will be typed but unavailable at runtime if you disabled their corresponding flags.