webflow-code-component%3apre-deploy-check（Webflow 代码 component 3apre 部署 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

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:

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

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

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