webflow-code-component:pre-deploy-check

What this skill does

# 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 Contex