webflow-code-component:pre-deploy-check

ビルドの検証

デプロイ前にコードコンポーネントを検証して、問題を早期に発見します。

このスキルを使用するタイミング

次の場合に使用します：

• ユーザーがデプロイを控えていて、事前に問題を確認したい場合
• webflow library share を実行する前に、先回りして確認する場合
• ユーザーがコンポーネントの検証、確認、またはチェックを依頼した場合
• コンポーネントに大幅な変更を加えた後

次の場合は使用しないでください：

• デプロイにすでに失敗している場合（代わりに troubleshoot-deploy を使用してください）
• ローカル開発用にビルドするだけの場合
• コード品質を監査する場合（代わりに component-audit を使用してください）

手順

フェーズ 1：プロジェクト構成の確認

1. webflow.json が存在することを確認します：

   • 必須フィールド（library.name、library.components）を確認します
   • glob パターンがコンポーネントファイルに一致することを検証します。推奨パターンは、サポートされるすべての拡張子を対象とする "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)" です
   • globals のパスが指定されている場合は確認します。ファイルが存在し、インポート可能である必要があります
   • bundleConfig のパスが指定されている場合は確認します。ファイルが存在する必要があります

2. 依存関係を確認します：

   • @webflow/webflow-cli がインストールされていることを確認します
   • @webflow/data-types がインストールされていることを確認します
   • @webflow/react がインストールされていることを確認します
   • バージョンの互換性を確認します（インストール済みのバージョンを確認し、特定のバージョンを想定しないでください）

3. コンポーネントファイルを確認します：

   • glob パターンに一致するすべての .webflow.tsx / .webflow.ts ファイルを探します
   • 対応する React コンポーネントが存在することを確認します
   • 孤立した定義ファイルがないか確認します

4. .webflow.tsx ファイル内のインポートを検証します：

   • @webflow/react から declareComponent をインポートする必要があります
   • プロパティが定義されている場合は、@webflow/data-types から props をインポートする必要があります
   • 宣言対象の実際の React コンポーネントをインポートする必要があります

フェーズ 2：コンポーネントの分析

5. 各コンポーネントについて、以下を確認します。

   • declareComponent がコンポーネントと設定オブジェクトを指定して呼び出されている
   • 設定で name が指定されている
   • すべてのプロパティに name プロパティがあり、該当する場合は適切な defaultValue が設定されている
   • プロパティの型が有効である — サポートされている 11 種類の型は以下のとおりです。
     • Text（別名：String）— 1 行のテキスト入力
     • RichText — 書式設定が可能な複数行テキスト
     • TextNode — キャンバス上で編集可能な 1 行または複数行のテキスト
     • Link — URL 入力（{ href, target, preload } オブジェクトを返します）
     • Image — 画像のアップロードと選択
     • Number — 数値入力
     • Boolean — true/false の切り替え
     • Variant — 定義済みの選択肢を含むドロップダウン（options 配列が必要です）
     • Visibility — 表示／非表示の制御
     • Slot — 子コンポーネント用のコンテンツ領域
     • ID — HTML 要素の ID

6. コンポーネントのオプションを検証します。

   • options オブジェクトがある場合は、以下を検証します。
     • applyTagSelectors がブール値である（デフォルト：false）— Shadow DOM でサイトのタグセレクターを有効にします
     • ssr がブール値である（デフォルト：true）— サーバーサイドレンダリングを制御します

7. SSR の問題を確認します。

   • useEffect の外部またはガードされたブロック外での、ブラウザー専用 API の使用を検索します。
     • window、document、localStorage、sessionStorage、navigator
   • 動的なコンテンツやパーソナライズされたコンテンツのパターン（ユーザー固有のダッシュボード、認証済みビュー）にフラグを立てます
   • SSR のメリットがない、重い UI やインタラクティブな UI（チャート、3D シーン、マップ、アニメーションを多用する要素）にフラグを立てます
   • 非決定的な出力（サーバー側とクライアント側で異なる乱数や時間依存の値）にフラグを立てます
   • コンポーネントが純粋にインタラクティブ、またはブラウザーに依存する場合は、オプションに ssr: false を設定するよう提案します

8. スタイルを確認します。

   • スタイルが .webflow.tsx またはグローバルファイルからインポートされていることを確認します
   • サイトクラスの使用を確認します — サイトクラスは Shadow DOM では機能しません
   • サイト変数は機能します：var(--variable-name, fallback)
   • 継承される CSS プロパティは機能します：font-family: inherit
   • コンポーネントのオプションで applyTagSelectors: true が設定されている場合、タグセレクターは機能します
   • CSS-in-JS が使用されている場合は、設定を検証します（下記の CSS-in-JS の検出を参照）

