Webflow Code Component:pre Deploy Check

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

1. 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

1. 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)

1. Verify component files:

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

1. 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

1. 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

1. 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

1. 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

1. 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)

1. 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

1. Run TypeScript/build check:

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

1. 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

1. 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

1. 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

1. 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)

1. 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

1. 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

1. 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 { 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

``bash npm install --save-dev @webflow/react ``

1. 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: ``typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator]; ` → Reference globals in webflow.json: `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:

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

### SSR Detection Patterns

Look for these patterns that indicate SSR issues:

```typescript
// 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:

1. File must exist at the specified path
2. Must use CommonJS: module.exports = { ... }
3. Blocked properties that are silently ignored: entry, output, target
4. module.rules must be a function, not an array: rules: (currentRules) => { ... }
5. 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:

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: webflow
• Source: webflow/webflow-skills
• License: MIT

Install and usage instructions live in the source repository linked above.