@wix/agent-skills 1.6.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/README.md +2 -2
  2. package/package.json +1 -1
  3. package/skills/wix-app/SKILL.md +49 -42
  4. package/skills/wix-app/references/BACKEND_EVENT.md +10 -65
  5. package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md +101 -406
  6. package/skills/wix-app/references/DASHBOARD_MENU_PLUGIN.md +14 -111
  7. package/skills/wix-app/references/DASHBOARD_MODAL.md +56 -205
  8. package/skills/wix-app/references/DASHBOARD_PAGE.md +19 -98
  9. package/skills/wix-app/references/DASHBOARD_PLUGIN.md +6 -108
  10. package/skills/wix-app/references/DATA_COLLECTION.md +113 -198
  11. package/skills/wix-app/references/EMBEDDED_SCRIPT.md +41 -268
  12. package/skills/wix-app/references/EXTENSION_REGISTRATION.md +27 -76
  13. package/skills/wix-app/references/SERVICE_PLUGIN.md +35 -188
  14. package/skills/wix-app/references/SITE_PLUGIN.md +8 -92
  15. package/skills/wix-app/references/backend-event/COMMON-EVENTS.md +0 -44
  16. package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md +19 -330
  17. package/skills/wix-app/references/dashboard-menu-plugin/bookings-slots.md +0 -12
  18. package/skills/wix-app/references/dashboard-menu-plugin/ecommerce-slots.md +7 -0
  19. package/skills/wix-app/references/dashboard-menu-plugin/restaurants-slots.md +0 -12
  20. package/skills/wix-app/references/dashboard-plugin/SLOTS.md +3 -15
  21. package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md +2 -18
  22. package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md +2 -42
  23. package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md +1 -11
  24. package/skills/wix-app/references/service-plugin/GIFT-CARDS.md +1 -11
  25. package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md +2 -40
  26. package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md +2 -19
  27. package/skills/wix-app/references/service-plugin/VALIDATIONS.md +2 -18
  28. package/skills/wix-app/references/site-plugin/SLOTS.md +17 -68
  29. package/skills/wix-headless/SKILL.md +111 -389
  30. package/skills/wix-headless/references/BUILD.md +307 -0
  31. package/skills/wix-headless/references/DESIGN_SYSTEM.md +115 -0
  32. package/skills/wix-headless/references/DISCOVERY.md +237 -112
  33. package/skills/wix-headless/references/PLAN.md +82 -0
  34. package/skills/wix-headless/references/SEED.md +205 -0
  35. package/skills/wix-headless/references/SETUP.md +140 -134
  36. package/skills/wix-headless/references/astro/COMPOSE.md +142 -0
  37. package/skills/wix-headless/references/{blog → astro/blog}/BLOG_PAGES.md +1 -1
  38. package/skills/wix-headless/references/{blog → astro/blog}/BLOG_SETUP.md +2 -2
  39. package/skills/wix-headless/references/astro/cms/CMS_FOUNDATIONS.md +214 -0
  40. package/skills/wix-headless/references/{cms → astro/cms}/FAQ_KNOWLEDGE_BASE.md +6 -4
  41. package/skills/wix-headless/references/{cms → astro/cms}/PORTFOLIO.md +5 -5
  42. package/skills/wix-headless/references/{cms → astro/cms}/RESOURCE_LIBRARY.md +5 -5
  43. package/skills/wix-headless/references/{cms → astro/cms}/TEAM_DIRECTORY.md +5 -5
  44. package/skills/wix-headless/references/astro/designer/INSTRUCTIONS.md +331 -0
  45. package/skills/wix-headless/references/{ecom → astro/ecom}/CART_PAGES.md +1 -1
  46. package/skills/wix-headless/references/{ecom → astro/ecom}/CART_WIRING.md +1 -1
  47. package/skills/wix-headless/references/{ecom → astro/ecom}/COMPONENTS_CSS.md +3 -3
  48. package/skills/wix-headless/references/{forms → astro/forms}/CONTACT_FORM.md +13 -13
  49. package/skills/wix-headless/references/{gift-cards → astro/gift-cards}/COMPONENTS.md +1 -1
  50. package/skills/wix-headless/references/{gift-cards → astro/gift-cards}/PAGES.md +1 -1
  51. package/skills/wix-headless/references/{stores → astro/stores}/BACK_IN_STOCK.md +1 -1
  52. package/skills/wix-headless/references/{stores → astro/stores}/CATEGORY_PAGES.md +12 -13
  53. package/skills/wix-headless/references/{stores → astro/stores}/COMPONENTS_CSS.md +4 -4
  54. package/skills/wix-headless/references/{stores → astro/stores}/HOME_AND_NAV.md +11 -9
  55. package/skills/wix-headless/references/{stores → astro/stores}/PRODUCT_PAGES.md +5 -3
  56. package/skills/wix-headless/references/{stores → astro/stores}/SHARED_WIRING.md +3 -3
  57. package/skills/wix-headless/references/astro/templates/Footer.astro +27 -0
  58. package/skills/wix-headless/references/astro/templates/Layout.astro +132 -0
  59. package/skills/wix-headless/references/astro/templates/Navigation.astro +38 -0
  60. package/skills/wix-headless/references/astro/templates/astro.config.mjs +41 -0
  61. package/skills/wix-headless/references/astro/templates/ecom/components-ecom.css +302 -0
  62. package/skills/wix-headless/references/astro/templates/global.css +286 -0
  63. package/skills/wix-headless/references/astro/templates/index.astro +56 -0
  64. package/skills/wix-headless/{templates → references/astro/templates}/stores/back-in-stock.ts +1 -1
  65. package/skills/wix-headless/{templates → references/astro/templates}/stores/components-stores.css +138 -33
  66. package/skills/wix-headless/references/blog/BLOG_CONTENT.md +10 -11
  67. package/skills/wix-headless/references/blog/INSTRUCTIONS.md +5 -5
  68. package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md +31 -230
  69. package/skills/wix-headless/references/cms/INSTRUCTIONS.md +13 -8
  70. package/skills/wix-headless/references/custom/INSTRUCTIONS.md +38 -0
  71. package/skills/wix-headless/references/ecom/INSTRUCTIONS.md +10 -10
  72. package/skills/wix-headless/references/forms/INSTRUCTIONS.md +5 -5
  73. package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md +11 -11
  74. package/skills/wix-headless/references/images/INSTRUCTIONS.md +47 -50
  75. package/skills/wix-headless/references/seed-recipes.md +49 -0
  76. package/skills/wix-headless/references/shared/AUTHENTICATION.md +110 -0
  77. package/skills/wix-headless/references/shared/BUILD_NOISE.md +2 -2
  78. package/skills/wix-headless/references/shared/DOCS_SEARCH.md +41 -0
  79. package/skills/wix-headless/references/shared/IMAGE_GENERATION.md +17 -17
  80. package/skills/wix-headless/references/shared/IMPLEMENTER.md +20 -29
  81. package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md +1 -1
  82. package/skills/wix-headless/references/shared/RETURN_CONTRACT.md +25 -16
  83. package/skills/wix-headless/references/shared/STYLING.md +47 -10
  84. package/skills/wix-headless/references/stores/INSTRUCTIONS.md +25 -25
  85. package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md +17 -17
  86. package/skills/wix-headless/references/verticals/_schema.json +31 -117
  87. package/skills/wix-headless/references/verticals/_schema.md +60 -150
  88. package/skills/wix-headless/references/verticals/blog.md +5 -99
  89. package/skills/wix-headless/references/verticals/cms.md +9 -100
  90. package/skills/wix-headless/references/verticals/ecom.md +5 -76
  91. package/skills/wix-headless/references/verticals/forms.md +5 -85
  92. package/skills/wix-headless/references/verticals/gift-cards.md +6 -103
  93. package/skills/wix-headless/references/verticals/stores.md +10 -144
  94. package/skills/wix-headless/scripts/check-manifest.mjs +5 -5
  95. package/skills/wix-headless/scripts/emit-design-tokens.mjs +29 -23
  96. package/skills/wix-headless/scripts/init-site-json.mjs +59 -21
  97. package/skills/wix-headless/scripts/patch-decorative-slots.mjs +67 -43
  98. package/skills/wix-headless/scripts/plan-entity-image-waves.mjs +3 -3
  99. package/skills/wix-headless/scripts/preview.sh +3 -3
  100. package/skills/wix-headless/scripts/release.sh +4 -4
  101. package/skills/wix-headless/scripts/scaffold.sh +75 -20
  102. package/skills/wix-headless/scripts/seed-utilities.sh +50 -12
  103. package/skills/wix-manage/SKILL.md +4 -8
  104. package/skills/wix-manage/references/blog/how-to-create-blog-posts.md +2 -0
  105. package/skills/wix-manage/references/cms/cms-data-items-crud.md +4 -0
  106. package/skills/wix-manage/references/cms/cms-references-and-relationships.md +2 -0
  107. package/skills/wix-manage/references/cms/cms-schema-management.md +4 -0
  108. package/skills/wix-manage/references/ecommerce/api-shipping.md +443 -0
  109. package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +5 -6
  110. package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +4 -5
  111. package/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +4 -5
  112. package/skills/wix-manage/references/ecommerce/goal-increase-aov.md +1 -1
  113. package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +1 -2
  114. package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +2 -2
  115. package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +4 -5
  116. package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +7 -7
  117. package/skills/wix-manage/references/ecommerce/setup-discount-rules.md +209 -72
  118. package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +9 -10
  119. package/skills/wix-manage/references/ecommerce/skill-graph.md +4 -4
  120. package/skills/wix-manage/references/forms/create-form.md +2 -0
  121. package/skills/wix-manage/references/stores/bulk-create-products-with-options.md +2 -0
  122. package/skills/wix-manage/references/stores/create-product-from-image.md +91 -38
  123. package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md +2 -0
  124. package/skills/wix-app/references/custom-element-widget/default-thumbnail.png +0 -0
  125. package/skills/wix-app/references/data-collection/extension-template.ts +0 -107
  126. package/skills/wix-headless/references/ORCHESTRATION.md +0 -269
  127. package/skills/wix-headless/references/commands/install-app.md +0 -42
  128. package/skills/wix-headless/references/commands/mcp-bootstrap.md +0 -28
  129. package/skills/wix-headless/references/designer/INSTRUCTIONS.md +0 -828
  130. package/skills/wix-headless/references/shared/MCP_PREFIX.md +0 -105
  131. package/skills/wix-headless/scripts/copy-utility-templates.mjs +0 -153
  132. package/skills/wix-headless/templates/ecom/components-ecom.css +0 -215
  133. package/skills/wix-manage/references/events/list-events.md +0 -203
  134. /package/skills/wix-headless/{templates → references/astro/templates}/ecom/CartBadge.tsx +0 -0
  135. /package/skills/wix-headless/{templates → references/astro/templates}/ecom/CartView.tsx +0 -0
  136. /package/skills/wix-headless/{templates → references/astro/templates}/ecom/cart.astro +0 -0
  137. /package/skills/wix-headless/{templates → references/astro/templates}/ecom/discounts.ts +0 -0
  138. /package/skills/wix-headless/{templates → references/astro/templates}/ecom/thank-you.astro +0 -0
  139. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/GiftCardPurchase.tsx +0 -0
  140. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/_home-teaser-snippet.astro +0 -0
  141. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/_nav-snippet.astro +0 -0
  142. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/components-gift-cards.css +0 -0
  143. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/gift-cards.astro +0 -0
  144. /package/skills/wix-headless/{templates → references/astro/templates}/gift-cards/gift-cards.ts +0 -0
  145. /package/skills/wix-headless/{templates → references/astro/templates}/stores/AddToCartButton.tsx +0 -0
  146. /package/skills/wix-headless/{templates → references/astro/templates}/stores/BackInStockForm.tsx +0 -0
  147. /package/skills/wix-headless/{templates → references/astro/templates}/stores/CategoryRail.astro +0 -0
  148. /package/skills/wix-headless/{templates → references/astro/templates}/stores/ProductCard.astro +0 -0
  149. /package/skills/wix-headless/{templates → references/astro/templates}/stores/ProductPurchase.tsx +0 -0
  150. /package/skills/wix-headless/{templates → references/astro/templates}/stores/SeoTags.astro +0 -0
  151. /package/skills/wix-headless/{templates → references/astro/templates}/stores/categories.ts +0 -0
  152. /package/skills/wix-headless/{templates → references/astro/templates}/stores/category/[slug].astro +0 -0
  153. /package/skills/wix-headless/{templates → references/astro/templates}/stores/products/[slug].astro +0 -0
  154. /package/skills/wix-headless/{templates → references/astro/templates}/stores/products/index.astro +0 -0
