FAQs and troubleshooting

$
npm i --save-dev @webflow/webflow-cli @webflow/react @webflow/data-types

$
npx webflow library share

See the getting started guide for detailed steps.

Code components support React with TypeScript. You can use:

• React hooks and functional components
• TypeScript for type safety
• Popular React libraries (with some limitations)
• CSS-in-JS solutions (with configuration)

There’s no strict limit on the number of components per library, but keep your bundle size under 50MB for optimal performance.

Code components render in Shadow DOM, which isolates styles. Common issues:

• Site classes don’t work - Use component-specific CSS classes
• CSS-in-JS libraries need configuration - See bundling guide

Reference site variables in your component CSS:

1
.my-component {
2
  color: var(--background-primary, #000);
3
}

Get the exact variable name from the Variables panel in Webflow Designer.

Yes, but with important limitations:

• Client-side only - No server-side rendering
• Public APIs only - Don’t include auth tokens or secrets
• CORS considerations - APIs must allow cross-origin requests

Example of safe API usage:

1
useEffect(() => {
2
  fetch('/api/public-data')
3
    .then(response => response.json())
4
    .then(setData);
5
}, []);

1. Make your changes locally
2. Run npx webflow library share to deploy
3. The updated component replaces the previous version

Note: You can’t update individual components - the entire library is deployed as one unit.

Yes, use the local bundling feature:

$
npx webflow library bundle --public-path http://localhost:4000/ --dev

This creates a dist folder you can serve locally for testing.

Currently, code components don’t support versioning. Each deployment replaces the previous version. Consider:

• Using Git for version control
• Testing thoroughly before deployment
• Keeping deployment logs for rollback reference

Check these common issues:

1. Build errors - Check your terminal for compilation errors
2. Missing dependencies - Ensure all imports are available
3. Bundle size - Keep under 50MB limit
4. Single root element - Components must have one root element (no fragments)

Shadow DOM limitations can cause styling issues:

• Site classes - Use component-specific classes instead
• CSS-in-JS - Configure for Shadow DOM (see bundling guide)
• Inheritance - Use inherit values for cross-boundary styling

Each code component runs in its own React root, so:

• React Context doesn’t work across components
• Redux/global state isn’t shared between components
• Use alternatives like URL parameters, localStorage, or external state management

Learn more about component architecture and state management when building code components.

Common deployment issues:

• Authentication - Ensure your Workspace token is valid in your .env file
• Bundle size - Check if you’re under the 50MB limit
• Build errors - Fix any compilation issues first
• Network issues - Check your internet connection

Maximum bundle size is 50MB. To optimize:

• Use tree shaking
• Minimize dependencies
• Remove unused code
• Optimize images and assets

Not currently. Code components render only on the client side. Server-side rendering is planned for future releases.

Since each component has its own React root, use:

• URL parameters for simple state
• localStorage/sessionStorage for persistent data
• External state management libraries compatible with isolated roots
• Custom events for component communication

Learn more about component architecture and state management when building code components.

Most React libraries work, but some have limitations:

• Multiple entry points - Libraries with ESM + CJS may not work
• Style injection - CSS-in-JS libraries need Shadow DOM configuration
• Global dependencies - Libraries that modify window or document may conflict

Learn more about styling components when building code components.

1. Browser dev tools - Inspect the Shadow DOM
2. Console logging - Add console.log statements
3. Local bundling - Use --dev flag for better error messages
4. Source maps - Enable for easier debugging

Yes, TypeScript is fully supported. Use .tsx files for your components and configure tsconfig.json for your project.

Use standard CSS media queries within your component:

1
.my-component {
2
  width: 100%;
3
}
4
5
@media (min-width: 768px) {
6
  .my-component {
7
    width: 50%;
8
  }
9
}

Yes, CSS animations and transitions work normally within the Shadow DOM boundary. Use standard CSS animation properties and @keyframes.