Build Flags

unlazy uses build-time flags to enable tree-shaking of unused features, reducing bundle size. Bundlers replace these flags at build time, allowing dead code elimination for features your project doesn't use.

Common bundlers support the define option for setting build flags:

• Vite
• @rollup/plugin-replace
• esbuild

As an example, you can tree-shake the hash decoding algorithms in Vite by setting the define option in your vite.config.ts file:

// `vite.config.ts`
import { defineConfig } from 'vite'

export default defineConfig({
  define: {
    // Defaults to `true`
    __UNLAZY_HASH_DECODING__: false,
    // Defaults to `true`
    __UNLAZY_LOGGING__: false,
  },
})

Disable Hash Decoding ^0.10.0

unlazy includes BlurHash and ThumbHash decoding algorithms (from fast-blurhash and thumbhash packages). If your project doesn't use hash-based placeholders, you can exclude these dependencies entirely:

• __UNLAZY_HASH_DECODING__: Set to false to tree-shake hash decoding code. Default is true.

When disabled, the bundler removes:

• BlurHash and ThumbHash decoding libraries
• Hash-related code paths in lazyLoad()
• Associated dependencies from the final bundle

WARNING

This flag only affects the main entry point. If you directly import unlazy/blurhash or unlazy/thumbhash, those modules will still be bundled regardless of this flag.

Disable Client Logging ^0.10.2

unlazy emits dev-time console output to help you catch configuration mistakes. Set __UNLAZY_LOGGING__ to false to strip all of it from production builds. Default is true.

When disabled, the bundler removes:

• Missing data-src / data-srcset errors: logged when an image passed to lazyLoad is missing both attributes.
• Hash decoder failure errors: logged when a BlurHash or ThumbHash string cannot be decoded.
• Largest Contentful Paint warning: logged when the LCP element is still configured for lazy loading.

This is recommended for production IIFE bundles.