package/skills/wix-app/references/EMBEDDED_SCRIPT.md CHANGED
@@ -1,19 +1,26 @@
1
1
 
2
2
  # Wix Embedded Script Builder
3
3
 
4
- Creates embedded script extensions for Wix CLI applications. Embedded scripts are HTML code fragments that get injected into the DOM of Wix sites, enabling integration with third-party services, analytics tracking, advertising, and custom JavaScript functionality.
4
+ Embedded scripts are HTML code fragments injected into the DOM of Wix sites — for integration with third-party services, analytics tracking, advertising, and custom JavaScript functionality.
5
5
 
6
- ## Quick Start Checklist
6
+ ## Scaffold
7
7
 
8
- Follow these steps in order when creating an embedded script:
8
+ Use `wix generate --params` with all 5 required fields:
9
9
 
10
- 1. [ ] Create script folder: `src/extensions/site/embedded-scripts/<script-name>/`
11
- 2. [ ] Create `embedded.html` with config element, styles, and script logic
12
- 3. [ ] Create `extensions.ts` with `extensions.embeddedScript()` and unique UUID
13
- 4. [ ] Create dashboard config page: `src/extensions/dashboard/pages/<script-name>-settings/`
14
- 5. [ ] Implement config page with `embeddedScripts` API from `@wix/app-management`
15
- 6. [ ] Update `src/extensions.ts` to import and use both extensions
16
- 7. [ ] Add the `SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS` permission in the Wix Dev Center (see [Enable Embedded Script Permission](#enable-embedded-script-permission))
10
+ ```bash
11
+ wix generate --params '{"extensionType":"EMBEDDED_SCRIPT","name":"<name>","folder":"<folder>","scriptType":"<scriptType>","placement":"<placement>"}'
12
+ ```
13
+
14
+ | Field | Constraint |
15
+ | --- | --- |
16
+ | `name` | Display name, any string. |
17
+ | `folder` | Lowercase alphanumeric, hyphens, slashes (for sub-paths). |
18
+ | `scriptType` | One of: `ESSENTIAL`, `FUNCTIONAL`, `ANALYTICS`, `ADVERTISING`. |
19
+ | `placement` | One of: `HEAD`, `BODY_START`, `BODY_END`. |
20
+
21
+ The CLI generates the folder, `<folder>.html` (the actual script HTML), the builder file, the UUID, and the `src/extensions.ts` registration. (It may also drop a sample `<other>.ts` module to demonstrate `<script type="module" src="./xxx.ts">` imports — feel free to delete or repurpose it.)
22
+
23
+ After implementation, the app developer must enable `SCOPE.DC-APPS.MANAGE-EMBEDDED-SCRIPTS` in the Wix Dev Center — see [Enable Embedded Script Permission](#enable-embedded-script-permission).
17
24
 
18
25
  ## Script Types
19
26
 
@@ -30,42 +37,15 @@ Embedded scripts must declare a type for consent management:
30
37
 
31
38
  ## Placement Options
32
39
 
33
- | Placement | Description | Best For |
34
- | ------------ | ---------------------------------------- | --------------------------------- |
35
- | `HEAD` | Between `<head>` and `</head>` tags | Analytics, early initialization |
36
- | `BODY_START` | Immediately after opening `<body>` tag | Critical functionality, noscript |
37
- | `BODY_END` | Immediately before closing `</body>` tag | Non-blocking scripts, performance |
38
-
39
- **Selection guidelines:**
40
-
41
- - Analytics/tracking → `HEAD` (initialize early)
42
- - Advertising pixels → `BODY_END` (non-blocking)
43
- - Critical functionality → `HEAD` or `BODY_START`
44
- - Non-critical features → `BODY_END` (better performance)
40
+ | Placement | Where in HTML | Best for |
41
+ | ------------ | ---------------------------------------- | ----------------------------------------------------------------------- |
42
+ | `HEAD` | Between `<head>` and `</head>` tags | Analytics, tracking, early initialization |
43
+ | `BODY_START` | Immediately after opening `<body>` tag | Critical functionality, `<noscript>` fallback |
44
+ | `BODY_END` | Immediately before closing `</body>` tag | Advertising pixels, non-critical features (non-blocking, better perf) |
45
45
 
46
46
  ## Dynamic Parameters and Dashboard Configuration
47
47
 
48
- **Every embedded script requires a companion dashboard page** to configure its parameters. Site owners use the dashboard page UI to set values, which are then passed to the embedded script as template variables.
49
-
50
- ### Architecture Flow
51
-
52
- ```
53
- Dashboard Page (React UI)
54
- │
55
- │ embeddedScripts.embedScript({ parameters: {...} })
56
- ▼
57
- Wix App Management API
58
- │
59
- │ Stores parameters, injects as template variables
60
- ▼
61
- Embedded Script (HTML)
62
- │
63
- │ {{parameterKey}} → actual value
64
- ▼
65
- Site DOM
66
- ```
67
-
68
- **Related skill:** Use DASHBOARD_PAGE.md to create the configuration UI for your embedded script.
48
+ **Every embedded script requires a companion dashboard page** to configure its parameters. Scaffold a separate `DASHBOARD_PAGE` extension and use `embeddedScripts` from `@wix/app-management` to load/save parameters (see [DASHBOARD_PAGE.md](DASHBOARD_PAGE.md)). Wix stores the parameters and injects them as `{{templateVars}}` into the HTML at render time.
69
49
 
70
50
  ### Parameter Types
71
51
 
@@ -83,126 +63,29 @@ Site DOM
83
63
 
84
64
  ### Template Variable Syntax
85
65
 
86
- Embedded scripts support parameterization using template variable syntax `{{variableName}}`. These parameters are configured through the dashboard and passed as template variables that should be used in your HTML/JavaScript code.
87
-
88
- **Usage Instructions:**
89
-
90
- 1. **Template Variable Syntax:**
91
- - Use `{{parameterKey}}` syntax to insert parameter values into your HTML
92
- - Template variables work in HTML attributes
93
- - They will be replaced with actual values when the script is injected
94
-
95
- 2. **HTML Attributes (REQUIRED):**
96
- - Store ALL parameter values in data attributes on a configuration element
97
- - Template variables can ONLY be used here, not directly in JavaScript
98
- - Example: `<div id="config" data-headline="{{headline}}" data-text="{{text}}"></div>`
99
-
100
- 3. **JavaScript Access:**
101
- - JavaScript must read parameter values from the data attributes
102
- - Use `getAttribute()` or the `dataset` property
103
- - Examples:
104
- ```javascript
105
- const config = document.getElementById("config");
106
- const headline = config?.getAttribute("data-headline");
107
- // OR using dataset:
108
- const { headline, text } = config.dataset;
109
- ```
110
-
111
- 4. **Type Safety:**
112
- - Be aware of parameter types when using them in JavaScript
113
- - NUMBER types: convert with `Number()` or `parseInt()`
114
- - BOOLEAN types: compare with `'true'` or `'false'` strings
115
- - DATE/DATETIME: parse with `new Date()`
116
-
117
- 5. **Required vs Optional:**
118
- - Required parameters will always have values
119
- - Optional parameters may be empty - handle gracefully
120
- - Provide fallback values for optional parameters
121
-
122
- 6. **Relevant Parameter Usage:**
123
- - Only use dynamic parameters that are relevant to your current use case
124
- - Ignore parameters that don't apply to the functionality you're implementing
125
- - Each parameter you use should serve a clear purpose in the script's functionality
126
- - It's perfectly fine to not use all parameters if they're not applicable
127
-
128
- **Example Patterns:**
129
-
130
- **Pattern 1 - Configuration in Data Attributes:**
66
+ `{{parameterKey}}` placeholders are substituted at injection time, **but only inside HTML attribute values** — not inside `<script>` bodies. The required pattern is: render every parameter as a data attribute on a config element, then read it from `dataset` in JS.
131
67
 
132
68
  ```html
133
- <div
134
- id="script-config"
69
+ <div id="config"
135
70
  data-api-key="{{apiKey}}"
136
71
  data-enabled="{{enabled}}"
137
- data-color="{{primaryColor}}"
138
- ></div>
139
- <script>
140
- const config = document.getElementById("script-config");
141
- const apiKey = config.getAttribute("data-api-key");
142
- const enabled = config.getAttribute("data-enabled") === "true";
143
- const color = config.getAttribute("data-color");
144
-
145
- if (enabled && apiKey) {
146
- // Initialize with configuration
147
- }
148
- </script>
149
- ```
150
-
151
- **Pattern 2 - Using dataset Property:**
152
-
153
- ```html
154
- <div
155
- id="script-config"
156
72
  data-headline="{{headline}}"
157
- data-message="{{message}}"
158
- data-image-url="{{imageUrl}}"
159
- ></div>
160
- <script>
161
- const config = document.getElementById("script-config");
162
- const { headline, message, imageUrl } = config.dataset;
163
-
164
- // Use the variables in your script logic
165
- if (headline) {
166
- document.querySelector("#headline").textContent = headline;
167
- }
168
- </script>
169
- ```
170
-
171
- **Pattern 3 - Conditional Logic:**
172
-
173
- ```html
174
- <div
175
- id="config"
176
- data-mode="{{activationMode}}"
177
- data-start="{{startDate}}"
178
- data-end="{{endDate}}"
179
73
  ></div>
180
74
  <script>
181
- const config = document.getElementById("config");
182
- const mode = config.getAttribute("data-mode");
183
-
184
- if (mode === "timed") {
185
- const startDate = new Date(config.getAttribute("data-start"));
186
- const endDate = new Date(config.getAttribute("data-end"));
187
- const now = new Date();
188
-
189
- if (now >= startDate && now <= endDate) {
190
- // Show content
191
- }
192
- } else if (mode === "active") {
193
- // Show content immediately
194
- }
75
+ const { apiKey, enabled, headline } = document.getElementById("config").dataset;
76
+ // ...
195
77
  </script>
196
78
  ```
197
79
 
198
- **Validation Requirements:**
80
+ **Type handling (all `dataset` values are strings):**
81
+ - `NUMBER` → `Number(value)` or `parseInt(value, 10)`
82
+ - `BOOLEAN` → compare against `"true"` / `"false"`
83
+ - `DATE` / `DATETIME` → `new Date(value)`
199
84
 
200
- - Only use dynamic parameters that are relevant to your specific use case
201
- - Ignore parameters that don't apply to the functionality being implemented
202
- - Template variables `{{parameterKey}}` must match the exact key names from the parameter definitions
203
- - Handle both required and optional parameters appropriately
204
- - Provide sensible default behavior when optional parameters are not set
205
- - Ensure type-appropriate usage (don't use NUMBER parameters as strings without conversion)
85
+ **Other rules:**
86
+ - Template variable names must match the parameter keys exactly.
87
+ - Required parameters always have values; optional parameters may be empty — provide fallbacks.
88
+ - Only use parameters that are relevant to the use case; don't reference parameters you don't implement.
206
89
 
207
90
  ### Common Parameters
208
91
 
@@ -216,86 +99,14 @@ Every embedded script should have at minimum an **enable/disable toggle** parame
216
99
  | `headline` | `TEXT` | Customizable display text |
217
100
  | `color` | `COLOR` | UI customization |
218
101
 
219
- ## Output Structure
220
-
221
- A complete embedded script implementation requires **two parts**:
222
-
223
- ### 1. Embedded Script Extension
224
-
225
- ```
226
- src/extensions/site/embedded-scripts/
227
- └── {script-name}/
228
- ├── embedded.html # HTML/JavaScript code to inject
229
- └── extensions.ts # Metadata (scriptType, placement)
230
- ```
231
-
232
- ### 2. Dashboard Configuration Page (Required)
233
-
234
- ```
235
- src/extensions/dashboard/
236
- ├── withProviders.tsx # WDS provider wrapper (required)
237
- └── pages/
238
- └── {script-name}-settings/
239
- ├── extensions.ts # Extension registration (REQUIRED)
240
- └── page.tsx # Configuration UI using embeddedScripts API
241
- ```
102
+ ## Module-script Rules
242
103
 
243
- **Note:** The dashboard page requires its own `extensions.ts` file. Without this file, the dashboard page will not appear in the Wix dashboard.
104
+ The `<script type="module">` block runs at module scope, where Rollup (used by Astro) **disallows `return` statements**.
244
105
 
245
- **WARNING:** The dashboard page uses DIFFERENT field names than embedded scripts:
246
-
247
- - Dashboard pages use `title`, `routePath`, `component`
248
- - Embedded scripts use `name`, `source`, `placement`, `scriptType`
249
-
250
- Do NOT apply embedded script field names to dashboard page registrations.
251
-
252
- **See the DASHBOARD_PAGE.md reference** for dashboard page implementation details and the extension registration pattern.
253
-
254
- ## Implementation Pattern
255
-
256
- ```html
257
- <!-- Configuration element with template variables -->
258
- <div id="my-config" data-api-key="{{apiKey}}" data-enabled="{{enabled}}"></div>
106
+ - Use `throw new Error(...)` for early exits at module scope (e.g., "script disabled" / "config element not found").
107
+ - Wrap the main logic in a named `async function` and call it from a `DOMContentLoaded` listener (or directly if `document.readyState !== "loading"`); `return` is valid inside the function.
259
108
 
260
- <!-- Container for dynamic content -->
261
- <div id="my-container"></div>
262
-
263
- <style>
264
- /* Scoped styles for the embedded content */
265
- #my-container {
266
- /* styles */
267
- }
268
- </style>
269
-
270
- <script type="module">
271
- // Get configuration from data attributes
272
- const config = document.getElementById("my-config");
273
- if (!config) throw new Error("Config element not found");
274
-
275
- const { apiKey, enabled } = config.dataset;
276
-
277
- // Exit early if disabled (use throw at module scope, not return)
278
- if (enabled !== "true") {
279
- throw new Error("Script disabled");
280
- }
281
-
282
- // Implement functionality in a named function (return is allowed here)
283
- async function initialize() {
284
- try {
285
- // Your implementation
286
- } catch (error) {
287
- console.error("Script error:", error);
288
- }
289
- }
290
-
291
- // Initialize when DOM is ready
292
- if (document.readyState === "loading") {
293
- document.addEventListener("DOMContentLoaded", initialize);
294
- } else {
295
- initialize();
296
- }
297
- </script>
298
- ```
109
+ See the [Complete Example](#complete-example-coupon-popup) below for the full skeleton.
299
110
 
300
111
  ## Examples
301
112
 
@@ -358,7 +169,7 @@ Parameters for "cart-coupon-popup":
358
169
  - enablePopup (BOOLEAN, required) - Enable/disable toggle
359
170
  ```
360
171
 
361
- ### 2. Embedded Script (`embedded.html`)
172
+ ### 2. Embedded Script (`<folder>.html`)
362
173
 
363
174
  ```html
364
175
  <div
@@ -419,44 +230,6 @@ await embeddedScripts.embedScript({
419
230
  });
420
231
  ```
421
232
 
422
- ## Extension Registration
423
-
424
- **Extension registration is MANDATORY and has TWO required steps.**
425
-
426
- ### Step 1: Create Script-Specific Extension File
427
-
428
- Each embedded script requires an `extensions.ts` file in its folder:
429
-
430
- ```typescript
431
- import { extensions } from "@wix/astro/builders";
432
-
433
- export const embeddedscriptMyScript = extensions.embeddedScript({
434
- id: "{{GENERATE_UUID}}",
435
- name: "My Script",
436
- source: "./extensions/site/embedded-scripts/my-script/embedded.html",
437
- placement: "BODY_END",
438
- scriptType: "FUNCTIONAL",
439
- });
440
- ```
441
-
442
- **CRITICAL: UUID Generation**
443
-
444
- The `id` must be a unique, static UUID v4 string. Generate a fresh UUID for each extension - do NOT use `randomUUID()` or copy UUIDs from examples. Replace `{{GENERATE_UUID}}` with a freshly generated UUID like `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`.
445
-
446
- | Property | Type | Description |
447
- | ------------ | ------ | ----------------------------------------------------- |
448
- | `id` | string | Unique static UUID v4 (generate fresh) |
449
- | `name` | string | Display name for the script |
450
- | `source` | string | Relative path to the HTML file |
451
- | `placement` | enum | `HEAD`, `BODY_START`, or `BODY_END` |
452
- | `scriptType` | enum | `ESSENTIAL`, `FUNCTIONAL`, `ANALYTICS`, `ADVERTISING` |
453
-
454
- ### Step 2: Register in Main Extensions File
455
-
456
- **CRITICAL:** After creating the script-specific extension file, you MUST read [Extension Registration reference](EXTENSION_REGISTRATION.md) and follow the "App Registration" section to update `src/extensions.ts`.
457
-
458
- **Without completing Step 2, the embedded script will not be deployed to the site.**
459
-
460
233
  ## Enable Embedded Script Permission
461
234
 
462
235
  After implementation, the app developer must manually enable the embedded script permission:
package/skills/wix-app/references/EXTENSION_REGISTRATION.md CHANGED
@@ -1,96 +1,47 @@
1
1
 
2
- # Wix App Registration
2
+ # Extension Registration
3
3
 
4
- After creating any extension file, you must update the main `src/extensions.ts` file to register the extension with the app.
4
+ `src/extensions.ts` is the single entry point that tells the build system which extensions exist. Without a `.use()` call for an extension, it does not load.
5
5
 
6
- ## Why Registration Matters
6
+ ## Registration is automatic via the CLI
7
7
 
8
- The Wix CLI discovers extensions through the `src/extensions.ts` file — it's the single entry point that tells the build system which extensions exist. Without registration:
8
+ For every CLI-supported extension type, `wix generate --params` updates `src/extensions.ts` for you — you do NOT need to write the import or the `.use()` call by hand. Verify the file was updated after each `wix generate` invocation.
9
9
 
10
- - Dashboard pages won't appear in the sidebar
11
- - Custom element widgets won't show in the Wix Editor
12
- - Service plugins won't be called during checkout flows
13
- - Event handlers won't receive webhook deliveries
14
- - Embedded scripts won't be injected into site pages
10
+ ## Extension types that require manual registration
15
11
 
16
- The most common cause of "my extension isn't working" is a missing `.use()` call in this file.
12
+ | Type | Why manual |
13
+ | --- | --- |
14
+ | **Backend API** | Astro endpoints under `src/pages/api/` are auto-discovered by the runtime. They do not need to be added to `src/extensions.ts`. |
17
15
 
18
- ## Simple Pattern (Recommended for Small Apps)
16
+ Every other extension type is wired up automatically by the CLI.
19
17
 
20
- **`src/extensions.ts`** - Import and register extensions directly:
18
+ ## Manual recovery (when the CLI output drifts)
21
19
 
22
- ```typescript
23
- import { app } from "@wix/astro/builders";
24
- import { dataExtension } from "./extensions/data/extensions.ts";
25
- import { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions.ts";
26
- import { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions.ts";
27
-
28
- export default app()
29
- .use(dataExtension)
30
- .use(dashboardpageMyPage)
31
- .use(embeddedscriptMyScript);
32
- ```
33
-
34
- **Steps for each new extension:**
20
+ Edit `src/extensions.ts` directly only when:
35
21
 
36
- 1. Import the extension from its `extensions.ts` file
37
- 2. Add `.use(extensionName)` to the app chain
38
- 3. Chain multiple extensions together
39
-
40
- ## Advanced Pattern (For Large Apps)
41
-
42
- **`src/index.ts`** - Re-export all extensions:
43
-
44
- ```typescript
45
- export { dashboardpageMyPage } from "./extensions/dashboard/pages/my-page/extensions";
46
- export { embeddedscriptMyScript } from "./extensions/site/embedded-scripts/my-script/extensions";
47
- export { dataExtension } from "./extensions/data/extensions";
48
- ```
22
+ - The CLI failed mid-run and left the file out of sync
23
+ - A user hand-edited the file and broke the chain
24
+ - You're adding a Backend API helper (uncommon)
49
25
 
50
- **`src/extensions.ts`** - Register all extensions programmatically:
26
+ Each extension file is a default export from `<folder>/<folder>.extension.ts`. In `src/extensions.ts`, import it as a default import using the camelCase of the folder name, then chain `.use(...)`:
51
27
 
52
28
  ```typescript
53
- import { app } from "@wix/astro/builders";
54
- import * as allExtensions from "./index";
29
+ import { app } from '@wix/astro/builders';
30
+ import myPage from './extensions/dashboard/pages/my-page/my-page.extension.ts';
31
+ import contactCreated from './extensions/backend/events/contact-created/contact-created.extension.ts';
55
32
 
56
- const extensionList = Object.values(allExtensions);
57
-
58
- const appBuilder = app();
59
- extensionList.forEach((extension) => {
60
- appBuilder.use(extension);
61
- });
62
-
63
- export default appBuilder;
33
+ export default app()
34
+ .use(myPage)
35
+ .use(contactCreated);
64
36
  ```
65
37
 
66
- ## Extension Types Without Registration
67
-
68
- The following extension types do **not** require `extensions.ts` files:
69
-
70
- - **Backend API** - Astro server endpoints are auto-discovered
71
-
72
- ## Naming Conventions
73
-
74
- Extension export names follow this pattern: `{extensiontype}{CamelCaseName}`
75
-
76
- Examples:
77
-
78
- - `dashboardpageCartPopupManager`
79
- - `dashboardpluginBlogPostsBanner`
80
- - `dashboardmenupluginExportPosts`
81
- - `embeddedscriptCouponPopup`
82
- - `customelementwidgetCountdownWidget`
83
- - `sitepluginProductBadge`
84
- - `ecomshippingratesCustomShipping`
85
-
86
- The type prefix is the extension type in lowercase with no separators.
38
+ Re-run `wix generate --params` whenever possible — manual edits drift faster than CLI-generated ones.
87
39
 
88
40
  ## Troubleshooting
89
41
 
90
42
  | Symptom | Cause | Fix |
91
- |---------|-------|-----|
92
- | Extension not appearing at all | Missing `.use()` call | Add import and `.use(extensionName)` to `src/extensions.ts` |
93
- | "Cannot find module" on build | Wrong import path | Verify the path in your import matches the actual file location (relative to `src/`) |
94
- | Extension registered but not working | Export name mismatch | Ensure the exported name in the extension file matches the import in `extensions.ts` |
95
- | Multiple extensions, only some work | Incomplete chain | Check that every extension has both an import and a `.use()` call |
96
- | TypeScript error on `.use()` | Wrong export type | Ensure extension file uses the correct builder method (e.g., `extensions.dashboardPage()` not `extensions.embeddedScript()`) |
43
+ | --- | --- | --- |
44
+ | Extension not appearing at all | Missing `.use()` call | Re-run `wix generate --params`; if that's not possible, add the import + `.use(<binding>)` |
45
+ | "Cannot find module" on build | Wrong import path | Verify the path matches `./extensions/<area>/<folder>/<folder>.extension.ts` relative to `src/` |
46
+ | Multiple extensions, only some work | Incomplete chain | Check every extension has both an import and a `.use()` call |
47
+ | TypeScript error on `.use()` | Wrong builder method | Ensure the extension file uses the correct builder (e.g., `extensions.dashboardPage()` not `extensions.embeddedScript()`) |