9. Shadow DOM と React Context の問題を確認します。

   • コンポーネントがスロット（props.Slot）を使用し、かつ useContext または Context Provider をインポートまたは使用している場合：
     • スロット内の親コンポーネントと子コンポーネントは React Context を共有できないことを警告します — 各子コンポーネントは別々の React ルートを持つ個別の Shadow DOM でレンダリングされます
     • 代替手段として、Nano Stores、カスタムイベント、URL パラメーター、ブラウザーストレージを提案します

フェーズ 3：ビルドテスト

10. TypeScript／ビルドチェックを実行します。

    • TypeScript のコンパイルエラーを確認します
    • すべてのインポートが正しく解決されることを確認します
    • ビルド時の問題を特定します

11. バンドルサイズを確認します。

    • ビルド出力がある場合は、バンドルの合計サイズが 50MB（バンドルの最大サイズ制限）未満であることを確認します
    • 上限を超えている場合はエラーとしてフラグを立て、最適化を提案します

12. ローカルでのバンドルテストを実行します（任意。ユーザーに提案します）。

    • 共有する前にバンドルをテストするため、npx webflow library bundle --public-path http://localhost:4000/ の実行を提案します
    • バンドルで問題が発生した場合は、最終的な webpack 設定を確認するため、--debug-bundler フラグの使用を提案します

フェーズ 4：フレームワーク固有のセットアップを検出

13. CSS-in-JS ライブラリの検出：

    • プロジェクトで styled-components を使用している場合：@webflow/styled-components-utils がインストールされていること、および styledComponentsShadowDomDecorator が globals の decorators 配列からエクスポートされていることを確認します
    • プロジェクトで Emotion または Material UI（@emotion/styled、@emotion/react、@mui/material）を使用している場合：@webflow/emotion-utils がインストールされていること、および emotionShadowDomDecorator が globals の decorators 配列からエクスポートされていることを確認します

14. Tailwind CSS の検出：

    • プロジェクトで Tailwind CSS（依存関係に tailwindcss がある場合）を使用している場合：
      • @tailwindcss/postcss がインストールされていることを確認します
      • postcss.config.mjs が存在し、@tailwindcss/postcss プラグインが設定されていることを確認します
      • globals ファイルで Tailwind CSS がインポートされていることを確認します（例：globals.css の @import "tailwindcss"）

15. Sass/Less プリプロセッサの検出：

    • プロジェクトで Sass（.scss ファイルがある場合、または依存関係に sass がある場合）を使用している場合：sass と sass-loader がインストールされていること、および webpack 設定で .scss ルールが追加されていることを確認します
    • プロジェクトで Less（.less ファイルがある場合、または依存関係に less がある場合）を使用している場合：less と less-loader がインストールされていること、および webpack 設定で .less ルールが追加されていることを確認します
    • いずれの場合も、bundleConfig が webflow.json に設定され、webpack 設定を指していることを確認します

16. Webpack カスタム設定の検証（bundleConfig が指定されている場合）：

    • 指定されたパスにファイルが存在することを確認します
    • CommonJS エクスポート（module.exports）を使用していることを確認します
    • ブロック対象のプロパティ（entry、output、target）を上書きしようとしている場合は警告します（これらは暗黙的に除外されます）
    • module.rules が配列ではなく、関数構文 (currentRules) => { ... } を使用していることを確認します

フェーズ 5：結果をレポート

17. 検証レポートを生成：
    • 実行したすべてのチェックを一覧表示します
    • 合格／不合格／警告のステータスを示します
    • 不合格の場合は修正案を提示します
    • デプロイの準備状況を示します

検証チェック

必須チェック

チェック	重要度	説明
webflow.json の存在	エラー	CLI に必須
依存関係のインストール	エラー	@webflow/webflow-cli、@webflow/data-types、@webflow/react
コンポーネントファイルの存在	エラー	React ファイルと定義ファイルが存在すること
declareComponent の呼び出し	エラー	正しいインポートを含む .webflow.tsx で必須
有効なプロパティ型	エラー	サポートされている 11 種類の型のみ（Text/String、RichText、TextNode、Link、Image、Number、Boolean、Variant、Visibility、Slot、ID）
ビルドの成功	エラー	コンパイルエラーがないこと
バンドルサイズ < 50MB	エラー	Webflow によって最大バンドルサイズが適用されます

