json-render AGENTS.md

AGENTS.md

Instructions for AI coding agents working with this codebase.

Package Management

Always check the latest version before installing a package.

Before adding or updating any dependency, verify the current latest version on npm:

npm view <package-name> version

Or check multiple packages at once:

npm view ai version
npm view @ai-sdk/provider-utils version
npm view zod version

This ensures we don't install outdated versions that may have incompatible types or missing features.

Code Style

• Do not use emojis in code or UI
• Use shadcn CLI to add shadcn/ui components: pnpm dlx shadcn@latest add <component>
• Web app docs (apps/web/): Never use Markdown table syntax (| col | col |). Always use HTML <table> with <thead>, <tbody>, <tr>, <th>, <td>. Markdown tables do not render correctly in the web app. Inside HTML table cells, curly braces must be escaped as JSX expressions (e.g. <code>{'{ "$state": "/path" }'}</code>) because MDX parses { as a JSX expression boundary.

AI SDK / AI Gateway

When using the Vercel AI SDK (ai package) with AI Gateway, pass the model as a plain string identifier -- do not import a provider constructor:

import { streamText } from "ai";

const result = streamText({
  model: "anthropic/claude-haiku-4.5",
  prompt: "...",
});

This requires AI_GATEWAY_API_KEY to be set in the environment. See tests/e2e/ for examples.

Dev Servers

All apps and examples with dev servers use portless to avoid hardcoded ports. Portless assigns random ports and exposes each app via .localhost URLs.

Naming convention:

• Main web app: json-render → json-render.localhost:1355
• Examples: [name]-demo.json-render → [name]-demo.json-render.localhost:1355

When adding a new example that runs a dev server, wrap its dev script with portless <name>:

{
  "scripts": {
    "dev": "portless my-example-demo.json-render next dev --turbopack"
  }
}