@decocms/start 0.19.0

package/.cursor/skills/deco-typescript-fixes/common-fixes.md

@@ -0,0 +1,330 @@
+# Common TypeScript Fixes - Detailed Patterns
+
+## 1. Props Exports for Deco Sections
+
+Deco's admin UI needs to read the Props type to generate the form. Without an export, blocks may fail to render or configure.
+
+### Detection
+
+```bash
+# Find sections/components without exported Props
+grep -r "interface Props" sections/ components/ | grep -v "export"
+```
+
+### Fix Pattern
+
+```typescript
+// sections/MySection.tsx
+
+// WRONG - interface not exported
+interface Props {
+  title: string;
+  description?: string;
+}
+
+// CORRECT - export the interface
+export interface Props {
+  title: string;
+  description?: string;
+}
+
+// Also valid - type alias
+export type Props = {
+  title: string;
+  description?: string;
+};
+```
+
+### Deco-Specific Requirements
+
+For sections that are used in blocks:
+- Props MUST be exported
+- Props must use serializable types (no functions, classes)
+- Use JSDoc comments for field descriptions in the admin
+
+```typescript
+export interface Props {
+  /** @title Page Title */
+  /** @description The main heading shown to users */
+  title: string;
+
+  /** @format rich-text */
+  content?: string;
+}
+```
+
+---
+
+## 2. Global Type Declarations
+
+Third-party scripts inject globals into the window. TypeScript doesn't know about them.
+
+### Common Globals in E-commerce
+
+```typescript
+// types/global.d.ts
+
+// Marketing/Recommendation platform queue pattern
+export type AnalyticsCommand =
+  | ["cart", CartItem[]]
+  | ["setEmail", string]
+  | ["searchTerm", string]
+  | ["go"]
+  | ["view", string]
+  | ["category", string]
+  | ["recommend", RecommendOptions];
+
+// Tag manager
+// deno-lint-ignore no-var
+declare global {
+  var dataLayer: unknown[];
+}
+
+// Third-party tracker pattern
+export type TrackerFn = {
+  (args: unknown): void;
+  q?: unknown[];  // Queue for calls before script loads
+  aid?: string;   // Account/API identifier
+};
+
+declare global {
+  // deno-lint-ignore no-var
+  var tracker: TrackerFn;
+  // deno-lint-ignore no-var
+  var AnalyticsQueue: AnalyticsCommand[];
+}
+
+// Export empty to make it a module
+export {};
+```
+
+### Usage After Declaration
+
+```typescript
+// Now TypeScript knows about these globals
+AnalyticsQueue.push(["view", productId]);
+dataLayer.push({ event: "pageview" });
+```
+
+---
+
+## 3. VTEX GraphQL Type Mismatches
+
+VTEX SDK types often don't match the actual GraphQL response. Create bridge types.
+
+### Problem
+
+```typescript
+// SDK says order has this shape:
+interface Order {
+  items: OrderItem[];
+  shippingData: ShippingData;
+}
+
+// But GraphQL returns different fields:
+{
+  items: [...],
+  logistics: [...],  // Not shippingData!
+}
+```
+
+### Solution: Custom Response Types
+
+```typescript
+// types/vtex-orders.ts
+
+// Match what GraphQL actually returns
+export interface LogisticsInfo {
+  deliveryChannel?: string;
+  shippingEstimateDate?: string;
+}
+
+export interface VtexOrderData {
+  orderId: string;
+  items: OrderItem[];
+  logistics: LogisticsInfo[];  // Different from SDK type
+  totals: Total[];
+}
+
+// Usage with type assertion
+const orderData = await fetchOrder(orderId);
+const order = orderData as unknown as VtexOrderData;
+```
+
+---
+
+## 4. Optional Chaining Patterns
+
+### Array Access
+
+```typescript
+// BEFORE - may throw if products is undefined
+const firstProduct = products[0];
+
+// AFTER
+const firstProduct = products?.[0];
+```
+
+### Nested Optional Access
+
+```typescript
+// BEFORE
+const city = order.shippingData.address.city;
+
+// AFTER
+const city = order?.shippingData?.address?.city ?? "Unknown";
+```
+
+### Method Calls on Optional
+
+```typescript
+// BEFORE
+const upper = user.getName().toUpperCase();
+
+// AFTER
+const upper = user?.getName?.()?.toUpperCase?.() ?? "";
+```
+
+### With Fallbacks for Different Types
+
+```typescript
+// For strings
+const title = product?.name ?? "Untitled";
+
+// For numbers
+const price = product?.price ?? 0;
+
+// For arrays
+const tags = product?.tags ?? [];
+
+// For objects
+const specs = product?.specifications ?? {};
+```
+
+---
+
+## 5. Event Handler Types
+
+### Mouse Events
+
+```typescript
+// BEFORE - implicit any
+const handleClick = (e) => { ... };
+
+// AFTER
+const handleClick = (e: MouseEvent) => { ... };
+
+// For React/Preact
+const handleClick = (e: h.JSX.TargetedMouseEvent<HTMLButtonElement>) => { ... };
+```
+
+### Input Events
+
+```typescript
+// Generic input
+const handleInput = (e: Event) => {
+  const target = e.target as HTMLInputElement;
+  const value = target.value;
+};
+
+// Preact specific
+const handleInput = (e: h.JSX.TargetedEvent<HTMLInputElement>) => {
+  const value = e.currentTarget.value;
+};
+```
+
+### Form Events
+
+```typescript
+const handleSubmit = (e: h.JSX.TargetedEvent<HTMLFormElement>) => {
+  e.preventDefault();
+  // ...
+};
+```
+
+---
+
+## 6. Import Path Updates After Migration
+
+When migrating from a fork to official apps:
+
+### Common Changes
+
+```typescript
+// BEFORE - forked apps
+import { ProductDetailsPage } from "apps/commerce/types.ts";
+import type { Product } from "apps/commerce/types.ts";
+
+// AFTER - may need different paths or types
+import { ProductDetailsPage } from "apps/commerce/types.ts";
+import type { Product } from "apps/commerce/types.ts";
+// Often the same, but verify the types match
+```
+
+### Loader Props Pattern
+
+```typescript
+// Ensure loaders export Props for deco
+import type { Props as VTEXProps } from "apps/vtex/loaders/intelligentSearch/productList.ts";
+
+export interface Props extends VTEXProps {
+  // Additional custom props
+  customField?: string;
+}
+```
+
+---
+
+## 7. Discriminated Unions for Platform Code
+
+If supporting multiple platforms, use discriminated unions:
+
+```typescript
+type CartProps =
+  | { platform: "vtex"; cartId: string }
+  | { platform: "shopify"; checkoutId: string }
+  | { platform: "wake"; cartToken: string };
+
+function getCart(props: CartProps) {
+  switch (props.platform) {
+    case "vtex":
+      return vtexCart(props.cartId);
+    case "shopify":
+      return shopifyCart(props.checkoutId);
+    case "wake":
+      return wakeCart(props.cartToken);
+  }
+}
+```
+
+---
+
+## 8. Type Narrowing Patterns
+
+### Using Type Guards
+
+```typescript
+function isProduct(item: unknown): item is Product {
+  return (
+    typeof item === "object" &&
+    item !== null &&
+    "productID" in item &&
+    "name" in item
+  );
+}
+
+// Usage
+if (isProduct(data)) {
+  console.log(data.name);  // TypeScript knows it's a Product
+}
+```
+
+### Assertion Functions
+
+```typescript
+function assertProduct(item: unknown): asserts item is Product {
+  if (!isProduct(item)) {
+    throw new Error("Expected Product");
+  }
+}
+```