警告チェック

チェック	重要度	説明
プロパティにデフォルト値がある	警告	デザイナーの操作性が向上します
SSR 互換性	警告	ブラウザー API、動的コンテンツ、重い UI、非決定的な出力
スタイルのインポート	警告	Shadow DOM にスタイルが表示されない場合があります
サイトクラスの使用	警告	サイトクラスは Shadow DOM では機能しません。コンポーネント固有のクラスを使用してください
Shadow DOM と Context	警告	スロットにより、親子間で React Context を共有できません
CSS-in-JS デコレーター	警告	styled-components／Emotion には Shadow DOM デコレーターが必要です
Tailwind のセットアップ	警告	postcss 設定または globals のインポートがありません
Sass/Less のセットアップ	警告	ローダーまたは webpack 設定がありません
Webpack のブロック対象プロパティ	警告	entry、output、target の上書きは暗黙的に無視されます
Webpack ルールの形式	警告	配列ではなく関数構文を使用する必要があります
コンポーネントオプション	警告	applyTagSelectors と ssr はブール値である必要があります
Glob パターンの網羅性	警告	パターンですべてのサポート対象拡張子（.js、.jsx、.mjs、.ts、.tsx）をカバーする必要があります
bundleConfig ファイル	警告	webflow.json で指定する場合、ファイルが存在する必要があります

情報チェック

チェック項目	重要度	説明
コンポーネント数	情報	コンポーネントの数
Props 数	情報	コンポーネントごとの Props 数
バンドルサイズ	情報	現在のバンドルサイズと 50MB の上限
検出されたフレームワーク	情報	CSS-in-JS、Tailwind、Sass/Less の使用状況

例

ユーザーのプロンプト：

Check if my components are ready to deploy

応答：

🔍 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 の使用 CartIcon.tsx を更新します：

   const [count, setCount] = useState(() => {
     if (typeof window === "undefined") return 0;
     return parseInt(localStorage.getItem("cartCount") || "0");
   });
   

---

💡 デプロイするには：npx webflow library share 💡 まずローカルでテストするには：npx webflow library bundle --public-path http://localhost:4000/

---

**Example: Build Failure**

🔍 ビルド検証：My Component Library

デプロイ前チェックを実行しています...

---

プロジェクト構成

✅ webflow.json が見つかりました ⚠️ library.components の glob が限定的です："./src//*.webflow.tsx" → 推奨："./src//*.webflow.@(js|jsx|mjs|ts|tsx)" を使用して、サポートされているすべての拡張子を対象にします

---

依存関係

❌ 不足：@webflow/react 修正方法：npm install --save-dev @webflow/react

---

ビルドテスト

❌ ビルドに失敗しました

src/components/Button/Button.webflow.tsx のエラー：

Module not found: Error: Can't resolve '@webflow/react'

---

概要

カテゴリー	ステータス
依存関係	❌ 1 件のエラー
ビルド	❌ 失敗

---

デプロイ準備完了：❌ いいえ

デプロイする前に、以下を修正してください：

1. 不足している依存関係をインストール

   npm install --save-dev @webflow/react
   

2. 検証を再実行 インストール後、このチェックをもう一度実行してください。

---

**Example: CSS-in-JS Missing Decorator**

🔍 ビルド検証：My Component Library

---

検出されたフレームワーク

⚠️ styled-components が検出されましたが、Shadow DOM デコレーターが設定されていません → インストール：npm install @webflow/styled-components-utils → globals.ts に追加： typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator]; → webflow.json で globals を参照： json { "library": { "globals": "./src/globals.ts" } }

これを設定しない場合、styled-components のスタイルは Shadow DOM ではなく document.head に挿入され、コンポーネントのスタイルが適用されません。

---

**Example: Webpack Config Issues**

🔍 ビルド検証：My Component Library

---

Webpack の設定

⚠️ webpack.webflow.js：「module.rules」で配列構文が使用されています → 関数構文を使用する必要があります：rules: (currentRules) => { return [...]; } → 配列構文は機能しません — 関数には拡張対象の現在のルールが渡されます

⚠️ webpack.webflow.js：「output」プロパティが上書きされています → 「output」プロパティはブロックされており、黙って無視されます → ブロックされるプロパティ：entry、output、target

