# vtex-io-rootpath

A skill for VTEX IO apps in multi-binding stores: shows how to build URLs with the binding's path prefix. Useful when links 404 or point to the wrong locale.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 740 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/vtex-io-rootpath/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-rootpath

## What it does

This skill covers `rootPath` handling in VTEX IO stores where several bindings share one domain behind path prefixes (`store.com/us/`, `store.com/br/`). It walks through pulling `rootPath` out of the `x-vtex-root-path` header, the `useRuntime().rootPath` hook in React, URL building on the backend, link generation and asset paths.

Inside are decision rules and hard constraints. A Node backend needs an early middleware, usually named `prepare`, that reads the header, normalizes the value and stores it on `ctx.state.rootPath`; the same middleware sets `Vary: x-vtex-root-path` so CDN caching stays per binding. React components read the prefix through the hook from `vtex.render-runtime`. One more requirement: sanitize `rootPath`, since a value of `"/"` concatenated with a path yields a double slash (`//product/shoes`) — that breaks canonical URLs and can trigger redirect loops.

The skill is not meant for stores with a separate domain per locale, nor for general IO backend patterns. Hardcoding a prefix such as `/us/` breaks every other binding, and that is the failure this skill is built around.

## Install

### Claude Code (native platform)

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

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rootpath -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rootpath -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-rootpath
```

2. **Manually: put the files in place**
- File: `.github/skills/vtex-io-rootpath/SKILL.md`

### Gemini CLI

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

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-rootpath
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-rootpath -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/vtex-io-rootpath/SKILL.md

## When to use it
- build canonical URLs that carry the binding prefix
- fix 404s and wrong links in a multi-binding store
- wire a `prepare` middleware that reads `x-vtex-root-path`
- strip double slashes when `rootPath === "/"`
- generate sitemap entries per binding

## Example prompts
- Show me how the `prepare` middleware should read `x-vtex-root-path` into `ctx.state.rootPath`.
- Build a product canonical URL with `rootPath` on a VTEX IO backend.
- How do I read `rootPath` in a React component with `useRuntime()`?

## Similar
- [frontend-design](https://affpapa.org/en/nevibecode/skills/frontend-design.md) — skill · 1025790 installs
- [design-taste-frontend](https://affpapa.org/en/nevibecode/skills/design-taste-frontend.md) — skill · 678700 installs
- [prototype](https://affpapa.org/en/nevibecode/skills/prototype.md) — skill · 986201 installs
- [hyperframes](https://affpapa.org/en/nevibecode/skills/heygen-com-hyperframes.md) — skill · 1200000 installs
- [hyperframes-cli](https://affpapa.org/en/nevibecode/skills/heygen-com-hyperframes-cli.md) — skill · 1300000 installs
- [webapp-testing](https://affpapa.org/en/nevibecode/skills/webapp-testing.md) — skill · 186758 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 43 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