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

Run TypeScript/build check:

• Check for TypeScript compilation errors

• Verify all imports resolve correctly

• Identify any build-time issues

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

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

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

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)

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

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

• 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

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
   }
   
   

• 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:

Install missing dependency

npm install --save-dev @webflow/react

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:

- 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