Deco Full Analysis

Run a comprehensive analysis of a Deco e-commerce site. Generates AGENTS.md - a complete guide with architecture, custom code inventory, navigation flows, and everything an AI agent needs to work effectively with the codebase.

Includes 114 optimization learnings from real Deco sites organized into 9 checklists covering loaders, images, caching, SEO, hydration, assets, bugs, dependencies, and site cleanup.

When to Use This Skill

• Onboarding to a new Deco site

• Before making significant changes

• Understanding the site's architecture

• Documenting custom implementations

• Preparing for code reviews

• Validating block configurations match TypeScript Props

What It Produces

1. AGENTS.md

A comprehensive guide for AI agents containing:

• Framework versions and stack (Fresh vs HTMX)

• Apps installed and their versions

• Key page blocks (Home, PDP, PLP, Search, etc.)

• Navigation flow - How pages connect to each other

• Lazy loading map - Which sections are lazy on each page

• Caching inventory - Which loaders have cache vs don't

• Custom sections, loaders, and actions

• Integration details (VTEX, Shopify, etc.)

• Critical user journeys - Common flows to test

• Debugging tips - How to troubleshoot common issues

• Top committers and ownership

2. BLOCKS_DIAGNOSTICS.md

A human-readable diagnostics report from block validation:

• Summary metrics - Total files, valid %, errors, unused counts

• Critical issues - Top errors grouped by root cause with impact assessment

• Schema errors - Tables of sections/loaders/actions with type mismatches

• Unused code inventory - Categorized lists for cleanup review

• Prioritized recommendations - Actionable fix suggestions

• Re-run commands - How to regenerate the report

3. validation-report.json

Structured JSON report for programmatic use:

• Timestamps and project metadata

• Summary counts (sections, errors, warnings, unused)

• Detailed error list with file, line, property, message

• Full unused files list

4. README.md Updates

If the README is outdated or missing key info:

• How to run the site locally

• Environment setup

• Key commands

• Link to AGENTS.md

Workflow

1. Analyze deno.json → Framework versions, dependencies, apps
2. Analyze .deco/blocks/ → Page configurations, key blocks
3. Map page navigation → How pages link together
4. Identify lazy sections → Find Rendering/Lazy.tsx wrappers
5. Analyze loaders/ → Custom data loading
6. Audit cache headers → Check for export const cache
7. Analyze sections/ → Custom UI components
8. Analyze actions/ → Custom mutations
9. Run block validation → Generate validation-report.json
10. Generate BLOCKS_DIAGNOSTICS.md → Human-readable diagnostics
11. Search Deco docs → Understand patterns used
12. Check git log → Top committers
13. Generate AGENTS.md → Comprehensive guide with all sections
14. Update README.md → Quick start, run commands

Tools Used

Code Analysis (file system)

• Read deno.json for dependencies and versions

