Webpack Configuration Overrides
This guide covers how to customize your webpack configuration for advanced implementation of code components.
Overview
The CLI uses an internal webpack configuration optimized for Webflow’s requirements, including Module Federation, CSS extraction, TypeScript/React support, and other optimizations. When you need to customize this configuration, you can provide an override configuration file that will be merged with the base configuration.
Review the default configuration
To view the webpack configuration used to bundle your library, use the --debug-bundler
flag when running library
commands:
This will output the final merged webpack configuration to help you understand how your overrides are being applied.
Configuration file setup
Specify the configuration path
In your webflow.json
manifest file, add a bundleConfig
property pointing to your configuration file:
Configuration API
Your override configuration should follow the standard Webpack Configuration API with the following important exceptions and special handling:
Blocked properties
The following properties are automatically filtered out and can’t be overridden for security and compatibility reasons:
If you attempt to override these properties, a warning will be logged and they will be ignored.
Special property handling
Module rules
Instead of providing an array of rules, you must provide a function that receives the current rules and returns the modified rules array:
Plugins
Your custom plugins
array is merged with the default configuration using webpack-merge
.
To prevent common build errors, the following plugins are automatically de-duplicated, ensuring only one instance is present in the final configuration:
ModuleFederationPlugin
MiniCssExtractPlugin
Examples
Add a new loader
To handle file types that build on existing configurations (like SCSS extending CSS), you can add a new rule that reuses parts of an existing loader chain. This ensures consistency and compatibility.
Support for common CSS frameworks
Code components support popular CSS frameworks and libraries, including Tailwind CSS, styled-components, and Emotion, material UI, shadcn/ui, and more. For detailed guidance on using these frameworks with code components, see the frameworks and libraries guide.
The example below adds a rule for .scss
files by finding the existing CSS rule and appending sass-loader
to it:
Add a new rule
To process custom file types not handled by the default configuration, add a new rule. The following example adds markdown-loader
to handle .md
files:
Extend an existing loader
You can modify the options for an existing loader to customize its behavior. This requires finding the specific rule and then updating its options
object.
The following example shows how to modify the css-loader
to change its configuration for CSS Modules:
Add custom plugins
To add custom build-time functionality, provide an array of plugins. This example shows how to add a custom plugin to the configuration:
Provide aliases
To create shorter, more convenient import paths, define aliases in the resolve.alias
object. This example creates an @
alias that points to the project’s root directory:
Best practices
- Use functions for module rules: Always provide a function for
module.rules
to ensure proper integration with existing rules - Minimal changes: Only override what you absolutely need to customize
- Check for conflicts: Ensure your custom loaders don’t conflict with existing ones
Troubleshooting
Configuration not loading
- Ensure the
bundleConfig
path in yourwebflow.json
is correct and relative to your project root. - Verify your configuration file exports a valid object using
module.exports
.
Rules not working
- Make sure you’re providing a function for
module.rules
, not an array. - Check that your rule matching logic correctly identifies the rules you want to modify.
Plugins conflicting
- Remember that
ModuleFederationPlugin
andMiniCssExtractPlugin
are automatically de-duplicated. - Ensure custom plugins don’t conflict with the base configuration.
For more information about webpack configuration options, refer to the official Webpack documentation.