💡 最終的にマージされた webpack 設定を確認するには、--debug-bundler フラグを使用します： npx webflow library bundle --debug-bundler

---

**Example: Shadow DOM Context Warning**

見つかったコンポーネント（2）

1. ThemeProvider ⚠️

• ファイル：src/components/ThemeProvider/ThemeProvider.webflow.tsx

• Props：theme（Variant）、children（Slot）

• ⚠️ Shadow DOM と React Context の問題： このコンポーネントは Slot prop と React Context（ThemeContext）を使用しています。 スロットに配置された子要素は、それぞれ独自の React ルートを持つ個別の Shadow DOM コンテナに レンダリングされるため、この Context にアクセスできません。

  コンポーネント間で状態を共有する方法：

  • Nano Stores（軽量なリアクティブ状態管理）
  • カスタムイベント（window.dispatchEvent/addEventListener）
  • URL パラメーター（共有可能な状態用）
  • ブラウザーのストレージ（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;
});

SSR の問題が見つかった場合は、ssr: false オプションを目立つように提案します：

export default declareComponent(MyComponent, {
  name: "My Component",
  options: {
    ssr: false  // Disables server-side rendering
  },
});

CSS-in-JS／Tailwind／プリプロセッサの検出

プロジェクトの依存関係とファイルを確認し、スタイル設定のフレームワークを検出します。

styled-components:

• 検出：package.json の依存関係に styled-components がある
• 必須：@webflow/styled-components-utils がインストールされている
• 必須：globals の decorators 配列に styledComponentsShadowDomDecorator がある

Emotion／Material UI:

• 検出：依存関係に @emotion/styled、@emotion/react、または @mui/material がある
• 必須：@webflow/emotion-utils がインストールされている
• 必須：globals の decorators 配列に emotionShadowDomDecorator がある

Tailwind CSS:

• 検出：依存関係に tailwindcss がある
• 必須：@tailwindcss/postcss がインストールされている
• 必須：@tailwindcss/postcss プラグインを含む postcss.config.mjs がある
• 必須：globals CSS に Tailwind のインポートがある（@import "tailwindcss"）

Sass:

• 検出：src に .scss ファイルがある、または依存関係に sass がある
• 必須：sass と sass-loader が開発依存関係としてインストールされている
• 必須：module.rules に関数構文を使用する .scss ルールを含む webpack 設定がある
• 必須：webflow.json に bundleConfig が設定されている

Less:

• 検出：src に .less ファイルがある、または依存関係に less がある
• 必須：less と less-loader が開発依存関係としてインストールされている
• 必須：module.rules に関数構文を使用する .less ルールを含む webpack 設定がある
• 必須：webflow.json に bundleConfig が設定されている

Webpack 設定の検証ルール

webflow.json で bundleConfig が指定されている場合：

1. 指定されたパスにファイルが存在する必要があります
2. CommonJS を使用する必要があります：module.exports = { ... }
3. 無視される禁止プロパティ：entry、output、target
4. module.rules は配列ではなく関数である必要があります：rules: (currentRules) => { ... }
5. ModuleFederationPlugin と MiniCssExtractPlugin は自動的に重複排除されます

よくあるビルドエラー

エラー	原因	修正方法
"'@webflow/react' を解決できません"	依存関係が不足しています	npm i -D @webflow/react
"モジュール './Component' が見つかりません"	インポートパスが間違っています	相対パスを確認します
"型 'X' を割り当てることができません"	TypeScript のエラーです	型の不一致を修正します
"予期しないトークン"	構文エラーです	JSX／TS の構文を確認します
"コールスタックの上限に達しました"	循環インポート	依存関係の循環を解消します
バンドルが 50MB を超えています	依存関係が多すぎる、または大きすぎます	ツリーシェイク、遅延読み込み、重いライブラリの置き換えを行います
スタイルが表示されません	Shadow DOM デコレーターが不足しています	CSS-in-JS デコレーターを追加するか、.webflow.tsx でスタイルをインポートします

バンドルサイズの最適化

バンドルサイズを削減するための簡単な方法：

1. 本番ビルドを使用する：圧縮が有効になっていることを確認します
2. インポートをツリーシェイクする：特定のエクスポートをインポートします
3. 重いライブラリを置き換える：moment → date-fns、lodash → lodash-es
4. 遅延読み込みを行う：重いコンポーネントには動的インポートを使用します
5. 重複を確認する：複数の React バージョンなど
6. サイズを監視する：バンドルを 50MB の上限未満に保つ必要があります