• Read .deco/blocks/*.json for page configurations

• List sections/ , loaders/ , actions/ directories

• Read key component files

Deco Documentation

SearchDecoCx({ query: "blocks sections loaders" })

Use this to understand Deco patterns and concepts.

Git Analysis

git log --format='%an' | sort | uniq -c | sort -rn | head -10

Find top committers (code owners).

Key Files to Analyze

File/Directory Purpose

deno.json

Framework versions, apps, dependencies

.deco/blocks/pages-*.json

Page configurations

.deco/blocks/Header*.json

Header configurations

sections/

Custom UI components

loaders/

Custom data loaders

actions/

Custom mutations

apps/

App configurations

fresh.gen.ts

Generated routes/islands

manifest.gen.ts

Generated manifest

Framework Detection

Fresh Stack (SSR + Islands)

// deno.json { "imports": { "@deco/deco": "jsr:@deco/deco@...", "preact": "npm:preact@...", "$fresh/": "..." } }

• Uses islands/ for interactive components

• Uses routes/ for pages

• Sections render on server

HTMX Stack

// deno.json { "imports": { "@deco/deco/htmx": "..." } }

• Uses HTMX for interactivity

• Sections can have hx-* attributes

Understanding Page Blocks

Page blocks in .deco/blocks/pages-*.json define which sections appear on each page:

{ "name": "Home (principal)", "__resolveType": "website/pages/Page.tsx", "sections": [ { "__resolveType": "site/sections/Header/Header.tsx" }, { "__resolveType": "website/sections/Rendering/Lazy.tsx", "section": { "__resolveType": "site/sections/Product/ProductShelf.tsx" } } ] }

Key patterns:

• site/sections/*

• Custom sections in the repo

• website/sections/*

• Sections from website app

• Rendering/Lazy.tsx

• Lazy-loaded sections

• Rendering/Deferred.tsx

• Deferred sections

App Analysis

Apps in Deco provide loaders, sections, and integrations. Check deno.json :

{ "imports": { "apps/": "https://cdn.jsdelivr.net/gh/deco-cx/apps@...", // or forked "apps/": "https://cdn.jsdelivr.net/gh/OrgName/deco-apps@..." } }

Common apps:

• apps/vtex/

• VTEX integration

• apps/shopify/

• Shopify integration

• apps/wake/

• Wake integration

• apps/website/

• Core website features

• apps/analytics/

• Analytics

Custom Code Analysis

Custom Sections

sections/ ├── Header/ │ └── Header.tsx # Custom header ├── Product/ │ ├── ProductShelf.tsx │ └── ProductCard.tsx └── Footer/ └── Footer.tsx

Custom Loaders

loaders/ ├── search/ │ └── intelligenseSearch.ts # Custom search ├── product/ │ └── productDetails.ts └── getUserGeolocation.ts

Custom Actions

actions/ ├── cart/ │ └── addToCart.ts └── newsletter/ └── subscribe.ts

AGENTS.md Template

AGENTS.md - [Site Name]

Quick Reference

How to Run

```bash deno task dev

or

deno task start ```

Architecture

Stack

• Framework: Deco with Fresh (SSR + Islands)
• Platform: VTEX IO
• CDN: Deco Edge

Key Pages

Navigation Flow

``` Home (/) ├── Search (/s) ───────────────────┐ ├── Category (PLP) ────────────────┤ │ └── Subcategory ─────────────┤ └── Product Cards ────────────────→┴─→ PDP (/:slug/p) ├── Add to Cart → Minicart └── Buy Now → Checkout ```

Lazy Loading Map

Which sections are lazy-loaded on each key page:

Caching Inventory

Custom Code

Critical User Journeys

1. Browse & Purchase

``` Home → Search/Category → PDP → Add to Cart → Checkout ```

2. Direct Search

``` Home → Searchbar → Search Results → PDP → Add to Cart ```

3. Account Access

``` Any Page → Login → Account Dashboard → Orders/Wishlist ```

Debugging Tips

Common Issues

Useful Debug Commands

```bash

Check which loaders are called on a page

curl -sI "https://site.com/page?__d" | grep server-timing

Find sections with a specific loader

grep -r "loaderName" .deco/blocks/

Check for missing cache headers

grep -L "export const cache" loaders/**/*.ts ```

Performance Flags

• ?__d - Shows server timing with loader breakdown
• ?__d=verbose - Extended debug info
• Check /deco/render calls in Network tab for lazy sections

Block Health

Run deno task validate-blocks -report validation-report.json to check for configuration issues.

Sections with Errors

• sections/Product/NotFound.tsx (7 errors) - missing required props
• loaders/SAP/createCase.ts (9 errors) - type mismatches

Unused Files (candidates for removal)

• sections/Product/Wishlist.tsx
• sections/Social/InstagramPosts.tsx
• loaders/legacy/oldProductLoader.ts

Code Owners

Important Files

• deno.json - Dependencies and tasks
• .deco/blocks/ - Page configurations
• sections/ - Custom UI components
• loaders/ - Custom data loading

Common Tasks

Add a new section

1. Create file in sections/YourSection.tsx
2. Export default component with Props interface
3. Add to page via Admin or .deco/blocks/

Modify a page

1. Find the page block in .deco/blocks/pages-*.json
2. Edit sections array
3. Or use the Deco Admin UI

Add caching to a loader

```typescript // loaders/myLoader.ts export const cache = "stale-while-revalidate"; export const cacheKey = (props: Props) => `${props.key}`; ```

