/convert-component

name: webflow-code-component:convert-component
description: Convert an existing React component into a Webflow Code Component. Analyzes TypeScript props, maps to Webflow prop types, generates the .webflow.tsx definition file, and identifies required modifications.
compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli
metadata:
  author: webflow
  version: "1.0"

Convert Component

Convert an existing React component into a Webflow Code Component by analyzing its structure and generating the appropriate `.webflow.tsx` definition file.

When to Use This Skill

**Use when:**

• User has an existing React component they want to use in Webflow
• User asks to "convert", "adapt", or "make this work with Webflow"
• User provides a React component file and wants a Webflow definition
• User is migrating components from another React project

**Do NOT use when:**

• Creating a component from scratch (use component-scaffold)
• User just wants to understand code components (answer directly)
• Component is already a Webflow code component (use component-audit)

Instructions

Phase 1: Analyze Existing Component

1. **Read the React component file**: Get the full source code

2. **Extract component information**:

• Component name (function/const name)
• Props interface or type definition
• Each prop's TypeScript type
• Default values if defined
• Whether component uses `children`

3. **Identify incompatible patterns**:

| Pattern | Issue | Resolution | |---------|-------|------------| | React Context usage | Context doesn't work across Webflow components | Refactor to props or use nano stores | | `window`/`document` in render | SSR will fail | Wrap in useEffect or set `ssr: false` | | `localStorage`/`sessionStorage` in render | SSR will fail | Wrap in useEffect or set `ssr: false` | | Complex object props | Can't map to Webflow prop types | Break into individual props | | Function props (callbacks) | Not supported in Webflow | Remove or internalize logic | | `useContext` hook | Won't work across components | Use alternative state patterns | | External CSS imports | May not work in Shadow DOM | Import in .webflow.tsx instead | | CSS class references to global styles | Won't work in Shadow DOM | Use component-scoped styles | | styled-components | Needs Shadow DOM decorator | Set up globals.ts with decorator | | Emotion (@emotion/styled) | Needs Shadow DOM decorator | Set up globals.ts with decorator |

4. **Detect styling approach** and note required setup:

**If using styled-components:**

   npm i @webflow/styled-components-utils styled-components

Create/update `globals.ts`:

   import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";
   export const decorators = [styledComponentsShadowDomDecorator];

**If using Emotion:**

   npm i @webflow/emotion-utils @emotion/cache @emotion/react

Create/update `globals.ts`:

   import { emotionShadowDomDecorator } from "@webflow/emotion-utils";
   export const decorators = [emotionShadowDomDecorator];

**For both CSS-in-JS approaches**, update `webflow.json`:

styled-components:

   {
     "library": {
       "globals": "./src/globals.ts",
       "renderer": {
         "server": "@webflow/styled-components-utils/server"
       }
     }
   }

Emotion:

   {
     "library": {
       "globals": "./src/globals.ts",
       "renderer": {
         "server": "@webflow/emotion-utils/server"
       }
     }
   }

5. **Flag any dependencies** that might cause issues:

• Large libraries (bundle size concern)
• Browser-only libraries
• Libraries that manipulate DOM directly

Phase 2: Map Props to Webflow Types

6. **Apply TypeScript → Webflow prop type mapping**:

| TypeScript Type | Webflow Prop | Notes | |-----------------|--------------|-------| | `string` | `props.Text()` | Default for short text | | `string` (long/HTML content) | `props.RichText()` | If prop name suggests content/body/description | | `React.ReactNode` / `children` | `props.Slot()` | For nested content | | `number` | `props.Number()` | Numeric values | | `boolean` | `props.Boolean()` | Toggles | | `"option1" \| "option2"` | `props.Variant()` | String literal unions (requires `options` array) | | `enum` | `props.Variant()` | Convert enum values to `options` array (required) | | `{ href: string; ... }` | `props.Link()` | Returns `{ href, target?, preload? }` object — may need wrapper if component expects separate `href`/`target` props | | Image-related types | `props.Image()` | Image src, url, etc. | | `string` (canvas-editable text) | `props.TextNode()` | For text editable directly on canvas; has `multiline` param | | `boolean` (show/hide) | `props.Visibility()` | Semantic show/hide toggle | | `string` (for HTML id) | `props.Id()` | If prop is named "id" or used for accessibility | | Complex objects | **SPLIT** | Break into multiple simple props | | Functions/callbacks | **REMOVE** | Not supported | | Arrays | **SPECIAL** | May need component redesign |

7. **Handle special cases**:

**Complex object props** - Break them down:

   // Original
   interface Props {
     author: {
       name: string;
       avatar: string;
       bio: string;
     }
   }

   // Converted to flat props
   props: {
     authorName: props.Text({ name: "Author Name" }),
     authorAvatar: props.Image({ name: "Author Avatar" }),
     authorBio: props.RichText({ name: "Author Bio" })
   }

**Union types with more than simple strings**:

   // Original - complex union
   type Size = "sm" | "md" | "lg" | { width: number; height: number };

   // Convert to Variant with only string options
   size: props.Variant({
     name: "Size",
     options: ["sm", "md", "lg", "custom"],