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

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
2. 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
3. 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
4. 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)
5. 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
2. 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
3. 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
2. 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)
3. 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
4. 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

Warning Checks

Info Checks

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
   }

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

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:

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

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