Example Output

When you run this skill on an e-commerce site, you'll discover:

• Using Deco + Fresh stack

• Platform integration (VTEX, Shopify, etc.)

• Custom intelligent search loader

• Forked or custom deco-apps

• 50+ custom sections

• Key pages: Home, PDP, PLP, Search, Checkout

• Top contributors and their commit counts

Block Validation (validate-blocks)

Run block validation to ensure JSON configurations match TypeScript Props.

How to Run

Run directly from any deco site directory (no installation needed):

Validate all sections, loaders, and actions

deno run -A https://deco.cx/validate

Generate a JSON report for analysis

deno run -A https://deco.cx/validate -report validation-report.json

Optional: Add as a deno task for convenience:

Add to your site's deno.json :

{ "tasks": { "validate-blocks": "deno run -A https://deco.cx/validate" } }

Then run:

deno task validate-blocks -report validation-report.json

What It Validates

• Type Matching - JSON values match Props interface types

• Required Properties - All required props are present

• Unused Files - Sections, loaders, and actions not referenced in any block

• Extra Properties - Properties in JSON not defined in types (with -unused flag)

• Anti-Patterns - Dead code and structural issues (see Anti-Patterns section below)

Unused Detection

Type Detection Auto-Removal

Unused Sections ✅ Detected ✅ With -rm-sections

Unused Loaders ✅ Detected ❌ Manual only*

Unused Actions ✅ Detected ❌ Manual only*

Unused Properties ✅ With -unused

✅ With -rm-vars

*Loaders and actions are not auto-removed because they may be imported dynamically.

Sample Output

🔍 Validating sections, loaders, and actions...

✅ sections/Header/Header.tsx - 15 occurrence(s) ⚠️ sections/Footer/Footer.tsx - 1 occurrence(s), 2 warning(s) ❌ sections/Category/CategoryGrid.tsx - 1 error(s)

• "items": required property missing

═══════════════════════════════════════ 📊 SUMMARY ═══════════════════════════════════════ Total sections/loaders/actions: 95 Total occurrences: 284 ✅ No issues: 85 ⚠️ With warnings: 3 ⚠️ Unused: 3 ❌ With errors: 4

JSON Report (-report flag)

Generate a structured JSON report for automated analysis:

deno run -A https://deco.cx/validate -report validation-report.json

The report includes:

• summary : Total counts (sections, errors, warnings, unused)

• sectionsWithErrors : Detailed error list with file, line, property, message

• sectionsWithWarnings : Detailed warning list

• unusedSections : List of unreferenced files

Use the report to:

• Track validation status over time

• Integrate with CI/CD pipelines

• Generate AGENTS.md Block Health sections automatically

Diagnostics MD Report

After running block validation with -report , generate a human-readable diagnostics file:

1. Run validation and save JSON report

deno run -A https://deco.cx/validate -report validation-report.json

2. Generate BLOCKS_DIAGNOSTICS.md from the JSON report

The diagnostics MD should include:

• Summary table - Total files, valid, errors, warnings, unused counts

• Critical issues - Top errors grouped by root cause

• Sections with errors - Table of files with error counts

• Loader/action errors - Separate section for non-section files

• Warnings - Props interface issues

• Unused code inventory - Sections, loaders, actions not referenced

• Recommendations - Prioritized fix suggestions

• How to re-run - Commands to regenerate the report

BLOCKS_DIAGNOSTICS.md Template

Block Validation Diagnostics - [Site Name]

Generated: [Date] Tool: validate-blocks v1.1.0

Summary

Critical Issues

1. [Root Cause Name] (X errors)

File: sections/Example/Example.tsx Impact: HIGH/MEDIUM/LOW - Affects X pages

[Description of the issue and root cause]

Affected Pages (sample):

• page1.json
• page2.json

Fix Required: [Specific instructions]

Sections with Schema Errors

