Webflow Code Component:pre Deploy Check Agent Skill

Build Validate

Validate code components before deployment to catch issues early.

When to Use This Skill

Use when:

• User is about to deploy and wants to check for issues first
• Proactively before running webflow library share
• User asks to validate, check, or verify their components
• After making significant changes to components

Do NOT use when:

• Deployment already failed (use troubleshoot-deploy instead)
• Just building for local development
• Auditing code quality (use component-audit instead)

Instructions

Phase 1: Project Structure Check

• Verify webflow.json exists:
• Check for required fields (library.name, library.components)
• Validate glob pattern matches component files — the recommended pattern is "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)" covering all supported extensions
• Check globals path if specified — file must exist and be importable
• Check bundleConfig path if specified — file must exist

• Check dependencies:
• Verify @webflow/webflow-cli installed
• Verify @webflow/data-types installed
• Verify @webflow/react installed
• Check for version compatibility (check installed versions, don't assume specific versions)

• Verify component files:
• Find all .webflow.tsx / .webflow.ts files matching the glob pattern
• Ensure matching React components exist
• Check for orphaned definition files

• Validate imports in .webflow.tsx files:
• Must import declareComponent from @webflow/react
• Must import props from @webflow/data-types (if props are defined)
• Must import the actual React component being declared

Phase 2: Component Analysis

• For each component, check:
• declareComponent is called with the component and a config object
• name is provided in the config
• All props have name properties and appropriate defaultValue where applicable
• Prop types are valid — the 11 supported types are:
• Text (alias: String) — single line text input
• RichText — multi-line text with formatting
• TextNode — single/multi-line text editable on canvas
• Link — URL input (returns { href, target, preload } object)
• Image — image upload and selection
• Number — numeric input
• Boolean — true/false toggle
• Variant — dropdown with predefined options (requires options array)
• Visibility — show/hide controls
• Slot — content areas for child components
• ID — HTML element ID

• Validate component options:
• If options object is present, validate:
• applyTagSelectors is a boolean (default: false) — enables site tag selectors in Shadow DOM
• ssr is a boolean (default: true) — controls server-side rendering

• Check for SSR issues:
• Scan for browser-only API usage outside of useEffect or guarded blocks:
• window, document, localStorage, sessionStorage, navigator
• Flag dynamic/personalized content patterns (user-specific dashboards, authenticated views)
• Flag heavy/interactive UI that doesn't benefit from SSR (charts, 3D scenes, maps, animation-heavy elements)
• Flag non-deterministic output (random numbers, time-based values that differ server vs client)
• Suggest ssr: false in options if component is purely interactive or browser-dependent

• Check styling:
• Verify styles are imported in .webflow.tsx or via globals file
• Check for site class usage — site classes do NOT work in Shadow DOM
• Site variables DO work: var(--variable-name, fallback)
• Inherited CSS properties DO work: font-family: inherit
• Tag selectors work IF applyTagSelectors: true is set in component options
• Validate CSS-in-JS setup if used (see CSS-in-JS detection below)

• Check for Shadow DOM + React Context issues:
• If a component uses slots (props.Slot) AND imports/uses useContext or a Context Provider:
• Warn that parent and child components in slots cannot share React Context — each child renders in its own Shadow DOM with a separate React root
• Suggest alternatives: Nano Stores, custom events, URL parameters, or browser storage

Phase 3: Build Test

10. Run TypeScript/build check:

• Check for TypeScript compilation errors
• Verify all imports resolve correctly
• Identify any build-time issues

11. Check bundle size:

• If a build output exists, verify total bundle size is under 50MB (maximum bundle limit)
• If over limit, flag as error and suggest optimization

12. Run local bundle test (optional, suggest to user):

• Suggest running npx webflow library bundle --public-path http://localhost:4000/ to test bundling before sharing
• If bundling issues occur, suggest --debug-bundler flag to inspect the final webpack config

Phase 4: Detect Framework-Specific Setup

13. CSS-in-JS library detection:

• If project uses styled-components: verify @webflow/styled-components-utils is installed and styledComponentsShadowDomDecorator is exported from globals decorators array
• If project uses Emotion or Material UI (@emotion/styled, @emotion/react, @mui/material): verify @webflow/emotion-utils is installed and emotionShadowDomDecorator is exported from globals decorators array

14. Tailwind CSS detection:

• If project uses Tailwind CSS (tailwindcss in dependencies):
• Verify @tailwindcss/postcss is installed
• Verify postcss.config.mjs exists with @tailwindcss/postcss plugin
• Verify Tailwind CSS is imported in globals file (e.g., @import "tailwindcss" in globals.css)

15. Sass/Less preprocessor detection:

• If project uses Sass (.scss files or sass in dependencies): verify sass and sass-loader are installed, and a webpack config adds the .scss rule
• If project uses Less (.less files or less in dependencies): verify less and less-loader are installed, and a webpack config adds the .less rule
• For either: verify bundleConfig is set in webflow.json pointing to the webpack config

16. Webpack custom config validation (if bundleConfig is specified):

• Verify the file exists at the specified path
• Verify it uses CommonJS exports (module.exports)
• Warn if it attempts to override blocked properties: entry, output, target (these are silently filtered out)
• Verify module.rules uses function syntax (currentRules) => { ... }, not an array

Phase 5: Report Results

17. Generate validation report:

• List all checks performed
• Show passed/failed/warning status
• Provide fix suggestions for failures
• Indicate deployment readiness

Validation Checks

Required Checks

| Check | Severity | Description |

|-------|----------|-------------|

| webflow.json exists | Error | Required for CLI |

| Dependencies installed | Error | @webflow/webflow-cli, @webflow/data-types, @webflow/react |

| Component files exist | Error | React + definition files present |

| declareComponent called | Error | Required in .webflow.tsx with correct imports |

| Valid prop types | Error | Only the 11 supported types (Text/String, RichText, TextNode, Link, Image, Number, Boolean, Variant, Visibility, Slot, ID) |

| Build succeeds | Error | No compilation errors |

| Bundle size < 50MB | Error | Maximum bundle limit enforced by Webflow |

Warning Checks

| Check | Severity | Description |

|-------|----------|-------------|

| Props have defaults | Warning | Better designer experience |

| SSR compatibility | Warning | Browser APIs, dynamic content, heavy UI, non-deterministic output |

| Styles imported | Warning | Styles may not appear in Shadow DOM |

| Site class usage | Warning | Site classes don't work in Shadow DOM — use component-specific classes |

| Shadow DOM + Context | Warning | Slots prevent React Context sharing between parent/child |

| CSS-in-JS decorator | Warning | styled-components/Emotion need Shadow DOM decorators |

| Tailwind setup | Warning | Missing postcss config or globals import |

| Sass/Less setup | Warning | Missing loaders or webpack config |

| Webpack blocked props | Warning | entry, output, target overrides are silently ignored |

| Webpack rules format | Warning | Must use function syntax, not array |

| Component options | Warning | applyTagSelectors and ssr must be booleans |

| Glob pattern coverage | Warning | Pattern should cover all supported extensions (.js, .jsx, .mjs, .ts, .tsx) |

| bundleConfig file | Warning | File must exist if specified in webflow.json |

Info Checks

| Check | Severity | Description |

|-------|----------|-------------|

| Component count | Info | Number of components |

| Prop count | Info | Props per component |

| Bundle size | Info | Current bundle size vs 50MB limit |

| Frameworks detected | Info | CSS-in-JS, Tailwind, Sass/Less usage |

Examples

User prompt:

Check if my components are ready to deploy

Response:

🔍 Build Validation: My Component Library

Running pre-deployment checks...

---

## Project Structure

✅ webflow.json found
✅ library.name: "My Component Library"
✅ library.components: "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"
✅ globals: "./src/globals.ts"
✅ bundleConfig: not specified (using defaults)

---

## Dependencies

✅ @webflow/webflow-cli: installed
✅ @webflow/data-types: installed
✅ @webflow/react: installed
✅ react: installed
✅ typescript: installed

---

## Frameworks Detected

✅ Tailwind CSS detected
  ✅ @tailwindcss/postcss installed
  ✅ postcss.config.mjs found
  ✅ globals.css imports Tailwind

---

## Components Found (4)

### 1. Button ✅
- File: src/components/Button/Button.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Button component
- Props: label (Text), variant (Variant), disabled (Boolean)
- All props have defaults ✅
- SSR compatible ✅
- Options: applyTagSelectors: true ✅
- Styles imported ✅

### 2. Card ✅
- File: src/components/Card/Card.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Card component
- Props: title (Text), image (Image), content (RichText), link (Link)
- All props have defaults ✅
- SSR compatible ✅
- Styles imported ✅

### 3. Modal ⚠️
- File: src/components/Modal/Modal.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Modal component
- Props: title (Text), isOpen (Boolean), content (Slot)
- All props have defaults ✅
- ⚠️ SSR Issue: Uses `document.body` in render
  → Suggestion: Add `ssr: false` to options or wrap in useEffect
- Styles imported ✅

### 4. CartIcon ⚠️
- File: src/components/CartIcon/CartIcon.webflow.tsx
- Imports: ✅ declareComponent, ✅ CartIcon component
- Props: none
- ⚠️ Missing props - component has no editable properties
  → Suggestion: Consider adding props for designer customization
- ⚠️ Uses localStorage without SSR guard
  → Suggestion: Wrap in useEffect or useState initializer
- Styles imported ✅

---

## Build Test

✅ Build completed successfully
✅ No TypeScript errors
✅ No webpack errors
✅ Bundle size: 2.3MB / 50MB limit

---

## Summary

| Category | Status |
|----------|--------|
| Project Structure | ✅ Pass |
| Dependencies | ✅ Pass |
| Frameworks | ✅ Pass |
| Components | ⚠️ 2 warnings |
| Build | ✅ Pass |

---

## Ready to Deploy: ⚠️ WITH WARNINGS

You can deploy, but consider fixing these issues:

1. **Modal SSR Issue**
   Add to Modal.webflow.tsx:

options: {

ssr: false

}

2. **CartIcon localStorage Usage**
   Update CartIcon.tsx:

const [count, setCount] = useState(() => {

if (typeof window === "undefined") return 0;

return parseInt(localStorage.getItem("cartCount") || "0");

});

---

💡 To deploy: `npx webflow library share`
💡 To test locally first: `npx webflow library bundle --public-path http://localhost:4000/`

Example: Build Failure

🔍 Build Validation: My Component Library

Running pre-deployment checks...

---

## Project Structure

✅ webflow.json found
⚠️ library.components uses narrow glob: "./src/**/*.webflow.tsx"
  → Recommendation: Use "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)" to cover all supported extensions

---

## Dependencies

❌ Missing: @webflow/react
   Fix: npm install --save-dev @webflow/react

---

## Build Test

❌ Build Failed

Error in src/components/Button/Button.webflow.tsx:

Module not found: Error: Can't resolve '@webflow/react'

---

## Summary

| Category | Status |
|----------|--------|
| Dependencies | ❌ 1 error |
| Build | ❌ Failed |

---

## Ready to Deploy: ❌ NO

Fix the following before deployment:

1. **Install missing dependency**

npm install --save-dev @webflow/react

2. **Re-run validation**
   After installing, run this check again.

Example: CSS-in-JS Missing Decorator

🔍 Build Validation: My Component Library

---

## Frameworks Detected

⚠️ styled-components detected but Shadow DOM decorator not configured
  → Install: npm install @webflow/styled-components-utils
  → Add to globals.ts:

import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";

export const decorators = [styledComponentsShadowDomDecorator];

  → Reference globals in webflow.json:

{ "library": { "globals": "./src/globals.ts" } }

Without this, styled-components styles will be injected into document.head
instead of the Shadow DOM, and your components will appear unstyled.

Example: Webpack Config Issues

🔍 Build Validation: My Component Library

---

## Webpack Configuration

⚠️ webpack.webflow.js: `module.rules` uses array syntax
  → Must use function syntax: `rules: (currentRules) => { return [...]; }`
  → Array syntax will not work — the function receives current rules to extend

⚠️ webpack.webflow.js: overrides `output` property
  → The `output` property is blocked and will be silently ignored
  → Blocked properties: entry, output, target

💡 Use `--debug-bundler` flag to inspect the final merged webpack config:
   npx webflow library bundle --debug-bundler

Example: Shadow DOM Context Warning

## Components Found (2)

### 1. ThemeProvider ⚠️
- File: src/components/ThemeProvider/ThemeProvider.webflow.tsx
- Props: theme (Variant), children (Slot)
- ⚠️ Shadow DOM + React Context Issue:
  Component uses Slot prop AND React Context (ThemeContext).
  Children placed in slots render in separate Shadow DOM containers
  with their own React roots — they cannot access this Context.

  Alternatives for cross-component state:
  - Nano Stores (lightweight reactive state)
  - Custom events (window.dispatchEvent/addEventListener)
  - URL parameters (for shareable state)
  - Browser storage (localStorage/sessionStorage)

Guidelines

Validation Order

Run checks in this order for efficiency:

• Project structure (fast, catches obvious issues)
• Dependencies (medium, required for build)
• Component analysis (medium, catches code issues)
• Framework detection (medium, validates CSS-in-JS/Tailwind/Sass setup)
• Build test (slow, but required)

SSR Detection Patterns

Look for these patterns that indicate SSR issues:

// Direct browser API usage (will break SSR)
window.innerWidth
document.getElementById
localStorage.getItem
navigator.userAgent
sessionStorage.getItem

// Dynamic/personalized content (may cause hydration mismatch)
// User-specific dashboards, authenticated views

// Heavy/interactive UI (SSR adds no value, re-renders anyway)
// Charts, 3D scenes, maps, animation-driven elements

// Non-deterministic output (differs server vs client)
Math.random()
new Date().toLocaleString()

// Safe patterns (in useEffect or state initializer)
useEffect(() => {
  // Browser APIs here are fine
}, []);

useState(() => {
  if (typeof window === "undefined") return default;
  return window.innerWidth;
});

When SSR issues are found, prominently suggest the ssr: false option:

export default declareComponent(MyComponent, {
  name: "My Component",
  options: {
    ssr: false  // Disables server-side rendering
  },
});

CSS-in-JS / Tailwind / Preprocessor Detection

Check project dependencies and files to detect styling frameworks:

styled-components:

• Detect: styled-components in package.json dependencies
• Require: @webflow/styled-components-utils installed
• Require: styledComponentsShadowDomDecorator in globals decorators array

Emotion / Material UI:

• Detect: @emotion/styled, @emotion/react, or @mui/material in dependencies
• Require: @webflow/emotion-utils installed
• Require: emotionShadowDomDecorator in globals decorators array

Tailwind CSS:

• Detect: tailwindcss in dependencies
• Require: @tailwindcss/postcss installed
• Require: postcss.config.mjs with @tailwindcss/postcss plugin
• Require: Tailwind import in globals CSS (@import "tailwindcss")

Sass:

• Detect: .scss files in src or sass in dependencies
• Require: sass and sass-loader installed as dev dependencies
• Require: webpack config with .scss rule using function syntax for module.rules
• Require: bundleConfig set in webflow.json

Less:

• Detect: .less files in src or less in dependencies
• Require: less and less-loader installed as dev dependencies
• Require: webpack config with .less rule using function syntax for module.rules
• Require: bundleConfig set in webflow.json

Webpack Config Validation Rules

When bundleConfig is specified in webflow.json:

• File must exist at the specified path
• Must use CommonJS: module.exports = { ... }
• Blocked properties that are silently ignored: entry, output, target
• module.rules must be a function, not an array: rules: (currentRules) => { ... }
• ModuleFederationPlugin and MiniCssExtractPlugin are auto-deduplicated

Common Build Errors

| Error | Cause | Fix |

|-------|-------|-----|

| "Can't resolve '@webflow/react'" | Missing dependency | npm i -D @webflow/react |

| "Cannot find module './Component'" | Wrong import path | Check relative paths |

| "Type 'X' is not assignable" | TypeScript error | Fix type mismatch |

| "Unexpected token" | Syntax error | Check JSX/TS syntax |

| "Maximum call stack" | Circular import | Break dependency cycle |

| Bundle exceeds 50MB | Too many/large dependencies | Tree-shake, lazy load, replace heavy libs |

| Styles not appearing | Missing Shadow DOM decorator | Add CSS-in-JS decorator or import styles in .webflow.tsx |

Bundle Size Optimization

Quick wins for reducing bundle size:

• Use production build: Ensure minification is enabled
• Tree-shake imports: Import specific exports
• Replace heavy libraries: moment → date-fns, lodash → lodash-es
• Lazy load: Dynamic imports for heavy components
• Check for duplicates: Multiple React versions, etc.
• Monitor size: Bundle must stay under 50MB limit