Troubleshooting DevLink

Issue: DevLink sync 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.local file
3. Ensure the token is being accessed correctly in your .webflowrc.js / webflow.json file

Issue: The DevLink CLI can’t find your configuration

Solutions:

1. Ensure .webflowrc.js / webflow.json 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 JavaScript syntax

Many code examples in the DevLink guides reference importing DevLink components from an alias like so:

1
import { Button } from "@/devlink/Button";

You can set up your project to import via this alias in various ways once you’ve synced 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 DevLink components.

1
{
2
  "compilerOptions": {
3
    "paths": {
4
      "@/*": ["./src/*"],
5
      "@/devlink": ["./devlink"],
6
      "@/devlink/*": ["./devlink/*"]
7
    }
8
  }
9
}

Via Webpack

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

1
const path = require('path');
2
3
module.exports = {
4
  // ...
5
  resolve: {
6
    alias: {
7
      '@': path.resolve(__dirname, 'devlink'),
8
    }
9
  }
10
}

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
3. Ensure component names don’t contain special characters or spaces

PageLayout example

Consider a PageLayout component that has a header, footer, and left sidebar built into the component in Webflow, but has the body of the component left open for dynamic content to be passed in as a custom React component. You can create a wrapper <div> in Webflow and bind it to a slot property. When using the DevLink-generated component, you can then pass in the React components to fill in the body content.

1
import { PageLayout } from "@/devlink";
2
3
export default function MyPage() {
4
  return (
5
    <PageLayout
6
      bodyContent={
7
        <div>
8
          <h1>My Page</h1>
9
          <p>This is my page content.</p>
10
        </div>
11
      }
12
    />
13
  );
14
}

Issue: The sync process starts but fails to complete

Solutions:

1. Check for network connectivity issues
2. Verify you’re not exceeding API rate limits
3. Try syncing specific components instead of all at once

You can sync a specific component by name:

$
webflow devlink sync YourComponentName

Issue: Components don’t look the same as in Webflow

Solutions:

1. Ensure the DevLink global.css file is imported at the application root
2. Verify the DevLinkProvider component is wrapping your application at the root
3. Check for CSS conflicts with other styles in your application
4. Inspect the browser console for CSS-related errors

Issue: Custom fonts don’t appear correctly

Solutions:

1. Check if the fonts are being loaded from the correct source
2. Ensure font imports in global.css are loading correctly
3. Verify fonts aren’t being blocked by CORS policies
4. Consider self-hosting the fonts if they’re from external sources
5. Make sure font weights and styles match those used in Webflow

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 for complex stacking situations

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

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:

1
"use client";
2
3
import { MyDevLinkComponent } from '@/devlink';
4
5
export default function ClientComponent() {
6
  return <MyDevLinkComponent />;
7
}

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

Solution: Replace DevLink Image elements with Next.js Image components

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
4. Enable skipTagSelectors in your DevLink configuration to prevent conflicts between Tailwind CSS defaults and global.css rules

Some rules from tue DevLink global.css might conflict with the defaults set by Tailwind CSS. If you wish to use DevLink and Tailwind CSS on the same project, we recommend enabling skipTagSelectors to disable opinionated rules and selectors and only include the bare minimum required for DevLink components to work.

In your CSS:

1
/* Give DevLink styles higher priority */
2
@layer base, components, utilities, devlink;

In your .webflowrc.js / webflow.json:

1
module.exports = {
2
  skipTagSelectors: true
3
}

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

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 devlink directory
3. Consider lazy loading components that aren’t needed on initial render
4. Use production builds to minimize JavaScript and CSS

Issue: Issues installing or running the Webflow CLI

Solutions:

1. Check Node.js version (v20+ recommended)
2. Clear npm cache and try reinstalling
3. Ensure you have proper permissions for the installation directory

$
# Clear npm cache
>
npm cache clean --force
>
>
# Reinstall the CLI
>
npm install @webflow/webflow-cli

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:

1
"scripts": {
2
  "sync": "webflow devlink sync"
3
}

Then run:

$
npm run sync