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

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

3. Verify component files:

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

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

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

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

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

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

9. 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:
   ```typescript
   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: 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