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

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 and configuration flags defined in 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, 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 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 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:

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:

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:

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 to automate bundle generation:

{
  "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 to eliminate dead code based on feature flags defined in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}