> This page is for DevLink.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# Troubleshooting Exported Components

> Solutions for common issues when working with DevLink

This guide covers common issues you might encounter when working with DevLink and provides solutions to help you resolve them.

## Authentication and setup

#### API token authentication failures

**Issue**: DevLink Export fails with authentication errors

**Solutions**:

1. Verify your Webflow API token has the correct permissions
2. Check that your token is properly stored in your `.env` file
3. Ensure the token is being accessed correctly in your `webflow.json` file

#### Configuration File Location

**Issue**: The DevLink CLI can't find your configuration

**Solutions**:

1. Ensure the `webflow.json` file is in the root directory of your project
2. Check that the file has the correct name and extension
3. Verify the file has proper syntax

#### Cannot resolve \`webflow/\*\` imports

Many code examples in this documentation show importing components from an alias:

```typescript
import { Button } from "webflow/Button";
```

You can set up your project to import via this alias in various ways after you've exported your components. Here are a few examples:

**Via `tsconfig.json`**

Update the `paths` in the `tsconfig.json` file to point to the correct location of your exported components.

**`tsconfig.json`**

```json title="tsconfig.json"
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "webflow/*": ["./webflow/*"]
    }
  }
}
```

**Via Webpack**

Update the `resolve.alias` settings in your Webpack configuration to point to the correct location of your exported components.

**`webpack.config.js`**

```javascript title="webpack.config.js"
const path = require('path');

module.exports = {
  // ...
  resolve: {
    alias: {
      'webflow': path.resolve(__dirname, 'webflow'),
    }
  }
}
```

## Component export issues

#### Missing components

**Issue**: Some components aren't exported from Webflow

**Solutions**:

1. Verify the elements are properly converted to Components in Webflow (not just elements on the canvas)
2. Check if the components use only [supported elements](/devlink/docs/component-export/design-guidelines/component-architecture#supported-elements)
3. Ensure component names don't contain special characters or spaces

#### Export Process Failures

**Issue**: The export process starts but fails to complete

**Solutions**:

1. Check for network connectivity issues
2. Verify you're not exceeding API rate limits
3. Try exporting a narrower set of components instead of all at once

You can narrow the export to a specific component by setting the `devlink-export.components` regex in `webflow.json` (for example, `"components": "YourComponentName"`) before re-running:

```bash
webflow devlink export
```

## Styling and rendering issues

#### Missing Styles

**Issue**: Components don't look the same as in Webflow

**Solutions**:

1. Ensure the DevLink `global.css` file is [imported at the application root](/devlink/docs/component-export/installation)
2. Verify the `DevLinkProvider` component is [wrapping your application at the root](/webflow-cloud/devlink/styling-and-interactions#handling-webflow-interactions)
3. Check for CSS conflicts with other styles in your application
4. Inspect the browser console for CSS-related errors

#### Font loading issues

See the [fonts guide](/devlink/docs/component-export/fonts) for how Google, Adobe, and custom uploaded fonts ship with DevLink — including domain allowlists, CSP directives, and a full troubleshooting checklist.

#### Z-index Issues

**Issue**: Elements appearing behind or in front of others incorrectly

**Solutions**:

1. Check z-index values in the exported CSS
2. Inspect stacking contexts in your application
3. Adjust z-index values as needed
4. Consider using [React portals](https://react.dev/reference/react-dom/createPortal) for complex stacking situations

## Interaction issues

#### Interactions Not Working

**Issue**: Animations or interactions from Webflow don't work

**Solutions**:

1. Verify the `DevLinkProvider` is properly set up in your application
2. Check if the interactions use supported features
3. Inspect browser console for JavaScript errors
4. Consider simplifying complex interactions

#### Interactions with GSAP (IX3) don't run

**Issue**: Animations built in the new GSAP-powered Interactions panel don't run in the exported React project.

**Solutions**:

1. Verify you're on `@webflow/webflow-cli` v1.19.0 or later and Node.js v22 or later.
2. Confirm that the Interactions are scoped to the component that you exported.
   Page-level interactions are not exported for IX3; the "only first page interaction is exported" limitation applies to Classic Interactions (IX2) only.
3. Confirm your application is wrapped in `DevLinkProvider`.
   The provider handles both IX2 and IX3, so no separate provider is needed.
4. Inspect the browser network tab to confirm `webflow_modules/devlink-ix3.js` and `webflow_modules/devlink-gsap.js` load when the animated component mounts.
   These bundles are lazy-loaded only when a component that uses `useIX3Interactions` renders.

#### Warnings about unsupported action types

**Issue**: The CLI prints warnings about Lottie, Spline, or Rive actions during export.

**Cause**: These action types are not yet supported by DevLink Export.

**Solutions**: The warnings do not block the export.
The component is exported without those actions, and remaining triggers and timelines run as designed.
To remove the warnings, remove the unsupported actions from the Interaction in the Designer.

#### Astro: IX3 context not shared across islands

**Issue**: In an Astro project, animations don't run when the exported component is rendered in one island and `DevLinkProvider` is rendered in another.

**Cause**: Two separate `client:load` islands do not share React context, including the IX3 provider that `DevLinkProvider` mounts.

**Solution**: Place a single `client:load` directive on the component that wraps both `DevLinkProvider` and any DevLink components.
Don't split the provider and the animated component into separate islands.

## Framework-specific issues

#### Next.js App Router Issues

**Issue**: DevLink components don't work with React Server Components

**Solutions**:

1. Add the `"use client"` directive to component files that use client-side features
2. Import DevLink components only in client components
3. Ensure the DevLinkProvider is in a client-side context

Example client component:

```jsx
"use client";

import { MyDevLinkComponent } from 'webflow/MyDevLinkComponent';

export default function ClientComponent() {
  return <MyDevLinkComponent />;
}
```

#### Next.js Image Optimization

**Issue**: Images in DevLink components don't work with Next.js Image optimization

**Solution**:
Replace DevLink Image elements with [Next.js Image components](/webflow-cloud/devlink/framework-integrations#links-and-images)

#### CSS Conflicts with Tailwind

**Issue**: DevLink styles conflict with Tailwind CSS

**Solutions**:

1. Use Tailwind's preflight reset cautiously
2. Consider using Tailwind's `@layer` directive to control specificity
3. Use more specific selectors for custom styles

#### CSS Loading Issues

If styles aren't loading correctly:

1. Verify the DevLink `global.css` import path is correct for your framework
2. Ensure CSS loading is configured correctly in your app
3. Check for CSS isolation, scoping, and conflict issues with browser tools

#### Performance Optimizations

To optimize DevLink components in production:

1. Enable code splitting in your framework configuration
2. Only import the DevLink components you need from their respective file, rather than importing from the entire `webflow` directory
3. Consider lazy loading components that aren't needed on initial render
4. Use production builds to minimize JavaScript and CSS

## DevLink CLI Issues

#### CLI Installation Problems

**Issue**: Issues installing or running the Webflow CLI

**Solutions**:

1. Check Node.js version — v22 or higher is required
2. Clear npm cache and try reinstalling
3. Ensure you have proper permissions for the installation directory

```bash
# Clear npm cache
npm cache clean --force

# Reinstall the CLI (use -g if you originally installed it globally)
npm install -D @webflow/webflow-cli@latest
```

#### CLI Command Not Found

**Issue**: `Webflow` command not found after installation

**Solutions**:

1. Ensure the package is installed and up to date
2. Use `npx` to run the CLI commands
3. Add the CLI to your `package.json` scripts

In your package.json:

```json
"scripts": {
  "export": "webflow devlink export"
}
```

Then run:

```bash
npm run export
```