Unused Code (X files)

Unused Sections (X files)

Unused Loaders (X files)

Recommendations

Priority 1 - [Issue Name] (HIGH)

[Specific fix instructions]

Priority 2 - [Issue Name] (MEDIUM)

[Specific fix instructions]

How to Re-run Validation

```bash deno run -A https://deco.cx/validate -report validation-report.json ```

Task: Generate Diagnostics MD

When analyzing a site, always generate both files:

• validation-report.json - For programmatic use

• BLOCKS_DIAGNOSTICS.md - For human review

The diagnostics MD makes it easier to:

• Share findings with the team

• Track issues in PRs/tickets

• Reference specific errors without parsing JSON

• Prioritize fixes by impact

Cleanup Options

Remove properties not in Props interface

deno task validate-blocks -rm-vars

Remove unused section files (with confirmation - type 'yes')

deno task validate-blocks -rm-sections

Show warnings for extra properties

deno task validate-blocks -unused

Use custom blocks directory

deno task validate-blocks -blocks /path/to/.deco/blocks

Anti-Patterns Detection

The validator detects structural issues beyond type mismatches:

1. Dead Code (never rule)

Sections with website/matchers/never.ts rule will never execute:

{ "__resolveType": "website/flags/multivariate/section.ts", "variants": [{ "rule": { "__resolveType": "website/matchers/never.ts" }, // 💀 DEAD CODE "value": { "__resolveType": "site/sections/Product/ProductShelf.tsx" } }] }

Impact: Bloats page config, confuses developers, slows admin load. Fix: Remove the entire variant or replace with always matcher.

2. Lazy Wrapping Multivariate (Anti-Pattern)

Lazy should not wrap multivariate - the flag evaluation happens immediately anyway:

{ "__resolveType": "website/sections/Rendering/Lazy.tsx", "section": { "__resolveType": "website/flags/multivariate/section.ts", // ❌ WRONG "variants": [...] } }

Why it's wrong: Lazy defers rendering, but multivariate flags are evaluated at request time regardless. If you need lazy loading per variant, the multivariate should wrap Lazy sections:

{ "__resolveType": "website/flags/multivariate/section.ts", "variants": [{ "rule": { "__resolveType": "website/matchers/always.ts" }, "value": { "__resolveType": "website/sections/Rendering/Lazy.tsx", // ✅ CORRECT "section": { "__resolveType": "site/sections/Product/ProductShelf.tsx" } } }] }

Sample Anti-Pattern Output

🚨 ANTI-PATTERNS DETECTED

💀 Dead Code (40 sections with 'never' rule): 📄 pages-Home.json: 30 dead code section(s) 📄 pages-BlackFriday.json: 10 dead code section(s)

⚠️ Lazy wrapping Multivariate (5 instances): 📄 pages-Home.json Path: sections.variants[0].value[5] Lazy wrapping multivariate is an anti-pattern...

Common Block Corruption Patterns

Exploded Strings

Sometimes strings get corrupted into character-indexed objects:

// ❌ Corrupted { "image": { "0": "h", "1": "t", "2": "t", "3": "p", "4": "s", "5": ":", "6": "/", "7": "/", ... } }

// ✅ Should be { "image": "https://example.com/image.jpg" }

Detection: Objects with 50+ numeric keys where values are single characters. Fix Script: Reconstruct string from numeric keys sorted by index.

Arrays as Objects

Sometimes arrays get saved as indexed objects:

// ❌ Corrupted { "items": { "0": {...}, "1": {...}, "2": {...} } }

// ✅ Should be { "items": [{...}, {...}, {...}] }

Loader-Injected Props Pattern

When a loader injects props at runtime (like device from ctx.device ), use this pattern:

// sections/Product/ProductShelfGroup.tsx

export interface Props { shelves: ShelfConfig[]; /**

• @hide */ device: "mobile" | "desktop" | "tablet"; // Required with @hide }

export function loader(props: Props, _req: Request, ctx: AppContext) { return { ...props, device: ctx.device, // Loader always provides actual device }; }

In the JSON block, store a default value (will be overwritten by loader):

{ "__resolveType": "site/sections/Product/ProductShelfGroup.tsx", "shelves": [...], "device": "mobile" }

Why this pattern:

• @hide prevents the prop from showing in admin UI

• Prop is required in Props, so TypeScript is happy

• JSON has a value, so deco admin validation passes

• Loader overwrites with actual runtime value

Validator divergence: Our script validates against the Props interface. Deco admin may validate against SectionProps<typeof loader> which includes loader return types. If you see admin errors not caught by the script, check for loader-injected props.

Nested Props with Loader-Injected Values

When a section has nested props that reference another component's Props (which includes loader-injected values like device ), you must Omit those values:

// ❌ WRONG - ProductShelfProps includes required device export interface ProductShelfTimedOffersConfig { type: "ProductShelfTimedOffers"; props: ProductShelfTimedOffersProps; // shelfProps.device is required! }

// ✅ CORRECT - Omit device from nested props type ShelfPropsWithoutDevice = Omit<ProductShelfProps, "device">;

export interface ProductShelfTimedOffersConfig { type: "ProductShelfTimedOffers"; props: Omit<ProductShelfTimedOffersProps, "shelfProps" | "shelfPropsOffer"> & { shelfProps: ShelfPropsWithoutDevice; shelfPropsOffer?: ShelfPropsWithoutDevice; }; }

Why: The parent component injects device at runtime, but deco admin validates the JSON before runtime. If nested props require device , admin shows validation errors even though the code works.

Add to AGENTS.md

Include block health summary:

Block Health

Files with errors:

• sections/Product/NotFound.tsx (7 errors)
• loaders/SAP/createCase.ts (9 errors)

Unused files (candidates for removal):

• sections/Product/Wishlist.tsx
• sections/Social/InstagramPosts.tsx
• actions/legacy/oldAction.ts

Optimization Checklists

Based on 105 learnings from real Deco sites, run these checklists during analysis:

Available Checklists

Checklist Items Key Focus

loader-optimization.md 33 Lazy sections, VTEX simulation, deduplication

image-optimization.md 18 LCP, eager/lazy loading, responsive images

cache-strategy.md 7 SWR, cache keys, rate limiting

seo-fix.md 10 JSON-LD, meta tags, canonicals

hydration-fix.md 9 SDK race conditions, SSR/client mismatch

asset-optimization.md 17 Third-party scripts, lazy loading, CSP

bug-fix.md 8 Defensive coding, content sanitization

dependency-update.md 3 Version alignment, Deco 2.0

site-cleanup.md 9 Platform files, dead code, type fixes

Top Patterns to Check

Loader Optimization (most common):

• Heavy sections wrapped in Lazy (BuyTogether, Reviews, Shelves)

• VTEX simulation set to skip or only1P

• No sync product loaders in Header

• AbortController timeout on external APIs

Image Optimization:

• LCP image has loading="eager" and fetchPriority="high"

• First 4-6 PLP products are eager loaded

• All images use Deco <Image /> component

• SVGs bypass optimization proxy

Cache Strategy:

• Custom loaders have export const cache = "stale-while-revalidate"

• Cache keys are deterministic (no URL params, sorted arrays)

• Common loaders use shared blocks for deduplication

SEO:

• JSON-LD escapes < character

• Every page has SEO section

• Prices have exactly 2 decimal places

Hydration:

• No direct window /document access without IS_BROWSER check

• External widgets wait for load via callback

• No Math.random() for ID generation

How to Use Checklists

• During analysis: Reference relevant checklists when examining code

• In AGENTS.md: Include findings table showing pass/fail for each area

• For recommendations: Use checklist items as specific action items

Example Findings Table (add to AGENTS.md)

Optimization Audit

Next Steps After Generating AGENTS.md

• Review the generated AGENTS.md

• Run block validation to generate validation-report.json

• Generate BLOCKS_DIAGNOSTICS.md from the validation report

• Run through optimization checklists for each category

• Check if README.md needs updates

• Identify areas that need documentation

• Use the performance-audit skill for runtime analysis