package/.cursor/skills/deco-typescript-fixes/strategy.md

@@ -0,0 +1,148 @@
+# Incremental TypeScript Fixing Strategy
+
+## The Core Problem
+
+Running `deno check` on a large deco storefront can take 30-60+ seconds. With 200+ errors, a naive fix-one-check-repeat loop would take hours.
+
+## Solution: Fast Feedback with `--unstable-tsgo`
+
+Deno 2.1+ includes an experimental fast type checker based on the TSGo port:
+
+```bash
+# FAST - TSGo checker (~3-5s per run) - ALWAYS use this
+deno check --unstable-tsgo --allow-import main.ts
+```
+
+**Requirements**: Deno 2.1 or later (ideally 2.6+)
+
+> **Note for Deno 2.0+**: Always include `--allow-import` flag as it's required for remote imports.
+
+```bash
+# Check your version
+deno --version
+
+# Update if needed
+deno upgrade
+```
+
+## The Iterative Strategy
+
+### Phase 1: Assessment
+
+```bash
+# Get total error count
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "ERROR"
+
+# Save full error list
+deno check --unstable-tsgo --allow-import main.ts 2>&1 > /tmp/type-errors.txt
+
+# Categorize errors
+grep "possibly 'undefined'" /tmp/type-errors.txt | wc -l
+grep "Cannot find name" /tmp/type-errors.txt | wc -l
+grep "not assignable" /tmp/type-errors.txt | wc -l
+grep "Property .* does not exist" /tmp/type-errors.txt | wc -l
+```
+
+### Phase 2: Batch Fixes
+
+Fix errors in batches of 5-20, grouped by category:
+
+1. **First batch**: Missing global types (biggest impact, unlocks other fixes)
+2. **Second batch**: Props exports (straightforward, mechanical)
+3. **Third batch**: Possibly undefined errors (repetitive pattern)
+4. **Fourth batch**: Type mismatches (may need custom types)
+5. **Final batch**: Edge cases and complex fixes
+
+### Phase 3: Incremental Verification
+
+After each batch:
+
+```bash
+# Quick check - should see error count decreasing
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+
+# Commit progress
+git add -A
+git commit -m "fix(types): reduce deno check errors from X to Y"
+```
+
+### Commit Message Pattern
+
+Use consistent commit messages to track progress:
+
+```
+fix(types): reduce deno check errors from 200 to 180
+fix(types): reduce deno check errors from 180 to 150
+fix(types): reduce deno check errors from 150 to 100
+...
+fix(types): achieve zero deno check TypeScript errors
+```
+
+## Useful Commands Cheatsheet
+
+```bash
+# Fast type check
+deno check --unstable-tsgo --allow-import main.ts
+
+# Count errors
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+
+# Find errors in specific file
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "MyComponent.tsx"
+
+# Find specific error patterns
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "TS2532"  # possibly undefined
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "TS2304"  # cannot find name
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "TS2339"  # property does not exist
+
+# List files with most errors
+deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep "error:" | \
+  sed 's/:.*//g' | sort | uniq -c | sort -rn | head -20
+```
+
+## Common Gotchas
+
+### Large Codebases May Need More Memory
+
+```bash
+# If you hit memory issues
+DENO_V8_FLAGS="--max-old-space-size=8192" deno check --unstable-tsgo --allow-import main.ts
+```
+
+### Some Errors Cascade
+
+Fixing one error may reveal or fix others. If error count changes unexpectedly, re-run and re-categorize.
+
+## Example Session
+
+```bash
+$ deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+215
+
+# Fix global types
+$ vim types/global.d.ts
+$ deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+181
+$ git add -A && git commit -m "fix(types): reduce deno check errors from 215 to 181"
+
+# Fix Props exports
+$ # ... edit multiple files ...
+$ deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+150
+$ git add -A && git commit -m "fix(types): reduce deno check errors from 181 to 150"
+
+# Continue until...
+$ deno check --unstable-tsgo --allow-import main.ts 2>&1 | grep -c "error:"
+0
+
+# Done!
+```
+
+## Time Estimates
+
+| Errors | With --unstable-tsgo | Without |
+|--------|---------------------|---------|
+| 200 errors, 10 fix cycles | ~30-50 min | ~5-10 hours |
+| 50 errors, 5 fix cycles | ~15-25 min | ~2-3 hours |
+
+The fast checker makes this process actually feasible for large codebases.