# headless-caching-strategy

Sets caching rules and TTL values for headless VTEX storefronts. Keeps public endpoints fast while preventing accidental caching of sensitive shopper data.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1100 installs · ★ 46
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/headless-caching-strategy/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/headless-caching-strategy

## What it does

This skill governs caching across headless VTEX stores. It isolates public catalog traffic from transactional shopper requests. Without caching, API rate limits trigger 429 errors. Keeping search responses and category trees at the edge or within a BFF cache drops latency by 200–500ms.

The logic relies on `stale-while-revalidate` alongside moderate TTLs between 2 and 15 minutes. It sets explicit windows: category trees persist up to 15 minutes, while search autocomplete entries refresh after one or two minutes. Invalidation should follow catalog update events rather than multi-hour expiration windows.

Sensitive shopper routes must stay uncached. Storing checkout or customer details creates compliance liabilities and corrupts carts. Because of this, the skill forbids caching Checkout, Profile, OMS, and Payments on any tier, including Redis and browser storage.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-caching-strategy -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/headless-caching-strategy/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/headless-caching-strategy/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-caching-strategy -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/headless-caching-strategy/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-caching-strategy -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/headless-caching-strategy/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills headless-caching-strategy
```

2. **Manually: put the files in place**
- File: `.github/skills/headless-caching-strategy/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-caching-strategy -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/headless-caching-strategy
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/headless-caching-strategy/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill headless-caching-strategy -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/headless-caching-strategy/SKILL.md

## When to use it
- prevent VTEX API rate limit errors caused by repetitive search queries
- implement stale-while-revalidate patterns inside an Express BFF layer
- assign suitable TTL values for public catalog endpoints
- block checkout and personal customer records from being cached

## Example prompts
- Set up an in-memory stale-while-revalidate cache for my VTEX category tree in Express.
- What TTL values and headers should I configure for Intelligent Search endpoints?
- Review my storefront API proxy to ensure Checkout and Profile routes stay uncached.

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 38 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md