Bundling and Import

This reference covers bundling your React components and importing them to Webflow.

Import

Import your components to Webflow using DevLink. DevLink bundles your component files and uploads them to your Workspace as a shared library.

Use the following command to import your components to Webflow:

webflow devlink import

CI/CD pipelines

For automated workflows, add the --no-input flag to skip interactive prompts:

webflow devlink import --no-input

Important: Add change detection to prevent inadvertently removing components:

• Compare current library state with previous import
• Only share when components have actually changed

webflow devlink import and webflow devlink bundle exit with 0 on success. Treat any non-zero exit code as a failure.

To check that your library builds without sharing it, for example on every pull request, run webflow devlink import --dry-run --no-input. See Import in the CLI reference.

For more options, see the Webflow CLI reference. →.

Bundling

Webflow uses Webpack to bundle your component libraries. During this process, the bundler handles TypeScript compilation, resolves all dependencies and imports, optimizes your code for production, and generates bundles ready for import.

The default configuration handles most use cases automatically. Extend it when you need:

• Custom CSS processing
• Specialized file handling (SVG, images, fonts)
• Build optimizations (tree shaking, code splitting)

To override the default configuration, see the guide on Webpack configuration overrides.

Bundle limits

The maximum bundle size is 50 MB. Component count alone doesn’t determine bundle size, it also depends on dependencies and bundled assets in the library.

Run the local bundle command to see the total size of your generated files. Check how that size changes when you add dependencies or large assets, such as images and fonts.

Debugging

This section provides common debugging techniques for troubleshooting the bundling process and resolving configuration issues.

Disable minification

By default, the bundler minifies your code to reduce file size for production. To troubleshoot issues, you can disable minification in your webpack configuration.

This keeps your bundled code readable and ensures that any errors you see in the browser’s developer console will have accurate line numbers that map back to your original source code.

module.exports = {
    mode: "development",
  };

{
  "library": {
    "name": "My Library",
    "components": ["./src/components/**/*.webflow.{js,ts,tsx}"],
    "bundleConfig": "./webpack.webflow.js"
  }
}

Multiple copies of React

Code components only render when the whole bundle uses a single copy of React. Two copies build without errors, but every component then crashes in the Webflow Designer with React error #525 or “Invalid hook call”. A dependency that installs its own copy of react, or react and react-dom at different versions, causes this.

The CLI resolves react and react-dom from the folder that contains your manifest file. If the bundler still finds more than one copy, or the versions don’t match, the build fails and lists where each copy comes from. For example:

Found 2 copies of "react" in the bundle. Code components need a single React instance, or they crash in the Webflow Designer (React error #525 or "Invalid hook call"):
  - react@18.3.1 at node_modules/kit-a/node_modules/react (imported by node_modules/kit-a/index.js)
  - react@19.1.0 at node_modules/kit-b/node_modules/react (imported by node_modules/kit-b/index.js)

"react" and "react-dom" versions don't match. Code components crash in the Webflow Designer when they differ:
  - react@18.3.1 at node_modules/react (imported by src/Counter.tsx)
  - react-dom@19.1.0 at node_modules/react-dom (imported by src/Counter.tsx)

To fix it:

1. Install react and react-dom in the folder that contains your manifest file, or make sure your package manager hoists them there.
2. Use the same version of react and react-dom. See React and React DOM for the version rules.
3. Align the versions in your package.json files, or pin one version with your package manager’s overrides (npm), resolutions (Yarn), or pnpm.overrides (pnpm). Then reinstall your dependencies.

The --force flag doesn’t skip this check, because the bundle would crash in the Designer anyway.

CSS modules

CSS Modules scope styles by generating unique class names, preventing conflicts between components.

By default, you must use bracket notation to access CSS classes:

import * as styles from "./Button.module.css";
export const Button = (text: string) => {
    return (
        <a className={(styles as any)["my-button"]}>
            {text}
        </a>
    );
};

To enable dot notation, and to use the default import syntax for CSS modules, update the css-loader configuration:

module.exports = {
    module: {
      // Override the existing rules to modify CSS processing
      rules: (currentRules) => {
        return currentRules.map((rule) => {
          // Find the rule that handles CSS files
          if (
            rule.test instanceof RegExp &&
            rule.test.test("test.css") &&
            Array.isArray(rule.use)
          ) {
              for (const [index, loader] of rule.use.entries()) {
              // Find the css-loader
              if (typeof loader === "object" && loader?.ident === "css-loader") {
                // Preserve existing options and add a custom configuration
                const options =
                  typeof loader.options === "object" ? loader.options : {};
                rule.use[index] = {
                  ...loader,
                  options: {
                    ...options,
                    modules: {
                      exportLocalsConvention: "as-is", // Use original class names
                      namedExport: false, // ⚠️ Allow dot notation access
                    },
                  },
                };
              }
            }
          }
          return rule;
        });
      },
    },
  };

Bundle locally

To test and debug your React components locally, you can bundle your library using the Webflow CLI command.

webflow devlink bundle --public-path http://localhost:4000/

The public path is the URL where you can serve your bundled library. The CLI will generate a dist folder with your bundled library.

To inspect the final configuration being used by webpack, use the --debug-bundler option.