dify/web/AGENTS.md

Frontend Workflow

• Prefer vinext for frontend development. With a local backend, start the API separately and use ./dev/start-web or pnpm -C web dev for the frontend only; the Dev Container start-web alias also starts only the frontend. For a remote backend, use root pnpm dev to start vinext and the API proxy. The local API and proxy both default to port 5001, so do not start both on that port. Switch to the Next.js development server (pnpm -C web dev:next) only when testing Next.js-specific functionality or investigating behavior that differs from Next.js.
• Read docs/test.md only for frontend test work and docs/lint.md only when running or changing static checks.
• Use the repo-local how-to-write-component skill when implementation requires component ownership, state, data-flow, effect, or interaction-boundary decisions. Do not load it for test-only, copy-only, or styling-only changes.
• Use frontend-code-review only for explicit frontend review or audit requests, including test reviews. Use frontend-testing when writing or changing Vitest or React Testing Library tests.

Package Contracts

Web owns application-specific requirements and consumes shared architecture guidance from skills and primitive contracts from Dify UI. Link to those owners instead of redefining their rules here.

• For truncated text disclosure and native title decisions, follow Truncated Text Disclosure.
• Before adding or keeping a toast, follow Toasts. A toast is only for a result the user cannot see where they acted.
• When adding or changing page layouts, navigation, or landmark elements, follow Page landmarks and inspect the composed page, including parent layouts.
• User-facing strings must use web/i18n/locales/en-US/ keys. When adding or renaming a key, update every supported locale with the correct localized value.
• For new backend calls and migrated surfaces, use generated consoleQuery / consoleClient APIs from @/service/console. Do not add handwritten REST helpers or DTO mirrors, mock-backed app state, or direct edits to generated contracts.
• Prefer @langgenius/dify-ui/* primitives, data attributes, and design tokens. Use the Dify UI package index to find a primitive; read the relevant contract directly when it is already known. Preserve a visible focus indicator on the final focusable element.
• Reuse the Web SearchInput composite when its search, clear, and IME contract matches the feature; otherwise follow the canonical Input Group contract.
• Give save and submit flows a real form boundary with visible labels and accessible errors. Use Dify UI Form when its structured submission and validation contract is the owner; otherwise use a native form. Follow the canonical form contract.
• Follow the canonical Button contract and IconButton contract for action semantics, loading, accessible names, and primitive composition. Do not add a Web wrapper that hides those contracts.
• Follow Keyboard commands for hotkey ownership, targets, event consumption, typed bindings, and keycap display. Keep widget and editor keyboard semantics in their local owners.
• Follow Accessible names and descriptions when choosing or changing visible labels, ARIA naming, descriptions, or visually hidden text. Web owns localization and feature-specific status announcements; do not redefine the Dify UI naming contract locally.
• Before switching UI by viewport width, read Responsive layout: one component tree, CSS for appearance, width in JavaScript only for behaviour.
• Follow the Dify UI overlay contract for primitive selection, portals, focus, and layering. Use @langgenius/dify-ui/infotip for an info glyph that opens explanatory content. Do not introduce a generic Web wrapper that recreates Dify UI overlay behavior.
• For custom SVG icons, follow ../packages/iconify-collections/README.md; do not add generated React icons under app/components/base/icons/src/.
• docs/test.md is the single source of truth for Web automated-test policy. Skills may route and execute that policy but must not redefine it.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.