feat: initial commit
This commit is contained in:
143
.agents/skills/find-skills/SKILL.md
Normal file
143
.agents/skills/find-skills/SKILL.md
Normal file
@@ -0,0 +1,143 @@
|
|||||||
|
---
|
||||||
|
name: find-skills
|
||||||
|
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Find Skills
|
||||||
|
|
||||||
|
This skill helps you discover and install skills from the open agent skills ecosystem.
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
Use this skill when the user:
|
||||||
|
|
||||||
|
- Asks "how do I do X" where X might be a common task with an existing skill
|
||||||
|
- Says "find a skill for X" or "is there a skill for X"
|
||||||
|
- Asks "can you do X" where X is a specialized capability
|
||||||
|
- Expresses interest in extending agent capabilities
|
||||||
|
- Wants to search for tools, templates, or workflows
|
||||||
|
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
|
||||||
|
|
||||||
|
## What is the Skills CLI?
|
||||||
|
|
||||||
|
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
|
||||||
|
|
||||||
|
**Key commands:**
|
||||||
|
|
||||||
|
- `npx skills find [query]` - Search for skills interactively or by keyword
|
||||||
|
- `npx skills add <package>` - Install a skill from GitHub or other sources
|
||||||
|
- `npx skills check` - Check for skill updates
|
||||||
|
- `npx skills update` - Update all installed skills
|
||||||
|
|
||||||
|
**Browse skills at:** https://skills.sh/
|
||||||
|
|
||||||
|
## How to Help Users Find Skills
|
||||||
|
|
||||||
|
### Step 1: Understand What They Need
|
||||||
|
|
||||||
|
When a user asks for help with something, identify:
|
||||||
|
|
||||||
|
1. The domain (e.g., React, testing, design, deployment)
|
||||||
|
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
|
||||||
|
3. Whether this is a common enough task that a skill likely exists
|
||||||
|
|
||||||
|
### Step 2: Check the Leaderboard First
|
||||||
|
|
||||||
|
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
|
||||||
|
|
||||||
|
For example, top skills for web development include:
|
||||||
|
|
||||||
|
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
|
||||||
|
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
|
||||||
|
|
||||||
|
### Step 3: Search for Skills
|
||||||
|
|
||||||
|
If the leaderboard doesn't cover the user's need, run the find command:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx skills find [query]
|
||||||
|
```
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
- User asks "how do I make my React app faster?" → `npx skills find react performance`
|
||||||
|
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
|
||||||
|
- User asks "I need to create a changelog" → `npx skills find changelog`
|
||||||
|
|
||||||
|
### Step 4: Verify Quality Before Recommending
|
||||||
|
|
||||||
|
**Do not recommend a skill based solely on search results.** Always verify:
|
||||||
|
|
||||||
|
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
|
||||||
|
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
|
||||||
|
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
|
||||||
|
|
||||||
|
### Step 5: Present Options to the User
|
||||||
|
|
||||||
|
When you find relevant skills, present them to the user with:
|
||||||
|
|
||||||
|
1. The skill name and what it does
|
||||||
|
2. The install count and source
|
||||||
|
3. The install command they can run
|
||||||
|
4. A link to learn more at skills.sh
|
||||||
|
|
||||||
|
Example response:
|
||||||
|
|
||||||
|
```
|
||||||
|
I found a skill that might help! The "react-best-practices" skill provides
|
||||||
|
React and Next.js performance optimization guidelines from Vercel Engineering.
|
||||||
|
(185K installs)
|
||||||
|
|
||||||
|
To install it:
|
||||||
|
npx skills add vercel-labs/agent-skills@react-best-practices
|
||||||
|
|
||||||
|
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Offer to Install
|
||||||
|
|
||||||
|
If the user wants to proceed, you can install the skill for them:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx skills add <owner/repo@skill> -g -y
|
||||||
|
```
|
||||||
|
|
||||||
|
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
|
||||||
|
|
||||||
|
## Common Skill Categories
|
||||||
|
|
||||||
|
When searching, consider these common categories:
|
||||||
|
|
||||||
|
| Category | Example Queries |
|
||||||
|
| --------------- | ---------------------------------------- |
|
||||||
|
| Web Development | react, nextjs, typescript, css, tailwind |
|
||||||
|
| Testing | testing, jest, playwright, e2e |
|
||||||
|
| DevOps | deploy, docker, kubernetes, ci-cd |
|
||||||
|
| Documentation | docs, readme, changelog, api-docs |
|
||||||
|
| Code Quality | review, lint, refactor, best-practices |
|
||||||
|
| Design | ui, ux, design-system, accessibility |
|
||||||
|
| Productivity | workflow, automation, git |
|
||||||
|
|
||||||
|
## Tips for Effective Searches
|
||||||
|
|
||||||
|
1. **Use specific keywords**: "react testing" is better than just "testing"
|
||||||
|
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
|
||||||
|
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
|
||||||
|
|
||||||
|
## When No Skills Are Found
|
||||||
|
|
||||||
|
If no relevant skills exist:
|
||||||
|
|
||||||
|
1. Acknowledge that no existing skill was found
|
||||||
|
2. Offer to help with the task directly using your general capabilities
|
||||||
|
3. Suggest the user could create their own skill with `npx skills init`
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```
|
||||||
|
I searched for skills related to "xyz" but didn't find any matches.
|
||||||
|
I can still help you with this task directly! Would you like me to proceed?
|
||||||
|
|
||||||
|
If this is something you do often, you could create your own skill:
|
||||||
|
npx skills init my-xyz-skill
|
||||||
|
```
|
||||||
177
.agents/skills/frontend-design/LICENSE.txt
Normal file
177
.agents/skills/frontend-design/LICENSE.txt
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
45
.agents/skills/frontend-design/SKILL.md
Normal file
45
.agents/skills/frontend-design/SKILL.md
Normal file
@@ -0,0 +1,45 @@
|
|||||||
|
---
|
||||||
|
name: frontend-design
|
||||||
|
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||||
|
license: Complete terms in LICENSE.txt
|
||||||
|
---
|
||||||
|
|
||||||
|
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||||
|
|
||||||
|
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||||
|
|
||||||
|
## Design Thinking
|
||||||
|
|
||||||
|
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||||
|
|
||||||
|
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||||
|
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||||
|
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||||
|
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||||
|
|
||||||
|
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||||
|
|
||||||
|
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||||
|
|
||||||
|
- Production-grade and functional
|
||||||
|
- Visually striking and memorable
|
||||||
|
- Cohesive with a clear aesthetic point-of-view
|
||||||
|
- Meticulously refined in every detail
|
||||||
|
|
||||||
|
## Frontend Aesthetics Guidelines
|
||||||
|
|
||||||
|
Focus on:
|
||||||
|
|
||||||
|
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||||
|
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||||
|
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||||
|
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||||
|
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||||
|
|
||||||
|
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||||
|
|
||||||
|
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||||
|
|
||||||
|
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||||
|
|
||||||
|
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||||
615
.agents/skills/kiranism-shadcn-dashboard/SKILL.md
Normal file
615
.agents/skills/kiranism-shadcn-dashboard/SKILL.md
Normal file
@@ -0,0 +1,615 @@
|
|||||||
|
---
|
||||||
|
name: kiranism-shadcn-dashboard
|
||||||
|
description: |
|
||||||
|
Guide for building features, pages, tables, forms, themes, and navigation in this Next.js 16 shadcn dashboard template. Use this skill whenever the user wants to add a new page, create a feature module, build a data table, add a form, configure navigation items, add a theme, set up RBAC access control, or work with the dashboard's patterns and conventions. Also triggers when adding routes under /dashboard, working with Clerk auth/orgs/billing, creating mock APIs, or modifying the sidebar. Even if the user doesn't mention "dashboard" explicitly — if they're adding UI, pages, or features to this project, use this skill.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Dashboard Development Guide
|
||||||
|
|
||||||
|
This skill encodes the exact patterns and conventions used in this Next.js 16 + shadcn/ui admin dashboard template.
|
||||||
|
|
||||||
|
## Quick Reference: What Goes Where
|
||||||
|
|
||||||
|
| Task | Location |
|
||||||
|
| --------------------- | --------------------------------------- |
|
||||||
|
| New page | `src/app/dashboard/<name>/page.tsx` |
|
||||||
|
| New feature module | `src/features/<name>/` |
|
||||||
|
| Feature components | `src/features/<name>/components/` |
|
||||||
|
| API types | `src/features/<name>/api/types.ts` |
|
||||||
|
| Service layer | `src/features/<name>/api/service.ts` |
|
||||||
|
| Query options | `src/features/<name>/api/queries.ts` |
|
||||||
|
| Mutation options | `src/features/<name>/api/mutations.ts` |
|
||||||
|
| Zod schemas | `src/features/<name>/schemas/<name>.ts` |
|
||||||
|
| Filter/select options | `src/features/<name>/constants/` |
|
||||||
|
| Nav config | `src/config/nav-config.ts` |
|
||||||
|
| Types | `src/types/index.ts` |
|
||||||
|
| Mock data | `src/constants/mock-api-<name>.ts` |
|
||||||
|
| Search params | `src/lib/searchparams.ts` |
|
||||||
|
| Query client | `src/lib/query-client.ts` |
|
||||||
|
| Theme CSS | `src/styles/themes/<name>.css` |
|
||||||
|
| Theme registry | `src/components/themes/theme.config.ts` |
|
||||||
|
| Custom hook | `src/hooks/` |
|
||||||
|
| Icons registry | `src/components/icons.tsx` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adding a New Feature (End-to-End)
|
||||||
|
|
||||||
|
When a user asks to add a feature (e.g., "add an orders page"), follow these steps in order. Each step below shows the minimal pattern — see reference files for full templates.
|
||||||
|
|
||||||
|
### Step 1: Mock API (`src/constants/mock-api-<name>.ts`)
|
||||||
|
|
||||||
|
See [references/mock-api-guide.md](references/mock-api-guide.md) for the complete template. Key structure:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { faker } from '@faker-js/faker';
|
||||||
|
import { matchSorter } from 'match-sorter';
|
||||||
|
import { delay } from './mock-api';
|
||||||
|
|
||||||
|
export type Order = {
|
||||||
|
id: number;
|
||||||
|
customer: string;
|
||||||
|
status: string;
|
||||||
|
total: number;
|
||||||
|
created_at: string;
|
||||||
|
updated_at: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
export const fakeOrders = {
|
||||||
|
records: [] as Order[],
|
||||||
|
initialize() {
|
||||||
|
/* generate with faker */
|
||||||
|
},
|
||||||
|
async getOrders({ page, limit, search, sort }) {
|
||||||
|
/* filter, sort, paginate, return { items, total_items } */
|
||||||
|
},
|
||||||
|
async getOrderById(id: number) {
|
||||||
|
/* find by id */
|
||||||
|
},
|
||||||
|
async createOrder(data) {
|
||||||
|
/* push to records */
|
||||||
|
},
|
||||||
|
async updateOrder(id, data) {
|
||||||
|
/* merge into record */
|
||||||
|
},
|
||||||
|
async deleteOrder(id) {
|
||||||
|
/* filter out */
|
||||||
|
}
|
||||||
|
};
|
||||||
|
fakeOrders.initialize();
|
||||||
|
```
|
||||||
|
|
||||||
|
Every method should call `await delay(800)` to simulate network latency. Use `matchSorter` for search. Return `{ items, total_items }` from list methods.
|
||||||
|
|
||||||
|
### Step 2: API Layer (`src/features/<name>/api/`)
|
||||||
|
|
||||||
|
Each feature has 4 API files: **types** → **service** → **queries** → **mutations**.
|
||||||
|
|
||||||
|
**Types** (`api/types.ts`) — re-export the entity type from mock API, plus filter/response/payload types:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export type { Order } from '@/constants/mock-api-orders';
|
||||||
|
export type OrderFilters = { page?: number; limit?: number; search?: string; sort?: string };
|
||||||
|
export type OrdersResponse = { items: Order[]; total_items: number };
|
||||||
|
export type OrderMutationPayload = { customer: string; status: string; total: number };
|
||||||
|
```
|
||||||
|
|
||||||
|
**Service** (`api/service.ts`) — data access layer. One exported function per operation:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { fakeOrders } from '@/constants/mock-api-orders';
|
||||||
|
import type { OrderFilters, OrdersResponse, OrderMutationPayload } from './types';
|
||||||
|
|
||||||
|
export async function getOrders(filters: OrderFilters): Promise<OrdersResponse> {
|
||||||
|
return fakeOrders.getOrders(filters);
|
||||||
|
}
|
||||||
|
export async function getOrderById(id: number) {
|
||||||
|
return fakeOrders.getOrderById(id);
|
||||||
|
}
|
||||||
|
export async function createOrder(data: OrderMutationPayload) {
|
||||||
|
return fakeOrders.createOrder(data);
|
||||||
|
}
|
||||||
|
export async function updateOrder(id: number, data: OrderMutationPayload) {
|
||||||
|
return fakeOrders.updateOrder(id, data);
|
||||||
|
}
|
||||||
|
export async function deleteOrder(id: number) {
|
||||||
|
return fakeOrders.deleteOrder(id);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Queries** (`api/queries.ts`) — query key factory + query options:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { queryOptions } from '@tanstack/react-query';
|
||||||
|
import { getOrders, getOrderById } from './service';
|
||||||
|
import type { Order, OrderFilters } from './types';
|
||||||
|
|
||||||
|
export type { Order };
|
||||||
|
|
||||||
|
export const orderKeys = {
|
||||||
|
all: ['orders'] as const,
|
||||||
|
list: (filters: OrderFilters) => [...orderKeys.all, 'list', filters] as const,
|
||||||
|
detail: (id: number) => [...orderKeys.all, 'detail', id] as const
|
||||||
|
};
|
||||||
|
|
||||||
|
export const ordersQueryOptions = (filters: OrderFilters) =>
|
||||||
|
queryOptions({
|
||||||
|
queryKey: orderKeys.list(filters),
|
||||||
|
queryFn: () => getOrders(filters)
|
||||||
|
});
|
||||||
|
|
||||||
|
export const orderByIdOptions = (id: number) =>
|
||||||
|
queryOptions({
|
||||||
|
queryKey: orderKeys.detail(id),
|
||||||
|
queryFn: () => getOrderById(id)
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Mutations** (`api/mutations.ts`) — use `mutationOptions` + `getQueryClient()` (not custom hooks with `useQueryClient()`):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { mutationOptions } from '@tanstack/react-query';
|
||||||
|
import { getQueryClient } from '@/lib/query-client';
|
||||||
|
import { createOrder, updateOrder, deleteOrder } from './service';
|
||||||
|
import { orderKeys } from './queries';
|
||||||
|
import type { OrderMutationPayload } from './types';
|
||||||
|
|
||||||
|
export const createOrderMutation = mutationOptions({
|
||||||
|
mutationFn: (data: OrderMutationPayload) => createOrder(data),
|
||||||
|
onSuccess: () => {
|
||||||
|
getQueryClient().invalidateQueries({ queryKey: orderKeys.all });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
export const updateOrderMutation = mutationOptions({
|
||||||
|
mutationFn: ({ id, values }: { id: number; values: OrderMutationPayload }) =>
|
||||||
|
updateOrder(id, values),
|
||||||
|
onSuccess: () => {
|
||||||
|
getQueryClient().invalidateQueries({ queryKey: orderKeys.all });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
export const deleteOrderMutation = mutationOptions({
|
||||||
|
mutationFn: (id: number) => deleteOrder(id),
|
||||||
|
onSuccess: () => {
|
||||||
|
getQueryClient().invalidateQueries({ queryKey: orderKeys.all });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
`mutationOptions` is the right abstraction because it works outside React (event handlers, tests, utilities), composes via spread at the call site, and uses `getQueryClient()` which handles both SSR (fresh per request) and client (singleton) correctly. See [references/query-abstractions.md](references/query-abstractions.md) for the full rationale.
|
||||||
|
|
||||||
|
### Step 3: Zod Schema (`src/features/<name>/schemas/<name>.ts`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { z } from 'zod';
|
||||||
|
|
||||||
|
export const orderSchema = z.object({
|
||||||
|
customer: z.string().min(2, 'Customer name must be at least 2 characters'),
|
||||||
|
status: z.string().min(1, 'Please select a status'),
|
||||||
|
total: z.number({ message: 'Total is required' })
|
||||||
|
});
|
||||||
|
|
||||||
|
export type OrderFormValues = z.infer<typeof orderSchema>;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Feature Components
|
||||||
|
|
||||||
|
Create `src/features/<name>/components/` with:
|
||||||
|
|
||||||
|
**Listing page** (server component — `<name>-listing.tsx`):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { HydrationBoundary, dehydrate } from '@tanstack/react-query';
|
||||||
|
import { getQueryClient } from '@/lib/query-client';
|
||||||
|
import { searchParamsCache } from '@/lib/searchparams';
|
||||||
|
import { ordersQueryOptions } from '../api/queries';
|
||||||
|
import { OrderTable, OrderTableSkeleton } from './orders-table';
|
||||||
|
import { Suspense } from 'react';
|
||||||
|
|
||||||
|
export default function OrderListingPage() {
|
||||||
|
const page = searchParamsCache.get('page');
|
||||||
|
const search = searchParamsCache.get('name');
|
||||||
|
const pageLimit = searchParamsCache.get('perPage');
|
||||||
|
const sort = searchParamsCache.get('sort');
|
||||||
|
|
||||||
|
const filters = {
|
||||||
|
page,
|
||||||
|
limit: pageLimit,
|
||||||
|
...(search && { search }),
|
||||||
|
...(sort && { sort })
|
||||||
|
};
|
||||||
|
|
||||||
|
const queryClient = getQueryClient();
|
||||||
|
void queryClient.prefetchQuery(ordersQueryOptions(filters));
|
||||||
|
|
||||||
|
return (
|
||||||
|
<HydrationBoundary state={dehydrate(queryClient)}>
|
||||||
|
<Suspense fallback={<OrderTableSkeleton />}>
|
||||||
|
<OrderTable />
|
||||||
|
</Suspense>
|
||||||
|
</HydrationBoundary>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Table + skeleton** (client component — `orders-table/index.tsx`):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { useSuspenseQuery } from '@tanstack/react-query';
|
||||||
|
import { parseAsInteger, parseAsString, useQueryStates } from 'nuqs';
|
||||||
|
import { getSortingStateParser } from '@/lib/parsers';
|
||||||
|
import { useDataTable } from '@/hooks/use-data-table';
|
||||||
|
import { DataTable } from '@/components/ui/table/data-table';
|
||||||
|
import { DataTableToolbar } from '@/components/ui/table/data-table-toolbar';
|
||||||
|
import { Skeleton } from '@/components/ui/skeleton';
|
||||||
|
import { ordersQueryOptions } from '../../api/queries';
|
||||||
|
import { columns } from './columns';
|
||||||
|
|
||||||
|
const columnIds = columns.map((c) => c.id).filter(Boolean) as string[];
|
||||||
|
|
||||||
|
export function OrderTable() {
|
||||||
|
const [params] = useQueryStates({
|
||||||
|
page: parseAsInteger.withDefault(1),
|
||||||
|
perPage: parseAsInteger.withDefault(10),
|
||||||
|
name: parseAsString,
|
||||||
|
sort: getSortingStateParser(columnIds).withDefault([])
|
||||||
|
});
|
||||||
|
|
||||||
|
const filters = {
|
||||||
|
page: params.page,
|
||||||
|
limit: params.perPage,
|
||||||
|
...(params.name && { search: params.name }),
|
||||||
|
...(params.sort.length > 0 && { sort: JSON.stringify(params.sort) })
|
||||||
|
};
|
||||||
|
|
||||||
|
const { data } = useSuspenseQuery(ordersQueryOptions(filters));
|
||||||
|
|
||||||
|
const { table } = useDataTable({
|
||||||
|
data: data.items,
|
||||||
|
columns,
|
||||||
|
pageCount: Math.ceil(data.total_items / params.perPage),
|
||||||
|
shallow: true,
|
||||||
|
debounceMs: 500,
|
||||||
|
initialState: { columnPinning: { right: ['actions'] } }
|
||||||
|
});
|
||||||
|
|
||||||
|
return (
|
||||||
|
<DataTable table={table}>
|
||||||
|
<DataTableToolbar table={table} />
|
||||||
|
</DataTable>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
export function OrderTableSkeleton() {
|
||||||
|
return (
|
||||||
|
<div className='space-y-4 p-4'>
|
||||||
|
<Skeleton className='h-10 w-full' />
|
||||||
|
<Skeleton className='h-96 w-full' />
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Column definitions** (`orders-table/columns.tsx`):
|
||||||
|
|
||||||
|
Each column needs `id`, `accessorKey` (or `accessorFn`), `header` with `DataTableColumnHeader`, and optionally `meta` for filtering + `enableColumnFilter: true`.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export const columns: ColumnDef<Order>[] = [
|
||||||
|
{
|
||||||
|
id: 'customer',
|
||||||
|
accessorKey: 'customer',
|
||||||
|
header: ({ column }) => <DataTableColumnHeader column={column} title='Customer' />,
|
||||||
|
meta: { label: 'Customer', placeholder: 'Search...', variant: 'text', icon: Icons.text },
|
||||||
|
enableColumnFilter: true
|
||||||
|
},
|
||||||
|
{
|
||||||
|
id: 'status',
|
||||||
|
accessorKey: 'status',
|
||||||
|
header: ({ column }) => <DataTableColumnHeader column={column} title='Status' />,
|
||||||
|
cell: ({ cell }) => (
|
||||||
|
<Badge variant='outline' className='capitalize'>
|
||||||
|
{cell.getValue<string>()}
|
||||||
|
</Badge>
|
||||||
|
),
|
||||||
|
enableColumnFilter: true,
|
||||||
|
meta: { label: 'Status', variant: 'multiSelect', options: STATUS_OPTIONS }
|
||||||
|
},
|
||||||
|
{ id: 'actions', cell: ({ row }) => <CellAction data={row.original} /> }
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
Filter `meta.variant` options: `text`, `number`, `range`, `date`, `dateRange`, `select`, `multiSelect`, `boolean`. For multiSelect, provide `options: { value, label, icon? }[]`.
|
||||||
|
|
||||||
|
**Cell actions** (`orders-table/cell-action.tsx`):
|
||||||
|
|
||||||
|
Pattern: `DropdownMenu` with edit/delete items + `AlertModal` for delete confirmation + `useMutation` for the delete API call.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { deleteOrderMutation } from '../../api/mutations';
|
||||||
|
|
||||||
|
export const CellAction: React.FC<{ data: Order }> = ({ data }) => {
|
||||||
|
const [deleteOpen, setDeleteOpen] = useState(false);
|
||||||
|
const deleteMutation = useMutation({
|
||||||
|
...deleteOrderMutation,
|
||||||
|
onSuccess: () => {
|
||||||
|
toast.success('Deleted');
|
||||||
|
setDeleteOpen(false);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
return (
|
||||||
|
<>
|
||||||
|
<AlertModal
|
||||||
|
isOpen={deleteOpen}
|
||||||
|
onClose={() => setDeleteOpen(false)}
|
||||||
|
onConfirm={() => deleteMutation.mutate(data.id)}
|
||||||
|
loading={deleteMutation.isPending}
|
||||||
|
/>
|
||||||
|
<DropdownMenu modal={false}>
|
||||||
|
<DropdownMenuTrigger asChild>
|
||||||
|
<Button variant='ghost' className='h-8 w-8 p-0'>
|
||||||
|
<Icons.ellipsis className='h-4 w-4' />
|
||||||
|
</Button>
|
||||||
|
</DropdownMenuTrigger>
|
||||||
|
<DropdownMenuContent align='end'>
|
||||||
|
<DropdownMenuLabel>Actions</DropdownMenuLabel>
|
||||||
|
<DropdownMenuItem onClick={() => router.push(`/dashboard/orders/${data.id}`)}>
|
||||||
|
<Icons.edit className='mr-2 h-4 w-4' /> Edit
|
||||||
|
</DropdownMenuItem>
|
||||||
|
<DropdownMenuItem onClick={() => setDeleteOpen(true)}>
|
||||||
|
<Icons.trash className='mr-2 h-4 w-4' /> Delete
|
||||||
|
</DropdownMenuItem>
|
||||||
|
</DropdownMenuContent>
|
||||||
|
</DropdownMenu>
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
For **sheet-based editing** (like Users), replace `router.push` with opening a `<FormSheet>` — see the Forms section below.
|
||||||
|
|
||||||
|
### Step 5: Page Route (`src/app/dashboard/<name>/page.tsx`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import PageContainer from '@/components/layout/page-container';
|
||||||
|
import OrderListingPage from '@/features/orders/components/order-listing';
|
||||||
|
import { searchParamsCache } from '@/lib/searchparams';
|
||||||
|
import type { SearchParams } from 'nuqs/server';
|
||||||
|
|
||||||
|
export const metadata = { title: 'Dashboard: Orders' };
|
||||||
|
type PageProps = { searchParams: Promise<SearchParams> };
|
||||||
|
|
||||||
|
export default async function Page(props: PageProps) {
|
||||||
|
const searchParams = await props.searchParams;
|
||||||
|
searchParamsCache.parse(searchParams);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<PageContainer
|
||||||
|
scrollable={false}
|
||||||
|
pageTitle='Orders'
|
||||||
|
pageDescription='Manage your orders.'
|
||||||
|
pageHeaderAction={/* Add button — Link or SheetTrigger */}
|
||||||
|
>
|
||||||
|
<OrderListingPage />
|
||||||
|
</PageContainer>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**PageContainer props**: `scrollable`, `pageTitle`, `pageDescription`, `pageHeaderAction` (React node for the top-right button), `infoContent` (help sidebar), `access` + `accessFallback` (RBAC gating).
|
||||||
|
|
||||||
|
**Detail/Edit page** (`src/app/dashboard/<name>/[id]/page.tsx`):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import PageContainer from '@/components/layout/page-container';
|
||||||
|
import OrderViewPage from '@/features/orders/components/order-view-page';
|
||||||
|
|
||||||
|
export const metadata = { title: 'Dashboard: Order Details' };
|
||||||
|
type PageProps = { params: Promise<{ id: string }> };
|
||||||
|
|
||||||
|
export default async function Page(props: PageProps) {
|
||||||
|
const { id } = await props.params;
|
||||||
|
return (
|
||||||
|
<PageContainer scrollable pageTitle='Order Details'>
|
||||||
|
<OrderViewPage orderId={id} />
|
||||||
|
</PageContainer>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**View page component** (client — handles new vs edit):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { useSuspenseQuery } from '@tanstack/react-query';
|
||||||
|
import { notFound } from 'next/navigation';
|
||||||
|
import { orderByIdOptions } from '../api/queries';
|
||||||
|
import OrderForm from './order-form';
|
||||||
|
|
||||||
|
export default function OrderViewPage({ orderId }: { orderId: string }) {
|
||||||
|
if (orderId === 'new') return <OrderForm initialData={null} pageTitle='Create Order' />;
|
||||||
|
const { data } = useSuspenseQuery(orderByIdOptions(Number(orderId)));
|
||||||
|
if (!data) notFound();
|
||||||
|
return <OrderForm initialData={data} pageTitle='Edit Order' />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6: Search Params (`src/lib/searchparams.ts`)
|
||||||
|
|
||||||
|
Add any new filter keys. Existing params: `page`, `perPage`, `name`, `gender`, `category`, `role`, `sort`.
|
||||||
|
|
||||||
|
### Step 7: Navigation (`src/config/nav-config.ts`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
{ title: 'Orders', url: '/dashboard/orders', icon: 'product', items: [] }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 8: Icons (`src/components/icons.tsx`)
|
||||||
|
|
||||||
|
To register a new icon, import from `@tabler/icons-react` and add to the `Icons` object:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { IconShoppingCart } from '@tabler/icons-react';
|
||||||
|
export const Icons = { /* ...existing */ cart: IconShoppingCart };
|
||||||
|
```
|
||||||
|
|
||||||
|
Never import `@tabler/icons-react` anywhere else. Always use `Icons.keyName`.
|
||||||
|
|
||||||
|
**Existing icon keys** (partial): `dashboard`, `product`, `kanban`, `chat`, `forms`, `user`, `teams`, `billing`, `settings`, `add`, `edit`, `trash`, `search`, `check`, `close`, `clock`, `ellipsis`, `text`, `calendar`, `upload`, `spinner`, `chevronDown/Left/Right/Up`, `sun`, `moon`, `palette`, `pro`, `workspace`, `notification`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Forms
|
||||||
|
|
||||||
|
Forms use **TanStack Form + Zod** with `useAppForm` + `useFormFields<T>()` and `useMutation` for submission. See [references/forms-guide.md](references/forms-guide.md) for all field types, validation strategies, multi-step forms, and advanced patterns.
|
||||||
|
|
||||||
|
### Page Form (Create/Edit on a dedicated route)
|
||||||
|
|
||||||
|
The full pattern is shown in Steps 1-4 above. The key structure:
|
||||||
|
|
||||||
|
1. **Schema** — Zod schema + inferred type in `schemas/<name>.ts`
|
||||||
|
2. **Form component** — `useAppForm({ defaultValues, validators: { onSubmit: schema }, onSubmit })` + `useFormFields<T>()` for typed fields
|
||||||
|
3. **Mutations** — `useMutation({ ...createOrderMutation, onSuccess: () => { toast(); router.push() } })`, spread shared mutation options from `api/mutations.ts` and layer on UI callbacks
|
||||||
|
4. **View page** — client component that checks `id === 'new'` for create vs `useSuspenseQuery(byIdOptions)` for edit
|
||||||
|
|
||||||
|
### Sheet Form (Inline create/edit in a side panel)
|
||||||
|
|
||||||
|
For features where a separate page is overkill (like Users). The sheet manages open state; the form uses a `form` attribute to connect to the sheet footer's submit button.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { Sheet, SheetContent, SheetFooter, SheetHeader, SheetTitle } from '@/components/ui/sheet';
|
||||||
|
|
||||||
|
export function OrderFormSheet({
|
||||||
|
order,
|
||||||
|
open,
|
||||||
|
onOpenChange
|
||||||
|
}: {
|
||||||
|
order?: Order;
|
||||||
|
open: boolean;
|
||||||
|
onOpenChange: (open: boolean) => void;
|
||||||
|
}) {
|
||||||
|
const isEdit = !!order;
|
||||||
|
const mutation = useMutation({
|
||||||
|
...(isEdit ? updateOrderMutation : createOrderMutation),
|
||||||
|
onSuccess: () => {
|
||||||
|
onOpenChange(false);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
const form = useAppForm({
|
||||||
|
defaultValues: { customer: order?.customer ?? '' /* ... */ } as OrderFormValues,
|
||||||
|
validators: { onSubmit: orderSchema },
|
||||||
|
onSubmit: async ({ value }) => {
|
||||||
|
await mutation.mutateAsync(value);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
const { FormTextField, FormSelectField } = useFormFields<OrderFormValues>();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Sheet open={open} onOpenChange={onOpenChange}>
|
||||||
|
<SheetContent className='flex flex-col'>
|
||||||
|
<SheetHeader>
|
||||||
|
<SheetTitle>{isEdit ? 'Edit' : 'New'} Order</SheetTitle>
|
||||||
|
</SheetHeader>
|
||||||
|
<div className='flex-1 overflow-auto'>
|
||||||
|
<form.AppForm>
|
||||||
|
<form.Form id='order-sheet-form' className='space-y-4'>
|
||||||
|
<FormTextField name='customer' label='Customer' required />
|
||||||
|
<FormSelectField name='status' label='Status' required options={STATUS_OPTIONS} />
|
||||||
|
</form.Form>
|
||||||
|
</form.AppForm>
|
||||||
|
</div>
|
||||||
|
<SheetFooter>
|
||||||
|
<Button variant='outline' onClick={() => onOpenChange(false)}>
|
||||||
|
Cancel
|
||||||
|
</Button>
|
||||||
|
<Button type='submit' form='order-sheet-form' disabled={mutation.isPending}>
|
||||||
|
{mutation.isPending ? 'Saving...' : isEdit ? 'Update' : 'Create'}
|
||||||
|
</Button>
|
||||||
|
</SheetFooter>
|
||||||
|
</SheetContent>
|
||||||
|
</Sheet>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For cell actions, add `const [editOpen, setEditOpen] = useState(false)` and render `<OrderFormSheet order={data} open={editOpen} onOpenChange={setEditOpen} />` with a `<DropdownMenuItem onClick={() => setEditOpen(true)}>`. For the page header "Add" button, create a trigger component that manages `open` state and renders the sheet.
|
||||||
|
|
||||||
|
**Available field components** from `useFormFields<T>()`: `FormTextField`, `FormTextareaField`, `FormSelectField`, `FormCheckboxField`, `FormSwitchField`, `FormRadioGroupField`, `FormSliderField`, `FormFileUploadField`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Fetching with React Query
|
||||||
|
|
||||||
|
The pattern is: server prefetch → HydrationBoundary → client useSuspenseQuery.
|
||||||
|
|
||||||
|
1. **Server**: `void queryClient.prefetchQuery(options)` — fire-and-forget during SSR streaming
|
||||||
|
2. **Client**: `useSuspenseQuery(options)` — picks up dehydrated data, suspends until resolved
|
||||||
|
3. **HydrationBoundary + dehydrate**: bridges server cache → client cache
|
||||||
|
4. **Suspense fallback**: skeleton shown while data streams
|
||||||
|
|
||||||
|
**Why `useSuspenseQuery` not `useQuery`:** `useQuery` doesn't integrate with Suspense — it shows loading even when data is prefetched. `useSuspenseQuery` picks up the dehydrated pending query. Once cached (within `staleTime: 60s`), subsequent visits are instant.
|
||||||
|
|
||||||
|
**Mutations** use `mutationOptions` + `getQueryClient()` in `mutations.ts`, composed via spread at the call site:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// In mutations.ts — shared config
|
||||||
|
export const createOrderMutation = mutationOptions({
|
||||||
|
mutationFn: (data) => createOrder(data),
|
||||||
|
onSuccess: () => {
|
||||||
|
getQueryClient().invalidateQueries({ queryKey: orderKeys.all });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// In component — spread + layer UI callbacks
|
||||||
|
const mutation = useMutation({
|
||||||
|
...createOrderMutation,
|
||||||
|
onSuccess: () => toast.success('Created')
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
See [references/query-abstractions.md](references/query-abstractions.md) for why `mutationOptions`/`queryOptions` are the right abstraction over custom hooks.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Navigation & RBAC
|
||||||
|
|
||||||
|
Configure in `src/config/nav-config.ts`. Items are filtered client-side in `src/hooks/use-nav.ts` using Clerk.
|
||||||
|
|
||||||
|
**Access control properties** on nav items:
|
||||||
|
|
||||||
|
- `requireOrg: boolean` — requires active Clerk organization
|
||||||
|
- `permission: string` — requires specific Clerk permission
|
||||||
|
- `role: string` — requires specific Clerk role
|
||||||
|
- `plan: string` — requires subscription plan (server-side)
|
||||||
|
- `feature: string` — requires feature flag (server-side)
|
||||||
|
|
||||||
|
Items without `access` are visible to everyone. All client-side checks are synchronous — no loading states.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Themes
|
||||||
|
|
||||||
|
See [references/theming-guide.md](references/theming-guide.md) for the complete guide. Quick steps:
|
||||||
|
|
||||||
|
1. Create `src/styles/themes/<name>.css` with OKLCH color tokens + `@theme inline` block
|
||||||
|
2. Import in `src/styles/theme.css`
|
||||||
|
3. Register in `THEMES` array in `src/components/themes/theme.config.ts`
|
||||||
|
4. (Optional) Add Google Fonts in `src/components/themes/font.config.ts`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Code Conventions
|
||||||
|
|
||||||
|
- **`cn()`** for class merging — never concatenate className strings
|
||||||
|
- **Server components by default** — only add `'use client'` when needed
|
||||||
|
- **React Query** — `void prefetchQuery()` on server + `useSuspenseQuery` on client
|
||||||
|
- **API layer** — `types.ts` → `service.ts` → `queries.ts` → `mutations.ts` per feature; `queryOptions`/`mutationOptions` as base abstractions (not custom hooks); `getQueryClient()` in mutations (not `useQueryClient()`); key factories (`entityKeys.all/list/detail`); components never import mock APIs directly
|
||||||
|
- **nuqs** — `searchParamsCache` on server, `useQueryStates` on client with `shallow: true`
|
||||||
|
- **Icons** — only from `@/components/icons`, never from `@tabler/icons-react` directly
|
||||||
|
- **Forms** — `useAppForm` + `useFormFields<T>()` from `@/components/ui/tanstack-form`
|
||||||
|
- **Page headers** — `PageContainer` props, never import `<Heading>` manually
|
||||||
|
- **Sort parser** — use `getSortingStateParser` from `@/lib/parsers` (same parser as `useDataTable`)
|
||||||
|
- **Formatting** — single quotes, JSX single quotes, no trailing comma, 2-space indent
|
||||||
@@ -0,0 +1,420 @@
|
|||||||
|
# Charts & Analytics Guide
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Overview Architecture](#overview-architecture)
|
||||||
|
2. [Parallel Routes Pattern](#parallel-routes-pattern)
|
||||||
|
3. [Chart Components](#chart-components)
|
||||||
|
4. [Stats Cards](#stats-cards)
|
||||||
|
5. [Skeleton Loading](#skeleton-loading)
|
||||||
|
6. [Adding a New Chart Section](#adding-a-new-chart-section)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview Architecture
|
||||||
|
|
||||||
|
The analytics dashboard at `/dashboard/overview` uses **Next.js parallel routes** to load multiple chart sections independently. Each chart slot streams in as its data becomes ready — no waterfall, no blocking.
|
||||||
|
|
||||||
|
**File structure:**
|
||||||
|
|
||||||
|
```
|
||||||
|
src/app/dashboard/overview/
|
||||||
|
├── layout.tsx # Composes all slots into a grid
|
||||||
|
├── @area_stats/
|
||||||
|
│ ├── page.tsx # Async server component (fetches data)
|
||||||
|
│ ├── loading.tsx # Skeleton shown while streaming
|
||||||
|
│ └── error.tsx # Error boundary if fetch fails
|
||||||
|
├── @bar_stats/
|
||||||
|
│ ├── page.tsx
|
||||||
|
│ ├── loading.tsx
|
||||||
|
│ └── error.tsx
|
||||||
|
├── @pie_stats/
|
||||||
|
│ ├── page.tsx
|
||||||
|
│ ├── loading.tsx
|
||||||
|
│ └── error.tsx
|
||||||
|
└── @sales/
|
||||||
|
├── page.tsx
|
||||||
|
├── loading.tsx
|
||||||
|
└── error.tsx
|
||||||
|
|
||||||
|
src/features/overview/components/
|
||||||
|
├── area-graph.tsx # Client chart component
|
||||||
|
├── area-graph-skeleton.tsx # Matching skeleton
|
||||||
|
├── bar-graph.tsx
|
||||||
|
├── bar-graph-skeleton.tsx
|
||||||
|
├── pie-graph.tsx
|
||||||
|
├── pie-graph-skeleton.tsx
|
||||||
|
├── recent-sales.tsx
|
||||||
|
└── recent-sales-skeleton.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Parallel Routes Pattern
|
||||||
|
|
||||||
|
### Layout (`layout.tsx`)
|
||||||
|
|
||||||
|
The layout receives each parallel route as a prop and arranges them in a grid:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function OverviewLayout({
|
||||||
|
sales,
|
||||||
|
pie_stats,
|
||||||
|
bar_stats,
|
||||||
|
area_stats
|
||||||
|
}: {
|
||||||
|
sales: React.ReactNode;
|
||||||
|
pie_stats: React.ReactNode;
|
||||||
|
bar_stats: React.ReactNode;
|
||||||
|
area_stats: React.ReactNode;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<PageContainer pageTitle='Dashboard' pageDescription='Overview analytics.'>
|
||||||
|
{/* Stats cards row */}
|
||||||
|
<div className='grid gap-4 md:grid-cols-2 lg:grid-cols-4'>
|
||||||
|
<Card>
|
||||||
|
<CardHeader className='flex flex-row items-center justify-between pb-2'>
|
||||||
|
<CardTitle className='text-sm font-medium'>Total Revenue</CardTitle>
|
||||||
|
<Icons.billing className='h-4 w-4 text-muted-foreground' />
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>
|
||||||
|
<div className='text-2xl font-bold'>$45,231.89</div>
|
||||||
|
<p className='text-xs text-muted-foreground'>+20.1% from last month</p>
|
||||||
|
</CardContent>
|
||||||
|
</Card>
|
||||||
|
{/* ...more stat cards */}
|
||||||
|
</div>
|
||||||
|
|
||||||
|
{/* Charts grid — each slot loads independently */}
|
||||||
|
<div className='grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-7'>
|
||||||
|
<div className='col-span-4'>{area_stats}</div>
|
||||||
|
<div className='col-span-3'>{sales}</div>
|
||||||
|
<div className='col-span-4'>{bar_stats}</div>
|
||||||
|
<div className='col-span-3'>{pie_stats}</div>
|
||||||
|
</div>
|
||||||
|
</PageContainer>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Slot Page (`@area_stats/page.tsx`)
|
||||||
|
|
||||||
|
Each slot is an async server component that fetches data then renders the chart:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { delay } from '@/constants/mock-api';
|
||||||
|
import { AreaGraph } from '@/features/overview/components/area-graph';
|
||||||
|
|
||||||
|
export default async function AreaStatsPage() {
|
||||||
|
await delay(2000); // Simulates API fetch
|
||||||
|
return <AreaGraph />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Slot Loading (`@area_stats/loading.tsx`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { AreaGraphSkeleton } from '@/features/overview/components/area-graph-skeleton';
|
||||||
|
|
||||||
|
export default function Loading() {
|
||||||
|
return <AreaGraphSkeleton />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Slot Error (`@area_stats/error.tsx`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
|
||||||
|
import { Icons } from '@/components/icons';
|
||||||
|
|
||||||
|
export default function AreaStatsError({ error }: { error: Error }) {
|
||||||
|
return (
|
||||||
|
<Alert variant='destructive'>
|
||||||
|
<Icons.alertCircle className='h-4 w-4' />
|
||||||
|
<AlertTitle>Error</AlertTitle>
|
||||||
|
<AlertDescription>Failed to load area stats: {error.message}</AlertDescription>
|
||||||
|
</Alert>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each slot can fail independently without affecting others.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Chart Components
|
||||||
|
|
||||||
|
All chart components are `'use client'` and use **Recharts** wrapped in shadcn's `ChartContainer`.
|
||||||
|
|
||||||
|
### Chart Config
|
||||||
|
|
||||||
|
Every chart defines a config object mapping data keys to labels and theme colors:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import {
|
||||||
|
type ChartConfig,
|
||||||
|
ChartContainer,
|
||||||
|
ChartTooltip,
|
||||||
|
ChartTooltipContent
|
||||||
|
} from '@/components/ui/chart';
|
||||||
|
|
||||||
|
const chartConfig = {
|
||||||
|
desktop: { label: 'Desktop', color: 'var(--chart-1)' },
|
||||||
|
mobile: { label: 'Mobile', color: 'var(--chart-2)' }
|
||||||
|
} satisfies ChartConfig;
|
||||||
|
```
|
||||||
|
|
||||||
|
Theme colors `--chart-1` through `--chart-5` are defined in each theme's CSS file and automatically adapt to light/dark mode.
|
||||||
|
|
||||||
|
### Area Chart Example
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { Area, AreaChart, CartesianGrid, XAxis } from 'recharts';
|
||||||
|
import {
|
||||||
|
type ChartConfig,
|
||||||
|
ChartContainer,
|
||||||
|
ChartTooltip,
|
||||||
|
ChartTooltipContent
|
||||||
|
} from '@/components/ui/chart';
|
||||||
|
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
|
||||||
|
import { Badge } from '@/components/ui/badge';
|
||||||
|
import { Icons } from '@/components/icons';
|
||||||
|
|
||||||
|
const chartData = [
|
||||||
|
{ month: 'January', desktop: 186, mobile: 80 },
|
||||||
|
{ month: 'February', desktop: 305, mobile: 200 }
|
||||||
|
// ...more months
|
||||||
|
];
|
||||||
|
|
||||||
|
const chartConfig = {
|
||||||
|
desktop: { label: 'Desktop', color: 'var(--chart-1)' },
|
||||||
|
mobile: { label: 'Mobile', color: 'var(--chart-2)' }
|
||||||
|
} satisfies ChartConfig;
|
||||||
|
|
||||||
|
export function AreaGraph() {
|
||||||
|
return (
|
||||||
|
<Card className='@container/card'>
|
||||||
|
<CardHeader>
|
||||||
|
<CardTitle>Area Chart - Stacked</CardTitle>
|
||||||
|
<Badge variant='outline'>
|
||||||
|
<Icons.trendingUp className='mr-1 h-3 w-3' /> +12.5%
|
||||||
|
</Badge>
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>
|
||||||
|
<ChartContainer config={chartConfig} className='aspect-auto h-[250px] w-full'>
|
||||||
|
<AreaChart data={chartData}>
|
||||||
|
<CartesianGrid vertical={false} />
|
||||||
|
<XAxis
|
||||||
|
dataKey='month'
|
||||||
|
tickLine={false}
|
||||||
|
axisLine={false}
|
||||||
|
tickFormatter={(value) => value.slice(0, 3)}
|
||||||
|
/>
|
||||||
|
<ChartTooltip content={<ChartTooltipContent indicator='dot' />} />
|
||||||
|
<Area
|
||||||
|
dataKey='mobile'
|
||||||
|
type='natural'
|
||||||
|
fill='var(--color-mobile)'
|
||||||
|
stroke='var(--color-mobile)'
|
||||||
|
stackId='a'
|
||||||
|
/>
|
||||||
|
<Area
|
||||||
|
dataKey='desktop'
|
||||||
|
type='natural'
|
||||||
|
fill='var(--color-desktop)'
|
||||||
|
stroke='var(--color-desktop)'
|
||||||
|
stackId='a'
|
||||||
|
/>
|
||||||
|
</AreaChart>
|
||||||
|
</ChartContainer>
|
||||||
|
</CardContent>
|
||||||
|
</Card>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bar Chart Pattern
|
||||||
|
|
||||||
|
Same structure, using `BarChart` + `Bar`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<ChartContainer config={chartConfig}>
|
||||||
|
<BarChart data={chartData}>
|
||||||
|
<CartesianGrid vertical={false} />
|
||||||
|
<XAxis dataKey='month' tickLine={false} axisLine={false} />
|
||||||
|
<ChartTooltip content={<ChartTooltipContent />} />
|
||||||
|
<Bar dataKey='desktop' fill='var(--color-desktop)' radius={4} />
|
||||||
|
<Bar dataKey='mobile' fill='var(--color-mobile)' radius={4} />
|
||||||
|
</BarChart>
|
||||||
|
</ChartContainer>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pie/Donut Chart Pattern
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<ChartContainer config={chartConfig}>
|
||||||
|
<PieChart>
|
||||||
|
<ChartTooltip content={<ChartTooltipContent hideLabel />} />
|
||||||
|
<Pie data={chartData} dataKey='visitors' nameKey='browser' innerRadius={30}>
|
||||||
|
<LabelList dataKey='visitors' className='fill-background' />
|
||||||
|
</Pie>
|
||||||
|
</PieChart>
|
||||||
|
</ChartContainer>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stats Cards
|
||||||
|
|
||||||
|
Stats cards are simple server-rendered `Card` components at the top of the layout — no parallel routes needed since they render instantly:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Card>
|
||||||
|
<CardHeader className='flex flex-row items-center justify-between space-y-0 pb-2'>
|
||||||
|
<CardTitle className='text-sm font-medium'>Total Revenue</CardTitle>
|
||||||
|
<Icons.billing className='h-4 w-4 text-muted-foreground' />
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>
|
||||||
|
<div className='text-2xl font-bold'>$45,231.89</div>
|
||||||
|
<p className='text-xs text-muted-foreground'>+20.1% from last month</p>
|
||||||
|
</CardContent>
|
||||||
|
</Card>
|
||||||
|
```
|
||||||
|
|
||||||
|
For dynamic stats that need data fetching, wrap in their own Suspense boundary or parallel route slot.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skeleton Loading
|
||||||
|
|
||||||
|
Each chart has a matching skeleton component. Pattern:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { Card, CardContent, CardHeader } from '@/components/ui/card';
|
||||||
|
import { Skeleton } from '@/components/ui/skeleton';
|
||||||
|
|
||||||
|
export function AreaGraphSkeleton() {
|
||||||
|
return (
|
||||||
|
<Card className='@container/card'>
|
||||||
|
<CardHeader>
|
||||||
|
<Skeleton className='h-5 w-[140px]' />
|
||||||
|
<Skeleton className='h-4 w-[80px]' />
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>
|
||||||
|
<Skeleton className='h-[250px] w-full rounded-md' />
|
||||||
|
</CardContent>
|
||||||
|
</Card>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Match the skeleton dimensions to the actual chart for smooth visual transitions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adding a New Chart Section
|
||||||
|
|
||||||
|
To add a new chart (e.g., line chart for user growth):
|
||||||
|
|
||||||
|
### 1. Create the chart component
|
||||||
|
|
||||||
|
`src/features/overview/components/line-graph.tsx`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { Line, LineChart, CartesianGrid, XAxis } from 'recharts';
|
||||||
|
import {
|
||||||
|
type ChartConfig,
|
||||||
|
ChartContainer,
|
||||||
|
ChartTooltip,
|
||||||
|
ChartTooltipContent
|
||||||
|
} from '@/components/ui/chart';
|
||||||
|
|
||||||
|
const chartConfig = {
|
||||||
|
users: { label: 'Users', color: 'var(--chart-3)' }
|
||||||
|
} satisfies ChartConfig;
|
||||||
|
|
||||||
|
const chartData = [
|
||||||
|
/* monthly user data */
|
||||||
|
];
|
||||||
|
|
||||||
|
export function LineGraph() {
|
||||||
|
return (
|
||||||
|
<Card>
|
||||||
|
<CardHeader>
|
||||||
|
<CardTitle>User Growth</CardTitle>
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>
|
||||||
|
<ChartContainer config={chartConfig} className='aspect-auto h-[250px] w-full'>
|
||||||
|
<LineChart data={chartData}>
|
||||||
|
<CartesianGrid vertical={false} />
|
||||||
|
<XAxis dataKey='month' tickLine={false} axisLine={false} />
|
||||||
|
<ChartTooltip content={<ChartTooltipContent />} />
|
||||||
|
<Line dataKey='users' type='monotone' stroke='var(--color-users)' strokeWidth={2} />
|
||||||
|
</LineChart>
|
||||||
|
</ChartContainer>
|
||||||
|
</CardContent>
|
||||||
|
</Card>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Create matching skeleton
|
||||||
|
|
||||||
|
`src/features/overview/components/line-graph-skeleton.tsx`
|
||||||
|
|
||||||
|
### 3. Create parallel route slot
|
||||||
|
|
||||||
|
```
|
||||||
|
src/app/dashboard/overview/@line_stats/
|
||||||
|
├── page.tsx → async, fetches data, returns <LineGraph />
|
||||||
|
├── loading.tsx → returns <LineGraphSkeleton />
|
||||||
|
├── error.tsx → error alert
|
||||||
|
└── default.tsx → return null (fallback when route doesn't match)
|
||||||
|
```
|
||||||
|
|
||||||
|
`default.tsx` is required for parallel routes — return `null` or a fallback:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function Default() {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Add slot to layout
|
||||||
|
|
||||||
|
Update `src/app/dashboard/overview/layout.tsx`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function OverviewLayout({
|
||||||
|
sales,
|
||||||
|
pie_stats,
|
||||||
|
bar_stats,
|
||||||
|
area_stats,
|
||||||
|
line_stats // ← add new slot
|
||||||
|
}: {
|
||||||
|
/* ...types */
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<div className='grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-7'>
|
||||||
|
{/* existing charts */}
|
||||||
|
<div className='col-span-4'>{line_stats}</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available Recharts Components
|
||||||
|
|
||||||
|
Common chart types to use with `ChartContainer`:
|
||||||
|
|
||||||
|
- `AreaChart` + `Area` — filled area charts (stacked or standalone)
|
||||||
|
- `BarChart` + `Bar` — vertical/horizontal bars
|
||||||
|
- `LineChart` + `Line` — line/trend charts
|
||||||
|
- `PieChart` + `Pie` — pie/donut charts
|
||||||
|
- `RadarChart` + `Radar` — radar/spider charts
|
||||||
|
- `RadialBarChart` + `RadialBar` — radial progress bars
|
||||||
|
|
||||||
|
All support `ChartTooltip`, `ChartLegend`, and theme-aware colors via `var(--chart-N)`.
|
||||||
@@ -0,0 +1,304 @@
|
|||||||
|
# Forms Guide
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Architecture](#architecture)
|
||||||
|
2. [Field Types](#field-types)
|
||||||
|
3. [Usage Patterns](#usage-patterns)
|
||||||
|
4. [Validation Strategies](#validation-strategies)
|
||||||
|
5. [Sheet/Dialog Forms](#sheetdialog-forms)
|
||||||
|
6. [Multi-Step Forms](#multi-step-forms)
|
||||||
|
7. [Advanced Patterns](#advanced-patterns)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
The form system is built on **TanStack Form + Zod** with a composable field layer.
|
||||||
|
|
||||||
|
**Key files:**
|
||||||
|
|
||||||
|
- `src/components/ui/tanstack-form.tsx` — exports `useAppForm`, `useFormFields<T>()`, composed fields
|
||||||
|
- `src/components/ui/form-context.tsx` — contexts, `createFormField`, structural components
|
||||||
|
- `src/components/forms/fields/*.tsx` — 8 field type implementations
|
||||||
|
|
||||||
|
**Key exports:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useAppForm, useFormFields } from '@/components/ui/tanstack-form';
|
||||||
|
```
|
||||||
|
|
||||||
|
- `useAppForm(config)` — creates a form instance with `defaultValues`, `validators`, `onSubmit`
|
||||||
|
- `useFormFields<T>()` — returns all 8 typed field components with name autocomplete from `T`
|
||||||
|
- `form.AppForm` — context provider wrapper
|
||||||
|
- `form.Form` — `<form>` element that handles submit
|
||||||
|
- `form.SubmitButton` — auto-disabled when form is invalid or submitting
|
||||||
|
- `form.AppField` — low-level render prop for custom fields
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Field Types
|
||||||
|
|
||||||
|
All fields accept: `name`, `label`, `description`, `required`, `disabled`, `validators`, `listeners`, `className`.
|
||||||
|
|
||||||
|
| Component | Props | Notes |
|
||||||
|
| --------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------- |
|
||||||
|
| `FormTextField` | `type` (text/email/number/password/tel/url), `placeholder`, `min`, `max`, `step`, `maxLength` | For numbers use `type='number'` |
|
||||||
|
| `FormTextareaField` | `placeholder`, `rows`, `maxLength` | Multiline text |
|
||||||
|
| `FormSelectField` | `options: {value, label}[]`, `placeholder` | Single select dropdown |
|
||||||
|
| `FormCheckboxField` | `options?: {value, label}[]` | Single checkbox or multi-checkbox group |
|
||||||
|
| `FormSwitchField` | — | Toggle switch |
|
||||||
|
| `FormRadioGroupField` | `options: {value, label}[]`, `orientation` | Radio button group |
|
||||||
|
| `FormSliderField` | `min`, `max`, `step` | Range slider |
|
||||||
|
| `FormFileUploadField` | `maxSize`, `maxFiles`, `accept` | Drag-and-drop with preview |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Usage Patterns
|
||||||
|
|
||||||
|
### Pattern 1: `useFormFields<T>()` (Recommended)
|
||||||
|
|
||||||
|
Type-safe field components with name autocomplete:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const { FormTextField, FormSelectField } = useFormFields<OrderFormValues>();
|
||||||
|
|
||||||
|
<FormTextField name='customer' label='Customer' required placeholder='Name'
|
||||||
|
validators={{ onBlur: z.string().min(2) }} />
|
||||||
|
|
||||||
|
<FormSelectField name='status' label='Status' required options={STATUS_OPTIONS}
|
||||||
|
validators={{ onBlur: z.string().min(1) }} />
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: `form.AppField` render prop
|
||||||
|
|
||||||
|
Full control for custom field rendering:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.AppField name='framework'>
|
||||||
|
{(field) => (
|
||||||
|
<field.FieldSet>
|
||||||
|
<field.Field>
|
||||||
|
<field.TextField label='Framework' />
|
||||||
|
</field.Field>
|
||||||
|
<field.FieldError />
|
||||||
|
</field.FieldSet>
|
||||||
|
)}
|
||||||
|
</form.AppField>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 3: Direct import (no type safety)
|
||||||
|
|
||||||
|
For quick prototyping:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { FormTextField } from '@/components/ui/tanstack-form';
|
||||||
|
<FormTextField name='name' label='Name' />;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Validation Strategies
|
||||||
|
|
||||||
|
### Field-level (recommended for UX)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormTextField
|
||||||
|
name='email'
|
||||||
|
label='Email'
|
||||||
|
validators={{
|
||||||
|
onBlur: z.string().email('Invalid email') // Validates when field loses focus
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form-level (catch-all on submit)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const form = useAppForm({
|
||||||
|
validators: { onSubmit: orderSchema }, // Validates entire form on submit
|
||||||
|
onSubmit: async ({ value }) => {
|
||||||
|
/* ... */
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Async validation (server-side checks)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormTextField
|
||||||
|
name='username'
|
||||||
|
label='Username'
|
||||||
|
validators={{
|
||||||
|
onChangeAsync: async ({ value }) => {
|
||||||
|
const exists = await checkUsername(value);
|
||||||
|
return exists ? 'Username taken' : undefined;
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
asyncDebounceMs={500}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linked field validation
|
||||||
|
|
||||||
|
For dependent fields (e.g., confirm password):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormTextField
|
||||||
|
name='confirmPassword'
|
||||||
|
label='Confirm Password'
|
||||||
|
validators={{
|
||||||
|
onChangeListenTo: ['password'],
|
||||||
|
onChange: ({ value, fieldApi }) => {
|
||||||
|
const password = fieldApi.form.getFieldValue('password');
|
||||||
|
return value !== password ? 'Passwords must match' : undefined;
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sheet/Dialog Forms
|
||||||
|
|
||||||
|
The key pattern for forms inside sheets or dialogs: give the `<form.Form>` an `id`, and use that `id` on the submit button's `form` attribute. This allows the submit button to live outside the form element (e.g., in `SheetFooter`).
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.AppForm>
|
||||||
|
<form.Form id='my-sheet-form' className='space-y-4'>
|
||||||
|
{/* fields */}
|
||||||
|
</form.Form>
|
||||||
|
</form.AppForm>;
|
||||||
|
|
||||||
|
{
|
||||||
|
/* In SheetFooter — button is outside the <form> but still submits it */
|
||||||
|
}
|
||||||
|
<SheetFooter>
|
||||||
|
<Button type='submit' form='my-sheet-form'>
|
||||||
|
Save
|
||||||
|
</Button>
|
||||||
|
</SheetFooter>;
|
||||||
|
```
|
||||||
|
|
||||||
|
On success, call `onOpenChange(false)` to close the sheet and `form.reset()` for create forms.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Multi-Step Forms
|
||||||
|
|
||||||
|
Use `withFieldGroup` + `useAppForm` with `StepButton`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Define field groups for each step
|
||||||
|
const Step1 = withFieldGroup({
|
||||||
|
fields: ['name', 'email'],
|
||||||
|
render: ({ form }) => {
|
||||||
|
const { FormTextField } = useFormFields<FormValues>();
|
||||||
|
return (
|
||||||
|
<>
|
||||||
|
<FormTextField name='name' label='Name' />
|
||||||
|
<FormTextField name='email' label='Email' />
|
||||||
|
<form.StepButton direction='next' label='Next' />
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
const Step2 = withFieldGroup({
|
||||||
|
fields: ['address', 'city'],
|
||||||
|
render: ({ form }) => {
|
||||||
|
const { FormTextField } = useFormFields<FormValues>();
|
||||||
|
return (
|
||||||
|
<>
|
||||||
|
<FormTextField name='address' label='Address' />
|
||||||
|
<FormTextField name='city' label='City' />
|
||||||
|
<form.StepButton direction='prev' label='Back' />
|
||||||
|
<form.SubmitButton label='Submit' />
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the `useStepper` hook from `src/hooks/use-stepper.tsx` to manage step state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Patterns
|
||||||
|
|
||||||
|
### Nested objects (dot notation)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormTextField name='address.street' label='Street' />
|
||||||
|
<FormTextField name='address.city' label='City' />
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dynamic array rows
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.AppField name='items' mode='array'>
|
||||||
|
{(field) => (
|
||||||
|
<>
|
||||||
|
{field.state.value.map((_, i) => (
|
||||||
|
<form.AppField key={i} name={`items[${i}].name`}>
|
||||||
|
{(subField) => <subField.TextField label={`Item ${i + 1}`} />}
|
||||||
|
</form.AppField>
|
||||||
|
))}
|
||||||
|
<Button onClick={() => field.pushValue({ name: '' })}>Add Row</Button>
|
||||||
|
</>
|
||||||
|
)}
|
||||||
|
</form.AppField>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Side effects with listeners
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FormSelectField
|
||||||
|
name='country'
|
||||||
|
label='Country'
|
||||||
|
options={countryOptions}
|
||||||
|
listeners={{
|
||||||
|
onChange: ({ value }) => {
|
||||||
|
// Reset city when country changes
|
||||||
|
form.setFieldValue('city', '');
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Custom field with `form.AppField`
|
||||||
|
|
||||||
|
For fields not covered by the built-in 8 types:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.AppField name='color'>
|
||||||
|
{(field) => (
|
||||||
|
<field.FieldSet>
|
||||||
|
<Label>Pick a color</Label>
|
||||||
|
<field.Field>
|
||||||
|
<input
|
||||||
|
type='color'
|
||||||
|
value={field.state.value}
|
||||||
|
onChange={(e) => field.handleChange(e.target.value)}
|
||||||
|
/>
|
||||||
|
</field.Field>
|
||||||
|
<field.FieldError />
|
||||||
|
</field.FieldSet>
|
||||||
|
)}
|
||||||
|
</form.AppField>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form-level errors
|
||||||
|
|
||||||
|
Display errors that apply to the whole form (e.g., server errors):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { FormErrors } from '@/components/ui/form-context';
|
||||||
|
|
||||||
|
<form.AppForm>
|
||||||
|
<form.Form>
|
||||||
|
<FormErrors /> {/* Renders form-level validation errors */}
|
||||||
|
{/* fields... */}
|
||||||
|
</form.Form>
|
||||||
|
</form.AppForm>;
|
||||||
|
```
|
||||||
@@ -0,0 +1,255 @@
|
|||||||
|
# Mock API Guide
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Structure](#structure)
|
||||||
|
2. [Full Template](#full-template)
|
||||||
|
3. [Key Patterns](#key-patterns)
|
||||||
|
4. [Integrating with React Query](#integrating-with-react-query)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
Each mock API file lives in `src/constants/mock-api-<name>.ts` and is a self-contained in-memory database. It uses:
|
||||||
|
|
||||||
|
- **faker** for generating sample data
|
||||||
|
- **match-sorter** for fuzzy search across fields
|
||||||
|
- **delay** (from `./mock-api`) to simulate network latency
|
||||||
|
|
||||||
|
The `delay` function is exported from `src/constants/mock-api.ts`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export async function delay(ms: number) {
|
||||||
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Full Template
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { faker } from '@faker-js/faker';
|
||||||
|
import { matchSorter } from 'match-sorter';
|
||||||
|
import { delay } from './mock-api';
|
||||||
|
|
||||||
|
// 1. Define the entity type
|
||||||
|
export type Order = {
|
||||||
|
id: number;
|
||||||
|
customer: string;
|
||||||
|
email: string;
|
||||||
|
status: string;
|
||||||
|
total: number;
|
||||||
|
created_at: string;
|
||||||
|
updated_at: string;
|
||||||
|
};
|
||||||
|
|
||||||
|
// 2. Create the fake database object
|
||||||
|
export const fakeOrders = {
|
||||||
|
records: [] as Order[],
|
||||||
|
|
||||||
|
// 3. Initialize with faker data
|
||||||
|
initialize() {
|
||||||
|
const statuses = ['pending', 'processing', 'completed', 'cancelled'];
|
||||||
|
for (let i = 1; i <= 20; i++) {
|
||||||
|
this.records.push({
|
||||||
|
id: i,
|
||||||
|
customer: faker.person.fullName(),
|
||||||
|
email: faker.internet.email(),
|
||||||
|
status: faker.helpers.arrayElement(statuses),
|
||||||
|
total: parseFloat(faker.commerce.price({ min: 10, max: 500 })),
|
||||||
|
created_at: faker.date.between({ from: '2023-01-01', to: Date.now() }).toISOString(),
|
||||||
|
updated_at: faker.date.recent().toISOString()
|
||||||
|
});
|
||||||
|
}
|
||||||
|
},
|
||||||
|
|
||||||
|
// 4. Get all with optional search (used internally)
|
||||||
|
async getAll({ search }: { search?: string } = {}) {
|
||||||
|
let items = [...this.records];
|
||||||
|
if (search) {
|
||||||
|
items = matchSorter(items, search, {
|
||||||
|
keys: ['customer', 'email']
|
||||||
|
});
|
||||||
|
}
|
||||||
|
return items;
|
||||||
|
},
|
||||||
|
|
||||||
|
// 5. Paginated list with filtering and sorting
|
||||||
|
async getOrders(params: {
|
||||||
|
page?: number;
|
||||||
|
limit?: number;
|
||||||
|
search?: string;
|
||||||
|
statuses?: string;
|
||||||
|
sort?: string;
|
||||||
|
}) {
|
||||||
|
await delay(800);
|
||||||
|
const { page = 1, limit = 10, search, statuses, sort } = params;
|
||||||
|
|
||||||
|
let items = await this.getAll({ search });
|
||||||
|
|
||||||
|
// Filter by comma-separated values
|
||||||
|
if (statuses) {
|
||||||
|
const statusList = statuses.split('.');
|
||||||
|
items = items.filter((item) => statusList.includes(item.status));
|
||||||
|
}
|
||||||
|
|
||||||
|
// Sort by column
|
||||||
|
if (sort) {
|
||||||
|
const parsedSort = JSON.parse(sort) as { id: string; desc: boolean }[];
|
||||||
|
if (parsedSort.length > 0) {
|
||||||
|
const { id, desc } = parsedSort[0];
|
||||||
|
items.sort((a, b) => {
|
||||||
|
const aVal = a[id as keyof Order];
|
||||||
|
const bVal = b[id as keyof Order];
|
||||||
|
if (aVal < bVal) return desc ? 1 : -1;
|
||||||
|
if (aVal > bVal) return desc ? -1 : 1;
|
||||||
|
return 0;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Paginate
|
||||||
|
const total_items = items.length;
|
||||||
|
items = items.slice((page - 1) * limit, page * limit);
|
||||||
|
|
||||||
|
return { items, total_items };
|
||||||
|
},
|
||||||
|
|
||||||
|
// 6. Get single record by ID
|
||||||
|
async getOrderById(id: number) {
|
||||||
|
await delay(800);
|
||||||
|
return this.records.find((r) => r.id === id) || null;
|
||||||
|
},
|
||||||
|
|
||||||
|
// 7. Create
|
||||||
|
async createOrder(data: Omit<Order, 'id' | 'created_at' | 'updated_at'>) {
|
||||||
|
await delay(800);
|
||||||
|
const newRecord: Order = {
|
||||||
|
...data,
|
||||||
|
id: this.records.length + 1,
|
||||||
|
created_at: new Date().toISOString(),
|
||||||
|
updated_at: new Date().toISOString()
|
||||||
|
};
|
||||||
|
this.records.push(newRecord);
|
||||||
|
return newRecord;
|
||||||
|
},
|
||||||
|
|
||||||
|
// 8. Update
|
||||||
|
async updateOrder(id: number, data: Partial<Order>) {
|
||||||
|
await delay(800);
|
||||||
|
const idx = this.records.findIndex((r) => r.id === id);
|
||||||
|
if (idx === -1) return null;
|
||||||
|
this.records[idx] = {
|
||||||
|
...this.records[idx],
|
||||||
|
...data,
|
||||||
|
updated_at: new Date().toISOString()
|
||||||
|
};
|
||||||
|
return this.records[idx];
|
||||||
|
},
|
||||||
|
|
||||||
|
// 9. Delete
|
||||||
|
async deleteOrder(id: number) {
|
||||||
|
await delay(800);
|
||||||
|
this.records = this.records.filter((r) => r.id !== id);
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// 10. Auto-initialize on import
|
||||||
|
fakeOrders.initialize();
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Patterns
|
||||||
|
|
||||||
|
### Search with match-sorter
|
||||||
|
|
||||||
|
Always specify which fields to search across:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
matchSorter(items, search, { keys: ['customer', 'email', 'status'] });
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comma-separated filter values
|
||||||
|
|
||||||
|
For multi-select filters (roles, statuses), the URL param uses `.` as delimiter:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
if (statuses) {
|
||||||
|
const list = statuses.split('.');
|
||||||
|
items = items.filter((item) => list.includes(item.status));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Computed column sorting
|
||||||
|
|
||||||
|
When a table has a computed column (e.g., combining first_name + last_name into "name"), handle it in the sort logic:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
if (id === 'name') {
|
||||||
|
const aName = `${a.first_name} ${a.last_name}`;
|
||||||
|
const bName = `${b.first_name} ${b.last_name}`;
|
||||||
|
return desc ? bName.localeCompare(aName) : aName.localeCompare(bName);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Return shape
|
||||||
|
|
||||||
|
List methods must return `{ items, total_items }` (or `{ products, total }` etc. — match the query option expectations). The total is the count **before** pagination, used for `pageCount` calculation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integrating with the API Layer
|
||||||
|
|
||||||
|
The mock API is only imported in `service.ts`. Queries and components import from the service and types files:
|
||||||
|
|
||||||
|
```
|
||||||
|
mock-api-orders.ts → api/service.ts → api/queries.ts → components
|
||||||
|
(data source) (data access) (key factory + (useSuspenseQuery
|
||||||
|
queryOptions) + useMutation)
|
||||||
|
```
|
||||||
|
|
||||||
|
**service.ts** imports from the mock API:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { fakeOrders } from '@/constants/mock-api-orders';
|
||||||
|
import type { OrderFilters, OrdersResponse } from './types';
|
||||||
|
|
||||||
|
export async function getOrders(filters: OrderFilters): Promise<OrdersResponse> {
|
||||||
|
return fakeOrders.getOrders(filters);
|
||||||
|
}
|
||||||
|
export async function createOrder(data: OrderMutationPayload) {
|
||||||
|
return fakeOrders.createOrder(data);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**queries.ts** imports from service, uses key factories:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { getOrders } from './service';
|
||||||
|
import type { OrderFilters } from './types';
|
||||||
|
|
||||||
|
export const orderKeys = {
|
||||||
|
all: ['orders'] as const,
|
||||||
|
list: (filters: OrderFilters) => [...orderKeys.all, 'list', filters] as const,
|
||||||
|
detail: (id: number) => [...orderKeys.all, 'detail', id] as const
|
||||||
|
};
|
||||||
|
|
||||||
|
export const ordersQueryOptions = (filters: OrderFilters) =>
|
||||||
|
queryOptions({ queryKey: orderKeys.list(filters), queryFn: () => getOrders(filters) });
|
||||||
|
```
|
||||||
|
|
||||||
|
**Mutations** in components use service functions + key factories:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { createOrder } from '../api/service';
|
||||||
|
import { orderKeys } from '../api/queries';
|
||||||
|
|
||||||
|
const mutation = useMutation({
|
||||||
|
mutationFn: (data) => createOrder(data),
|
||||||
|
onSuccess: () => queryClient.invalidateQueries({ queryKey: orderKeys.all })
|
||||||
|
});
|
||||||
|
```
|
||||||
@@ -0,0 +1,153 @@
|
|||||||
|
# TanStack Query Abstractions (v5)
|
||||||
|
|
||||||
|
The core insight: **`queryOptions` and `mutationOptions` are the right abstraction — not custom hooks.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Query Abstraction
|
||||||
|
|
||||||
|
### The Pattern
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// queries/invoice.ts
|
||||||
|
import { queryOptions } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
export function invoiceOptions(id: number) {
|
||||||
|
return queryOptions({
|
||||||
|
queryKey: ['invoice', id],
|
||||||
|
queryFn: () => fetchInvoice(id)
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
export function invoiceListOptions(filters: InvoiceFilters) {
|
||||||
|
return queryOptions({
|
||||||
|
queryKey: ['invoices', filters],
|
||||||
|
queryFn: () => fetchInvoices(filters),
|
||||||
|
staleTime: 30_000
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage — always compose at the call site
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// basic
|
||||||
|
const { data } = useQuery(invoiceOptions(id));
|
||||||
|
|
||||||
|
// with suspense — same options, different hook
|
||||||
|
const { data } = useSuspenseQuery(invoiceOptions(id));
|
||||||
|
|
||||||
|
// with extra options spread on top — full type inference, no TS pain
|
||||||
|
const { data } = useQuery({
|
||||||
|
...invoiceOptions(id),
|
||||||
|
select: (invoice) => invoice.createdAt, // data infers as string | undefined
|
||||||
|
enabled: !!id
|
||||||
|
});
|
||||||
|
|
||||||
|
// prefetch in a route loader (works outside React — this is why hooks are wrong)
|
||||||
|
await queryClient.prefetchQuery(invoiceOptions(id));
|
||||||
|
|
||||||
|
// read from cache imperatively — queryKey is typed via DataTag symbol
|
||||||
|
const invoice = queryClient.getQueryData(invoiceOptions(id).queryKey);
|
||||||
|
|
||||||
|
// invalidate
|
||||||
|
queryClient.invalidateQueries({ queryKey: invoiceOptions(id).queryKey });
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why NOT a custom hook
|
||||||
|
|
||||||
|
Custom hooks like `useInvoice(id)` have three critical problems:
|
||||||
|
|
||||||
|
1. **Hooks only work in components/hooks** — but queries are now used in route loaders, server prefetching, event handlers, and server components. `queryOptions` is just a plain function — works anywhere.
|
||||||
|
2. **They share logic, not configuration** — what you actually want to share is the `queryKey` + `queryFn` config. Hooks are the wrong primitive for that.
|
||||||
|
3. **They lock you to one hook** — you can't use `useInvoice()` with `useSuspenseQuery`, `useQueries`, or imperative `queryClient` methods.
|
||||||
|
|
||||||
|
### Why NOT `UseQueryOptions` type directly
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// BAD — data becomes unknown
|
||||||
|
function useInvoice(id: number, options?: Partial<UseQueryOptions>) { ... }
|
||||||
|
|
||||||
|
// STILL BAD — select breaks with TS error
|
||||||
|
function useInvoice(id: number, options?: Partial<UseQueryOptions<Invoice>>) { ... }
|
||||||
|
// select: (invoice) => invoice.createdAt
|
||||||
|
// Error: Type 'string' is not assignable to type 'Invoice'
|
||||||
|
```
|
||||||
|
|
||||||
|
`queryOptions` solves this via a `DataTag` symbol on the queryKey — full inference, zero manual generics.
|
||||||
|
|
||||||
|
### Custom hooks are still fine on top
|
||||||
|
|
||||||
|
If a component always uses the same composition, a hook is fine — but build it _on top of_ `queryOptions`:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// OK — hook built on queryOptions
|
||||||
|
function useInvoice(id: number) {
|
||||||
|
return useQuery(invoiceOptions(id));
|
||||||
|
}
|
||||||
|
|
||||||
|
// OK — hook that adds per-feature defaults
|
||||||
|
function useInvoiceWithSuspense(id: number) {
|
||||||
|
return useSuspenseQuery(invoiceOptions(id));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mutation Abstraction
|
||||||
|
|
||||||
|
### The Pattern
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// mutations/invoice.ts
|
||||||
|
import { mutationOptions } from '@tanstack/react-query';
|
||||||
|
import { getQueryClient } from '@/lib/query-client';
|
||||||
|
|
||||||
|
export const createInvoiceMutation = mutationOptions({
|
||||||
|
mutationFn: (data: CreateInvoiceInput) => createInvoice(data),
|
||||||
|
onSuccess: () => {
|
||||||
|
getQueryClient().invalidateQueries({ queryKey: ['invoices'] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
export const updateInvoiceMutation = mutationOptions({
|
||||||
|
mutationFn: ({ id, ...data }: UpdateInvoiceInput) => updateInvoice(id, data),
|
||||||
|
onSuccess: (updated) => {
|
||||||
|
const qc = getQueryClient();
|
||||||
|
qc.setQueryData(invoiceOptions(updated.id).queryKey, updated);
|
||||||
|
qc.invalidateQueries({ queryKey: ['invoices'] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note on queryClient**: Import `getQueryClient()` directly — do NOT pass `queryClient` as a function argument. The `getQueryClient()` pattern handles both SSR (fresh per request) and client (singleton) correctly.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// basic
|
||||||
|
const { mutate } = useMutation(createInvoiceMutation);
|
||||||
|
|
||||||
|
// composed — add per-usage callbacks on top
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
...createInvoiceMutation,
|
||||||
|
onError: (err) => toast.error(err.message),
|
||||||
|
onSuccess: (data) => {
|
||||||
|
// this runs AFTER the shared onSuccess above
|
||||||
|
router.push(`/invoices/${data.id}`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rules Summary
|
||||||
|
|
||||||
|
| Rule | Reason |
|
||||||
|
| ------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||||
|
| Use `queryOptions()` not custom hooks as the base abstraction | Works everywhere — loaders, server, imperative calls |
|
||||||
|
| Keep options factories lean — no extra config params | Best abstractions are not configurable |
|
||||||
|
| Compose extra options at the call site via spread | Full TS inference without manual generics |
|
||||||
|
| Import `getQueryClient()` in mutation files | Handles SSR/client correctly without prop drilling |
|
||||||
|
| Co-locate `queryKey` inside `queryOptions` | Typed key reuse in `invalidateQueries`, `setQueryData`, `getQueryData` |
|
||||||
|
| Custom hooks are fine — but built ON TOP of `queryOptions` | Hooks for component convenience, `queryOptions` for sharing config |
|
||||||
@@ -0,0 +1,180 @@
|
|||||||
|
# Theme Creation Guide
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Create Theme CSS](#1-create-theme-css)
|
||||||
|
2. [Import Theme](#2-import-theme)
|
||||||
|
3. [Register Theme](#3-register-theme)
|
||||||
|
4. [Add Custom Fonts](#4-add-custom-fonts-optional)
|
||||||
|
5. [Set as Default](#5-set-as-default-optional)
|
||||||
|
6. [Required Tokens](#required-tokens)
|
||||||
|
7. [Color Format Reference](#color-format-reference)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Create Theme CSS
|
||||||
|
|
||||||
|
Create `src/styles/themes/<name>.css`:
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* Light mode */
|
||||||
|
[data-theme='your-theme'] {
|
||||||
|
--background: oklch(1 0 0);
|
||||||
|
--foreground: oklch(0.145 0 0);
|
||||||
|
--card: oklch(...);
|
||||||
|
--card-foreground: oklch(...);
|
||||||
|
--popover: oklch(...);
|
||||||
|
--popover-foreground: oklch(...);
|
||||||
|
--primary: oklch(...);
|
||||||
|
--primary-foreground: oklch(...);
|
||||||
|
--secondary: oklch(...);
|
||||||
|
--secondary-foreground: oklch(...);
|
||||||
|
--muted: oklch(...);
|
||||||
|
--muted-foreground: oklch(...);
|
||||||
|
--accent: oklch(...);
|
||||||
|
--accent-foreground: oklch(...);
|
||||||
|
--destructive: oklch(...);
|
||||||
|
--destructive-foreground: oklch(...);
|
||||||
|
--border: oklch(...);
|
||||||
|
--input: oklch(...);
|
||||||
|
--ring: oklch(...);
|
||||||
|
--chart-1: oklch(...);
|
||||||
|
--chart-2: oklch(...);
|
||||||
|
--chart-3: oklch(...);
|
||||||
|
--chart-4: oklch(...);
|
||||||
|
--chart-5: oklch(...);
|
||||||
|
--sidebar: oklch(...);
|
||||||
|
--sidebar-foreground: oklch(...);
|
||||||
|
--sidebar-primary: oklch(...);
|
||||||
|
--sidebar-primary-foreground: oklch(...);
|
||||||
|
--sidebar-accent: oklch(...);
|
||||||
|
--sidebar-accent-foreground: oklch(...);
|
||||||
|
--sidebar-border: oklch(...);
|
||||||
|
--sidebar-ring: oklch(...);
|
||||||
|
--font-sans: 'Font Name', sans-serif;
|
||||||
|
--font-mono: 'Mono Font', monospace;
|
||||||
|
--radius: 0.5rem;
|
||||||
|
--spacing: 0.25rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Dark mode */
|
||||||
|
[data-theme='your-theme'].dark {
|
||||||
|
--background: oklch(0.145 0 0);
|
||||||
|
--foreground: oklch(0.985 0 0);
|
||||||
|
/* ... all tokens with dark values */
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Tailwind integration (required) */
|
||||||
|
[data-theme='your-theme'] {
|
||||||
|
@theme inline {
|
||||||
|
--color-background: var(--background);
|
||||||
|
--color-foreground: var(--foreground);
|
||||||
|
--color-card: var(--card);
|
||||||
|
--color-card-foreground: var(--card-foreground);
|
||||||
|
--color-popover: var(--popover);
|
||||||
|
--color-popover-foreground: var(--popover-foreground);
|
||||||
|
--color-primary: var(--primary);
|
||||||
|
--color-primary-foreground: var(--primary-foreground);
|
||||||
|
--color-secondary: var(--secondary);
|
||||||
|
--color-secondary-foreground: var(--secondary-foreground);
|
||||||
|
--color-muted: var(--muted);
|
||||||
|
--color-muted-foreground: var(--muted-foreground);
|
||||||
|
--color-accent: var(--accent);
|
||||||
|
--color-accent-foreground: var(--accent-foreground);
|
||||||
|
--color-destructive: var(--destructive);
|
||||||
|
--color-destructive-foreground: var(--destructive-foreground);
|
||||||
|
--color-border: var(--border);
|
||||||
|
--color-input: var(--input);
|
||||||
|
--color-ring: var(--ring);
|
||||||
|
--color-chart-1: var(--chart-1);
|
||||||
|
--color-chart-2: var(--chart-2);
|
||||||
|
--color-chart-3: var(--chart-3);
|
||||||
|
--color-chart-4: var(--chart-4);
|
||||||
|
--color-chart-5: var(--chart-5);
|
||||||
|
--color-sidebar: var(--sidebar);
|
||||||
|
--color-sidebar-foreground: var(--sidebar-foreground);
|
||||||
|
--color-sidebar-primary: var(--sidebar-primary);
|
||||||
|
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
|
||||||
|
--color-sidebar-accent: var(--sidebar-accent);
|
||||||
|
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
|
||||||
|
--color-sidebar-border: var(--sidebar-border);
|
||||||
|
--color-sidebar-ring: var(--sidebar-ring);
|
||||||
|
--font-sans: var(--font-sans);
|
||||||
|
--font-mono: var(--font-mono);
|
||||||
|
--font-serif: var(--font-serif);
|
||||||
|
--radius-sm: calc(var(--radius) - 4px);
|
||||||
|
--radius-md: calc(var(--radius) - 2px);
|
||||||
|
--radius-lg: var(--radius);
|
||||||
|
--radius-xl: calc(var(--radius) + 4px);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Import Theme
|
||||||
|
|
||||||
|
Add to `src/styles/theme.css`:
|
||||||
|
|
||||||
|
```css
|
||||||
|
@import './themes/your-theme.css';
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Register Theme
|
||||||
|
|
||||||
|
Add to `THEMES` array in `src/components/themes/theme.config.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
{ name: 'Your Theme', value: 'your-theme' }
|
||||||
|
```
|
||||||
|
|
||||||
|
The `value` must exactly match the `data-theme` attribute in your CSS.
|
||||||
|
|
||||||
|
## 4. Add Custom Fonts (Optional)
|
||||||
|
|
||||||
|
Only if using a Google Font not already loaded.
|
||||||
|
|
||||||
|
In `src/components/themes/font.config.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { Your_Font } from 'next/font/google';
|
||||||
|
|
||||||
|
const fontYourName = Your_Font({
|
||||||
|
subsets: ['latin'],
|
||||||
|
weight: ['400', '500', '700'],
|
||||||
|
variable: '--font-your-name'
|
||||||
|
});
|
||||||
|
|
||||||
|
export const fontVariables = cn(
|
||||||
|
// ... existing fonts
|
||||||
|
fontYourName.variable
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
In your theme CSS, use the font's **display name** (not the CSS variable):
|
||||||
|
|
||||||
|
```css
|
||||||
|
--font-sans: 'Your Font', sans-serif;
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. Set as Default (Optional)
|
||||||
|
|
||||||
|
In `src/components/themes/theme.config.ts`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export const DEFAULT_THEME = 'your-theme';
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required Tokens
|
||||||
|
|
||||||
|
Minimum required: `--background`, `--foreground`, `--card` & `--card-foreground`, `--popover` & `--popover-foreground`, `--primary` & `--primary-foreground`, `--secondary` & `--secondary-foreground`, `--muted` & `--muted-foreground`, `--accent` & `--accent-foreground`, `--destructive` & `--destructive-foreground`, `--border`, `--input`, `--ring`, `--radius`.
|
||||||
|
|
||||||
|
Optional: `--chart-*`, `--sidebar-*`, `--font-*`, `--shadow-*`, `--tracking-normal`, `--spacing`.
|
||||||
|
|
||||||
|
## Color Format Reference
|
||||||
|
|
||||||
|
OKLCH: `oklch(lightness chroma hue)`
|
||||||
|
|
||||||
|
- Lightness: 0-1 (0=black, 1=white)
|
||||||
|
- Chroma: 0+ (0=gray, higher=saturated)
|
||||||
|
- Hue: 0-360 (0=red, 120=green, 240=blue)
|
||||||
|
|
||||||
|
See `src/styles/themes/claude.css` for a complete example.
|
||||||
171
.agents/skills/next-best-practices/SKILL.md
Normal file
171
.agents/skills/next-best-practices/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
|||||||
|
---
|
||||||
|
name: next-best-practices
|
||||||
|
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
|
||||||
|
user-invocable: false
|
||||||
|
---
|
||||||
|
|
||||||
|
# Next.js Best Practices
|
||||||
|
|
||||||
|
Apply these rules when writing or reviewing Next.js code.
|
||||||
|
|
||||||
|
## File Conventions
|
||||||
|
|
||||||
|
See [file-conventions.md](./file-conventions.md) for:
|
||||||
|
|
||||||
|
- Project structure and special files
|
||||||
|
- Route segments (dynamic, catch-all, groups)
|
||||||
|
- Parallel and intercepting routes
|
||||||
|
- Middleware rename in v16 (middleware → proxy)
|
||||||
|
|
||||||
|
## RSC Boundaries
|
||||||
|
|
||||||
|
Detect invalid React Server Component patterns.
|
||||||
|
|
||||||
|
See [rsc-boundaries.md](./rsc-boundaries.md) for:
|
||||||
|
|
||||||
|
- Async client component detection (invalid)
|
||||||
|
- Non-serializable props detection
|
||||||
|
- Server Action exceptions
|
||||||
|
|
||||||
|
## Async Patterns
|
||||||
|
|
||||||
|
Next.js 15+ async API changes.
|
||||||
|
|
||||||
|
See [async-patterns.md](./async-patterns.md) for:
|
||||||
|
|
||||||
|
- Async `params` and `searchParams`
|
||||||
|
- Async `cookies()` and `headers()`
|
||||||
|
- Migration codemod
|
||||||
|
|
||||||
|
## Runtime Selection
|
||||||
|
|
||||||
|
See [runtime-selection.md](./runtime-selection.md) for:
|
||||||
|
|
||||||
|
- Default to Node.js runtime
|
||||||
|
- When Edge runtime is appropriate
|
||||||
|
|
||||||
|
## Directives
|
||||||
|
|
||||||
|
See [directives.md](./directives.md) for:
|
||||||
|
|
||||||
|
- `'use client'`, `'use server'` (React)
|
||||||
|
- `'use cache'` (Next.js)
|
||||||
|
|
||||||
|
## Functions
|
||||||
|
|
||||||
|
See [functions.md](./functions.md) for:
|
||||||
|
|
||||||
|
- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
|
||||||
|
- Server functions: `cookies`, `headers`, `draftMode`, `after`
|
||||||
|
- Generate functions: `generateStaticParams`, `generateMetadata`
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
See [error-handling.md](./error-handling.md) for:
|
||||||
|
|
||||||
|
- `error.tsx`, `global-error.tsx`, `not-found.tsx`
|
||||||
|
- `redirect`, `permanentRedirect`, `notFound`
|
||||||
|
- `forbidden`, `unauthorized` (auth errors)
|
||||||
|
- `unstable_rethrow` for catch blocks
|
||||||
|
|
||||||
|
## Data Patterns
|
||||||
|
|
||||||
|
See [data-patterns.md](./data-patterns.md) for:
|
||||||
|
|
||||||
|
- Server Components vs Server Actions vs Route Handlers
|
||||||
|
- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
|
||||||
|
- Client component data fetching
|
||||||
|
|
||||||
|
## Route Handlers
|
||||||
|
|
||||||
|
See [route-handlers.md](./route-handlers.md) for:
|
||||||
|
|
||||||
|
- `route.ts` basics
|
||||||
|
- GET handler conflicts with `page.tsx`
|
||||||
|
- Environment behavior (no React DOM)
|
||||||
|
- When to use vs Server Actions
|
||||||
|
|
||||||
|
## Metadata & OG Images
|
||||||
|
|
||||||
|
See [metadata.md](./metadata.md) for:
|
||||||
|
|
||||||
|
- Static and dynamic metadata
|
||||||
|
- `generateMetadata` function
|
||||||
|
- OG image generation with `next/og`
|
||||||
|
- File-based metadata conventions
|
||||||
|
|
||||||
|
## Image Optimization
|
||||||
|
|
||||||
|
See [image.md](./image.md) for:
|
||||||
|
|
||||||
|
- Always use `next/image` over `<img>`
|
||||||
|
- Remote images configuration
|
||||||
|
- Responsive `sizes` attribute
|
||||||
|
- Blur placeholders
|
||||||
|
- Priority loading for LCP
|
||||||
|
|
||||||
|
## Font Optimization
|
||||||
|
|
||||||
|
See [font.md](./font.md) for:
|
||||||
|
|
||||||
|
- `next/font` setup
|
||||||
|
- Google Fonts, local fonts
|
||||||
|
- Tailwind CSS integration
|
||||||
|
- Preloading subsets
|
||||||
|
|
||||||
|
## Bundling
|
||||||
|
|
||||||
|
See [bundling.md](./bundling.md) for:
|
||||||
|
|
||||||
|
- Server-incompatible packages
|
||||||
|
- CSS imports (not link tags)
|
||||||
|
- Polyfills (already included)
|
||||||
|
- ESM/CommonJS issues
|
||||||
|
- Bundle analysis
|
||||||
|
|
||||||
|
## Scripts
|
||||||
|
|
||||||
|
See [scripts.md](./scripts.md) for:
|
||||||
|
|
||||||
|
- `next/script` vs native script tags
|
||||||
|
- Inline scripts need `id`
|
||||||
|
- Loading strategies
|
||||||
|
- Google Analytics with `@next/third-parties`
|
||||||
|
|
||||||
|
## Hydration Errors
|
||||||
|
|
||||||
|
See [hydration-error.md](./hydration-error.md) for:
|
||||||
|
|
||||||
|
- Common causes (browser APIs, dates, invalid HTML)
|
||||||
|
- Debugging with error overlay
|
||||||
|
- Fixes for each cause
|
||||||
|
|
||||||
|
## Suspense Boundaries
|
||||||
|
|
||||||
|
See [suspense-boundaries.md](./suspense-boundaries.md) for:
|
||||||
|
|
||||||
|
- CSR bailout with `useSearchParams` and `usePathname`
|
||||||
|
- Which hooks require Suspense boundaries
|
||||||
|
|
||||||
|
## Parallel & Intercepting Routes
|
||||||
|
|
||||||
|
See [parallel-routes.md](./parallel-routes.md) for:
|
||||||
|
|
||||||
|
- Modal patterns with `@slot` and `(.)` interceptors
|
||||||
|
- `default.tsx` for fallbacks
|
||||||
|
- Closing modals correctly with `router.back()`
|
||||||
|
|
||||||
|
## Self-Hosting
|
||||||
|
|
||||||
|
See [self-hosting.md](./self-hosting.md) for:
|
||||||
|
|
||||||
|
- `output: 'standalone'` for Docker
|
||||||
|
- Cache handlers for multi-instance ISR
|
||||||
|
- What works vs needs extra setup
|
||||||
|
|
||||||
|
## Debug Tricks
|
||||||
|
|
||||||
|
See [debug-tricks.md](./debug-tricks.md) for:
|
||||||
|
|
||||||
|
- MCP endpoint for AI-assisted debugging
|
||||||
|
- Rebuild specific routes with `--debug-build-paths`
|
||||||
84
.agents/skills/next-best-practices/async-patterns.md
Normal file
84
.agents/skills/next-best-practices/async-patterns.md
Normal file
@@ -0,0 +1,84 @@
|
|||||||
|
# Async Patterns
|
||||||
|
|
||||||
|
In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
|
||||||
|
|
||||||
|
## Async Params and SearchParams
|
||||||
|
|
||||||
|
Always type them as `Promise<...>` and await them.
|
||||||
|
|
||||||
|
### Pages and Layouts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
type Props = { params: Promise<{ slug: string }> };
|
||||||
|
|
||||||
|
export default async function Page({ params }: Props) {
|
||||||
|
const { slug } = await params;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Route Handlers
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### SearchParams
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
type Props = {
|
||||||
|
params: Promise<{ slug: string }>;
|
||||||
|
searchParams: Promise<{ query?: string }>;
|
||||||
|
};
|
||||||
|
|
||||||
|
export default async function Page({ params, searchParams }: Props) {
|
||||||
|
const { slug } = await params;
|
||||||
|
const { query } = await searchParams;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Synchronous Components
|
||||||
|
|
||||||
|
Use `React.use()` for non-async components:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { use } from 'react';
|
||||||
|
|
||||||
|
type Props = { params: Promise<{ slug: string }> };
|
||||||
|
|
||||||
|
export default function Page({ params }: Props) {
|
||||||
|
const { slug } = use(params);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### generateMetadata
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
type Props = { params: Promise<{ slug: string }> };
|
||||||
|
|
||||||
|
export async function generateMetadata({ params }: Props): Promise<Metadata> {
|
||||||
|
const { slug } = await params;
|
||||||
|
return { title: slug };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Async Cookies and Headers
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { cookies, headers } from 'next/headers';
|
||||||
|
|
||||||
|
export default async function Page() {
|
||||||
|
const cookieStore = await cookies();
|
||||||
|
const headersList = await headers();
|
||||||
|
|
||||||
|
const theme = cookieStore.get('theme');
|
||||||
|
const userAgent = headersList.get('user-agent');
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Migration Codemod
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @next/codemod@latest next-async-request-api .
|
||||||
|
```
|
||||||
182
.agents/skills/next-best-practices/bundling.md
Normal file
182
.agents/skills/next-best-practices/bundling.md
Normal file
@@ -0,0 +1,182 @@
|
|||||||
|
# Bundling
|
||||||
|
|
||||||
|
Fix common bundling issues with third-party packages.
|
||||||
|
|
||||||
|
## Server-Incompatible Packages
|
||||||
|
|
||||||
|
Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
|
||||||
|
|
||||||
|
### Error Signs
|
||||||
|
|
||||||
|
```
|
||||||
|
ReferenceError: window is not defined
|
||||||
|
ReferenceError: document is not defined
|
||||||
|
ReferenceError: localStorage is not defined
|
||||||
|
Module not found: Can't resolve 'fs'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution 1: Mark as Client-Only
|
||||||
|
|
||||||
|
If the package is only needed on client:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Fails - package uses window
|
||||||
|
import SomeChart from 'some-chart-library';
|
||||||
|
|
||||||
|
export default function Page() {
|
||||||
|
return <SomeChart />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Use dynamic import with ssr: false
|
||||||
|
import dynamic from 'next/dynamic';
|
||||||
|
|
||||||
|
const SomeChart = dynamic(() => import('some-chart-library'), {
|
||||||
|
ssr: false
|
||||||
|
});
|
||||||
|
|
||||||
|
export default function Page() {
|
||||||
|
return <SomeChart />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution 2: Externalize from Server Bundle
|
||||||
|
|
||||||
|
For packages that should run on server but have bundling issues:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
serverExternalPackages: ['problematic-package']
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Use this for:
|
||||||
|
|
||||||
|
- Packages with native bindings (sharp, bcrypt)
|
||||||
|
- Packages that don't bundle well (some ORMs)
|
||||||
|
- Packages with circular dependencies
|
||||||
|
|
||||||
|
### Solution 3: Client Component Wrapper
|
||||||
|
|
||||||
|
Wrap the entire usage in a client component:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// components/ChartWrapper.tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import { Chart } from 'chart-library';
|
||||||
|
|
||||||
|
export function ChartWrapper(props) {
|
||||||
|
return <Chart {...props} />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// app/page.tsx (server component)
|
||||||
|
import { ChartWrapper } from '@/components/ChartWrapper';
|
||||||
|
|
||||||
|
export default function Page() {
|
||||||
|
return <ChartWrapper data={data} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## CSS Imports
|
||||||
|
|
||||||
|
Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Manual link tag
|
||||||
|
<link rel='stylesheet' href='/styles.css' />;
|
||||||
|
|
||||||
|
// Good: Import CSS
|
||||||
|
import './styles.css';
|
||||||
|
|
||||||
|
// Good: CSS Modules
|
||||||
|
import styles from './Button.module.css';
|
||||||
|
```
|
||||||
|
|
||||||
|
## Polyfills
|
||||||
|
|
||||||
|
Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
|
||||||
|
|
||||||
|
Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Redundant polyfills
|
||||||
|
<script src='https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from' />
|
||||||
|
|
||||||
|
// Good: Next.js includes these automatically
|
||||||
|
```
|
||||||
|
|
||||||
|
## ESM/CommonJS Issues
|
||||||
|
|
||||||
|
### Error Signs
|
||||||
|
|
||||||
|
```
|
||||||
|
SyntaxError: Cannot use import statement outside a module
|
||||||
|
Error: require() of ES Module
|
||||||
|
Module not found: ESM packages need to be imported
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution: Transpile Package
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
transpilePackages: ['some-esm-package', 'another-package']
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Problematic Packages
|
||||||
|
|
||||||
|
| Package | Issue | Solution |
|
||||||
|
| --------------- | --------------- | --------------------------------------------------------------- |
|
||||||
|
| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
|
||||||
|
| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
|
||||||
|
| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
|
||||||
|
| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
|
||||||
|
| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
|
||||||
|
| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
|
||||||
|
| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
|
||||||
|
| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
|
||||||
|
|
||||||
|
## Bundle Analysis
|
||||||
|
|
||||||
|
Analyze bundle size with the built-in analyzer (Next.js 16.1+):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
next experimental-analyze
|
||||||
|
```
|
||||||
|
|
||||||
|
This opens an interactive UI to:
|
||||||
|
|
||||||
|
- Filter by route, environment (client/server), and type
|
||||||
|
- Inspect module sizes and import chains
|
||||||
|
- View treemap visualization
|
||||||
|
|
||||||
|
Save output for comparison:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
next experimental-analyze --output
|
||||||
|
# Output saved to .next/diagnostics/analyze
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/guides/package-bundling
|
||||||
|
|
||||||
|
## Migrating from Webpack to Turbopack
|
||||||
|
|
||||||
|
Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
// Good: Works with Turbopack
|
||||||
|
serverExternalPackages: ['package'],
|
||||||
|
transpilePackages: ['package'],
|
||||||
|
|
||||||
|
// Bad: Webpack-only - migrate away from this
|
||||||
|
webpack: (config) => {
|
||||||
|
// custom webpack config
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack
|
||||||
300
.agents/skills/next-best-practices/data-patterns.md
Normal file
300
.agents/skills/next-best-practices/data-patterns.md
Normal file
@@ -0,0 +1,300 @@
|
|||||||
|
# Data Patterns
|
||||||
|
|
||||||
|
Choose the right data fetching pattern for each use case.
|
||||||
|
|
||||||
|
## Decision Tree
|
||||||
|
|
||||||
|
```
|
||||||
|
Need to fetch data?
|
||||||
|
├── From a Server Component?
|
||||||
|
│ └── Use: Fetch directly (no API needed)
|
||||||
|
│
|
||||||
|
├── From a Client Component?
|
||||||
|
│ ├── Is it a mutation (POST/PUT/DELETE)?
|
||||||
|
│ │ └── Use: Server Action
|
||||||
|
│ └── Is it a read (GET)?
|
||||||
|
│ └── Use: Route Handler OR pass from Server Component
|
||||||
|
│
|
||||||
|
├── Need external API access (webhooks, third parties)?
|
||||||
|
│ └── Use: Route Handler
|
||||||
|
│
|
||||||
|
└── Need REST API for mobile app / external clients?
|
||||||
|
└── Use: Route Handler
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pattern 1: Server Components (Preferred for Reads)
|
||||||
|
|
||||||
|
Fetch data directly in Server Components - no API layer needed.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/users/page.tsx
|
||||||
|
async function UsersPage() {
|
||||||
|
// Direct database access - no API round-trip
|
||||||
|
const users = await db.user.findMany();
|
||||||
|
|
||||||
|
// Or fetch from external API
|
||||||
|
const posts = await fetch('https://api.example.com/posts').then((r) => r.json());
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ul>
|
||||||
|
{users.map((user) => (
|
||||||
|
<li key={user.id}>{user.name}</li>
|
||||||
|
))}
|
||||||
|
</ul>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefits**:
|
||||||
|
|
||||||
|
- No API to maintain
|
||||||
|
- No client-server waterfall
|
||||||
|
- Secrets stay on server
|
||||||
|
- Direct database access
|
||||||
|
|
||||||
|
## Pattern 2: Server Actions (Preferred for Mutations)
|
||||||
|
|
||||||
|
Server Actions are the recommended way to handle mutations.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/actions.ts
|
||||||
|
'use server';
|
||||||
|
|
||||||
|
import { revalidatePath } from 'next/cache';
|
||||||
|
|
||||||
|
export async function createPost(formData: FormData) {
|
||||||
|
const title = formData.get('title') as string;
|
||||||
|
|
||||||
|
await db.post.create({ data: { title } });
|
||||||
|
|
||||||
|
revalidatePath('/posts');
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function deletePost(id: string) {
|
||||||
|
await db.post.delete({ where: { id } });
|
||||||
|
|
||||||
|
revalidateTag('posts');
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/posts/new/page.tsx
|
||||||
|
import { createPost } from '@/app/actions';
|
||||||
|
|
||||||
|
export default function NewPost() {
|
||||||
|
return (
|
||||||
|
<form action={createPost}>
|
||||||
|
<input name='title' required />
|
||||||
|
<button type='submit'>Create</button>
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefits**:
|
||||||
|
|
||||||
|
- End-to-end type safety
|
||||||
|
- Progressive enhancement (works without JS)
|
||||||
|
- Automatic request handling
|
||||||
|
- Integrated with React transitions
|
||||||
|
|
||||||
|
**Constraints**:
|
||||||
|
|
||||||
|
- POST only (no GET caching semantics)
|
||||||
|
- Internal use only (no external access)
|
||||||
|
- Cannot return non-serializable data
|
||||||
|
|
||||||
|
## Pattern 3: Route Handlers (APIs)
|
||||||
|
|
||||||
|
Use Route Handlers when you need a REST API.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/api/posts/route.ts
|
||||||
|
import { NextRequest, NextResponse } from 'next/server';
|
||||||
|
|
||||||
|
// GET is cacheable
|
||||||
|
export async function GET(request: NextRequest) {
|
||||||
|
const posts = await db.post.findMany();
|
||||||
|
return NextResponse.json(posts);
|
||||||
|
}
|
||||||
|
|
||||||
|
// POST for mutations
|
||||||
|
export async function POST(request: NextRequest) {
|
||||||
|
const body = await request.json();
|
||||||
|
const post = await db.post.create({ data: body });
|
||||||
|
return NextResponse.json(post, { status: 201 });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
|
||||||
|
- External API access (mobile apps, third parties)
|
||||||
|
- Webhooks from external services
|
||||||
|
- GET endpoints that need HTTP caching
|
||||||
|
- OpenAPI/Swagger documentation needed
|
||||||
|
|
||||||
|
**When NOT to use**:
|
||||||
|
|
||||||
|
- Internal data fetching (use Server Components)
|
||||||
|
- Mutations from your UI (use Server Actions)
|
||||||
|
|
||||||
|
## Avoiding Data Waterfalls
|
||||||
|
|
||||||
|
### Problem: Sequential Fetches
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Sequential waterfalls
|
||||||
|
async function Dashboard() {
|
||||||
|
const user = await getUser(); // Wait...
|
||||||
|
const posts = await getPosts(); // Then wait...
|
||||||
|
const comments = await getComments(); // Then wait...
|
||||||
|
|
||||||
|
return <div>...</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution 1: Parallel Fetching with Promise.all
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Parallel fetching
|
||||||
|
async function Dashboard() {
|
||||||
|
const [user, posts, comments] = await Promise.all([getUser(), getPosts(), getComments()]);
|
||||||
|
|
||||||
|
return <div>...</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution 2: Streaming with Suspense
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Show content progressively
|
||||||
|
import { Suspense } from 'react';
|
||||||
|
|
||||||
|
async function Dashboard() {
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<Suspense fallback={<UserSkeleton />}>
|
||||||
|
<UserSection />
|
||||||
|
</Suspense>
|
||||||
|
<Suspense fallback={<PostsSkeleton />}>
|
||||||
|
<PostsSection />
|
||||||
|
</Suspense>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function UserSection() {
|
||||||
|
const user = await getUser(); // Fetches independently
|
||||||
|
return <div>{user.name}</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
async function PostsSection() {
|
||||||
|
const posts = await getPosts(); // Fetches independently
|
||||||
|
return <PostList posts={posts} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Solution 3: Preload Pattern
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// lib/data.ts
|
||||||
|
import { cache } from 'react';
|
||||||
|
|
||||||
|
export const getUser = cache(async (id: string) => {
|
||||||
|
return db.user.findUnique({ where: { id } });
|
||||||
|
});
|
||||||
|
|
||||||
|
export const preloadUser = (id: string) => {
|
||||||
|
void getUser(id); // Fire and forget
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/user/[id]/page.tsx
|
||||||
|
import { getUser, preloadUser } from '@/lib/data';
|
||||||
|
|
||||||
|
export default async function UserPage({ params }) {
|
||||||
|
const { id } = await params;
|
||||||
|
|
||||||
|
// Start fetching early
|
||||||
|
preloadUser(id);
|
||||||
|
|
||||||
|
// Do other work...
|
||||||
|
|
||||||
|
// Data likely ready by now
|
||||||
|
const user = await getUser(id);
|
||||||
|
return <div>{user.name}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Client Component Data Fetching
|
||||||
|
|
||||||
|
When Client Components need data:
|
||||||
|
|
||||||
|
### Option 1: Pass from Server Component (Preferred)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Server Component
|
||||||
|
async function Page() {
|
||||||
|
const data = await fetchData();
|
||||||
|
return <ClientComponent initialData={data} />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Client Component
|
||||||
|
('use client');
|
||||||
|
function ClientComponent({ initialData }) {
|
||||||
|
const [data, setData] = useState(initialData);
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option 2: Fetch on Mount (When Necessary)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { useEffect, useState } from 'react';
|
||||||
|
|
||||||
|
function ClientComponent() {
|
||||||
|
const [data, setData] = useState(null);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
fetch('/api/data')
|
||||||
|
.then((r) => r.json())
|
||||||
|
.then(setData);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
if (!data) return <Loading />;
|
||||||
|
return <div>{data.value}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option 3: Server Action for Reads (Works But Not Ideal)
|
||||||
|
|
||||||
|
Server Actions can be called from Client Components for reads, but this is not their intended purpose:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
import { getData } from './actions';
|
||||||
|
import { useEffect, useState } from 'react';
|
||||||
|
|
||||||
|
function ClientComponent() {
|
||||||
|
const [data, setData] = useState(null);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
getData().then(setData);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
return <div>{data?.value}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Pattern | Use Case | HTTP Method | Caching |
|
||||||
|
| ---------------------- | --------------------------- | ----------- | -------------------- |
|
||||||
|
| Server Component fetch | Internal reads | Any | Full Next.js caching |
|
||||||
|
| Server Action | Mutations, form submissions | POST only | No |
|
||||||
|
| Route Handler | External APIs, webhooks | Any | GET can be cached |
|
||||||
|
| Client fetch to API | Client-side reads | Any | HTTP cache headers |
|
||||||
122
.agents/skills/next-best-practices/debug-tricks.md
Normal file
122
.agents/skills/next-best-practices/debug-tricks.md
Normal file
@@ -0,0 +1,122 @@
|
|||||||
|
# Debug Tricks
|
||||||
|
|
||||||
|
Tricks to speed up debugging Next.js applications.
|
||||||
|
|
||||||
|
## MCP Endpoint (Dev Server)
|
||||||
|
|
||||||
|
Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
|
||||||
|
|
||||||
|
- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
|
||||||
|
- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/guides/mcp
|
||||||
|
|
||||||
|
**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
|
||||||
|
|
||||||
|
### Request Format
|
||||||
|
|
||||||
|
The endpoint uses JSON-RPC 2.0 over HTTP POST:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:<port>/_next/mcp \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Accept: application/json, text/event-stream" \
|
||||||
|
-d '{
|
||||||
|
"jsonrpc": "2.0",
|
||||||
|
"id": "1",
|
||||||
|
"method": "tools/call",
|
||||||
|
"params": {
|
||||||
|
"name": "<tool-name>",
|
||||||
|
"arguments": {}
|
||||||
|
}
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available Tools
|
||||||
|
|
||||||
|
#### `get_errors`
|
||||||
|
|
||||||
|
Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_errors", "arguments": {} }
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `get_routes`
|
||||||
|
|
||||||
|
Discover all routes by scanning filesystem:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_routes", "arguments": {} }
|
||||||
|
// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
|
||||||
|
|
||||||
|
#### `get_project_metadata`
|
||||||
|
|
||||||
|
Get project path and dev server URL:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_project_metadata", "arguments": {} }
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
|
||||||
|
|
||||||
|
#### `get_page_metadata`
|
||||||
|
|
||||||
|
Get runtime metadata about current page render (requires active browser session):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_page_metadata", "arguments": {} }
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns segment trie data showing layouts, boundaries, and page components.
|
||||||
|
|
||||||
|
#### `get_logs`
|
||||||
|
|
||||||
|
Get path to Next.js development log file:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_logs", "arguments": {} }
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns path to `<distDir>/logs/next-development.log`
|
||||||
|
|
||||||
|
#### `get_server_action_by_id`
|
||||||
|
|
||||||
|
Locate a Server Action by ID:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: Get Errors
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:<port>/_next/mcp \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Accept: application/json, text/event-stream" \
|
||||||
|
-d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rebuild Specific Routes (Next.js 16+)
|
||||||
|
|
||||||
|
Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Rebuild a specific route
|
||||||
|
next build --debug-build-paths "/dashboard"
|
||||||
|
|
||||||
|
# Rebuild routes matching a glob
|
||||||
|
next build --debug-build-paths "/api/*"
|
||||||
|
|
||||||
|
# Dynamic routes
|
||||||
|
next build --debug-build-paths "/blog/[slug]"
|
||||||
|
```
|
||||||
|
|
||||||
|
Use this to:
|
||||||
|
|
||||||
|
- Quickly verify a build fix without full rebuild
|
||||||
|
- Debug static generation issues for specific pages
|
||||||
|
- Iterate faster on build errors
|
||||||
74
.agents/skills/next-best-practices/directives.md
Normal file
74
.agents/skills/next-best-practices/directives.md
Normal file
@@ -0,0 +1,74 @@
|
|||||||
|
# Directives
|
||||||
|
|
||||||
|
## React Directives
|
||||||
|
|
||||||
|
These are React directives, not Next.js specific.
|
||||||
|
|
||||||
|
### `'use client'`
|
||||||
|
|
||||||
|
Marks a component as a Client Component. Required for:
|
||||||
|
|
||||||
|
- React hooks (`useState`, `useEffect`, etc.)
|
||||||
|
- Event handlers (`onClick`, `onChange`)
|
||||||
|
- Browser APIs (`window`, `localStorage`)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import { useState } from 'react';
|
||||||
|
|
||||||
|
export function Counter() {
|
||||||
|
const [count, setCount] = useState(0);
|
||||||
|
return <button onClick={() => setCount(count + 1)}>{count}</button>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: https://react.dev/reference/rsc/use-client
|
||||||
|
|
||||||
|
### `'use server'`
|
||||||
|
|
||||||
|
Marks a function as a Server Action. Can be passed to Client Components.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use server';
|
||||||
|
|
||||||
|
export async function submitForm(formData: FormData) {
|
||||||
|
// Runs on server
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Or inline within a Server Component:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function Page() {
|
||||||
|
async function submit() {
|
||||||
|
'use server';
|
||||||
|
// Runs on server
|
||||||
|
}
|
||||||
|
return <form action={submit}>...</form>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: https://react.dev/reference/rsc/use-server
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next.js Directive
|
||||||
|
|
||||||
|
### `'use cache'`
|
||||||
|
|
||||||
|
Marks a function or component for caching. Part of Next.js Cache Components.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use cache';
|
||||||
|
|
||||||
|
export async function getCachedData() {
|
||||||
|
return await fetchData();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Requires `cacheComponents: true` in `next.config.ts`.
|
||||||
|
|
||||||
|
For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache
|
||||||
228
.agents/skills/next-best-practices/error-handling.md
Normal file
228
.agents/skills/next-best-practices/error-handling.md
Normal file
@@ -0,0 +1,228 @@
|
|||||||
|
# Error Handling
|
||||||
|
|
||||||
|
Handle errors gracefully in Next.js applications.
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/getting-started/error-handling
|
||||||
|
|
||||||
|
## Error Boundaries
|
||||||
|
|
||||||
|
### `error.tsx`
|
||||||
|
|
||||||
|
Catches errors in a route segment and its children:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
export default function Error({
|
||||||
|
error,
|
||||||
|
reset
|
||||||
|
}: {
|
||||||
|
error: Error & { digest?: string };
|
||||||
|
reset: () => void;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<h2>Something went wrong!</h2>
|
||||||
|
<button onClick={() => reset()}>Try again</button>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** `error.tsx` must be a Client Component.
|
||||||
|
|
||||||
|
### `global-error.tsx`
|
||||||
|
|
||||||
|
Catches errors in root layout:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
export default function GlobalError({
|
||||||
|
error,
|
||||||
|
reset
|
||||||
|
}: {
|
||||||
|
error: Error & { digest?: string };
|
||||||
|
reset: () => void;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<body>
|
||||||
|
<h2>Something went wrong!</h2>
|
||||||
|
<button onClick={() => reset()}>Try again</button>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** Must include `<html>` and `<body>` tags.
|
||||||
|
|
||||||
|
## Server Actions: Navigation API Gotcha
|
||||||
|
|
||||||
|
**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use server'
|
||||||
|
|
||||||
|
import { redirect } from 'next/navigation'
|
||||||
|
import { notFound } from 'next/navigation'
|
||||||
|
|
||||||
|
// Bad: try-catch catches the navigation "error"
|
||||||
|
async function createPost(formData: FormData) {
|
||||||
|
try {
|
||||||
|
const post = await db.post.create({ ... })
|
||||||
|
redirect(`/posts/${post.id}`) // This throws!
|
||||||
|
} catch (error) {
|
||||||
|
// redirect() throw is caught here - navigation fails!
|
||||||
|
return { error: 'Failed to create post' }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Call navigation APIs outside try-catch
|
||||||
|
async function createPost(formData: FormData) {
|
||||||
|
let post
|
||||||
|
try {
|
||||||
|
post = await db.post.create({ ... })
|
||||||
|
} catch (error) {
|
||||||
|
return { error: 'Failed to create post' }
|
||||||
|
}
|
||||||
|
redirect(`/posts/${post.id}`) // Outside try-catch
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Re-throw navigation errors
|
||||||
|
async function createPost(formData: FormData) {
|
||||||
|
try {
|
||||||
|
const post = await db.post.create({ ... })
|
||||||
|
redirect(`/posts/${post.id}`)
|
||||||
|
} catch (error) {
|
||||||
|
if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
|
||||||
|
throw error // Re-throw navigation errors
|
||||||
|
}
|
||||||
|
return { error: 'Failed to create post' }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Same applies to:
|
||||||
|
|
||||||
|
- `redirect()` - 307 temporary redirect
|
||||||
|
- `permanentRedirect()` - 308 permanent redirect
|
||||||
|
- `notFound()` - 404 not found
|
||||||
|
- `forbidden()` - 403 forbidden
|
||||||
|
- `unauthorized()` - 401 unauthorized
|
||||||
|
|
||||||
|
Use `unstable_rethrow()` to re-throw these errors in catch blocks:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { unstable_rethrow } from 'next/navigation';
|
||||||
|
|
||||||
|
async function action() {
|
||||||
|
try {
|
||||||
|
// ...
|
||||||
|
redirect('/success');
|
||||||
|
} catch (error) {
|
||||||
|
unstable_rethrow(error); // Re-throws Next.js internal errors
|
||||||
|
return { error: 'Something went wrong' };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Redirects
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { redirect, permanentRedirect } from 'next/navigation';
|
||||||
|
|
||||||
|
// 307 Temporary - use for most cases
|
||||||
|
redirect('/new-path');
|
||||||
|
|
||||||
|
// 308 Permanent - use for URL migrations (cached by browsers)
|
||||||
|
permanentRedirect('/new-url');
|
||||||
|
```
|
||||||
|
|
||||||
|
## Auth Errors
|
||||||
|
|
||||||
|
Trigger auth-related error pages:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { forbidden, unauthorized } from 'next/navigation';
|
||||||
|
|
||||||
|
async function Page() {
|
||||||
|
const session = await getSession();
|
||||||
|
|
||||||
|
if (!session) {
|
||||||
|
unauthorized(); // Renders unauthorized.tsx (401)
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!session.hasAccess) {
|
||||||
|
forbidden(); // Renders forbidden.tsx (403)
|
||||||
|
}
|
||||||
|
|
||||||
|
return <Dashboard />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Create corresponding error pages:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/forbidden.tsx
|
||||||
|
export default function Forbidden() {
|
||||||
|
return <div>You don't have access to this resource</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// app/unauthorized.tsx
|
||||||
|
export default function Unauthorized() {
|
||||||
|
return <div>Please log in to continue</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Not Found
|
||||||
|
|
||||||
|
### `not-found.tsx`
|
||||||
|
|
||||||
|
Custom 404 page for a route segment:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export default function NotFound() {
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<h2>Not Found</h2>
|
||||||
|
<p>Could not find the requested resource</p>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Triggering Not Found
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { notFound } from 'next/navigation';
|
||||||
|
|
||||||
|
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
const post = await getPost(id);
|
||||||
|
|
||||||
|
if (!post) {
|
||||||
|
notFound(); // Renders closest not-found.tsx
|
||||||
|
}
|
||||||
|
|
||||||
|
return <div>{post.title}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Hierarchy
|
||||||
|
|
||||||
|
Errors bubble up to the nearest error boundary:
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── error.tsx # Catches errors from all children
|
||||||
|
├── blog/
|
||||||
|
│ ├── error.tsx # Catches errors in /blog/*
|
||||||
|
│ └── [slug]/
|
||||||
|
│ ├── error.tsx # Catches errors in /blog/[slug]
|
||||||
|
│ └── page.tsx
|
||||||
|
└── layout.tsx # Errors here go to global-error.tsx
|
||||||
|
```
|
||||||
141
.agents/skills/next-best-practices/file-conventions.md
Normal file
141
.agents/skills/next-best-practices/file-conventions.md
Normal file
@@ -0,0 +1,141 @@
|
|||||||
|
# File Conventions
|
||||||
|
|
||||||
|
Next.js App Router uses file-based routing with special file conventions.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/getting-started/project-structure
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── layout.tsx # Root layout (required)
|
||||||
|
├── page.tsx # Home page (/)
|
||||||
|
├── loading.tsx # Loading UI
|
||||||
|
├── error.tsx # Error UI
|
||||||
|
├── not-found.tsx # 404 UI
|
||||||
|
├── global-error.tsx # Global error UI
|
||||||
|
├── route.ts # API endpoint
|
||||||
|
├── template.tsx # Re-rendered layout
|
||||||
|
├── default.tsx # Parallel route fallback
|
||||||
|
├── blog/
|
||||||
|
│ ├── page.tsx # /blog
|
||||||
|
│ └── [slug]/
|
||||||
|
│ └── page.tsx # /blog/:slug
|
||||||
|
└── (group)/ # Route group (no URL impact)
|
||||||
|
└── page.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
## Special Files
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
| --------------- | ---------------------------------------- |
|
||||||
|
| `page.tsx` | UI for a route segment |
|
||||||
|
| `layout.tsx` | Shared UI for segment and children |
|
||||||
|
| `loading.tsx` | Loading UI (Suspense boundary) |
|
||||||
|
| `error.tsx` | Error UI (Error boundary) |
|
||||||
|
| `not-found.tsx` | 404 UI |
|
||||||
|
| `route.ts` | API endpoint |
|
||||||
|
| `template.tsx` | Like layout but re-renders on navigation |
|
||||||
|
| `default.tsx` | Fallback for parallel routes |
|
||||||
|
|
||||||
|
## Route Segments
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── blog/ # Static segment: /blog
|
||||||
|
├── [slug]/ # Dynamic segment: /:slug
|
||||||
|
├── [...slug]/ # Catch-all: /a/b/c
|
||||||
|
├── [[...slug]]/ # Optional catch-all: / or /a/b/c
|
||||||
|
└── (marketing)/ # Route group (ignored in URL)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parallel Routes
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── @analytics/
|
||||||
|
│ └── page.tsx
|
||||||
|
├── @sidebar/
|
||||||
|
│ └── page.tsx
|
||||||
|
└── layout.tsx # Receives { analytics, sidebar } as props
|
||||||
|
```
|
||||||
|
|
||||||
|
## Intercepting Routes
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── feed/
|
||||||
|
│ └── page.tsx
|
||||||
|
├── @modal/
|
||||||
|
│ └── (.)photo/[id]/ # Intercepts /photo/[id] from /feed
|
||||||
|
│ └── page.tsx
|
||||||
|
└── photo/[id]/
|
||||||
|
└── page.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Conventions:
|
||||||
|
|
||||||
|
- `(.)` - same level
|
||||||
|
- `(..)` - one level up
|
||||||
|
- `(..)(..)` - two levels up
|
||||||
|
- `(...)` - from root
|
||||||
|
|
||||||
|
## Private Folders
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── _components/ # Private folder (not a route)
|
||||||
|
│ └── Button.tsx
|
||||||
|
└── page.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Prefix with `_` to exclude from routing.
|
||||||
|
|
||||||
|
## Middleware / Proxy
|
||||||
|
|
||||||
|
### Next.js 14-15: `middleware.ts`
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// middleware.ts (root of project)
|
||||||
|
import { NextResponse } from 'next/server';
|
||||||
|
import type { NextRequest } from 'next/server';
|
||||||
|
|
||||||
|
export function middleware(request: NextRequest) {
|
||||||
|
// Auth, redirects, rewrites, etc.
|
||||||
|
return NextResponse.next();
|
||||||
|
}
|
||||||
|
|
||||||
|
export const config = {
|
||||||
|
matcher: ['/dashboard/:path*', '/api/:path*']
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Next.js 16+: `proxy.ts`
|
||||||
|
|
||||||
|
Renamed for clarity - same capabilities, different names:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
// proxy.ts (root of project)
|
||||||
|
import { NextResponse } from 'next/server';
|
||||||
|
import type { NextRequest } from 'next/server';
|
||||||
|
|
||||||
|
export function proxy(request: NextRequest) {
|
||||||
|
// Same logic as middleware
|
||||||
|
return NextResponse.next();
|
||||||
|
}
|
||||||
|
|
||||||
|
export const proxyConfig = {
|
||||||
|
matcher: ['/dashboard/:path*', '/api/:path*']
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
| Version | File | Export | Config |
|
||||||
|
| ------- | --------------- | -------------- | ------------- |
|
||||||
|
| v14-15 | `middleware.ts` | `middleware()` | `config` |
|
||||||
|
| v16+ | `proxy.ts` | `proxy()` | `proxyConfig` |
|
||||||
|
|
||||||
|
**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
|
||||||
|
|
||||||
|
## File Conventions Reference
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/api-reference/file-conventions
|
||||||
246
.agents/skills/next-best-practices/font.md
Normal file
246
.agents/skills/next-best-practices/font.md
Normal file
@@ -0,0 +1,246 @@
|
|||||||
|
# Font Optimization
|
||||||
|
|
||||||
|
Use `next/font` for automatic font optimization with zero layout shift.
|
||||||
|
|
||||||
|
## Google Fonts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/layout.tsx
|
||||||
|
import { Inter } from 'next/font/google';
|
||||||
|
|
||||||
|
const inter = Inter({ subsets: ['latin'] });
|
||||||
|
|
||||||
|
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||||
|
return (
|
||||||
|
<html lang='en' className={inter.className}>
|
||||||
|
<body>{children}</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multiple Fonts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { Inter, Roboto_Mono } from 'next/font/google';
|
||||||
|
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
variable: '--font-inter'
|
||||||
|
});
|
||||||
|
|
||||||
|
const robotoMono = Roboto_Mono({
|
||||||
|
subsets: ['latin'],
|
||||||
|
variable: '--font-roboto-mono'
|
||||||
|
});
|
||||||
|
|
||||||
|
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
||||||
|
return (
|
||||||
|
<html lang='en' className={`${inter.variable} ${robotoMono.variable}`}>
|
||||||
|
<body>{children}</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Use in CSS:
|
||||||
|
|
||||||
|
```css
|
||||||
|
body {
|
||||||
|
font-family: var(--font-inter);
|
||||||
|
}
|
||||||
|
|
||||||
|
code {
|
||||||
|
font-family: var(--font-roboto-mono);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Font Weights and Styles
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Single weight
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
weight: '400'
|
||||||
|
});
|
||||||
|
|
||||||
|
// Multiple weights
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
weight: ['400', '500', '700']
|
||||||
|
});
|
||||||
|
|
||||||
|
// Variable font (recommended) - includes all weights
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin']
|
||||||
|
// No weight needed - variable fonts support all weights
|
||||||
|
});
|
||||||
|
|
||||||
|
// With italic
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
style: ['normal', 'italic']
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Local Fonts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import localFont from 'next/font/local';
|
||||||
|
|
||||||
|
const myFont = localFont({
|
||||||
|
src: './fonts/MyFont.woff2'
|
||||||
|
});
|
||||||
|
|
||||||
|
// Multiple files for different weights
|
||||||
|
const myFont = localFont({
|
||||||
|
src: [
|
||||||
|
{
|
||||||
|
path: './fonts/MyFont-Regular.woff2',
|
||||||
|
weight: '400',
|
||||||
|
style: 'normal'
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: './fonts/MyFont-Bold.woff2',
|
||||||
|
weight: '700',
|
||||||
|
style: 'normal'
|
||||||
|
}
|
||||||
|
]
|
||||||
|
});
|
||||||
|
|
||||||
|
// Variable font
|
||||||
|
const myFont = localFont({
|
||||||
|
src: './fonts/MyFont-Variable.woff2',
|
||||||
|
variable: '--font-my-font'
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tailwind CSS Integration
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/layout.tsx
|
||||||
|
import { Inter } from 'next/font/google';
|
||||||
|
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
variable: '--font-inter'
|
||||||
|
});
|
||||||
|
|
||||||
|
export default function RootLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<html lang='en' className={inter.variable}>
|
||||||
|
<body>{children}</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```js
|
||||||
|
// tailwind.config.js
|
||||||
|
module.exports = {
|
||||||
|
theme: {
|
||||||
|
extend: {
|
||||||
|
fontFamily: {
|
||||||
|
sans: ['var(--font-inter)']
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Preloading Subsets
|
||||||
|
|
||||||
|
Only load needed character subsets:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Latin only (most common)
|
||||||
|
const inter = Inter({ subsets: ['latin'] });
|
||||||
|
|
||||||
|
// Multiple subsets
|
||||||
|
const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] });
|
||||||
|
```
|
||||||
|
|
||||||
|
## Display Strategy
|
||||||
|
|
||||||
|
Control font loading behavior:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const inter = Inter({
|
||||||
|
subsets: ['latin'],
|
||||||
|
display: 'swap' // Default - shows fallback, swaps when loaded
|
||||||
|
});
|
||||||
|
|
||||||
|
// Options:
|
||||||
|
// 'auto' - browser decides
|
||||||
|
// 'block' - short block period, then swap
|
||||||
|
// 'swap' - immediate fallback, swap when ready (recommended)
|
||||||
|
// 'fallback' - short block, short swap, then fallback
|
||||||
|
// 'optional' - short block, no swap (use if font is optional)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Don't Use Manual Font Links
|
||||||
|
|
||||||
|
Always use `next/font` instead of `<link>` tags for Google Fonts.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Manual link tag (blocks rendering, no optimization)
|
||||||
|
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
|
||||||
|
|
||||||
|
// Bad: Missing display and preconnect
|
||||||
|
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
|
||||||
|
|
||||||
|
// Good: Use next/font (self-hosted, zero layout shift)
|
||||||
|
import { Inter } from 'next/font/google'
|
||||||
|
|
||||||
|
const inter = Inter({ subsets: ['latin'] })
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Mistakes
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Importing font in every component
|
||||||
|
// components/Button.tsx
|
||||||
|
import { Inter } from 'next/font/google'
|
||||||
|
const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
|
||||||
|
|
||||||
|
// Good: Import once in layout, use CSS variable
|
||||||
|
// app/layout.tsx
|
||||||
|
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
|
||||||
|
|
||||||
|
// Bad: Using @import in CSS (blocks rendering)
|
||||||
|
/* globals.css */
|
||||||
|
@import url('https://fonts.googleapis.com/css2?family=Inter');
|
||||||
|
|
||||||
|
// Good: Use next/font (self-hosted, no network request)
|
||||||
|
import { Inter } from 'next/font/google'
|
||||||
|
|
||||||
|
// Bad: Loading all weights when only using a few
|
||||||
|
const inter = Inter({ subsets: ['latin'] }) // Loads all weights
|
||||||
|
|
||||||
|
// Good: Specify only needed weights (for non-variable fonts)
|
||||||
|
const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
|
||||||
|
|
||||||
|
// Bad: Missing subset - loads all characters
|
||||||
|
const inter = Inter({})
|
||||||
|
|
||||||
|
// Good: Always specify subset
|
||||||
|
const inter = Inter({ subsets: ['latin'] })
|
||||||
|
```
|
||||||
|
|
||||||
|
## Font in Specific Components
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// For component-specific fonts, export from a shared file
|
||||||
|
// lib/fonts.ts
|
||||||
|
import { Inter, Playfair_Display } from 'next/font/google';
|
||||||
|
|
||||||
|
export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
|
||||||
|
export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' });
|
||||||
|
|
||||||
|
// components/Heading.tsx
|
||||||
|
import { playfair } from '@/lib/fonts';
|
||||||
|
|
||||||
|
export function Heading({ children }) {
|
||||||
|
return <h1 className={playfair.className}>{children}</h1>;
|
||||||
|
}
|
||||||
|
```
|
||||||
108
.agents/skills/next-best-practices/functions.md
Normal file
108
.agents/skills/next-best-practices/functions.md
Normal file
@@ -0,0 +1,108 @@
|
|||||||
|
# Functions
|
||||||
|
|
||||||
|
Next.js function APIs.
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/api-reference/functions
|
||||||
|
|
||||||
|
## Navigation Hooks (Client)
|
||||||
|
|
||||||
|
| Hook | Purpose | Reference |
|
||||||
|
| --------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||||
|
| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) |
|
||||||
|
| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) |
|
||||||
|
| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) |
|
||||||
|
| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) |
|
||||||
|
| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) |
|
||||||
|
| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
|
||||||
|
| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) |
|
||||||
|
| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) |
|
||||||
|
|
||||||
|
## Server Functions
|
||||||
|
|
||||||
|
| Function | Purpose | Reference |
|
||||||
|
| ------------ | -------------------------------------------- | ---------------------------------------------------------------------- |
|
||||||
|
| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) |
|
||||||
|
| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) |
|
||||||
|
| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
|
||||||
|
| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) |
|
||||||
|
| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
|
||||||
|
| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) |
|
||||||
|
|
||||||
|
## Generate Functions
|
||||||
|
|
||||||
|
| Function | Purpose | Reference |
|
||||||
|
| ----------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||||
|
| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) |
|
||||||
|
| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) |
|
||||||
|
| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) |
|
||||||
|
| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) |
|
||||||
|
| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
|
||||||
|
|
||||||
|
## Request/Response
|
||||||
|
|
||||||
|
| Function | Purpose | Reference |
|
||||||
|
| --------------- | ------------------------------ | -------------------------------------------------------------------------- |
|
||||||
|
| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) |
|
||||||
|
| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) |
|
||||||
|
| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
|
||||||
|
|
||||||
|
## Common Examples
|
||||||
|
|
||||||
|
### Navigation
|
||||||
|
|
||||||
|
Use `next/link` for internal navigation instead of `<a>` tags.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Plain anchor tag
|
||||||
|
<a href='/about'>About</a>;
|
||||||
|
|
||||||
|
// Good: Next.js Link
|
||||||
|
import Link from 'next/link';
|
||||||
|
|
||||||
|
<Link href='/about'>About</Link>;
|
||||||
|
```
|
||||||
|
|
||||||
|
Active link styling:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import Link from 'next/link';
|
||||||
|
import { usePathname } from 'next/navigation';
|
||||||
|
|
||||||
|
export function NavLink({ href, children }) {
|
||||||
|
const pathname = usePathname();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Link href={href} className={pathname === href ? 'active' : ''}>
|
||||||
|
{children}
|
||||||
|
</Link>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Static Generation
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/blog/[slug]/page.tsx
|
||||||
|
export async function generateStaticParams() {
|
||||||
|
const posts = await getPosts();
|
||||||
|
return posts.map((post) => ({ slug: post.slug }));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### After Response
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { after } from 'next/server';
|
||||||
|
|
||||||
|
export async function POST(request: Request) {
|
||||||
|
const data = await processRequest(request);
|
||||||
|
|
||||||
|
after(async () => {
|
||||||
|
await logAnalytics(data);
|
||||||
|
});
|
||||||
|
|
||||||
|
return Response.json({ success: true });
|
||||||
|
}
|
||||||
|
```
|
||||||
86
.agents/skills/next-best-practices/hydration-error.md
Normal file
86
.agents/skills/next-best-practices/hydration-error.md
Normal file
@@ -0,0 +1,86 @@
|
|||||||
|
# Hydration Errors
|
||||||
|
|
||||||
|
Diagnose and fix React hydration mismatch errors.
|
||||||
|
|
||||||
|
## Error Signs
|
||||||
|
|
||||||
|
- "Hydration failed because the initial UI does not match"
|
||||||
|
- "Text content does not match server-rendered HTML"
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
In development, click the hydration error to see the server/client diff.
|
||||||
|
|
||||||
|
## Common Causes and Fixes
|
||||||
|
|
||||||
|
### Browser-only APIs
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Causes mismatch - window doesn't exist on server
|
||||||
|
<div>{window.innerWidth}</div>;
|
||||||
|
|
||||||
|
// Good: Use client component with mounted check
|
||||||
|
('use client');
|
||||||
|
import { useState, useEffect } from 'react';
|
||||||
|
|
||||||
|
export function ClientOnly({ children }: { children: React.ReactNode }) {
|
||||||
|
const [mounted, setMounted] = useState(false);
|
||||||
|
useEffect(() => setMounted(true), []);
|
||||||
|
return mounted ? children : null;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Date/Time Rendering
|
||||||
|
|
||||||
|
Server and client may be in different timezones:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Causes mismatch
|
||||||
|
<span>{new Date().toLocaleString()}</span>;
|
||||||
|
|
||||||
|
// Good: Render on client only
|
||||||
|
('use client');
|
||||||
|
const [time, setTime] = useState<string>();
|
||||||
|
useEffect(() => setTime(new Date().toLocaleString()), []);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Random Values or IDs
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Random values differ between server and client
|
||||||
|
<div id={Math.random().toString()}>
|
||||||
|
|
||||||
|
// Good: Use useId hook
|
||||||
|
import { useId } from 'react'
|
||||||
|
|
||||||
|
function Input() {
|
||||||
|
const id = useId()
|
||||||
|
return <input id={id} />
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Invalid HTML Nesting
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Invalid - div inside p
|
||||||
|
<p><div>Content</div></p>
|
||||||
|
|
||||||
|
// Bad: Invalid - p inside p
|
||||||
|
<p><p>Nested</p></p>
|
||||||
|
|
||||||
|
// Good: Valid nesting
|
||||||
|
<div><p>Content</p></div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Third-party Scripts
|
||||||
|
|
||||||
|
Scripts that modify DOM during hydration.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Use next/script with afterInteractive
|
||||||
|
import Script from 'next/script';
|
||||||
|
|
||||||
|
export default function Page() {
|
||||||
|
return <Script src='https://example.com/script.js' strategy='afterInteractive' />;
|
||||||
|
}
|
||||||
|
```
|
||||||
173
.agents/skills/next-best-practices/image.md
Normal file
173
.agents/skills/next-best-practices/image.md
Normal file
@@ -0,0 +1,173 @@
|
|||||||
|
# Image Optimization
|
||||||
|
|
||||||
|
Use `next/image` for automatic image optimization.
|
||||||
|
|
||||||
|
## Always Use next/image
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Avoid native img
|
||||||
|
<img src='/hero.png' alt='Hero' />;
|
||||||
|
|
||||||
|
// Good: Use next/image
|
||||||
|
import Image from 'next/image';
|
||||||
|
<Image src='/hero.png' alt='Hero' width={800} height={400} />;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Required Props
|
||||||
|
|
||||||
|
Images need explicit dimensions to prevent layout shift:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Local images - dimensions inferred automatically
|
||||||
|
import heroImage from './hero.png'
|
||||||
|
<Image src={heroImage} alt="Hero" />
|
||||||
|
|
||||||
|
// Remote images - must specify width/height
|
||||||
|
<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
|
||||||
|
|
||||||
|
// Or use fill for parent-relative sizing
|
||||||
|
<div style={{ position: 'relative', width: '100%', height: 400 }}>
|
||||||
|
<Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Remote Images Configuration
|
||||||
|
|
||||||
|
Remote domains must be configured in `next.config.js`:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
images: {
|
||||||
|
remotePatterns: [
|
||||||
|
{
|
||||||
|
protocol: 'https',
|
||||||
|
hostname: 'example.com',
|
||||||
|
pathname: '/images/**'
|
||||||
|
},
|
||||||
|
{
|
||||||
|
protocol: 'https',
|
||||||
|
hostname: '*.cdn.com' // Wildcard subdomain
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Responsive Images
|
||||||
|
|
||||||
|
Use `sizes` to tell the browser which size to download:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Full-width hero
|
||||||
|
<Image
|
||||||
|
src="/hero.png"
|
||||||
|
alt="Hero"
|
||||||
|
fill
|
||||||
|
sizes="100vw"
|
||||||
|
/>
|
||||||
|
|
||||||
|
// Responsive grid (3 columns on desktop, 1 on mobile)
|
||||||
|
<Image
|
||||||
|
src="/card.png"
|
||||||
|
alt="Card"
|
||||||
|
fill
|
||||||
|
sizes="(max-width: 768px) 100vw, 33vw"
|
||||||
|
/>
|
||||||
|
|
||||||
|
// Fixed sidebar image
|
||||||
|
<Image
|
||||||
|
src="/avatar.png"
|
||||||
|
alt="Avatar"
|
||||||
|
width={200}
|
||||||
|
height={200}
|
||||||
|
sizes="200px"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Blur Placeholder
|
||||||
|
|
||||||
|
Prevent layout shift with placeholders:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Local images - automatic blur hash
|
||||||
|
import heroImage from './hero.png'
|
||||||
|
<Image src={heroImage} alt="Hero" placeholder="blur" />
|
||||||
|
|
||||||
|
// Remote images - provide blurDataURL
|
||||||
|
<Image
|
||||||
|
src="https://example.com/image.jpg"
|
||||||
|
alt="Hero"
|
||||||
|
width={800}
|
||||||
|
height={400}
|
||||||
|
placeholder="blur"
|
||||||
|
blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
|
||||||
|
/>
|
||||||
|
|
||||||
|
// Or use color placeholder
|
||||||
|
<Image
|
||||||
|
src="https://example.com/image.jpg"
|
||||||
|
alt="Hero"
|
||||||
|
width={800}
|
||||||
|
height={400}
|
||||||
|
placeholder="empty"
|
||||||
|
style={{ backgroundColor: '#e0e0e0' }}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Priority Loading
|
||||||
|
|
||||||
|
Use `priority` for above-the-fold images (LCP):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Hero image - loads immediately
|
||||||
|
<Image src="/hero.png" alt="Hero" fill priority />
|
||||||
|
|
||||||
|
// Below-fold images - lazy loaded by default (no priority needed)
|
||||||
|
<Image src="/card.png" alt="Card" width={400} height={300} />
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Mistakes
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Missing sizes with fill - downloads largest image
|
||||||
|
<Image src="/hero.png" alt="Hero" fill />
|
||||||
|
|
||||||
|
// Good: Add sizes for proper responsive behavior
|
||||||
|
<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
|
||||||
|
|
||||||
|
// Bad: Using width/height for aspect ratio only
|
||||||
|
<Image src="/hero.png" alt="Hero" width={16} height={9} />
|
||||||
|
|
||||||
|
// Good: Use actual display dimensions or fill with sizes
|
||||||
|
<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
|
||||||
|
|
||||||
|
// Bad: Remote image without config
|
||||||
|
<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
|
||||||
|
// Error: Invalid src prop, hostname not configured
|
||||||
|
|
||||||
|
// Good: Add hostname to next.config.js remotePatterns
|
||||||
|
```
|
||||||
|
|
||||||
|
## Static Export
|
||||||
|
|
||||||
|
When using `output: 'export'`, use `unoptimized` or custom loader:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Option 1: Disable optimization
|
||||||
|
<Image src='/hero.png' alt='Hero' width={800} height={400} unoptimized />;
|
||||||
|
|
||||||
|
// Option 2: Global config
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
output: 'export',
|
||||||
|
images: { unoptimized: true }
|
||||||
|
};
|
||||||
|
|
||||||
|
// Option 3: Custom loader (Cloudinary, Imgix, etc.)
|
||||||
|
const cloudinaryLoader = ({ src, width, quality }) => {
|
||||||
|
return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`;
|
||||||
|
};
|
||||||
|
|
||||||
|
<Image loader={cloudinaryLoader} src='sample.jpg' alt='Sample' width={800} height={400} />;
|
||||||
|
```
|
||||||
292
.agents/skills/next-best-practices/metadata.md
Normal file
292
.agents/skills/next-best-practices/metadata.md
Normal file
@@ -0,0 +1,292 @@
|
|||||||
|
# Metadata
|
||||||
|
|
||||||
|
Add SEO metadata to Next.js pages using the Metadata API.
|
||||||
|
|
||||||
|
## Important: Server Components Only
|
||||||
|
|
||||||
|
The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
|
||||||
|
|
||||||
|
If the target page has `'use client'`:
|
||||||
|
|
||||||
|
1. Remove `'use client'` if possible, move client logic to child components
|
||||||
|
2. Or extract metadata to a parent Server Component layout
|
||||||
|
3. Or split the file: Server Component with metadata imports Client Components
|
||||||
|
|
||||||
|
## Static Metadata
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import type { Metadata } from 'next';
|
||||||
|
|
||||||
|
export const metadata: Metadata = {
|
||||||
|
title: 'Page Title',
|
||||||
|
description: 'Page description for search engines'
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dynamic Metadata
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import type { Metadata } from 'next';
|
||||||
|
|
||||||
|
type Props = { params: Promise<{ slug: string }> };
|
||||||
|
|
||||||
|
export async function generateMetadata({ params }: Props): Promise<Metadata> {
|
||||||
|
const { slug } = await params;
|
||||||
|
const post = await getPost(slug);
|
||||||
|
return { title: post.title, description: post.description };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Avoid Duplicate Fetches
|
||||||
|
|
||||||
|
Use React `cache()` when the same data is needed for both metadata and page:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { cache } from 'react';
|
||||||
|
|
||||||
|
export const getPost = cache(async (slug: string) => {
|
||||||
|
return await db.posts.findFirst({ where: { slug } });
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Viewport
|
||||||
|
|
||||||
|
Separate from metadata for streaming support:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import type { Viewport } from 'next';
|
||||||
|
|
||||||
|
export const viewport: Viewport = {
|
||||||
|
width: 'device-width',
|
||||||
|
initialScale: 1,
|
||||||
|
themeColor: '#000000'
|
||||||
|
};
|
||||||
|
|
||||||
|
// Or dynamic
|
||||||
|
export function generateViewport({ params }): Viewport {
|
||||||
|
return { themeColor: getThemeColor(params) };
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Title Templates
|
||||||
|
|
||||||
|
In root layout for consistent naming:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export const metadata: Metadata = {
|
||||||
|
title: { default: 'Site Name', template: '%s | Site Name' }
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Metadata File Conventions
|
||||||
|
|
||||||
|
Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
|
||||||
|
|
||||||
|
Place these files in `app/` directory (or route segments):
|
||||||
|
|
||||||
|
| File | Purpose |
|
||||||
|
| ------------------------------- | --------------------------------------------- |
|
||||||
|
| `favicon.ico` | Favicon |
|
||||||
|
| `icon.png` / `icon.svg` | App icon |
|
||||||
|
| `apple-icon.png` | Apple app icon |
|
||||||
|
| `opengraph-image.png` | OG image |
|
||||||
|
| `twitter-image.png` | Twitter card image |
|
||||||
|
| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
|
||||||
|
| `robots.ts` / `robots.txt` | Robots directives |
|
||||||
|
| `manifest.ts` / `manifest.json` | Web app manifest |
|
||||||
|
|
||||||
|
## SEO Best Practice: Static Files Are Often Enough
|
||||||
|
|
||||||
|
For most sites, **static metadata files provide excellent SEO coverage**:
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── favicon.ico
|
||||||
|
├── opengraph-image.png # Works for both OG and Twitter
|
||||||
|
├── sitemap.ts
|
||||||
|
├── robots.ts
|
||||||
|
└── layout.tsx # With title/description metadata
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tips:**
|
||||||
|
|
||||||
|
- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
|
||||||
|
- Static `title` and `description` in layout metadata is sufficient for most pages
|
||||||
|
- Only use dynamic `generateMetadata` when content varies per page
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# OG Image Generation
|
||||||
|
|
||||||
|
Generate dynamic Open Graph images using `next/og`.
|
||||||
|
|
||||||
|
## Important Rules
|
||||||
|
|
||||||
|
1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
|
||||||
|
2. **No searchParams** - OG images can't access search params, use route params instead
|
||||||
|
3. **Avoid Edge runtime** - Use default Node.js runtime
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good
|
||||||
|
import { ImageResponse } from 'next/og';
|
||||||
|
|
||||||
|
// Bad
|
||||||
|
// import { ImageResponse } from '@vercel/og'
|
||||||
|
// export const runtime = 'edge'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Basic OG Image
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/opengraph-image.tsx
|
||||||
|
import { ImageResponse } from 'next/og';
|
||||||
|
|
||||||
|
export const alt = 'Site Name';
|
||||||
|
export const size = { width: 1200, height: 630 };
|
||||||
|
export const contentType = 'image/png';
|
||||||
|
|
||||||
|
export default function Image() {
|
||||||
|
return new ImageResponse(
|
||||||
|
<div
|
||||||
|
style={{
|
||||||
|
fontSize: 128,
|
||||||
|
background: 'white',
|
||||||
|
width: '100%',
|
||||||
|
height: '100%',
|
||||||
|
display: 'flex',
|
||||||
|
alignItems: 'center',
|
||||||
|
justifyContent: 'center'
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
Hello World
|
||||||
|
</div>,
|
||||||
|
{ ...size }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dynamic OG Image
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/blog/[slug]/opengraph-image.tsx
|
||||||
|
import { ImageResponse } from 'next/og';
|
||||||
|
|
||||||
|
export const alt = 'Blog Post';
|
||||||
|
export const size = { width: 1200, height: 630 };
|
||||||
|
export const contentType = 'image/png';
|
||||||
|
|
||||||
|
type Props = { params: Promise<{ slug: string }> };
|
||||||
|
|
||||||
|
export default async function Image({ params }: Props) {
|
||||||
|
const { slug } = await params;
|
||||||
|
const post = await getPost(slug);
|
||||||
|
|
||||||
|
return new ImageResponse(
|
||||||
|
<div
|
||||||
|
style={{
|
||||||
|
fontSize: 48,
|
||||||
|
background: 'linear-gradient(to bottom, #1a1a1a, #333)',
|
||||||
|
color: 'white',
|
||||||
|
width: '100%',
|
||||||
|
height: '100%',
|
||||||
|
display: 'flex',
|
||||||
|
flexDirection: 'column',
|
||||||
|
alignItems: 'center',
|
||||||
|
justifyContent: 'center',
|
||||||
|
padding: 48
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
<div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
|
||||||
|
<div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
|
||||||
|
</div>,
|
||||||
|
{ ...size }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Custom Fonts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { ImageResponse } from 'next/og';
|
||||||
|
import { join } from 'path';
|
||||||
|
import { readFile } from 'fs/promises';
|
||||||
|
|
||||||
|
export default async function Image() {
|
||||||
|
const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf');
|
||||||
|
const fontData = await readFile(fontPath);
|
||||||
|
|
||||||
|
return new ImageResponse(
|
||||||
|
<div style={{ fontFamily: 'Inter', fontSize: 64 }}>Custom Font Text</div>,
|
||||||
|
{
|
||||||
|
width: 1200,
|
||||||
|
height: 630,
|
||||||
|
fonts: [{ name: 'Inter', data: fontData, style: 'normal' }]
|
||||||
|
}
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## File Naming
|
||||||
|
|
||||||
|
- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
|
||||||
|
- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
|
||||||
|
|
||||||
|
## Styling Notes
|
||||||
|
|
||||||
|
ImageResponse uses Flexbox layout:
|
||||||
|
|
||||||
|
- Use `display: 'flex'`
|
||||||
|
- No CSS Grid support
|
||||||
|
- Styles must be inline objects
|
||||||
|
|
||||||
|
## Multiple OG Images
|
||||||
|
|
||||||
|
Use `generateImageMetadata` for multiple images per route:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/blog/[slug]/opengraph-image.tsx
|
||||||
|
import { ImageResponse } from 'next/og';
|
||||||
|
|
||||||
|
export async function generateImageMetadata({ params }) {
|
||||||
|
const images = await getPostImages(params.slug);
|
||||||
|
return images.map((img, idx) => ({
|
||||||
|
id: idx,
|
||||||
|
alt: img.alt,
|
||||||
|
size: { width: 1200, height: 630 },
|
||||||
|
contentType: 'image/png'
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
|
||||||
|
export default async function Image({ params, id }) {
|
||||||
|
const images = await getPostImages(params.slug);
|
||||||
|
const image = images[id];
|
||||||
|
return new ImageResponse(/* ... */);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multiple Sitemaps
|
||||||
|
|
||||||
|
Use `generateSitemaps` for large sites:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/sitemap.ts
|
||||||
|
import type { MetadataRoute } from 'next';
|
||||||
|
|
||||||
|
export async function generateSitemaps() {
|
||||||
|
// Return array of sitemap IDs
|
||||||
|
return [{ id: 0 }, { id: 1 }, { id: 2 }];
|
||||||
|
}
|
||||||
|
|
||||||
|
export default async function sitemap({ id }: { id: number }): Promise<MetadataRoute.Sitemap> {
|
||||||
|
const start = id * 50000;
|
||||||
|
const end = start + 50000;
|
||||||
|
const products = await getProducts(start, end);
|
||||||
|
|
||||||
|
return products.map((product) => ({
|
||||||
|
url: `https://example.com/product/${product.id}`,
|
||||||
|
lastModified: product.updatedAt
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.
|
||||||
286
.agents/skills/next-best-practices/parallel-routes.md
Normal file
286
.agents/skills/next-best-practices/parallel-routes.md
Normal file
@@ -0,0 +1,286 @@
|
|||||||
|
# Parallel & Intercepting Routes
|
||||||
|
|
||||||
|
Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── @modal/ # Parallel route slot
|
||||||
|
│ ├── default.tsx # Required! Returns null
|
||||||
|
│ ├── (.)photos/ # Intercepts /photos/*
|
||||||
|
│ │ └── [id]/
|
||||||
|
│ │ └── page.tsx # Modal content
|
||||||
|
│ └── [...]catchall/ # Optional: catch unmatched
|
||||||
|
│ └── page.tsx
|
||||||
|
├── photos/
|
||||||
|
│ └── [id]/
|
||||||
|
│ └── page.tsx # Full page (direct access)
|
||||||
|
├── layout.tsx # Renders both children and @modal
|
||||||
|
└── page.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 1: Root Layout with Slot
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/layout.tsx
|
||||||
|
export default function RootLayout({
|
||||||
|
children,
|
||||||
|
modal
|
||||||
|
}: {
|
||||||
|
children: React.ReactNode;
|
||||||
|
modal: React.ReactNode;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<body>
|
||||||
|
{children}
|
||||||
|
{modal}
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 2: Default File (Critical!)
|
||||||
|
|
||||||
|
**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/@modal/default.tsx
|
||||||
|
export default function Default() {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
|
||||||
|
|
||||||
|
## Step 3: Intercepting Route (Modal)
|
||||||
|
|
||||||
|
The `(.)` prefix intercepts routes at the same level.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/@modal/(.)photos/[id]/page.tsx
|
||||||
|
import { Modal } from '@/components/modal';
|
||||||
|
|
||||||
|
export default async function PhotoModal({ params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
const photo = await getPhoto(id);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Modal>
|
||||||
|
<img src={photo.url} alt={photo.title} />
|
||||||
|
</Modal>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4: Full Page (Direct Access)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/photos/[id]/page.tsx
|
||||||
|
export default async function PhotoPage({ params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
const photo = await getPhoto(id);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className='full-page'>
|
||||||
|
<img src={photo.url} alt={photo.title} />
|
||||||
|
<h1>{photo.title}</h1>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 5: Modal Component with Correct Closing
|
||||||
|
|
||||||
|
**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// components/modal.tsx
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import { useRouter } from 'next/navigation';
|
||||||
|
import { useCallback, useEffect, useRef } from 'react';
|
||||||
|
|
||||||
|
export function Modal({ children }: { children: React.ReactNode }) {
|
||||||
|
const router = useRouter();
|
||||||
|
const overlayRef = useRef<HTMLDivElement>(null);
|
||||||
|
|
||||||
|
// Close on escape key
|
||||||
|
useEffect(() => {
|
||||||
|
function onKeyDown(e: KeyboardEvent) {
|
||||||
|
if (e.key === 'Escape') {
|
||||||
|
router.back(); // Correct
|
||||||
|
}
|
||||||
|
}
|
||||||
|
document.addEventListener('keydown', onKeyDown);
|
||||||
|
return () => document.removeEventListener('keydown', onKeyDown);
|
||||||
|
}, [router]);
|
||||||
|
|
||||||
|
// Close on overlay click
|
||||||
|
const handleOverlayClick = useCallback(
|
||||||
|
(e: React.MouseEvent) => {
|
||||||
|
if (e.target === overlayRef.current) {
|
||||||
|
router.back(); // Correct
|
||||||
|
}
|
||||||
|
},
|
||||||
|
[router]
|
||||||
|
);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div
|
||||||
|
ref={overlayRef}
|
||||||
|
onClick={handleOverlayClick}
|
||||||
|
className='fixed inset-0 bg-black/50 flex items-center justify-center z-50'
|
||||||
|
>
|
||||||
|
<div className='bg-white rounded-lg p-6 max-w-2xl w-full mx-4'>
|
||||||
|
<button
|
||||||
|
onClick={() => router.back()} // Correct!
|
||||||
|
className='absolute top-4 right-4'
|
||||||
|
>
|
||||||
|
Close
|
||||||
|
</button>
|
||||||
|
{children}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why NOT `router.push('/')` or `<Link href="/">`?
|
||||||
|
|
||||||
|
Using `push` or `Link` to "close" a modal:
|
||||||
|
|
||||||
|
1. Adds a new history entry (back button shows modal again)
|
||||||
|
2. Doesn't properly clear the intercepted route
|
||||||
|
3. Can cause the modal to flash or persist unexpectedly
|
||||||
|
|
||||||
|
`router.back()` correctly:
|
||||||
|
|
||||||
|
1. Removes the intercepted route from history
|
||||||
|
2. Returns to the previous page
|
||||||
|
3. Properly unmounts the modal
|
||||||
|
|
||||||
|
## Route Matcher Reference
|
||||||
|
|
||||||
|
Matchers match **route segments**, not filesystem paths:
|
||||||
|
|
||||||
|
| Matcher | Matches | Example |
|
||||||
|
| ---------- | ------------- | --------------------------------------------------------------------- |
|
||||||
|
| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
|
||||||
|
| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
|
||||||
|
| `(..)(..)` | Two levels up | Rarely used |
|
||||||
|
| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
|
||||||
|
|
||||||
|
**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
|
||||||
|
|
||||||
|
## Handling Hard Navigation
|
||||||
|
|
||||||
|
When users directly visit `/photos/123` (bookmark, refresh, shared link):
|
||||||
|
|
||||||
|
- The intercepting route is bypassed
|
||||||
|
- The full `photos/[id]/page.tsx` renders
|
||||||
|
- Modal doesn't appear (expected behavior)
|
||||||
|
|
||||||
|
If you want the modal to appear on direct access too, you need additional logic:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/photos/[id]/page.tsx
|
||||||
|
import { Modal } from '@/components/modal';
|
||||||
|
|
||||||
|
export default async function PhotoPage({ params }) {
|
||||||
|
const { id } = await params;
|
||||||
|
const photo = await getPhoto(id);
|
||||||
|
|
||||||
|
// Option: Render as modal on direct access too
|
||||||
|
return (
|
||||||
|
<Modal>
|
||||||
|
<img src={photo.url} alt={photo.title} />
|
||||||
|
</Modal>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Gotchas
|
||||||
|
|
||||||
|
### 1. Missing `default.tsx` → 404 on Refresh
|
||||||
|
|
||||||
|
Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
|
||||||
|
|
||||||
|
### 2. Modal Persists After Navigation
|
||||||
|
|
||||||
|
You're using `router.push()` instead of `router.back()`.
|
||||||
|
|
||||||
|
### 3. Nested Parallel Routes Need Defaults Too
|
||||||
|
|
||||||
|
If you have `@modal` inside a route group, each level needs its own `default.tsx`:
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── (marketing)/
|
||||||
|
│ ├── @modal/
|
||||||
|
│ │ └── default.tsx # Needed!
|
||||||
|
│ └── layout.tsx
|
||||||
|
└── layout.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Intercepted Route Shows Wrong Content
|
||||||
|
|
||||||
|
Check your matcher:
|
||||||
|
|
||||||
|
- `(.)photos` intercepts `/photos` from the same route level
|
||||||
|
- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
|
||||||
|
|
||||||
|
### 5. TypeScript Errors with `params`
|
||||||
|
|
||||||
|
In Next.js 15+, `params` is a Promise:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Correct
|
||||||
|
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Complete Example: Photo Gallery Modal
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── @modal/
|
||||||
|
│ ├── default.tsx
|
||||||
|
│ └── (.)photos/
|
||||||
|
│ └── [id]/
|
||||||
|
│ └── page.tsx
|
||||||
|
├── photos/
|
||||||
|
│ ├── page.tsx # Gallery grid
|
||||||
|
│ └── [id]/
|
||||||
|
│ └── page.tsx # Full photo page
|
||||||
|
├── layout.tsx
|
||||||
|
└── page.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Links in the gallery:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/photos/page.tsx
|
||||||
|
import Link from 'next/link';
|
||||||
|
|
||||||
|
export default async function Gallery() {
|
||||||
|
const photos = await getPhotos();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div className='grid grid-cols-3 gap-4'>
|
||||||
|
{photos.map((photo) => (
|
||||||
|
<Link key={photo.id} href={`/photos/${photo.id}`}>
|
||||||
|
<img src={photo.thumbnail} alt={photo.title} />
|
||||||
|
</Link>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Clicking a photo → Modal opens (intercepted)
|
||||||
|
Direct URL → Full page renders
|
||||||
|
Refresh while modal open → Full page renders
|
||||||
143
.agents/skills/next-best-practices/route-handlers.md
Normal file
143
.agents/skills/next-best-practices/route-handlers.md
Normal file
@@ -0,0 +1,143 @@
|
|||||||
|
# Route Handlers
|
||||||
|
|
||||||
|
Create API endpoints with `route.ts` files.
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/api/users/route.ts
|
||||||
|
export async function GET() {
|
||||||
|
const users = await getUsers();
|
||||||
|
return Response.json(users);
|
||||||
|
}
|
||||||
|
|
||||||
|
export async function POST(request: Request) {
|
||||||
|
const body = await request.json();
|
||||||
|
const user = await createUser(body);
|
||||||
|
return Response.json(user, { status: 201 });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Supported Methods
|
||||||
|
|
||||||
|
`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
|
||||||
|
|
||||||
|
## GET Handler Conflicts with page.tsx
|
||||||
|
|
||||||
|
**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── api/
|
||||||
|
│ └── users/
|
||||||
|
│ └── route.ts # /api/users
|
||||||
|
└── users/
|
||||||
|
├── page.tsx # /users (page)
|
||||||
|
└── route.ts # Warning: Conflicts with page.tsx!
|
||||||
|
```
|
||||||
|
|
||||||
|
If you need both a page and an API at the same path, use different paths:
|
||||||
|
|
||||||
|
```
|
||||||
|
app/
|
||||||
|
├── users/
|
||||||
|
│ └── page.tsx # /users (page)
|
||||||
|
└── api/
|
||||||
|
└── users/
|
||||||
|
└── route.ts # /api/users (API)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment Behavior
|
||||||
|
|
||||||
|
Route handlers run in a **Server Component-like environment**:
|
||||||
|
|
||||||
|
- Yes: Can use `async/await`
|
||||||
|
- Yes: Can access `cookies()`, `headers()`
|
||||||
|
- Yes: Can use Node.js APIs
|
||||||
|
- No: Cannot use React hooks
|
||||||
|
- No: Cannot use React DOM APIs
|
||||||
|
- No: Cannot use browser APIs
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: This won't work - no React DOM in route handlers
|
||||||
|
import { renderToString } from 'react-dom/server';
|
||||||
|
|
||||||
|
export async function GET() {
|
||||||
|
const html = renderToString(<Component />); // Error!
|
||||||
|
return new Response(html);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Dynamic Route Handlers
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/api/users/[id]/route.ts
|
||||||
|
export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
|
||||||
|
const { id } = await params;
|
||||||
|
const user = await getUser(id);
|
||||||
|
|
||||||
|
if (!user) {
|
||||||
|
return Response.json({ error: 'Not found' }, { status: 404 });
|
||||||
|
}
|
||||||
|
|
||||||
|
return Response.json(user);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Request Helpers
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export async function GET(request: Request) {
|
||||||
|
// URL and search params
|
||||||
|
const { searchParams } = new URL(request.url);
|
||||||
|
const query = searchParams.get('q');
|
||||||
|
|
||||||
|
// Headers
|
||||||
|
const authHeader = request.headers.get('authorization');
|
||||||
|
|
||||||
|
// Cookies (Next.js helper)
|
||||||
|
const cookieStore = await cookies();
|
||||||
|
const token = cookieStore.get('token');
|
||||||
|
|
||||||
|
return Response.json({ query, token });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Response Helpers
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// JSON response
|
||||||
|
return Response.json({ data });
|
||||||
|
|
||||||
|
// With status
|
||||||
|
return Response.json({ error: 'Not found' }, { status: 404 });
|
||||||
|
|
||||||
|
// With headers
|
||||||
|
return Response.json(data, {
|
||||||
|
headers: {
|
||||||
|
'Cache-Control': 'max-age=3600'
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Redirect
|
||||||
|
return Response.redirect(new URL('/login', request.url));
|
||||||
|
|
||||||
|
// Stream
|
||||||
|
return new Response(stream, {
|
||||||
|
headers: { 'Content-Type': 'text/event-stream' }
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use Route Handlers vs Server Actions
|
||||||
|
|
||||||
|
| Use Case | Route Handlers | Server Actions |
|
||||||
|
| ------------------------ | -------------- | -------------- |
|
||||||
|
| Form submissions | No | Yes |
|
||||||
|
| Data mutations from UI | No | Yes |
|
||||||
|
| Third-party webhooks | Yes | No |
|
||||||
|
| External API consumption | Yes | No |
|
||||||
|
| Public REST API | Yes | No |
|
||||||
|
| File uploads | Both work | Both work |
|
||||||
|
|
||||||
|
**Prefer Server Actions** for mutations triggered from your UI.
|
||||||
|
**Use Route Handlers** for external integrations and public APIs.
|
||||||
160
.agents/skills/next-best-practices/rsc-boundaries.md
Normal file
160
.agents/skills/next-best-practices/rsc-boundaries.md
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
# RSC Boundaries
|
||||||
|
|
||||||
|
Detect and prevent invalid patterns when crossing Server/Client component boundaries.
|
||||||
|
|
||||||
|
## Detection Rules
|
||||||
|
|
||||||
|
### 1. Async Client Components Are Invalid
|
||||||
|
|
||||||
|
Client components **cannot** be async functions. Only Server Components can be async.
|
||||||
|
|
||||||
|
**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: async client component
|
||||||
|
'use client';
|
||||||
|
export default async function UserProfile() {
|
||||||
|
const user = await getUser(); // Cannot await in client component
|
||||||
|
return <div>{user.name}</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Remove async, fetch data in parent server component
|
||||||
|
// page.tsx (server component - no 'use client')
|
||||||
|
export default async function Page() {
|
||||||
|
const user = await getUser();
|
||||||
|
return <UserProfile user={user} />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// UserProfile.tsx (client component)
|
||||||
|
('use client');
|
||||||
|
export function UserProfile({ user }: { user: User }) {
|
||||||
|
return <div>{user.name}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: async arrow function client component
|
||||||
|
'use client';
|
||||||
|
const Dashboard = async () => {
|
||||||
|
const data = await fetchDashboard();
|
||||||
|
return <div>{data}</div>;
|
||||||
|
};
|
||||||
|
|
||||||
|
// Good: Fetch in server component, pass data down
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Non-Serializable Props to Client Components
|
||||||
|
|
||||||
|
Props passed from Server → Client must be JSON-serializable.
|
||||||
|
|
||||||
|
**Detect:** Server component passes these to a client component:
|
||||||
|
|
||||||
|
- Functions (except Server Actions with `'use server'`)
|
||||||
|
- `Date` objects
|
||||||
|
- `Map`, `Set`, `WeakMap`, `WeakSet`
|
||||||
|
- Class instances
|
||||||
|
- `Symbol` (unless globally registered)
|
||||||
|
- Circular references
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Function prop
|
||||||
|
// page.tsx (server)
|
||||||
|
export default function Page() {
|
||||||
|
const handleClick = () => console.log('clicked');
|
||||||
|
return <ClientButton onClick={handleClick} />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Define function inside client component
|
||||||
|
// ClientButton.tsx
|
||||||
|
('use client');
|
||||||
|
export function ClientButton() {
|
||||||
|
const handleClick = () => console.log('clicked');
|
||||||
|
return <button onClick={handleClick}>Click</button>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Date object (silently becomes string, then crashes)
|
||||||
|
// page.tsx (server)
|
||||||
|
export default async function Page() {
|
||||||
|
const post = await getPost();
|
||||||
|
return <PostCard createdAt={post.createdAt} />; // Date object
|
||||||
|
}
|
||||||
|
|
||||||
|
// PostCard.tsx (client) - will crash on .getFullYear()
|
||||||
|
('use client');
|
||||||
|
export function PostCard({ createdAt }: { createdAt: Date }) {
|
||||||
|
return <span>{createdAt.getFullYear()}</span>; // Runtime error!
|
||||||
|
}
|
||||||
|
|
||||||
|
// Good: Serialize to string on server
|
||||||
|
// page.tsx (server)
|
||||||
|
export default async function Page() {
|
||||||
|
const post = await getPost();
|
||||||
|
return <PostCard createdAt={post.createdAt.toISOString()} />;
|
||||||
|
}
|
||||||
|
|
||||||
|
// PostCard.tsx (client)
|
||||||
|
('use client');
|
||||||
|
export function PostCard({ createdAt }: { createdAt: string }) {
|
||||||
|
const date = new Date(createdAt);
|
||||||
|
return <span>{date.getFullYear()}</span>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Class instance
|
||||||
|
const user = new UserModel(data)
|
||||||
|
<ClientProfile user={user} /> // Methods will be stripped
|
||||||
|
|
||||||
|
// Good: Pass plain object
|
||||||
|
const user = await getUser()
|
||||||
|
<ClientProfile user={{ id: user.id, name: user.name }} />
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Map/Set
|
||||||
|
<ClientComponent items={new Map([['a', 1]])} />
|
||||||
|
|
||||||
|
// Good: Convert to array/object
|
||||||
|
<ClientComponent items={Object.fromEntries(map)} />
|
||||||
|
<ClientComponent items={Array.from(set)} />
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Server Actions Are the Exception
|
||||||
|
|
||||||
|
Functions marked with `'use server'` CAN be passed to client components.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Valid: Server Action can be passed
|
||||||
|
// actions.ts
|
||||||
|
'use server';
|
||||||
|
export async function submitForm(formData: FormData) {
|
||||||
|
// server-side logic
|
||||||
|
}
|
||||||
|
|
||||||
|
// page.tsx (server)
|
||||||
|
import { submitForm } from './actions';
|
||||||
|
export default function Page() {
|
||||||
|
return <ClientForm onSubmit={submitForm} />; // OK!
|
||||||
|
}
|
||||||
|
|
||||||
|
// ClientForm.tsx (client)
|
||||||
|
('use client');
|
||||||
|
export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
|
||||||
|
return <form action={onSubmit}>...</form>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Pattern | Valid? | Fix |
|
||||||
|
| --------------------------------- | ------ | ------------------------------------- |
|
||||||
|
| `'use client'` + `async function` | No | Fetch in server parent, pass data |
|
||||||
|
| Pass `() => {}` to client | No | Define in client or use server action |
|
||||||
|
| Pass `new Date()` to client | No | Use `.toISOString()` |
|
||||||
|
| Pass `new Map()` to client | No | Convert to object/array |
|
||||||
|
| Pass class instance to client | No | Pass plain object |
|
||||||
|
| Pass server action to client | Yes | - |
|
||||||
|
| Pass `string/number/boolean` | Yes | - |
|
||||||
|
| Pass plain object/array | Yes | - |
|
||||||
40
.agents/skills/next-best-practices/runtime-selection.md
Normal file
40
.agents/skills/next-best-practices/runtime-selection.md
Normal file
@@ -0,0 +1,40 @@
|
|||||||
|
# Runtime Selection
|
||||||
|
|
||||||
|
## Use Node.js Runtime by Default
|
||||||
|
|
||||||
|
Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Default - no runtime config needed (uses Node.js)
|
||||||
|
export default function Page() { ... }
|
||||||
|
|
||||||
|
// Caution: Only if already used in project or specifically required
|
||||||
|
export const runtime = 'edge'
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use Each
|
||||||
|
|
||||||
|
### Node.js Runtime (Default)
|
||||||
|
|
||||||
|
- Full Node.js API support
|
||||||
|
- File system access (`fs`)
|
||||||
|
- Full `crypto` support
|
||||||
|
- Database connections
|
||||||
|
- Most npm packages work
|
||||||
|
|
||||||
|
### Edge Runtime
|
||||||
|
|
||||||
|
- Only for specific edge-location latency requirements
|
||||||
|
- Limited API (no `fs`, limited `crypto`)
|
||||||
|
- Smaller cold start
|
||||||
|
- Geographic distribution needs
|
||||||
|
|
||||||
|
## Detection
|
||||||
|
|
||||||
|
**Before adding `runtime = 'edge'`**, check:
|
||||||
|
|
||||||
|
1. Does the project already use Edge runtime?
|
||||||
|
2. Is there a specific latency requirement?
|
||||||
|
3. Are all dependencies Edge-compatible?
|
||||||
|
|
||||||
|
If unsure, use Node.js runtime.
|
||||||
137
.agents/skills/next-best-practices/scripts.md
Normal file
137
.agents/skills/next-best-practices/scripts.md
Normal file
@@ -0,0 +1,137 @@
|
|||||||
|
# Scripts
|
||||||
|
|
||||||
|
Loading third-party scripts in Next.js.
|
||||||
|
|
||||||
|
## Use next/script
|
||||||
|
|
||||||
|
Always use `next/script` instead of native `<script>` tags for better performance.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Native script tag
|
||||||
|
<script src='https://example.com/script.js'></script>;
|
||||||
|
|
||||||
|
// Good: Next.js Script component
|
||||||
|
import Script from 'next/script';
|
||||||
|
|
||||||
|
<Script src='https://example.com/script.js' />;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Inline Scripts Need ID
|
||||||
|
|
||||||
|
Inline scripts require an `id` attribute for Next.js to track them.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Missing id
|
||||||
|
<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
|
||||||
|
|
||||||
|
// Good: Has id
|
||||||
|
<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
|
||||||
|
|
||||||
|
// Good: Inline with id
|
||||||
|
<Script id="show-banner">
|
||||||
|
{`document.getElementById('banner').classList.remove('hidden')`}
|
||||||
|
</Script>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Don't Put Script in Head
|
||||||
|
|
||||||
|
`next/script` should not be placed inside `next/head`. It handles its own positioning.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Script inside Head
|
||||||
|
import Head from 'next/head'
|
||||||
|
import Script from 'next/script'
|
||||||
|
|
||||||
|
<Head>
|
||||||
|
<Script src="/analytics.js" />
|
||||||
|
</Head>
|
||||||
|
|
||||||
|
// Good: Script outside Head
|
||||||
|
<Head>
|
||||||
|
<title>Page</title>
|
||||||
|
</Head>
|
||||||
|
<Script src="/analytics.js" />
|
||||||
|
```
|
||||||
|
|
||||||
|
## Loading Strategies
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// afterInteractive (default) - Load after page is interactive
|
||||||
|
<Script src="/analytics.js" strategy="afterInteractive" />
|
||||||
|
|
||||||
|
// lazyOnload - Load during idle time
|
||||||
|
<Script src="/widget.js" strategy="lazyOnload" />
|
||||||
|
|
||||||
|
// beforeInteractive - Load before page is interactive (use sparingly)
|
||||||
|
// Only works in app/layout.tsx or pages/_document.js
|
||||||
|
<Script src="/critical.js" strategy="beforeInteractive" />
|
||||||
|
|
||||||
|
// worker - Load in web worker (experimental)
|
||||||
|
<Script src="/heavy.js" strategy="worker" />
|
||||||
|
```
|
||||||
|
|
||||||
|
## Google Analytics
|
||||||
|
|
||||||
|
Use `@next/third-parties` instead of inline GA scripts.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Inline GA script
|
||||||
|
<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
|
||||||
|
<Script id="ga-init">
|
||||||
|
{`window.dataLayer = window.dataLayer || [];
|
||||||
|
function gtag(){dataLayer.push(arguments);}
|
||||||
|
gtag('js', new Date());
|
||||||
|
gtag('config', 'G-XXXXX');`}
|
||||||
|
</Script>
|
||||||
|
|
||||||
|
// Good: Next.js component
|
||||||
|
import { GoogleAnalytics } from '@next/third-parties/google'
|
||||||
|
|
||||||
|
export default function Layout({ children }) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<body>{children}</body>
|
||||||
|
<GoogleAnalytics gaId="G-XXXXX" />
|
||||||
|
</html>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Google Tag Manager
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { GoogleTagManager } from '@next/third-parties/google';
|
||||||
|
|
||||||
|
export default function Layout({ children }) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<GoogleTagManager gtmId='GTM-XXXXX' />
|
||||||
|
<body>{children}</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Other Third-Party Scripts
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// YouTube embed
|
||||||
|
import { YouTubeEmbed } from '@next/third-parties/google';
|
||||||
|
|
||||||
|
<YouTubeEmbed videoid='dQw4w9WgXcQ' />;
|
||||||
|
|
||||||
|
// Google Maps
|
||||||
|
import { GoogleMapsEmbed } from '@next/third-parties/google';
|
||||||
|
|
||||||
|
<GoogleMapsEmbed apiKey='YOUR_API_KEY' mode='place' q='Brooklyn+Bridge,New+York,NY' />;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Pattern | Issue | Fix |
|
||||||
|
| --------------------------------------------- | -------------------------- | ------------------------- |
|
||||||
|
| `<script src="...">` | No optimization | Use `next/script` |
|
||||||
|
| `<Script>` without id | Can't track inline scripts | Add `id` attribute |
|
||||||
|
| `<Script>` inside `<Head>` | Wrong placement | Move outside Head |
|
||||||
|
| Inline GA/GTM scripts | No optimization | Use `@next/third-parties` |
|
||||||
|
| `strategy="beforeInteractive"` outside layout | Won't work | Only use in root layout |
|
||||||
375
.agents/skills/next-best-practices/self-hosting.md
Normal file
375
.agents/skills/next-best-practices/self-hosting.md
Normal file
@@ -0,0 +1,375 @@
|
|||||||
|
# Self-Hosting Next.js
|
||||||
|
|
||||||
|
Deploy Next.js outside of Vercel with confidence.
|
||||||
|
|
||||||
|
## Quick Start: Standalone Output
|
||||||
|
|
||||||
|
For Docker or any containerized deployment, use standalone output:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
output: 'standalone'
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates a minimal `standalone` folder with only production dependencies:
|
||||||
|
|
||||||
|
```
|
||||||
|
.next/
|
||||||
|
├── standalone/
|
||||||
|
│ ├── server.js # Entry point
|
||||||
|
│ ├── node_modules/ # Only production deps
|
||||||
|
│ └── .next/ # Build output
|
||||||
|
└── static/ # Must be copied separately
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker Deployment
|
||||||
|
|
||||||
|
### Dockerfile
|
||||||
|
|
||||||
|
```dockerfile
|
||||||
|
FROM node:20-alpine AS base
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
FROM base AS deps
|
||||||
|
WORKDIR /app
|
||||||
|
COPY package.json package-lock.json* ./
|
||||||
|
RUN npm ci
|
||||||
|
|
||||||
|
# Build
|
||||||
|
FROM base AS builder
|
||||||
|
WORKDIR /app
|
||||||
|
COPY --from=deps /app/node_modules ./node_modules
|
||||||
|
COPY . .
|
||||||
|
RUN npm run build
|
||||||
|
|
||||||
|
# Production
|
||||||
|
FROM base AS runner
|
||||||
|
WORKDIR /app
|
||||||
|
|
||||||
|
ENV NODE_ENV=production
|
||||||
|
|
||||||
|
# Create non-root user
|
||||||
|
RUN addgroup --system --gid 1001 nodejs
|
||||||
|
RUN adduser --system --uid 1001 nextjs
|
||||||
|
|
||||||
|
# Copy standalone output
|
||||||
|
COPY --from=builder /app/.next/standalone ./
|
||||||
|
COPY --from=builder /app/.next/static ./.next/static
|
||||||
|
COPY --from=builder /app/public ./public
|
||||||
|
|
||||||
|
USER nextjs
|
||||||
|
|
||||||
|
EXPOSE 3000
|
||||||
|
ENV PORT=3000
|
||||||
|
ENV HOSTNAME="0.0.0.0"
|
||||||
|
|
||||||
|
CMD ["node", "server.js"]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Docker Compose
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: '3.8'
|
||||||
|
|
||||||
|
services:
|
||||||
|
web:
|
||||||
|
build: .
|
||||||
|
ports:
|
||||||
|
- '3000:3000'
|
||||||
|
environment:
|
||||||
|
- NODE_ENV=production
|
||||||
|
restart: unless-stopped
|
||||||
|
healthcheck:
|
||||||
|
test: ['CMD', 'wget', '-q', '--spider', 'http://localhost:3000/api/health']
|
||||||
|
interval: 30s
|
||||||
|
timeout: 10s
|
||||||
|
retries: 3
|
||||||
|
```
|
||||||
|
|
||||||
|
## PM2 Deployment
|
||||||
|
|
||||||
|
For traditional server deployments:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// ecosystem.config.js
|
||||||
|
module.exports = {
|
||||||
|
apps: [
|
||||||
|
{
|
||||||
|
name: 'nextjs',
|
||||||
|
script: '.next/standalone/server.js',
|
||||||
|
instances: 'max',
|
||||||
|
exec_mode: 'cluster',
|
||||||
|
env: {
|
||||||
|
NODE_ENV: 'production',
|
||||||
|
PORT: 3000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
pm2 start ecosystem.config.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## ISR and Cache Handlers
|
||||||
|
|
||||||
|
### The Problem
|
||||||
|
|
||||||
|
ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
|
||||||
|
|
||||||
|
- Instance A regenerates page → saves to its local disk
|
||||||
|
- Instance B serves stale page → doesn't see Instance A's cache
|
||||||
|
- Load balancer sends users to random instances → inconsistent content
|
||||||
|
|
||||||
|
### Solution: Custom Cache Handler
|
||||||
|
|
||||||
|
Next.js 14+ supports custom cache handlers for shared storage:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
cacheHandler: require.resolve('./cache-handler.js'),
|
||||||
|
cacheMaxMemorySize: 0 // Disable in-memory cache
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Redis Cache Handler Example
|
||||||
|
|
||||||
|
```js
|
||||||
|
// cache-handler.js
|
||||||
|
const Redis = require('ioredis');
|
||||||
|
|
||||||
|
const redis = new Redis(process.env.REDIS_URL);
|
||||||
|
const CACHE_PREFIX = 'nextjs:';
|
||||||
|
|
||||||
|
module.exports = class CacheHandler {
|
||||||
|
constructor(options) {
|
||||||
|
this.options = options;
|
||||||
|
}
|
||||||
|
|
||||||
|
async get(key) {
|
||||||
|
const data = await redis.get(CACHE_PREFIX + key);
|
||||||
|
if (!data) return null;
|
||||||
|
|
||||||
|
const parsed = JSON.parse(data);
|
||||||
|
return {
|
||||||
|
value: parsed.value,
|
||||||
|
lastModified: parsed.lastModified
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
async set(key, data, ctx) {
|
||||||
|
const cacheData = {
|
||||||
|
value: data,
|
||||||
|
lastModified: Date.now()
|
||||||
|
};
|
||||||
|
|
||||||
|
// Set TTL based on revalidate option
|
||||||
|
if (ctx?.revalidate) {
|
||||||
|
await redis.setex(CACHE_PREFIX + key, ctx.revalidate, JSON.stringify(cacheData));
|
||||||
|
} else {
|
||||||
|
await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async revalidateTag(tags) {
|
||||||
|
// Implement tag-based invalidation
|
||||||
|
// This requires tracking which keys have which tags
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
#### S3 Cache Handler Example
|
||||||
|
|
||||||
|
```js
|
||||||
|
// cache-handler.js
|
||||||
|
const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3');
|
||||||
|
|
||||||
|
const s3 = new S3Client({ region: process.env.AWS_REGION });
|
||||||
|
const BUCKET = process.env.CACHE_BUCKET;
|
||||||
|
|
||||||
|
module.exports = class CacheHandler {
|
||||||
|
async get(key) {
|
||||||
|
try {
|
||||||
|
const response = await s3.send(
|
||||||
|
new GetObjectCommand({
|
||||||
|
Bucket: BUCKET,
|
||||||
|
Key: `cache/${key}`
|
||||||
|
})
|
||||||
|
);
|
||||||
|
const body = await response.Body.transformToString();
|
||||||
|
return JSON.parse(body);
|
||||||
|
} catch (err) {
|
||||||
|
if (err.name === 'NoSuchKey') return null;
|
||||||
|
throw err;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async set(key, data, ctx) {
|
||||||
|
await s3.send(
|
||||||
|
new PutObjectCommand({
|
||||||
|
Bucket: BUCKET,
|
||||||
|
Key: `cache/${key}`,
|
||||||
|
Body: JSON.stringify({
|
||||||
|
value: data,
|
||||||
|
lastModified: Date.now()
|
||||||
|
}),
|
||||||
|
ContentType: 'application/json'
|
||||||
|
})
|
||||||
|
);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## What Works vs What Needs Setup
|
||||||
|
|
||||||
|
| Feature | Single Instance | Multi-Instance | Notes |
|
||||||
|
| -------------------- | --------------- | ------------------- | --------------------------- |
|
||||||
|
| SSR | Yes | Yes | No special setup |
|
||||||
|
| SSG | Yes | Yes | Built at deploy time |
|
||||||
|
| ISR | Yes | Needs cache handler | Filesystem cache breaks |
|
||||||
|
| Image Optimization | Yes | Yes | CPU-intensive, consider CDN |
|
||||||
|
| Middleware | Yes | Yes | Runs on Node.js |
|
||||||
|
| Edge Runtime | Limited | Limited | Some features Node-only |
|
||||||
|
| `revalidatePath/Tag` | Yes | Needs cache handler | Must share cache |
|
||||||
|
| `next/font` | Yes | Yes | Fonts bundled at build |
|
||||||
|
| Draft Mode | Yes | Yes | Cookie-based |
|
||||||
|
|
||||||
|
## Image Optimization
|
||||||
|
|
||||||
|
Next.js Image Optimization works out of the box but is CPU-intensive.
|
||||||
|
|
||||||
|
### Option 1: Built-in (Simple)
|
||||||
|
|
||||||
|
Works automatically, but consider:
|
||||||
|
|
||||||
|
- Set `deviceSizes` and `imageSizes` in config to limit variants
|
||||||
|
- Use `minimumCacheTTL` to reduce regeneration
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
images: {
|
||||||
|
minimumCacheTTL: 60 * 60 * 24, // 24 hours
|
||||||
|
deviceSizes: [640, 750, 1080, 1920] // Limit sizes
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option 2: External Loader (Recommended for Scale)
|
||||||
|
|
||||||
|
Offload to Cloudinary, Imgix, or similar:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js
|
||||||
|
module.exports = {
|
||||||
|
images: {
|
||||||
|
loader: 'custom',
|
||||||
|
loaderFile: './lib/image-loader.js'
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
```js
|
||||||
|
// lib/image-loader.js
|
||||||
|
export default function cloudinaryLoader({ src, width, quality }) {
|
||||||
|
const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
|
||||||
|
return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
### Build-time vs Runtime
|
||||||
|
|
||||||
|
```js
|
||||||
|
// Available at build time only (baked into bundle)
|
||||||
|
NEXT_PUBLIC_API_URL=https://api.example.com
|
||||||
|
|
||||||
|
// Available at runtime (server-side only)
|
||||||
|
DATABASE_URL=postgresql://...
|
||||||
|
API_SECRET=...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Runtime Configuration
|
||||||
|
|
||||||
|
For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/api/config/route.ts
|
||||||
|
export async function GET() {
|
||||||
|
return Response.json({
|
||||||
|
apiUrl: process.env.API_URL,
|
||||||
|
features: process.env.FEATURES?.split(',')
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## OpenNext: Serverless Without Vercel
|
||||||
|
|
||||||
|
[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx create-sst@latest
|
||||||
|
# or
|
||||||
|
npx @opennextjs/aws build
|
||||||
|
```
|
||||||
|
|
||||||
|
Supports:
|
||||||
|
|
||||||
|
- AWS Lambda + CloudFront
|
||||||
|
- Cloudflare Workers
|
||||||
|
- Netlify Functions
|
||||||
|
- Deno Deploy
|
||||||
|
|
||||||
|
## Health Check Endpoint
|
||||||
|
|
||||||
|
Always include a health check for load balancers:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// app/api/health/route.ts
|
||||||
|
export async function GET() {
|
||||||
|
try {
|
||||||
|
// Optional: check database connection
|
||||||
|
// await db.$queryRaw`SELECT 1`;
|
||||||
|
|
||||||
|
return Response.json({ status: 'healthy' }, { status: 200 });
|
||||||
|
} catch (error) {
|
||||||
|
return Response.json({ status: 'unhealthy' }, { status: 503 });
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pre-Deployment Checklist
|
||||||
|
|
||||||
|
1. **Build locally first**: `npm run build` - catch errors before deploy
|
||||||
|
2. **Test standalone output**: `node .next/standalone/server.js`
|
||||||
|
3. **Set `output: 'standalone'`** for Docker
|
||||||
|
4. **Configure cache handler** for multi-instance ISR
|
||||||
|
5. **Set `HOSTNAME="0.0.0.0"`** for containers
|
||||||
|
6. **Copy `public/` and `.next/static/`** - not included in standalone
|
||||||
|
7. **Add health check endpoint**
|
||||||
|
8. **Test ISR revalidation** after deployment
|
||||||
|
9. **Monitor memory usage** - Node.js defaults may need tuning
|
||||||
|
|
||||||
|
## Testing Cache Handler
|
||||||
|
|
||||||
|
**Critical**: Test your cache handler on every Next.js upgrade:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start multiple instances
|
||||||
|
PORT=3001 node .next/standalone/server.js &
|
||||||
|
PORT=3002 node .next/standalone/server.js &
|
||||||
|
|
||||||
|
# Trigger ISR revalidation
|
||||||
|
curl http://localhost:3001/api/revalidate?path=/posts
|
||||||
|
|
||||||
|
# Verify both instances see the update
|
||||||
|
curl http://localhost:3001/posts
|
||||||
|
curl http://localhost:3002/posts
|
||||||
|
# Should return identical content
|
||||||
|
```
|
||||||
67
.agents/skills/next-best-practices/suspense-boundaries.md
Normal file
67
.agents/skills/next-best-practices/suspense-boundaries.md
Normal file
@@ -0,0 +1,67 @@
|
|||||||
|
# Suspense Boundaries
|
||||||
|
|
||||||
|
Client hooks that cause CSR bailout without Suspense boundaries.
|
||||||
|
|
||||||
|
## useSearchParams
|
||||||
|
|
||||||
|
Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad: Entire page becomes CSR
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import { useSearchParams } from 'next/navigation';
|
||||||
|
|
||||||
|
export default function SearchBar() {
|
||||||
|
const searchParams = useSearchParams();
|
||||||
|
return <div>Query: {searchParams.get('q')}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Wrap in Suspense
|
||||||
|
import { Suspense } from 'react';
|
||||||
|
import SearchBar from './search-bar';
|
||||||
|
|
||||||
|
export default function Page() {
|
||||||
|
return (
|
||||||
|
<Suspense fallback={<div>Loading...</div>}>
|
||||||
|
<SearchBar />
|
||||||
|
</Suspense>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## usePathname
|
||||||
|
|
||||||
|
Requires Suspense boundary when route has dynamic parameters.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// In dynamic route [slug]
|
||||||
|
// Bad: No Suspense
|
||||||
|
'use client';
|
||||||
|
import { usePathname } from 'next/navigation';
|
||||||
|
|
||||||
|
export function Breadcrumb() {
|
||||||
|
const pathname = usePathname();
|
||||||
|
return <nav>{pathname}</nav>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good: Wrap in Suspense
|
||||||
|
<Suspense fallback={<BreadcrumbSkeleton />}>
|
||||||
|
<Breadcrumb />
|
||||||
|
</Suspense>
|
||||||
|
```
|
||||||
|
|
||||||
|
If you use `generateStaticParams`, Suspense is optional.
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Hook | Suspense Required |
|
||||||
|
| ------------------- | -------------------- |
|
||||||
|
| `useSearchParams()` | Yes |
|
||||||
|
| `usePathname()` | Yes (dynamic routes) |
|
||||||
|
| `useParams()` | No |
|
||||||
|
| `useRouter()` | No |
|
||||||
242
.agents/skills/shadcn/SKILL.md
Normal file
242
.agents/skills/shadcn/SKILL.md
Normal file
@@ -0,0 +1,242 @@
|
|||||||
|
---
|
||||||
|
name: shadcn
|
||||||
|
description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
|
||||||
|
user-invocable: false
|
||||||
|
allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
|
||||||
|
---
|
||||||
|
|
||||||
|
# shadcn/ui
|
||||||
|
|
||||||
|
A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
|
||||||
|
|
||||||
|
> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
|
||||||
|
|
||||||
|
## Current Project Context
|
||||||
|
|
||||||
|
```json
|
||||||
|
!`npx shadcn@latest info --json`
|
||||||
|
```
|
||||||
|
|
||||||
|
The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
|
||||||
|
|
||||||
|
## Principles
|
||||||
|
|
||||||
|
1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
|
||||||
|
2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
|
||||||
|
3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
|
||||||
|
4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
|
||||||
|
|
||||||
|
## Critical Rules
|
||||||
|
|
||||||
|
These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
|
||||||
|
|
||||||
|
### Styling & Tailwind → [styling.md](./rules/styling.md)
|
||||||
|
|
||||||
|
- **`className` for layout, not styling.** Never override component colors or typography.
|
||||||
|
- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
|
||||||
|
- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
|
||||||
|
- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
|
||||||
|
- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
|
||||||
|
- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
|
||||||
|
- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
|
||||||
|
|
||||||
|
### Forms & Inputs → [forms.md](./rules/forms.md)
|
||||||
|
|
||||||
|
- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
|
||||||
|
- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
|
||||||
|
- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
|
||||||
|
- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
|
||||||
|
- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
|
||||||
|
- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
|
||||||
|
|
||||||
|
### Component Structure → [composition.md](./rules/composition.md)
|
||||||
|
|
||||||
|
- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
|
||||||
|
- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
|
||||||
|
- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
|
||||||
|
- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
|
||||||
|
- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
|
||||||
|
- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
|
||||||
|
- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
|
||||||
|
|
||||||
|
### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
|
||||||
|
|
||||||
|
- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
|
||||||
|
- **Callouts use `Alert`.** Don't build custom styled divs.
|
||||||
|
- **Empty states use `Empty`.** Don't build custom empty state markup.
|
||||||
|
- **Toast via `sonner`.** Use `toast()` from `sonner`.
|
||||||
|
- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
|
||||||
|
- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
|
||||||
|
- **Use `Badge`** instead of custom styled spans.
|
||||||
|
|
||||||
|
### Icons → [icons.md](./rules/icons.md)
|
||||||
|
|
||||||
|
- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
|
||||||
|
- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
|
||||||
|
- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.
|
||||||
|
|
||||||
|
### CLI
|
||||||
|
|
||||||
|
- **Never decode or fetch preset codes manually.** Pass them directly to `npx shadcn@latest init --preset <code>`.
|
||||||
|
|
||||||
|
## Key Patterns
|
||||||
|
|
||||||
|
These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Form layout: FieldGroup + Field, not div + Label.
|
||||||
|
<FieldGroup>
|
||||||
|
<Field>
|
||||||
|
<FieldLabel htmlFor="email">Email</FieldLabel>
|
||||||
|
<Input id="email" />
|
||||||
|
</Field>
|
||||||
|
</FieldGroup>
|
||||||
|
|
||||||
|
// Validation: data-invalid on Field, aria-invalid on the control.
|
||||||
|
<Field data-invalid>
|
||||||
|
<FieldLabel>Email</FieldLabel>
|
||||||
|
<Input aria-invalid />
|
||||||
|
<FieldDescription>Invalid email.</FieldDescription>
|
||||||
|
</Field>
|
||||||
|
|
||||||
|
// Icons in buttons: data-icon, no sizing classes.
|
||||||
|
<Button>
|
||||||
|
<SearchIcon data-icon="inline-start" />
|
||||||
|
Search
|
||||||
|
</Button>
|
||||||
|
|
||||||
|
// Spacing: gap-*, not space-y-*.
|
||||||
|
<div className="flex flex-col gap-4"> // correct
|
||||||
|
<div className="space-y-4"> // wrong
|
||||||
|
|
||||||
|
// Equal dimensions: size-*, not w-* h-*.
|
||||||
|
<Avatar className="size-10"> // correct
|
||||||
|
<Avatar className="w-10 h-10"> // wrong
|
||||||
|
|
||||||
|
// Status colors: Badge variants or semantic tokens, not raw colors.
|
||||||
|
<Badge variant="secondary">+20.1%</Badge> // correct
|
||||||
|
<span className="text-emerald-600">+20.1%</span> // wrong
|
||||||
|
```
|
||||||
|
|
||||||
|
## Component Selection
|
||||||
|
|
||||||
|
| Need | Use |
|
||||||
|
| -------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||||
|
| Button/action | `Button` with appropriate variant |
|
||||||
|
| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
|
||||||
|
| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` |
|
||||||
|
| Data display | `Table`, `Card`, `Badge`, `Avatar` |
|
||||||
|
| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` |
|
||||||
|
| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) |
|
||||||
|
| Feedback | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner` |
|
||||||
|
| Command palette | `Command` inside `Dialog` |
|
||||||
|
| Charts | `Chart` (wraps Recharts) |
|
||||||
|
| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` |
|
||||||
|
| Empty states | `Empty` |
|
||||||
|
| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` |
|
||||||
|
| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |
|
||||||
|
|
||||||
|
## Key Fields
|
||||||
|
|
||||||
|
The injected project context contains these key fields:
|
||||||
|
|
||||||
|
- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
|
||||||
|
- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.
|
||||||
|
- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
|
||||||
|
- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
|
||||||
|
- **`style`** → component visual treatment (e.g. `nova`, `vega`).
|
||||||
|
- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
|
||||||
|
- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
|
||||||
|
- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
|
||||||
|
- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
|
||||||
|
- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
|
||||||
|
|
||||||
|
See [cli.md — `info` command](./cli.md) for the full field reference.
|
||||||
|
|
||||||
|
## Component Docs, Examples, and Usage
|
||||||
|
|
||||||
|
Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest docs button dialog select
|
||||||
|
```
|
||||||
|
|
||||||
|
**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
|
||||||
|
2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
|
||||||
|
3. **Find components** — `npx shadcn@latest search`.
|
||||||
|
4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
|
||||||
|
5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
|
||||||
|
6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
|
||||||
|
7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
|
||||||
|
8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
|
||||||
|
9. **Switching presets** — Ask the user first: **reinstall**, **merge**, or **skip**?
|
||||||
|
- **Reinstall**: `npx shadcn@latest init --preset <code> --force --reinstall`. Overwrites all components.
|
||||||
|
- **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
|
||||||
|
- **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
|
||||||
|
- **Important**: Always run preset commands inside the user's project directory. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
|
||||||
|
|
||||||
|
## Updating Components
|
||||||
|
|
||||||
|
When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
|
||||||
|
|
||||||
|
1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
|
||||||
|
2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
|
||||||
|
3. Decide per file based on the diff:
|
||||||
|
- No local changes → safe to overwrite.
|
||||||
|
- Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
|
||||||
|
- User says "just update everything" → use `--overwrite`, but confirm first.
|
||||||
|
4. **Never use `--overwrite` without the user's explicit approval.**
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create a new project.
|
||||||
|
npx shadcn@latest init --name my-app --preset base-nova
|
||||||
|
npx shadcn@latest init --name my-app --preset a2r6bw --template vite
|
||||||
|
|
||||||
|
# Create a monorepo project.
|
||||||
|
npx shadcn@latest init --name my-app --preset base-nova --monorepo
|
||||||
|
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
|
||||||
|
|
||||||
|
# Initialize existing project.
|
||||||
|
npx shadcn@latest init --preset base-nova
|
||||||
|
npx shadcn@latest init --defaults # shortcut: --template=next --preset=base-nova
|
||||||
|
|
||||||
|
# Add components.
|
||||||
|
npx shadcn@latest add button card dialog
|
||||||
|
npx shadcn@latest add @magicui/shimmer-button
|
||||||
|
npx shadcn@latest add --all
|
||||||
|
|
||||||
|
# Preview changes before adding/updating.
|
||||||
|
npx shadcn@latest add button --dry-run
|
||||||
|
npx shadcn@latest add button --diff button.tsx
|
||||||
|
npx shadcn@latest add @acme/form --view button.tsx
|
||||||
|
|
||||||
|
# Search registries.
|
||||||
|
npx shadcn@latest search @shadcn -q "sidebar"
|
||||||
|
npx shadcn@latest search @tailark -q "stats"
|
||||||
|
|
||||||
|
# Get component docs and example URLs.
|
||||||
|
npx shadcn@latest docs button dialog select
|
||||||
|
|
||||||
|
# View registry item details (for items not yet installed).
|
||||||
|
npx shadcn@latest view @shadcn/button
|
||||||
|
```
|
||||||
|
|
||||||
|
**Named presets:** `base-nova`, `radix-nova`
|
||||||
|
**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
|
||||||
|
**Preset codes:** Base62 strings starting with `a` (e.g. `a2r6bw`), from [ui.shadcn.com](https://ui.shadcn.com).
|
||||||
|
|
||||||
|
## Detailed References
|
||||||
|
|
||||||
|
- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
|
||||||
|
- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
|
||||||
|
- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
|
||||||
|
- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
|
||||||
|
- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
|
||||||
|
- [cli.md](./cli.md) — Commands, flags, presets, templates
|
||||||
|
- [customization.md](./customization.md) — Theming, CSS variables, extending components
|
||||||
5
.agents/skills/shadcn/agents/openai.yml
Normal file
5
.agents/skills/shadcn/agents/openai.yml
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
interface:
|
||||||
|
display_name: 'shadcn/ui'
|
||||||
|
short_description: 'Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI.'
|
||||||
|
icon_small: './assets/shadcn-small.png'
|
||||||
|
icon_large: './assets/shadcn.png'
|
||||||
BIN
.agents/skills/shadcn/assets/shadcn-small.png
Normal file
BIN
.agents/skills/shadcn/assets/shadcn-small.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.0 KiB |
BIN
.agents/skills/shadcn/assets/shadcn.png
Normal file
BIN
.agents/skills/shadcn/assets/shadcn.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.8 KiB |
257
.agents/skills/shadcn/cli.md
Normal file
257
.agents/skills/shadcn/cli.md
Normal file
@@ -0,0 +1,257 @@
|
|||||||
|
# shadcn CLI Reference
|
||||||
|
|
||||||
|
Configuration is read from `components.json`.
|
||||||
|
|
||||||
|
> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
|
||||||
|
|
||||||
|
> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Commands: init, add (dry-run, smart merge), search, view, docs, info, build
|
||||||
|
- Templates: next, vite, start, react-router, astro
|
||||||
|
- Presets: named, code, URL formats and fields
|
||||||
|
- Switching presets
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
### `init` — Initialize or create a project
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest init [components...] [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step.
|
||||||
|
|
||||||
|
| Flag | Short | Description | Default |
|
||||||
|
| ----------------------- | ----- | --------------------------------------------------------- | ------- |
|
||||||
|
| `--template <template>` | `-t` | Template (next, start, vite, next-monorepo, react-router) | — |
|
||||||
|
| `--preset [name]` | `-p` | Preset configuration (named, code, or URL) | — |
|
||||||
|
| `--yes` | `-y` | Skip confirmation prompt | `true` |
|
||||||
|
| `--defaults` | `-d` | Use defaults (`--template=next --preset=base-nova`) | `false` |
|
||||||
|
| `--force` | `-f` | Force overwrite existing configuration | `false` |
|
||||||
|
| `--cwd <cwd>` | `-c` | Working directory | current |
|
||||||
|
| `--name <name>` | `-n` | Name for new project | — |
|
||||||
|
| `--silent` | `-s` | Mute output | `false` |
|
||||||
|
| `--rtl` | | Enable RTL support | — |
|
||||||
|
| `--reinstall` | | Re-install existing UI components | `false` |
|
||||||
|
| `--monorepo` | | Scaffold a monorepo project | — |
|
||||||
|
| `--no-monorepo` | | Skip the monorepo prompt | — |
|
||||||
|
|
||||||
|
`npx shadcn@latest create` is an alias for `npx shadcn@latest init`.
|
||||||
|
|
||||||
|
### `add` — Add components
|
||||||
|
|
||||||
|
> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `npx shadcn@latest add <component> --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest add [components...] [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Accepts component names, registry-prefixed names (`@magicui/shimmer-button`), URLs, or local paths.
|
||||||
|
|
||||||
|
| Flag | Short | Description | Default |
|
||||||
|
| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||||
|
| `--yes` | `-y` | Skip confirmation prompt | `false` |
|
||||||
|
| `--overwrite` | `-o` | Overwrite existing files | `false` |
|
||||||
|
| `--cwd <cwd>` | `-c` | Working directory | current |
|
||||||
|
| `--all` | `-a` | Add all available components | `false` |
|
||||||
|
| `--path <path>` | `-p` | Target path for the component | — |
|
||||||
|
| `--silent` | `-s` | Mute output | `false` |
|
||||||
|
| `--dry-run` | | Preview all changes without writing files | `false` |
|
||||||
|
| `--diff [path]` | | Show diffs. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |
|
||||||
|
| `--view [path]` | | Show file contents. Without a path, shows the first 5 files. With a path, shows that file only (implies `--dry-run`) | — |
|
||||||
|
|
||||||
|
#### Dry-Run Mode
|
||||||
|
|
||||||
|
Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Preview all changes.
|
||||||
|
npx shadcn@latest add button --dry-run
|
||||||
|
|
||||||
|
# Show diffs for all files (top 5).
|
||||||
|
npx shadcn@latest add button --diff
|
||||||
|
|
||||||
|
# Show the diff for a specific file.
|
||||||
|
npx shadcn@latest add button --diff button.tsx
|
||||||
|
|
||||||
|
# Show contents for all files (top 5).
|
||||||
|
npx shadcn@latest add button --view
|
||||||
|
|
||||||
|
# Show the full content of a specific file.
|
||||||
|
npx shadcn@latest add button --view button.tsx
|
||||||
|
|
||||||
|
# Works with URLs too.
|
||||||
|
npx shadcn@latest add https://api.npoint.io/abc123 --dry-run
|
||||||
|
|
||||||
|
# CSS diffs.
|
||||||
|
npx shadcn@latest add button --diff globals.css
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use dry-run:**
|
||||||
|
|
||||||
|
- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`.
|
||||||
|
- Before overwriting existing components — use `--diff` to preview the changes first.
|
||||||
|
- When the user wants to inspect component source code without installing — use `--view`.
|
||||||
|
- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`.
|
||||||
|
- When the user asks to review or audit third-party registry code before installing — use `--view` to inspect the source.
|
||||||
|
|
||||||
|
> **`npx shadcn@latest add --dry-run` vs `npx shadcn@latest view`:** Prefer `npx shadcn@latest add --dry-run/--diff/--view` over `npx shadcn@latest view` when the user wants to preview changes to their project. `npx shadcn@latest view` only shows raw registry metadata. `npx shadcn@latest add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `npx shadcn@latest view` only when the user wants to browse registry info without a project context.
|
||||||
|
|
||||||
|
#### Smart Merge from Upstream
|
||||||
|
|
||||||
|
See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
|
||||||
|
|
||||||
|
### `search` — Search registries
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest search <registries...> [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Fuzzy search across registries. Also aliased as `npx shadcn@latest list`. Without `-q`, lists all items.
|
||||||
|
|
||||||
|
| Flag | Short | Description | Default |
|
||||||
|
| ------------------- | ----- | ---------------------- | ------- |
|
||||||
|
| `--query <query>` | `-q` | Search query | — |
|
||||||
|
| `--limit <number>` | `-l` | Max items per registry | `100` |
|
||||||
|
| `--offset <number>` | `-o` | Items to skip | `0` |
|
||||||
|
| `--cwd <cwd>` | `-c` | Working directory | current |
|
||||||
|
|
||||||
|
### `view` — View item details
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest view <items...> [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Displays item info including file contents. Example: `npx shadcn@latest view @shadcn/button`.
|
||||||
|
|
||||||
|
### `docs` — Get component documentation URLs
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest docs <components...> [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Outputs resolved URLs for component documentation, examples, and API references. Accepts one or more component names. Fetch the URLs to get the actual content.
|
||||||
|
|
||||||
|
Example output for `npx shadcn@latest docs input button`:
|
||||||
|
|
||||||
|
```
|
||||||
|
base radix
|
||||||
|
|
||||||
|
input
|
||||||
|
docs https://ui.shadcn.com/docs/components/radix/input
|
||||||
|
examples https://raw.githubusercontent.com/.../examples/input-example.tsx
|
||||||
|
|
||||||
|
button
|
||||||
|
docs https://ui.shadcn.com/docs/components/radix/button
|
||||||
|
examples https://raw.githubusercontent.com/.../examples/button-example.tsx
|
||||||
|
```
|
||||||
|
|
||||||
|
Some components include an `api` link to the underlying library (e.g. `cmdk` for the command component).
|
||||||
|
|
||||||
|
### `diff` — Check for updates
|
||||||
|
|
||||||
|
Do not use this command. Use `npx shadcn@latest add --diff` instead.
|
||||||
|
|
||||||
|
### `info` — Project information
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest info [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Displays project info and `components.json` configuration. Run this first to discover the project's framework, aliases, Tailwind version, and resolved paths.
|
||||||
|
|
||||||
|
| Flag | Short | Description | Default |
|
||||||
|
| ------------- | ----- | ----------------- | ------- |
|
||||||
|
| `--cwd <cwd>` | `-c` | Working directory | current |
|
||||||
|
|
||||||
|
**Project Info fields:**
|
||||||
|
|
||||||
|
| Field | Type | Meaning |
|
||||||
|
| -------------------- | --------- | ------------------------------------------------------------------ |
|
||||||
|
| `framework` | `string` | Detected framework (`next`, `vite`, `react-router`, `start`, etc.) |
|
||||||
|
| `frameworkVersion` | `string` | Framework version (e.g. `15.2.4`) |
|
||||||
|
| `isSrcDir` | `boolean` | Whether the project uses a `src/` directory |
|
||||||
|
| `isRSC` | `boolean` | Whether React Server Components are enabled |
|
||||||
|
| `isTsx` | `boolean` | Whether the project uses TypeScript |
|
||||||
|
| `tailwindVersion` | `string` | `"v3"` or `"v4"` |
|
||||||
|
| `tailwindConfigFile` | `string` | Path to the Tailwind config file |
|
||||||
|
| `tailwindCssFile` | `string` | Path to the global CSS file |
|
||||||
|
| `aliasPrefix` | `string` | Import alias prefix (e.g. `@`, `~`, `@/`) |
|
||||||
|
| `packageManager` | `string` | Detected package manager (`npm`, `pnpm`, `yarn`, `bun`) |
|
||||||
|
|
||||||
|
**Components.json fields:**
|
||||||
|
|
||||||
|
| Field | Type | Meaning |
|
||||||
|
| -------------------- | --------- | ------------------------------------------------------------------------------------------ |
|
||||||
|
| `base` | `string` | Primitive library (`radix` or `base`) — determines component APIs and available props |
|
||||||
|
| `style` | `string` | Visual style (e.g. `nova`, `vega`) |
|
||||||
|
| `rsc` | `boolean` | RSC flag from config |
|
||||||
|
| `tsx` | `boolean` | TypeScript flag |
|
||||||
|
| `tailwind.config` | `string` | Tailwind config path |
|
||||||
|
| `tailwind.css` | `string` | Global CSS path — this is where custom CSS variables go |
|
||||||
|
| `iconLibrary` | `string` | Icon library — determines icon import package (e.g. `lucide-react`, `@tabler/icons-react`) |
|
||||||
|
| `aliases.components` | `string` | Component import alias (e.g. `@/components`) |
|
||||||
|
| `aliases.utils` | `string` | Utils import alias (e.g. `@/lib/utils`) |
|
||||||
|
| `aliases.ui` | `string` | UI component alias (e.g. `@/components/ui`) |
|
||||||
|
| `aliases.lib` | `string` | Lib alias (e.g. `@/lib`) |
|
||||||
|
| `aliases.hooks` | `string` | Hooks alias (e.g. `@/hooks`) |
|
||||||
|
| `resolvedPaths` | `object` | Absolute file-system paths for each alias |
|
||||||
|
| `registries` | `object` | Configured custom registries |
|
||||||
|
|
||||||
|
**Links fields:**
|
||||||
|
|
||||||
|
The `info` output includes a **Links** section with templated URLs for component docs, source, and examples. For resolved URLs, use `npx shadcn@latest docs <component>` instead.
|
||||||
|
|
||||||
|
### `build` — Build a custom registry
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest build [registry] [options]
|
||||||
|
```
|
||||||
|
|
||||||
|
Builds `registry.json` into individual JSON files for distribution. Default input: `./registry.json`, default output: `./public/r`.
|
||||||
|
|
||||||
|
| Flag | Short | Description | Default |
|
||||||
|
| ----------------- | ----- | ----------------- | ------------ |
|
||||||
|
| `--output <path>` | `-o` | Output directory | `./public/r` |
|
||||||
|
| `--cwd <cwd>` | `-c` | Working directory | current |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Templates
|
||||||
|
|
||||||
|
| Value | Framework | Monorepo support |
|
||||||
|
| -------------- | -------------- | ---------------- |
|
||||||
|
| `next` | Next.js | Yes |
|
||||||
|
| `vite` | Vite | Yes |
|
||||||
|
| `start` | TanStack Start | Yes |
|
||||||
|
| `react-router` | React Router | Yes |
|
||||||
|
| `astro` | Astro | Yes |
|
||||||
|
| `laravel` | Laravel | No |
|
||||||
|
|
||||||
|
All templates support monorepo scaffolding via the `--monorepo` flag. When passed, the CLI uses a monorepo-specific template directory (e.g. `next-monorepo`, `vite-monorepo`). When neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts interactively. Laravel does not support monorepo scaffolding.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Presets
|
||||||
|
|
||||||
|
Three ways to specify a preset via `--preset`:
|
||||||
|
|
||||||
|
1. **Named:** `--preset base-nova` or `--preset radix-nova`
|
||||||
|
2. **Code:** `--preset a2r6bw` (base62 string, starts with lowercase `a`)
|
||||||
|
3. **URL:** `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
|
||||||
|
|
||||||
|
> **IMPORTANT:** Never try to decode, fetch, or resolve preset codes manually. Preset codes are opaque — pass them directly to `npx shadcn@latest init --preset <code>` and let the CLI handle resolution.
|
||||||
|
|
||||||
|
## Switching Presets
|
||||||
|
|
||||||
|
Ask the user first: **reinstall**, **merge**, or **skip** existing components?
|
||||||
|
|
||||||
|
- **Re-install** → `npx shadcn@latest init --preset <code> --force --reinstall`. Overwrites all component files with the new preset styles. Use when the user hasn't customized components.
|
||||||
|
- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to get the list of installed components and use the [smart merge workflow](./SKILL.md#updating-components) to update them one by one, preserving local changes. Use when the user has customized components.
|
||||||
|
- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS variables, leaves existing components as-is.
|
||||||
|
|
||||||
|
Always run preset commands inside the user's project directory. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
|
||||||
203
.agents/skills/shadcn/customization.md
Normal file
203
.agents/skills/shadcn/customization.md
Normal file
@@ -0,0 +1,203 @@
|
|||||||
|
# Customization & Theming
|
||||||
|
|
||||||
|
Components reference semantic CSS variable tokens. Change the variables to change every component.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- How it works (CSS variables → Tailwind utilities → components)
|
||||||
|
- Color variables and OKLCH format
|
||||||
|
- Dark mode setup
|
||||||
|
- Changing the theme (presets, CSS variables)
|
||||||
|
- Adding custom colors (Tailwind v3 and v4)
|
||||||
|
- Border radius
|
||||||
|
- Customizing components (variants, className, wrappers)
|
||||||
|
- Checking for updates
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
|
||||||
|
2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
|
||||||
|
3. Components use these utilities — changing a variable changes all components that reference it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Color Variables
|
||||||
|
|
||||||
|
Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
|
||||||
|
|
||||||
|
| Variable | Purpose |
|
||||||
|
| -------------------------------------------- | -------------------------------- |
|
||||||
|
| `--background` / `--foreground` | Page background and default text |
|
||||||
|
| `--card` / `--card-foreground` | Card surfaces |
|
||||||
|
| `--primary` / `--primary-foreground` | Primary buttons and actions |
|
||||||
|
| `--secondary` / `--secondary-foreground` | Secondary actions |
|
||||||
|
| `--muted` / `--muted-foreground` | Muted/disabled states |
|
||||||
|
| `--accent` / `--accent-foreground` | Hover and accent states |
|
||||||
|
| `--destructive` / `--destructive-foreground` | Error and destructive actions |
|
||||||
|
| `--border` | Default border color |
|
||||||
|
| `--input` | Form input borders |
|
||||||
|
| `--ring` | Focus ring color |
|
||||||
|
| `--chart-1` through `--chart-5` | Chart/data visualization |
|
||||||
|
| `--sidebar-*` | Sidebar-specific colors |
|
||||||
|
| `--surface` / `--surface-foreground` | Secondary surface |
|
||||||
|
|
||||||
|
Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dark Mode
|
||||||
|
|
||||||
|
Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { ThemeProvider } from 'next-themes';
|
||||||
|
|
||||||
|
<ThemeProvider attribute='class' defaultTheme='system' enableSystem>
|
||||||
|
{children}
|
||||||
|
</ThemeProvider>;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Changing the Theme
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Apply a preset code from ui.shadcn.com.
|
||||||
|
npx shadcn@latest init --preset a2r6bw --force
|
||||||
|
|
||||||
|
# Switch to a named preset.
|
||||||
|
npx shadcn@latest init --preset radix-nova --force
|
||||||
|
npx shadcn@latest init --reinstall # update existing components to match
|
||||||
|
|
||||||
|
# Use a custom theme URL.
|
||||||
|
npx shadcn@latest init --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..." --force
|
||||||
|
```
|
||||||
|
|
||||||
|
Or edit CSS variables directly in `globals.css`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Adding Custom Colors
|
||||||
|
|
||||||
|
Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* 1. Define in the global CSS file. */
|
||||||
|
:root {
|
||||||
|
--warning: oklch(0.84 0.16 84);
|
||||||
|
--warning-foreground: oklch(0.28 0.07 46);
|
||||||
|
}
|
||||||
|
.dark {
|
||||||
|
--warning: oklch(0.41 0.11 46);
|
||||||
|
--warning-foreground: oklch(0.99 0.02 95);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* 2a. Register with Tailwind v4 (@theme inline). */
|
||||||
|
@theme inline {
|
||||||
|
--color-warning: var(--warning);
|
||||||
|
--color-warning-foreground: var(--warning-foreground);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
|
||||||
|
|
||||||
|
```js
|
||||||
|
// 2b. Register with Tailwind v3 (tailwind.config.js).
|
||||||
|
module.exports = {
|
||||||
|
theme: {
|
||||||
|
extend: {
|
||||||
|
colors: {
|
||||||
|
warning: 'oklch(var(--warning) / <alpha-value>)',
|
||||||
|
'warning-foreground': 'oklch(var(--warning-foreground) / <alpha-value>)'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// 3. Use in components.
|
||||||
|
<div className='bg-warning text-warning-foreground'>Warning</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Border Radius
|
||||||
|
|
||||||
|
`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Customizing Components
|
||||||
|
|
||||||
|
See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
|
||||||
|
|
||||||
|
Prefer these approaches in order:
|
||||||
|
|
||||||
|
### 1. Built-in variants
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button variant='outline' size='sm'>
|
||||||
|
Click
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Tailwind classes via `className`
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Card className='max-w-md mx-auto'>...</Card>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Add a new variant
|
||||||
|
|
||||||
|
Edit the component source to add a variant via `cva`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// components/ui/button.tsx
|
||||||
|
warning: "bg-warning text-warning-foreground hover:bg-warning/90",
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Wrapper components
|
||||||
|
|
||||||
|
Compose shadcn/ui primitives into higher-level components:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
export function ConfirmDialog({ title, description, onConfirm, children }) {
|
||||||
|
return (
|
||||||
|
<AlertDialog>
|
||||||
|
<AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
|
||||||
|
<AlertDialogContent>
|
||||||
|
<AlertDialogHeader>
|
||||||
|
<AlertDialogTitle>{title}</AlertDialogTitle>
|
||||||
|
<AlertDialogDescription>{description}</AlertDialogDescription>
|
||||||
|
</AlertDialogHeader>
|
||||||
|
<AlertDialogFooter>
|
||||||
|
<AlertDialogCancel>Cancel</AlertDialogCancel>
|
||||||
|
<AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
|
||||||
|
</AlertDialogFooter>
|
||||||
|
</AlertDialogContent>
|
||||||
|
</AlertDialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Checking for Updates
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest add button --diff
|
||||||
|
```
|
||||||
|
|
||||||
|
To preview exactly what would change before updating, use `--dry-run` and `--diff`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx shadcn@latest add button --dry-run # see all affected files
|
||||||
|
npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
|
||||||
|
```
|
||||||
|
|
||||||
|
See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.
|
||||||
47
.agents/skills/shadcn/evals/evals.json
Normal file
47
.agents/skills/shadcn/evals/evals.json
Normal file
@@ -0,0 +1,47 @@
|
|||||||
|
{
|
||||||
|
"skill_name": "shadcn",
|
||||||
|
"evals": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
|
||||||
|
"expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
|
||||||
|
"files": [],
|
||||||
|
"expectations": [
|
||||||
|
"Uses FieldGroup and Field components for form layout instead of raw div with space-y",
|
||||||
|
"Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
|
||||||
|
"Uses data-invalid on Field and aria-invalid on the input control for validation states",
|
||||||
|
"Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
|
||||||
|
"Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
|
||||||
|
"No manual dark: color overrides"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
|
||||||
|
"expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
|
||||||
|
"files": [],
|
||||||
|
"expectations": [
|
||||||
|
"Includes DialogTitle for accessibility (visible or with sr-only class)",
|
||||||
|
"Avatar component includes AvatarFallback",
|
||||||
|
"Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
|
||||||
|
"No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
|
||||||
|
"Uses tabler icons (@tabler/icons-react) instead of lucide-react",
|
||||||
|
"Uses asChild for custom triggers (radix preset)"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 3,
|
||||||
|
"prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
|
||||||
|
"expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
|
||||||
|
"files": [],
|
||||||
|
"expectations": [
|
||||||
|
"Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
|
||||||
|
"Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
|
||||||
|
"Uses Badge component for percentage change instead of custom styled spans",
|
||||||
|
"Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
|
||||||
|
"Uses gap-* instead of space-y-* or space-x-* for spacing",
|
||||||
|
"Uses size-* when width and height are equal instead of separate w-* h-*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
94
.agents/skills/shadcn/mcp.md
Normal file
94
.agents/skills/shadcn/mcp.md
Normal file
@@ -0,0 +1,94 @@
|
|||||||
|
# shadcn MCP Server
|
||||||
|
|
||||||
|
The CLI includes an MCP server that lets AI assistants search, browse, view, and install components from registries.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
shadcn mcp # start the MCP server (stdio)
|
||||||
|
shadcn mcp init # write config for your editor
|
||||||
|
```
|
||||||
|
|
||||||
|
Editor config files:
|
||||||
|
|
||||||
|
| Editor | Config file |
|
||||||
|
| ----------- | ------------------------------- |
|
||||||
|
| Claude Code | `.mcp.json` |
|
||||||
|
| Cursor | `.cursor/mcp.json` |
|
||||||
|
| VS Code | `.vscode/mcp.json` |
|
||||||
|
| OpenCode | `opencode.json` |
|
||||||
|
| Codex | `~/.codex/config.toml` (manual) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
|
||||||
|
|
||||||
|
### `shadcn:get_project_registries`
|
||||||
|
|
||||||
|
Returns registry names from `components.json`. Errors if no `components.json` exists.
|
||||||
|
|
||||||
|
**Input:** none
|
||||||
|
|
||||||
|
### `shadcn:list_items_in_registries`
|
||||||
|
|
||||||
|
Lists all items from one or more registries.
|
||||||
|
|
||||||
|
**Input:** `registries` (string[]), `limit` (number, optional), `offset` (number, optional)
|
||||||
|
|
||||||
|
### `shadcn:search_items_in_registries`
|
||||||
|
|
||||||
|
Fuzzy search across registries.
|
||||||
|
|
||||||
|
**Input:** `registries` (string[]), `query` (string), `limit` (number, optional), `offset` (number, optional)
|
||||||
|
|
||||||
|
### `shadcn:view_items_in_registries`
|
||||||
|
|
||||||
|
View item details including full file contents.
|
||||||
|
|
||||||
|
**Input:** `items` (string[]) — e.g. `["@shadcn/button", "@shadcn/card"]`
|
||||||
|
|
||||||
|
### `shadcn:get_item_examples_from_registries`
|
||||||
|
|
||||||
|
Find usage examples and demos with source code.
|
||||||
|
|
||||||
|
**Input:** `registries` (string[]), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
|
||||||
|
|
||||||
|
### `shadcn:get_add_command_for_items`
|
||||||
|
|
||||||
|
Returns the CLI install command.
|
||||||
|
|
||||||
|
**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
|
||||||
|
|
||||||
|
### `shadcn:get_audit_checklist`
|
||||||
|
|
||||||
|
Returns a checklist for verifying components (imports, deps, lint, TypeScript).
|
||||||
|
|
||||||
|
**Input:** none
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuring Registries
|
||||||
|
|
||||||
|
Registries are set in `components.json`. The `@shadcn` registry is always built-in.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"registries": {
|
||||||
|
"@acme": "https://acme.com/r/{name}.json",
|
||||||
|
"@private": {
|
||||||
|
"url": "https://private.com/r/{name}.json",
|
||||||
|
"headers": { "Authorization": "Bearer ${MY_TOKEN}" }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Names must start with `@`.
|
||||||
|
- URLs must contain `{name}`.
|
||||||
|
- `${VAR}` references are resolved from environment variables.
|
||||||
|
|
||||||
|
Community registry index: `https://ui.shadcn.com/r/registries.json`
|
||||||
308
.agents/skills/shadcn/rules/base-vs-radix.md
Normal file
308
.agents/skills/shadcn/rules/base-vs-radix.md
Normal file
@@ -0,0 +1,308 @@
|
|||||||
|
# Base vs Radix
|
||||||
|
|
||||||
|
API differences between `base` and `radix`. Check the `base` field from `npx shadcn@latest info`.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Composition: asChild vs render
|
||||||
|
- Button / trigger as non-button element
|
||||||
|
- Select (items prop, placeholder, positioning, multiple, object values)
|
||||||
|
- ToggleGroup (type vs multiple)
|
||||||
|
- Slider (scalar vs array)
|
||||||
|
- Accordion (type and defaultValue)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Composition: asChild (radix) vs render (base)
|
||||||
|
|
||||||
|
Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<DialogTrigger>
|
||||||
|
<div>
|
||||||
|
<Button>Open</Button>
|
||||||
|
</div>
|
||||||
|
</DialogTrigger>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<DialogTrigger asChild>
|
||||||
|
<Button>Open</Button>
|
||||||
|
</DialogTrigger>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<DialogTrigger render={<Button />}>Open</DialogTrigger>
|
||||||
|
```
|
||||||
|
|
||||||
|
This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Button / trigger as non-button element (base only)
|
||||||
|
|
||||||
|
When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
|
||||||
|
|
||||||
|
**Incorrect (base):** missing `nativeButton={false}`.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button render={<a href='/docs' />}>Read the docs</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button render={<a href='/docs' />} nativeButton={false}>
|
||||||
|
Read the docs
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button asChild>
|
||||||
|
<a href='/docs'>Read the docs</a>
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
Same for triggers whose `render` is not a `Button`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// base.
|
||||||
|
<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
|
||||||
|
Pick date
|
||||||
|
</PopoverTrigger>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Select
|
||||||
|
|
||||||
|
**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
|
||||||
|
|
||||||
|
**Incorrect (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Select>
|
||||||
|
<SelectTrigger>
|
||||||
|
<SelectValue placeholder='Select a fruit' />
|
||||||
|
</SelectTrigger>
|
||||||
|
</Select>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const items = [
|
||||||
|
{ label: "Select a fruit", value: null },
|
||||||
|
{ label: "Apple", value: "apple" },
|
||||||
|
{ label: "Banana", value: "banana" },
|
||||||
|
]
|
||||||
|
|
||||||
|
<Select items={items}>
|
||||||
|
<SelectTrigger>
|
||||||
|
<SelectValue />
|
||||||
|
</SelectTrigger>
|
||||||
|
<SelectContent>
|
||||||
|
<SelectGroup>
|
||||||
|
{items.map((item) => (
|
||||||
|
<SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
|
||||||
|
))}
|
||||||
|
</SelectGroup>
|
||||||
|
</SelectContent>
|
||||||
|
</Select>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Select>
|
||||||
|
<SelectTrigger>
|
||||||
|
<SelectValue placeholder='Select a fruit' />
|
||||||
|
</SelectTrigger>
|
||||||
|
<SelectContent>
|
||||||
|
<SelectGroup>
|
||||||
|
<SelectItem value='apple'>Apple</SelectItem>
|
||||||
|
<SelectItem value='banana'>Banana</SelectItem>
|
||||||
|
</SelectGroup>
|
||||||
|
</SelectContent>
|
||||||
|
</Select>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
|
||||||
|
|
||||||
|
**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// base.
|
||||||
|
<SelectContent alignItemWithTrigger={false} side="bottom">
|
||||||
|
|
||||||
|
// radix.
|
||||||
|
<SelectContent position="popper">
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Select — multiple selection and object values (base only)
|
||||||
|
|
||||||
|
Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
|
||||||
|
|
||||||
|
**Correct (base — multiple selection):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Select items={items} multiple defaultValue={[]}>
|
||||||
|
<SelectTrigger>
|
||||||
|
<SelectValue>
|
||||||
|
{(value: string[]) => (value.length === 0 ? 'Select fruits' : `${value.length} selected`)}
|
||||||
|
</SelectValue>
|
||||||
|
</SelectTrigger>
|
||||||
|
...
|
||||||
|
</Select>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base — object values):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
|
||||||
|
<SelectTrigger>
|
||||||
|
<SelectValue>{(value) => value.name}</SelectValue>
|
||||||
|
</SelectTrigger>
|
||||||
|
...
|
||||||
|
</Select>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ToggleGroup
|
||||||
|
|
||||||
|
Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
|
||||||
|
|
||||||
|
**Incorrect (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<ToggleGroup type='single' defaultValue='daily'>
|
||||||
|
<ToggleGroupItem value='daily'>Daily</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Single (no prop needed), defaultValue is always an array.
|
||||||
|
<ToggleGroup defaultValue={["daily"]} spacing={2}>
|
||||||
|
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
|
||||||
|
// Multi-selection.
|
||||||
|
<ToggleGroup multiple>
|
||||||
|
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Single, defaultValue is a string.
|
||||||
|
<ToggleGroup type="single" defaultValue="daily" spacing={2}>
|
||||||
|
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
|
||||||
|
// Multi-selection.
|
||||||
|
<ToggleGroup type="multiple">
|
||||||
|
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Controlled single value:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// base — wrap/unwrap arrays.
|
||||||
|
const [value, setValue] = React.useState("normal")
|
||||||
|
<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
|
||||||
|
|
||||||
|
// radix — plain string.
|
||||||
|
const [value, setValue] = React.useState("normal")
|
||||||
|
<ToggleGroup type="single" value={value} onValueChange={setValue}>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Slider
|
||||||
|
|
||||||
|
Base accepts a plain number for a single thumb. Radix always requires an array.
|
||||||
|
|
||||||
|
**Incorrect (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Slider defaultValue={[50]} max={100} step={1} />
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Slider defaultValue={50} max={100} step={1} />
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Slider defaultValue={[50]} max={100} step={1} />
|
||||||
|
```
|
||||||
|
|
||||||
|
Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// base.
|
||||||
|
const [value, setValue] = React.useState([0.3, 0.7])
|
||||||
|
<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
|
||||||
|
|
||||||
|
// radix.
|
||||||
|
const [value, setValue] = React.useState([0.3, 0.7])
|
||||||
|
<Slider value={value} onValueChange={setValue} />
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Accordion
|
||||||
|
|
||||||
|
Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
|
||||||
|
|
||||||
|
**Incorrect (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Accordion type='single' collapsible defaultValue='item-1'>
|
||||||
|
<AccordionItem value='item-1'>...</AccordionItem>
|
||||||
|
</Accordion>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (base):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Accordion defaultValue={["item-1"]}>
|
||||||
|
<AccordionItem value="item-1">...</AccordionItem>
|
||||||
|
</Accordion>
|
||||||
|
|
||||||
|
// Multi-select.
|
||||||
|
<Accordion multiple defaultValue={["item-1", "item-2"]}>
|
||||||
|
<AccordionItem value="item-1">...</AccordionItem>
|
||||||
|
<AccordionItem value="item-2">...</AccordionItem>
|
||||||
|
</Accordion>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (radix):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Accordion type='single' collapsible defaultValue='item-1'>
|
||||||
|
<AccordionItem value='item-1'>...</AccordionItem>
|
||||||
|
</Accordion>
|
||||||
|
```
|
||||||
197
.agents/skills/shadcn/rules/composition.md
Normal file
197
.agents/skills/shadcn/rules/composition.md
Normal file
@@ -0,0 +1,197 @@
|
|||||||
|
# Component Composition
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Items always inside their Group component
|
||||||
|
- Callouts use Alert
|
||||||
|
- Empty states use Empty component
|
||||||
|
- Toast notifications use sonner
|
||||||
|
- Choosing between overlay components
|
||||||
|
- Dialog, Sheet, and Drawer always need a Title
|
||||||
|
- Card structure
|
||||||
|
- Button has no isPending or isLoading prop
|
||||||
|
- TabsTrigger must be inside TabsList
|
||||||
|
- Avatar always needs AvatarFallback
|
||||||
|
- Use Separator instead of raw hr or border divs
|
||||||
|
- Use Skeleton for loading placeholders
|
||||||
|
- Use Badge instead of custom styled spans
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Items always inside their Group component
|
||||||
|
|
||||||
|
Never render items directly inside the content container.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<SelectContent>
|
||||||
|
<SelectItem value='apple'>Apple</SelectItem>
|
||||||
|
<SelectItem value='banana'>Banana</SelectItem>
|
||||||
|
</SelectContent>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<SelectContent>
|
||||||
|
<SelectGroup>
|
||||||
|
<SelectItem value='apple'>Apple</SelectItem>
|
||||||
|
<SelectItem value='banana'>Banana</SelectItem>
|
||||||
|
</SelectGroup>
|
||||||
|
</SelectContent>
|
||||||
|
```
|
||||||
|
|
||||||
|
This applies to all group-based components:
|
||||||
|
|
||||||
|
| Item | Group |
|
||||||
|
| ---------------------------------------------------------- | ------------------- |
|
||||||
|
| `SelectItem`, `SelectLabel` | `SelectGroup` |
|
||||||
|
| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
|
||||||
|
| `MenubarItem` | `MenubarGroup` |
|
||||||
|
| `ContextMenuItem` | `ContextMenuGroup` |
|
||||||
|
| `CommandItem` | `CommandGroup` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Callouts use Alert
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Alert>
|
||||||
|
<AlertTitle>Warning</AlertTitle>
|
||||||
|
<AlertDescription>Something needs attention.</AlertDescription>
|
||||||
|
</Alert>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Empty states use Empty component
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Empty>
|
||||||
|
<EmptyHeader>
|
||||||
|
<EmptyMedia variant='icon'>
|
||||||
|
<FolderIcon />
|
||||||
|
</EmptyMedia>
|
||||||
|
<EmptyTitle>No projects yet</EmptyTitle>
|
||||||
|
<EmptyDescription>Get started by creating a new project.</EmptyDescription>
|
||||||
|
</EmptyHeader>
|
||||||
|
<EmptyContent>
|
||||||
|
<Button>Create Project</Button>
|
||||||
|
</EmptyContent>
|
||||||
|
</Empty>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Toast notifications use sonner
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { toast } from 'sonner';
|
||||||
|
|
||||||
|
toast.success('Changes saved.');
|
||||||
|
toast.error('Something went wrong.');
|
||||||
|
toast('File deleted.', {
|
||||||
|
action: { label: 'Undo', onClick: () => undoDelete() }
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Choosing between overlay components
|
||||||
|
|
||||||
|
| Use case | Component |
|
||||||
|
| ---------------------------------- | ------------- |
|
||||||
|
| Focused task that requires input | `Dialog` |
|
||||||
|
| Destructive action confirmation | `AlertDialog` |
|
||||||
|
| Side panel with details or filters | `Sheet` |
|
||||||
|
| Mobile-first bottom panel | `Drawer` |
|
||||||
|
| Quick info on hover | `HoverCard` |
|
||||||
|
| Small contextual content on click | `Popover` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dialog, Sheet, and Drawer always need a Title
|
||||||
|
|
||||||
|
`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<DialogContent>
|
||||||
|
<DialogHeader>
|
||||||
|
<DialogTitle>Edit Profile</DialogTitle>
|
||||||
|
<DialogDescription>Update your profile.</DialogDescription>
|
||||||
|
</DialogHeader>
|
||||||
|
...
|
||||||
|
</DialogContent>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Card structure
|
||||||
|
|
||||||
|
Use full composition — don't dump everything into `CardContent`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Card>
|
||||||
|
<CardHeader>
|
||||||
|
<CardTitle>Team Members</CardTitle>
|
||||||
|
<CardDescription>Manage your team.</CardDescription>
|
||||||
|
</CardHeader>
|
||||||
|
<CardContent>...</CardContent>
|
||||||
|
<CardFooter>
|
||||||
|
<Button>Invite</Button>
|
||||||
|
</CardFooter>
|
||||||
|
</Card>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Button has no isPending or isLoading prop
|
||||||
|
|
||||||
|
Compose with `Spinner` + `data-icon` + `disabled`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button disabled>
|
||||||
|
<Spinner data-icon='inline-start' />
|
||||||
|
Saving...
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## TabsTrigger must be inside TabsList
|
||||||
|
|
||||||
|
Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Tabs defaultValue='account'>
|
||||||
|
<TabsList>
|
||||||
|
<TabsTrigger value='account'>Account</TabsTrigger>
|
||||||
|
<TabsTrigger value='password'>Password</TabsTrigger>
|
||||||
|
</TabsList>
|
||||||
|
<TabsContent value='account'>...</TabsContent>
|
||||||
|
</Tabs>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Avatar always needs AvatarFallback
|
||||||
|
|
||||||
|
Always include `AvatarFallback` for when the image fails to load:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Avatar>
|
||||||
|
<AvatarImage src='/avatar.png' alt='User' />
|
||||||
|
<AvatarFallback>JD</AvatarFallback>
|
||||||
|
</Avatar>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Use existing components instead of custom markup
|
||||||
|
|
||||||
|
| Instead of | Use |
|
||||||
|
| -------------------------------------------------- | ------------------------------------ |
|
||||||
|
| `<hr>` or `<div className="border-t">` | `<Separator />` |
|
||||||
|
| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
|
||||||
|
| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |
|
||||||
194
.agents/skills/shadcn/rules/forms.md
Normal file
194
.agents/skills/shadcn/rules/forms.md
Normal file
@@ -0,0 +1,194 @@
|
|||||||
|
# Forms & Inputs
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Forms use FieldGroup + Field
|
||||||
|
- InputGroup requires InputGroupInput/InputGroupTextarea
|
||||||
|
- Buttons inside inputs use InputGroup + InputGroupAddon
|
||||||
|
- Option sets (2–7 choices) use ToggleGroup
|
||||||
|
- FieldSet + FieldLegend for grouping related fields
|
||||||
|
- Field validation and disabled states
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Forms use FieldGroup + Field
|
||||||
|
|
||||||
|
Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FieldGroup>
|
||||||
|
<Field>
|
||||||
|
<FieldLabel htmlFor='email'>Email</FieldLabel>
|
||||||
|
<Input id='email' type='email' />
|
||||||
|
</Field>
|
||||||
|
<Field>
|
||||||
|
<FieldLabel htmlFor='password'>Password</FieldLabel>
|
||||||
|
<Input id='password' type='password' />
|
||||||
|
</Field>
|
||||||
|
</FieldGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
|
||||||
|
|
||||||
|
**Choosing form controls:**
|
||||||
|
|
||||||
|
- Simple text input → `Input`
|
||||||
|
- Dropdown with predefined options → `Select`
|
||||||
|
- Searchable dropdown → `Combobox`
|
||||||
|
- Native HTML select (no JS) → `native-select`
|
||||||
|
- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
|
||||||
|
- Single choice from few options → `RadioGroup`
|
||||||
|
- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
|
||||||
|
- OTP/verification code → `InputOTP`
|
||||||
|
- Multi-line text → `Textarea`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## InputGroup requires InputGroupInput/InputGroupTextarea
|
||||||
|
|
||||||
|
Never use raw `Input` or `Textarea` inside an `InputGroup`.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<InputGroup>
|
||||||
|
<Input placeholder='Search...' />
|
||||||
|
</InputGroup>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { InputGroup, InputGroupInput } from '@/components/ui/input-group';
|
||||||
|
|
||||||
|
<InputGroup>
|
||||||
|
<InputGroupInput placeholder='Search...' />
|
||||||
|
</InputGroup>;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Buttons inside inputs use InputGroup + InputGroupAddon
|
||||||
|
|
||||||
|
Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className='relative'>
|
||||||
|
<Input placeholder='Search...' className='pr-10' />
|
||||||
|
<Button className='absolute right-0 top-0' size='icon'>
|
||||||
|
<SearchIcon />
|
||||||
|
</Button>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { InputGroup, InputGroupInput, InputGroupAddon } from '@/components/ui/input-group';
|
||||||
|
|
||||||
|
<InputGroup>
|
||||||
|
<InputGroupInput placeholder='Search...' />
|
||||||
|
<InputGroupAddon>
|
||||||
|
<Button size='icon'>
|
||||||
|
<SearchIcon data-icon='inline-start' />
|
||||||
|
</Button>
|
||||||
|
</InputGroupAddon>
|
||||||
|
</InputGroup>;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Option sets (2–7 choices) use ToggleGroup
|
||||||
|
|
||||||
|
Don't manually loop `Button` components with active state.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const [selected, setSelected] = useState("daily")
|
||||||
|
|
||||||
|
<div className="flex gap-2">
|
||||||
|
{["daily", "weekly", "monthly"].map((option) => (
|
||||||
|
<Button
|
||||||
|
key={option}
|
||||||
|
variant={selected === option ? "default" : "outline"}
|
||||||
|
onClick={() => setSelected(option)}
|
||||||
|
>
|
||||||
|
{option}
|
||||||
|
</Button>
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
|
||||||
|
|
||||||
|
<ToggleGroup spacing={2}>
|
||||||
|
<ToggleGroupItem value='daily'>Daily</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value='weekly'>Weekly</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value='monthly'>Monthly</ToggleGroupItem>
|
||||||
|
</ToggleGroup>;
|
||||||
|
```
|
||||||
|
|
||||||
|
Combine with `Field` for labelled toggle groups:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Field orientation='horizontal'>
|
||||||
|
<FieldTitle id='theme-label'>Theme</FieldTitle>
|
||||||
|
<ToggleGroup aria-labelledby='theme-label' spacing={2}>
|
||||||
|
<ToggleGroupItem value='light'>Light</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value='dark'>Dark</ToggleGroupItem>
|
||||||
|
<ToggleGroupItem value='system'>System</ToggleGroupItem>
|
||||||
|
</ToggleGroup>
|
||||||
|
</Field>
|
||||||
|
```
|
||||||
|
|
||||||
|
> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## FieldSet + FieldLegend for grouping related fields
|
||||||
|
|
||||||
|
Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<FieldSet>
|
||||||
|
<FieldLegend variant='label'>Preferences</FieldLegend>
|
||||||
|
<FieldDescription>Select all that apply.</FieldDescription>
|
||||||
|
<FieldGroup className='gap-3'>
|
||||||
|
<Field orientation='horizontal'>
|
||||||
|
<Checkbox id='dark' />
|
||||||
|
<FieldLabel htmlFor='dark' className='font-normal'>
|
||||||
|
Dark mode
|
||||||
|
</FieldLabel>
|
||||||
|
</Field>
|
||||||
|
</FieldGroup>
|
||||||
|
</FieldSet>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Field validation and disabled states
|
||||||
|
|
||||||
|
Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Invalid.
|
||||||
|
<Field data-invalid>
|
||||||
|
<FieldLabel htmlFor="email">Email</FieldLabel>
|
||||||
|
<Input id="email" aria-invalid />
|
||||||
|
<FieldDescription>Invalid email address.</FieldDescription>
|
||||||
|
</Field>
|
||||||
|
|
||||||
|
// Disabled.
|
||||||
|
<Field data-disabled>
|
||||||
|
<FieldLabel htmlFor="email">Email</FieldLabel>
|
||||||
|
<Input id="email" disabled />
|
||||||
|
</Field>
|
||||||
|
```
|
||||||
|
|
||||||
|
Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.
|
||||||
101
.agents/skills/shadcn/rules/icons.md
Normal file
101
.agents/skills/shadcn/rules/icons.md
Normal file
@@ -0,0 +1,101 @@
|
|||||||
|
# Icons
|
||||||
|
|
||||||
|
**Always use the project's configured `iconLibrary` for imports.** Check the `iconLibrary` field from project context: `lucide` → `lucide-react`, `tabler` → `@tabler/icons-react`, etc. Never assume `lucide-react`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Icons in Button use data-icon attribute
|
||||||
|
|
||||||
|
Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button>
|
||||||
|
<SearchIcon className='mr-2 size-4' />
|
||||||
|
Search
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button>
|
||||||
|
<SearchIcon data-icon="inline-start"/>
|
||||||
|
Search
|
||||||
|
</Button>
|
||||||
|
|
||||||
|
<Button>
|
||||||
|
Next
|
||||||
|
<ArrowRightIcon data-icon="inline-end"/>
|
||||||
|
</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No sizing classes on icons inside components
|
||||||
|
|
||||||
|
Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other shadcn components. Unless the user explicitly asks for custom icon sizes.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button>
|
||||||
|
<SearchIcon className="size-4" data-icon="inline-start" />
|
||||||
|
Search
|
||||||
|
</Button>
|
||||||
|
|
||||||
|
<DropdownMenuItem>
|
||||||
|
<SettingsIcon className="mr-2 size-4" />
|
||||||
|
Settings
|
||||||
|
</DropdownMenuItem>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button>
|
||||||
|
<SearchIcon data-icon="inline-start" />
|
||||||
|
Search
|
||||||
|
</Button>
|
||||||
|
|
||||||
|
<DropdownMenuItem>
|
||||||
|
<SettingsIcon />
|
||||||
|
Settings
|
||||||
|
</DropdownMenuItem>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pass icons as component objects, not string keys
|
||||||
|
|
||||||
|
Use `icon={CheckIcon}`, not a string key to a lookup map.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const iconMap = {
|
||||||
|
check: CheckIcon,
|
||||||
|
alert: AlertIcon
|
||||||
|
};
|
||||||
|
|
||||||
|
function StatusBadge({ icon }: { icon: string }) {
|
||||||
|
const Icon = iconMap[icon];
|
||||||
|
return <Icon />;
|
||||||
|
}
|
||||||
|
|
||||||
|
<StatusBadge icon='check' />;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Import from the project's configured iconLibrary (e.g. lucide-react, @tabler/icons-react).
|
||||||
|
import { CheckIcon } from 'lucide-react';
|
||||||
|
|
||||||
|
function StatusBadge({ icon: Icon }: { icon: React.ComponentType }) {
|
||||||
|
return <Icon />;
|
||||||
|
}
|
||||||
|
|
||||||
|
<StatusBadge icon={CheckIcon} />;
|
||||||
|
```
|
||||||
161
.agents/skills/shadcn/rules/styling.md
Normal file
161
.agents/skills/shadcn/rules/styling.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# Styling & Customization
|
||||||
|
|
||||||
|
See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
- Semantic colors
|
||||||
|
- Built-in variants first
|
||||||
|
- className for layout only
|
||||||
|
- No space-x-_ / space-y-_
|
||||||
|
- Prefer size-_ over w-_ h-\* when equal
|
||||||
|
- Prefer truncate shorthand
|
||||||
|
- No manual dark: color overrides
|
||||||
|
- Use cn() for conditional classes
|
||||||
|
- No manual z-index on overlay components
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Semantic colors
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className='bg-blue-500 text-white'>
|
||||||
|
<p className='text-gray-600'>Secondary text</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className='bg-primary text-primary-foreground'>
|
||||||
|
<p className='text-muted-foreground'>Secondary text</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No raw color values for status/state indicators
|
||||||
|
|
||||||
|
For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<span className="text-emerald-600">+20.1%</span>
|
||||||
|
<span className="text-green-500">Active</span>
|
||||||
|
<span className="text-red-600">-3.2%</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Badge variant="secondary">+20.1%</Badge>
|
||||||
|
<Badge>Active</Badge>
|
||||||
|
<span className="text-destructive">-3.2%</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Built-in variants first
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button className='border border-input bg-transparent hover:bg-accent'>Click me</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Button variant='outline'>Click me</Button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## className for layout only
|
||||||
|
|
||||||
|
Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Card className='bg-blue-100 text-blue-900 font-bold'>
|
||||||
|
<CardContent>Dashboard</CardContent>
|
||||||
|
</Card>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Card className='max-w-md mx-auto'>
|
||||||
|
<CardContent>Dashboard</CardContent>
|
||||||
|
</Card>
|
||||||
|
```
|
||||||
|
|
||||||
|
To customize a component's appearance, prefer these approaches in order:
|
||||||
|
|
||||||
|
1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
|
||||||
|
2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
|
||||||
|
3. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No space-x-_ / space-y-_
|
||||||
|
|
||||||
|
Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className='flex flex-col gap-4'>
|
||||||
|
<Input />
|
||||||
|
<Input />
|
||||||
|
<Button>Submit</Button>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prefer size-_ over w-_ h-\* when equal
|
||||||
|
|
||||||
|
`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prefer truncate shorthand
|
||||||
|
|
||||||
|
`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No manual dark: color overrides
|
||||||
|
|
||||||
|
Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Use cn() for conditional classes
|
||||||
|
|
||||||
|
Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { cn } from "@/lib/utils"
|
||||||
|
|
||||||
|
<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No manual z-index on overlay components
|
||||||
|
|
||||||
|
`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.
|
||||||
202
.agents/skills/skill-creator/LICENSE.txt
Normal file
202
.agents/skills/skill-creator/LICENSE.txt
Normal file
@@ -0,0 +1,202 @@
|
|||||||
|
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
|
APPENDIX: How to apply the Apache License to your work.
|
||||||
|
|
||||||
|
To apply the Apache License to your work, attach the following
|
||||||
|
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||||
|
replaced with your own identifying information. (Don't include
|
||||||
|
the brackets!) The text should be enclosed in the appropriate
|
||||||
|
comment syntax for the file format. We also recommend that a
|
||||||
|
file or class name and description of purpose be included on the
|
||||||
|
same "printed page" as the copyright notice for easier
|
||||||
|
identification within third-party archives.
|
||||||
|
|
||||||
|
Copyright [yyyy] [name of copyright owner]
|
||||||
|
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
you may not use this file except in compliance with the License.
|
||||||
|
You may obtain a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
See the License for the specific language governing permissions and
|
||||||
|
limitations under the License.
|
||||||
510
.agents/skills/skill-creator/SKILL.md
Normal file
510
.agents/skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,510 @@
|
|||||||
|
---
|
||||||
|
name: skill-creator
|
||||||
|
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Skill Creator
|
||||||
|
|
||||||
|
A skill for creating new skills and iteratively improving them.
|
||||||
|
|
||||||
|
At a high level, the process of creating a skill goes like this:
|
||||||
|
|
||||||
|
- Decide what you want the skill to do and roughly how it should do it
|
||||||
|
- Write a draft of the skill
|
||||||
|
- Create a few test prompts and run claude-with-access-to-the-skill on them
|
||||||
|
- Help the user evaluate the results both qualitatively and quantitatively
|
||||||
|
- While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
|
||||||
|
- Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
|
||||||
|
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
|
||||||
|
- Repeat until you're satisfied
|
||||||
|
- Expand the test set and try again at larger scale
|
||||||
|
|
||||||
|
Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
|
||||||
|
|
||||||
|
On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
|
||||||
|
|
||||||
|
Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
|
||||||
|
|
||||||
|
Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
|
||||||
|
|
||||||
|
Cool? Cool.
|
||||||
|
|
||||||
|
## Communicating with the user
|
||||||
|
|
||||||
|
The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
|
||||||
|
|
||||||
|
So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
|
||||||
|
|
||||||
|
- "evaluation" and "benchmark" are borderline, but OK
|
||||||
|
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
|
||||||
|
|
||||||
|
It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Creating a skill
|
||||||
|
|
||||||
|
### Capture Intent
|
||||||
|
|
||||||
|
Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
|
||||||
|
|
||||||
|
1. What should this skill enable Claude to do?
|
||||||
|
2. When should this skill trigger? (what user phrases/contexts)
|
||||||
|
3. What's the expected output format?
|
||||||
|
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
|
||||||
|
|
||||||
|
### Interview and Research
|
||||||
|
|
||||||
|
Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
|
||||||
|
|
||||||
|
Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.
|
||||||
|
|
||||||
|
### Write the SKILL.md
|
||||||
|
|
||||||
|
Based on the user interview, fill in these components:
|
||||||
|
|
||||||
|
- **name**: Skill identifier
|
||||||
|
- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
|
||||||
|
- **compatibility**: Required tools, dependencies (optional, rarely needed)
|
||||||
|
- **the rest of the skill :)**
|
||||||
|
|
||||||
|
### Skill Writing Guide
|
||||||
|
|
||||||
|
#### Anatomy of a Skill
|
||||||
|
|
||||||
|
```
|
||||||
|
skill-name/
|
||||||
|
├── SKILL.md (required)
|
||||||
|
│ ├── YAML frontmatter (name, description required)
|
||||||
|
│ └── Markdown instructions
|
||||||
|
└── Bundled Resources (optional)
|
||||||
|
├── scripts/ - Executable code for deterministic/repetitive tasks
|
||||||
|
├── references/ - Docs loaded into context as needed
|
||||||
|
└── assets/ - Files used in output (templates, icons, fonts)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Progressive Disclosure
|
||||||
|
|
||||||
|
Skills use a three-level loading system:
|
||||||
|
|
||||||
|
1. **Metadata** (name + description) - Always in context (~100 words)
|
||||||
|
2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
|
||||||
|
3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
|
||||||
|
|
||||||
|
These word counts are approximate and you can feel free to go longer if needed.
|
||||||
|
|
||||||
|
**Key patterns:**
|
||||||
|
|
||||||
|
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
|
||||||
|
- Reference files clearly from SKILL.md with guidance on when to read them
|
||||||
|
- For large reference files (>300 lines), include a table of contents
|
||||||
|
|
||||||
|
**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
|
||||||
|
|
||||||
|
```
|
||||||
|
cloud-deploy/
|
||||||
|
├── SKILL.md (workflow + selection)
|
||||||
|
└── references/
|
||||||
|
├── aws.md
|
||||||
|
├── gcp.md
|
||||||
|
└── azure.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Claude reads only the relevant reference file.
|
||||||
|
|
||||||
|
#### Principle of Lack of Surprise
|
||||||
|
|
||||||
|
This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
|
||||||
|
|
||||||
|
#### Writing Patterns
|
||||||
|
|
||||||
|
Prefer using the imperative form in instructions.
|
||||||
|
|
||||||
|
**Defining output formats** - You can do it like this:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Report structure
|
||||||
|
|
||||||
|
ALWAYS use this exact template:
|
||||||
|
|
||||||
|
# [Title]
|
||||||
|
|
||||||
|
## Executive summary
|
||||||
|
|
||||||
|
## Key findings
|
||||||
|
|
||||||
|
## Recommendations
|
||||||
|
```
|
||||||
|
|
||||||
|
**Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Commit message format
|
||||||
|
|
||||||
|
**Example 1:**
|
||||||
|
Input: Added user authentication with JWT tokens
|
||||||
|
Output: feat(auth): implement JWT-based authentication
|
||||||
|
```
|
||||||
|
|
||||||
|
### Writing Style
|
||||||
|
|
||||||
|
Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
|
||||||
|
|
||||||
|
### Test Cases
|
||||||
|
|
||||||
|
After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
|
||||||
|
|
||||||
|
Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"skill_name": "example-skill",
|
||||||
|
"evals": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"prompt": "User's task prompt",
|
||||||
|
"expected_output": "Description of expected result",
|
||||||
|
"files": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later).
|
||||||
|
|
||||||
|
## Running and evaluating test cases
|
||||||
|
|
||||||
|
This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill.
|
||||||
|
|
||||||
|
Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go.
|
||||||
|
|
||||||
|
### Step 1: Spawn all runs (with-skill AND baseline) in the same turn
|
||||||
|
|
||||||
|
For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
|
||||||
|
|
||||||
|
**With-skill run:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Execute this task:
|
||||||
|
- Skill path: <path-to-skill>
|
||||||
|
- Task: <eval prompt>
|
||||||
|
- Input files: <eval files if any, or "none">
|
||||||
|
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
|
||||||
|
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Baseline run** (same prompt, but the baseline depends on context):
|
||||||
|
|
||||||
|
- **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`.
|
||||||
|
- **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r <skill-path> <workspace>/skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`.
|
||||||
|
|
||||||
|
Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"eval_id": 0,
|
||||||
|
"eval_name": "descriptive-name-here",
|
||||||
|
"prompt": "The user's task prompt",
|
||||||
|
"assertions": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: While runs are in progress, draft assertions
|
||||||
|
|
||||||
|
Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check.
|
||||||
|
|
||||||
|
Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.
|
||||||
|
|
||||||
|
Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.
|
||||||
|
|
||||||
|
### Step 3: As runs complete, capture timing data
|
||||||
|
|
||||||
|
When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"total_tokens": 84852,
|
||||||
|
"duration_ms": 23332,
|
||||||
|
"total_duration_seconds": 23.3
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
|
||||||
|
|
||||||
|
### Step 4: Grade, aggregate, and launch the viewer
|
||||||
|
|
||||||
|
Once all runs are done:
|
||||||
|
|
||||||
|
1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.
|
||||||
|
|
||||||
|
2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
|
||||||
|
```
|
||||||
|
|
||||||
|
This produces `benchmark.json` and `benchmark.md` with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects.
|
||||||
|
Put each with_skill version before its baseline counterpart.
|
||||||
|
|
||||||
|
3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.
|
||||||
|
|
||||||
|
4. **Launch the viewer** with both qualitative outputs and quantitative data:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
|
||||||
|
<workspace>/iteration-N \
|
||||||
|
--skill-name "my-skill" \
|
||||||
|
--benchmark <workspace>/iteration-N/benchmark.json \
|
||||||
|
> /dev/null 2>&1 &
|
||||||
|
VIEWER_PID=$!
|
||||||
|
```
|
||||||
|
|
||||||
|
For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
|
||||||
|
|
||||||
|
**Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
|
||||||
|
|
||||||
|
Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
|
||||||
|
|
||||||
|
5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."
|
||||||
|
|
||||||
|
### What the user sees in the viewer
|
||||||
|
|
||||||
|
The "Outputs" tab shows one test case at a time:
|
||||||
|
|
||||||
|
- **Prompt**: the task that was given
|
||||||
|
- **Output**: the files the skill produced, rendered inline where possible
|
||||||
|
- **Previous Output** (iteration 2+): collapsed section showing last iteration's output
|
||||||
|
- **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail
|
||||||
|
- **Feedback**: a textbox that auto-saves as they type
|
||||||
|
- **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox
|
||||||
|
|
||||||
|
The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.
|
||||||
|
|
||||||
|
Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`.
|
||||||
|
|
||||||
|
### Step 5: Read the feedback
|
||||||
|
|
||||||
|
When the user tells you they're done, read `feedback.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"reviews": [
|
||||||
|
{
|
||||||
|
"run_id": "eval-0-with_skill",
|
||||||
|
"feedback": "the chart is missing axis labels",
|
||||||
|
"timestamp": "..."
|
||||||
|
},
|
||||||
|
{ "run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..." },
|
||||||
|
{ "run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..." }
|
||||||
|
],
|
||||||
|
"status": "complete"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.
|
||||||
|
|
||||||
|
Kill the viewer server when you're done with it:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kill $VIEWER_PID 2>/dev/null
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Improving the skill
|
||||||
|
|
||||||
|
This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
|
||||||
|
|
||||||
|
### How to think about improvements
|
||||||
|
|
||||||
|
1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.
|
||||||
|
|
||||||
|
2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.
|
||||||
|
|
||||||
|
3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are _smart_. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
|
||||||
|
|
||||||
|
4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel.
|
||||||
|
|
||||||
|
This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.
|
||||||
|
|
||||||
|
### The iteration loop
|
||||||
|
|
||||||
|
After improving the skill:
|
||||||
|
|
||||||
|
1. Apply your improvements to the skill
|
||||||
|
2. Rerun all test cases into a new `iteration-<N+1>/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
|
||||||
|
3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration
|
||||||
|
4. Wait for the user to review and tell you they're done
|
||||||
|
5. Read the new feedback, improve again, repeat
|
||||||
|
|
||||||
|
Keep going until:
|
||||||
|
|
||||||
|
- The user says they're happy
|
||||||
|
- The feedback is all empty (everything looks good)
|
||||||
|
- You're not making meaningful progress
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced: Blind comparison
|
||||||
|
|
||||||
|
For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.
|
||||||
|
|
||||||
|
This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Description Optimization
|
||||||
|
|
||||||
|
The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
|
||||||
|
|
||||||
|
### Step 1: Generate trigger eval queries
|
||||||
|
|
||||||
|
Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{ "query": "the user prompt", "should_trigger": true },
|
||||||
|
{ "query": "another prompt", "should_trigger": false }
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
|
||||||
|
|
||||||
|
Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
|
||||||
|
|
||||||
|
Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`
|
||||||
|
|
||||||
|
For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
|
||||||
|
|
||||||
|
For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
|
||||||
|
|
||||||
|
The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
|
||||||
|
|
||||||
|
### Step 2: Review with user
|
||||||
|
|
||||||
|
Present the eval set to the user for review using the HTML template:
|
||||||
|
|
||||||
|
1. Read the template from `assets/eval_review.html`
|
||||||
|
2. Replace the placeholders:
|
||||||
|
- `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
|
||||||
|
- `__SKILL_NAME_PLACEHOLDER__` → the skill's name
|
||||||
|
- `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
|
||||||
|
3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
|
||||||
|
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
|
||||||
|
5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)
|
||||||
|
|
||||||
|
This step matters — bad eval queries lead to bad descriptions.
|
||||||
|
|
||||||
|
### Step 3: Run the optimization loop
|
||||||
|
|
||||||
|
Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
|
||||||
|
|
||||||
|
Save the eval set to the workspace, then run in the background:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m scripts.run_loop \
|
||||||
|
--eval-set <path-to-trigger-eval.json> \
|
||||||
|
--skill-path <path-to-skill> \
|
||||||
|
--model <model-id-powering-this-session> \
|
||||||
|
--max-iterations 5 \
|
||||||
|
--verbose
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
|
||||||
|
|
||||||
|
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
|
||||||
|
|
||||||
|
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||||
|
|
||||||
|
### How skill triggering works
|
||||||
|
|
||||||
|
Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
|
||||||
|
|
||||||
|
This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
|
||||||
|
|
||||||
|
### Step 4: Apply the result
|
||||||
|
|
||||||
|
Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Package and Present (only if `present_files` tool is available)
|
||||||
|
|
||||||
|
Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python -m scripts.package_skill <path/to/skill-folder>
|
||||||
|
```
|
||||||
|
|
||||||
|
After packaging, direct the user to the resulting `.skill` file path so they can install it.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Claude.ai-specific instructions
|
||||||
|
|
||||||
|
In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
|
||||||
|
|
||||||
|
**Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
|
||||||
|
|
||||||
|
**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
|
||||||
|
|
||||||
|
**Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
|
||||||
|
|
||||||
|
**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
|
||||||
|
|
||||||
|
**Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai.
|
||||||
|
|
||||||
|
**Blind comparison**: Requires subagents. Skip it.
|
||||||
|
|
||||||
|
**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.
|
||||||
|
|
||||||
|
**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
|
||||||
|
|
||||||
|
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
|
||||||
|
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
|
||||||
|
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cowork-Specific Instructions
|
||||||
|
|
||||||
|
If you're in Cowork, the main things to know are:
|
||||||
|
|
||||||
|
- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
|
||||||
|
- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
|
||||||
|
- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER _BEFORE_ evaluating inputs yourself. You want to get them in front of the human ASAP!
|
||||||
|
- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
|
||||||
|
- Packaging works — `package_skill.py` just needs Python and a filesystem.
|
||||||
|
- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
|
||||||
|
- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reference files
|
||||||
|
|
||||||
|
The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
|
||||||
|
|
||||||
|
- `agents/grader.md` — How to evaluate assertions against outputs
|
||||||
|
- `agents/comparator.md` — How to do blind A/B comparison between two outputs
|
||||||
|
- `agents/analyzer.md` — How to analyze why one version beat another
|
||||||
|
|
||||||
|
The references/ directory has additional documentation:
|
||||||
|
|
||||||
|
- `references/schemas.md` — JSON structures for evals.json, grading.json, etc.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Repeating one more time the core loop here for emphasis:
|
||||||
|
|
||||||
|
- Figure out what the skill is about
|
||||||
|
- Draft or edit the skill
|
||||||
|
- Run claude-with-access-to-the-skill on test prompts
|
||||||
|
- With the user, evaluate the outputs:
|
||||||
|
- Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
|
||||||
|
- Run quantitative evals
|
||||||
|
- Repeat until you and the user are satisfied
|
||||||
|
- Package the final skill and return it to the user.
|
||||||
|
|
||||||
|
Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
|
||||||
|
|
||||||
|
Good luck!
|
||||||
283
.agents/skills/skill-creator/agents/analyzer.md
Normal file
283
.agents/skills/skill-creator/agents/analyzer.md
Normal file
@@ -0,0 +1,283 @@
|
|||||||
|
# Post-hoc Analyzer Agent
|
||||||
|
|
||||||
|
Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.
|
||||||
|
|
||||||
|
## Role
|
||||||
|
|
||||||
|
After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
You receive these parameters in your prompt:
|
||||||
|
|
||||||
|
- **winner**: "A" or "B" (from blind comparison)
|
||||||
|
- **winner_skill_path**: Path to the skill that produced the winning output
|
||||||
|
- **winner_transcript_path**: Path to the execution transcript for the winner
|
||||||
|
- **loser_skill_path**: Path to the skill that produced the losing output
|
||||||
|
- **loser_transcript_path**: Path to the execution transcript for the loser
|
||||||
|
- **comparison_result_path**: Path to the blind comparator's output JSON
|
||||||
|
- **output_path**: Where to save the analysis results
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### Step 1: Read Comparison Result
|
||||||
|
|
||||||
|
1. Read the blind comparator's output at comparison_result_path
|
||||||
|
2. Note the winning side (A or B), the reasoning, and any scores
|
||||||
|
3. Understand what the comparator valued in the winning output
|
||||||
|
|
||||||
|
### Step 2: Read Both Skills
|
||||||
|
|
||||||
|
1. Read the winner skill's SKILL.md and key referenced files
|
||||||
|
2. Read the loser skill's SKILL.md and key referenced files
|
||||||
|
3. Identify structural differences:
|
||||||
|
- Instructions clarity and specificity
|
||||||
|
- Script/tool usage patterns
|
||||||
|
- Example coverage
|
||||||
|
- Edge case handling
|
||||||
|
|
||||||
|
### Step 3: Read Both Transcripts
|
||||||
|
|
||||||
|
1. Read the winner's transcript
|
||||||
|
2. Read the loser's transcript
|
||||||
|
3. Compare execution patterns:
|
||||||
|
- How closely did each follow their skill's instructions?
|
||||||
|
- What tools were used differently?
|
||||||
|
- Where did the loser diverge from optimal behavior?
|
||||||
|
- Did either encounter errors or make recovery attempts?
|
||||||
|
|
||||||
|
### Step 4: Analyze Instruction Following
|
||||||
|
|
||||||
|
For each transcript, evaluate:
|
||||||
|
|
||||||
|
- Did the agent follow the skill's explicit instructions?
|
||||||
|
- Did the agent use the skill's provided tools/scripts?
|
||||||
|
- Were there missed opportunities to leverage skill content?
|
||||||
|
- Did the agent add unnecessary steps not in the skill?
|
||||||
|
|
||||||
|
Score instruction following 1-10 and note specific issues.
|
||||||
|
|
||||||
|
### Step 5: Identify Winner Strengths
|
||||||
|
|
||||||
|
Determine what made the winner better:
|
||||||
|
|
||||||
|
- Clearer instructions that led to better behavior?
|
||||||
|
- Better scripts/tools that produced better output?
|
||||||
|
- More comprehensive examples that guided edge cases?
|
||||||
|
- Better error handling guidance?
|
||||||
|
|
||||||
|
Be specific. Quote from skills/transcripts where relevant.
|
||||||
|
|
||||||
|
### Step 6: Identify Loser Weaknesses
|
||||||
|
|
||||||
|
Determine what held the loser back:
|
||||||
|
|
||||||
|
- Ambiguous instructions that led to suboptimal choices?
|
||||||
|
- Missing tools/scripts that forced workarounds?
|
||||||
|
- Gaps in edge case coverage?
|
||||||
|
- Poor error handling that caused failures?
|
||||||
|
|
||||||
|
### Step 7: Generate Improvement Suggestions
|
||||||
|
|
||||||
|
Based on the analysis, produce actionable suggestions for improving the loser skill:
|
||||||
|
|
||||||
|
- Specific instruction changes to make
|
||||||
|
- Tools/scripts to add or modify
|
||||||
|
- Examples to include
|
||||||
|
- Edge cases to address
|
||||||
|
|
||||||
|
Prioritize by impact. Focus on changes that would have changed the outcome.
|
||||||
|
|
||||||
|
### Step 8: Write Analysis Results
|
||||||
|
|
||||||
|
Save structured analysis to `{output_path}`.
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Write a JSON file with this structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"comparison_summary": {
|
||||||
|
"winner": "A",
|
||||||
|
"winner_skill": "path/to/winner/skill",
|
||||||
|
"loser_skill": "path/to/loser/skill",
|
||||||
|
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||||
|
},
|
||||||
|
"winner_strengths": [
|
||||||
|
"Clear step-by-step instructions for handling multi-page documents",
|
||||||
|
"Included validation script that caught formatting errors",
|
||||||
|
"Explicit guidance on fallback behavior when OCR fails"
|
||||||
|
],
|
||||||
|
"loser_weaknesses": [
|
||||||
|
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||||
|
"No script for validation, agent had to improvise and made errors",
|
||||||
|
"No guidance on OCR failure, agent gave up instead of trying alternatives"
|
||||||
|
],
|
||||||
|
"instruction_following": {
|
||||||
|
"winner": {
|
||||||
|
"score": 9,
|
||||||
|
"issues": ["Minor: skipped optional logging step"]
|
||||||
|
},
|
||||||
|
"loser": {
|
||||||
|
"score": 6,
|
||||||
|
"issues": [
|
||||||
|
"Did not use the skill's formatting template",
|
||||||
|
"Invented own approach instead of following step 3",
|
||||||
|
"Missed the 'always validate output' instruction"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"improvement_suggestions": [
|
||||||
|
{
|
||||||
|
"priority": "high",
|
||||||
|
"category": "instructions",
|
||||||
|
"suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
|
||||||
|
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"priority": "high",
|
||||||
|
"category": "tools",
|
||||||
|
"suggestion": "Add validate_output.py script similar to winner skill's validation approach",
|
||||||
|
"expected_impact": "Would catch formatting errors before final output"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"priority": "medium",
|
||||||
|
"category": "error_handling",
|
||||||
|
"suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
|
||||||
|
"expected_impact": "Would prevent early failure on difficult documents"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"transcript_insights": {
|
||||||
|
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
|
||||||
|
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Guidelines
|
||||||
|
|
||||||
|
- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear"
|
||||||
|
- **Be actionable**: Suggestions should be concrete changes, not vague advice
|
||||||
|
- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent
|
||||||
|
- **Prioritize by impact**: Which changes would most likely have changed the outcome?
|
||||||
|
- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental?
|
||||||
|
- **Stay objective**: Analyze what happened, don't editorialize
|
||||||
|
- **Think about generalization**: Would this improvement help on other evals too?
|
||||||
|
|
||||||
|
## Categories for Suggestions
|
||||||
|
|
||||||
|
Use these categories to organize improvement suggestions:
|
||||||
|
|
||||||
|
| Category | Description |
|
||||||
|
| ---------------- | ---------------------------------------------- |
|
||||||
|
| `instructions` | Changes to the skill's prose instructions |
|
||||||
|
| `tools` | Scripts, templates, or utilities to add/modify |
|
||||||
|
| `examples` | Example inputs/outputs to include |
|
||||||
|
| `error_handling` | Guidance for handling failures |
|
||||||
|
| `structure` | Reorganization of skill content |
|
||||||
|
| `references` | External docs or resources to add |
|
||||||
|
|
||||||
|
## Priority Levels
|
||||||
|
|
||||||
|
- **high**: Would likely change the outcome of this comparison
|
||||||
|
- **medium**: Would improve quality but may not change win/loss
|
||||||
|
- **low**: Nice to have, marginal improvement
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Analyzing Benchmark Results
|
||||||
|
|
||||||
|
When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements.
|
||||||
|
|
||||||
|
## Role
|
||||||
|
|
||||||
|
Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
You receive these parameters in your prompt:
|
||||||
|
|
||||||
|
- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results
|
||||||
|
- **skill_path**: Path to the skill being benchmarked
|
||||||
|
- **output_path**: Where to save the notes (as JSON array of strings)
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### Step 1: Read Benchmark Data
|
||||||
|
|
||||||
|
1. Read the benchmark.json containing all run results
|
||||||
|
2. Note the configurations tested (with_skill, without_skill)
|
||||||
|
3. Understand the run_summary aggregates already calculated
|
||||||
|
|
||||||
|
### Step 2: Analyze Per-Assertion Patterns
|
||||||
|
|
||||||
|
For each expectation across all runs:
|
||||||
|
|
||||||
|
- Does it **always pass** in both configurations? (may not differentiate skill value)
|
||||||
|
- Does it **always fail** in both configurations? (may be broken or beyond capability)
|
||||||
|
- Does it **always pass with skill but fail without**? (skill clearly adds value here)
|
||||||
|
- Does it **always fail with skill but pass without**? (skill may be hurting)
|
||||||
|
- Is it **highly variable**? (flaky expectation or non-deterministic behavior)
|
||||||
|
|
||||||
|
### Step 3: Analyze Cross-Eval Patterns
|
||||||
|
|
||||||
|
Look for patterns across evals:
|
||||||
|
|
||||||
|
- Are certain eval types consistently harder/easier?
|
||||||
|
- Do some evals show high variance while others are stable?
|
||||||
|
- Are there surprising results that contradict expectations?
|
||||||
|
|
||||||
|
### Step 4: Analyze Metrics Patterns
|
||||||
|
|
||||||
|
Look at time_seconds, tokens, tool_calls:
|
||||||
|
|
||||||
|
- Does the skill significantly increase execution time?
|
||||||
|
- Is there high variance in resource usage?
|
||||||
|
- Are there outlier runs that skew the aggregates?
|
||||||
|
|
||||||
|
### Step 5: Generate Notes
|
||||||
|
|
||||||
|
Write freeform observations as a list of strings. Each note should:
|
||||||
|
|
||||||
|
- State a specific observation
|
||||||
|
- Be grounded in the data (not speculation)
|
||||||
|
- Help the user understand something the aggregate metrics don't show
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
|
||||||
|
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
|
||||||
|
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
|
||||||
|
- "Skill adds 13s average execution time but improves pass rate by 50%"
|
||||||
|
- "Token usage is 80% higher with skill, primarily due to script output parsing"
|
||||||
|
- "All 3 without-skill runs for eval 1 produced empty output"
|
||||||
|
|
||||||
|
### Step 6: Write Notes
|
||||||
|
|
||||||
|
Save notes to `{output_path}` as a JSON array of strings:
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||||
|
"Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
|
||||||
|
"Without-skill runs consistently fail on table extraction expectations",
|
||||||
|
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Guidelines
|
||||||
|
|
||||||
|
**DO:**
|
||||||
|
|
||||||
|
- Report what you observe in the data
|
||||||
|
- Be specific about which evals, expectations, or runs you're referring to
|
||||||
|
- Note patterns that aggregate metrics would hide
|
||||||
|
- Provide context that helps interpret the numbers
|
||||||
|
|
||||||
|
**DO NOT:**
|
||||||
|
|
||||||
|
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
|
||||||
|
- Make subjective quality judgments ("the output was good/bad")
|
||||||
|
- Speculate about causes without evidence
|
||||||
|
- Repeat information already in the run_summary aggregates
|
||||||
203
.agents/skills/skill-creator/agents/comparator.md
Normal file
203
.agents/skills/skill-creator/agents/comparator.md
Normal file
@@ -0,0 +1,203 @@
|
|||||||
|
# Blind Comparator Agent
|
||||||
|
|
||||||
|
Compare two outputs WITHOUT knowing which skill produced them.
|
||||||
|
|
||||||
|
## Role
|
||||||
|
|
||||||
|
The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
|
||||||
|
|
||||||
|
Your judgment is based purely on output quality and task completion.
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
You receive these parameters in your prompt:
|
||||||
|
|
||||||
|
- **output_a_path**: Path to the first output file or directory
|
||||||
|
- **output_b_path**: Path to the second output file or directory
|
||||||
|
- **eval_prompt**: The original task/prompt that was executed
|
||||||
|
- **expectations**: List of expectations to check (optional - may be empty)
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### Step 1: Read Both Outputs
|
||||||
|
|
||||||
|
1. Examine output A (file or directory)
|
||||||
|
2. Examine output B (file or directory)
|
||||||
|
3. Note the type, structure, and content of each
|
||||||
|
4. If outputs are directories, examine all relevant files inside
|
||||||
|
|
||||||
|
### Step 2: Understand the Task
|
||||||
|
|
||||||
|
1. Read the eval_prompt carefully
|
||||||
|
2. Identify what the task requires:
|
||||||
|
- What should be produced?
|
||||||
|
- What qualities matter (accuracy, completeness, format)?
|
||||||
|
- What would distinguish a good output from a poor one?
|
||||||
|
|
||||||
|
### Step 3: Generate Evaluation Rubric
|
||||||
|
|
||||||
|
Based on the task, generate a rubric with two dimensions:
|
||||||
|
|
||||||
|
**Content Rubric** (what the output contains):
|
||||||
|
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||||
|
|-----------|----------|----------------|---------------|
|
||||||
|
| Correctness | Major errors | Minor errors | Fully correct |
|
||||||
|
| Completeness | Missing key elements | Mostly complete | All elements present |
|
||||||
|
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |
|
||||||
|
|
||||||
|
**Structure Rubric** (how the output is organized):
|
||||||
|
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||||
|
|-----------|----------|----------------|---------------|
|
||||||
|
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
|
||||||
|
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
|
||||||
|
| Usability | Difficult to use | Usable with effort | Easy to use |
|
||||||
|
|
||||||
|
Adapt criteria to the specific task. For example:
|
||||||
|
|
||||||
|
- PDF form → "Field alignment", "Text readability", "Data placement"
|
||||||
|
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
|
||||||
|
- Data output → "Schema correctness", "Data types", "Completeness"
|
||||||
|
|
||||||
|
### Step 4: Evaluate Each Output Against the Rubric
|
||||||
|
|
||||||
|
For each output (A and B):
|
||||||
|
|
||||||
|
1. **Score each criterion** on the rubric (1-5 scale)
|
||||||
|
2. **Calculate dimension totals**: Content score, Structure score
|
||||||
|
3. **Calculate overall score**: Average of dimension scores, scaled to 1-10
|
||||||
|
|
||||||
|
### Step 5: Check Assertions (if provided)
|
||||||
|
|
||||||
|
If expectations are provided:
|
||||||
|
|
||||||
|
1. Check each expectation against output A
|
||||||
|
2. Check each expectation against output B
|
||||||
|
3. Count pass rates for each output
|
||||||
|
4. Use expectation scores as secondary evidence (not the primary decision factor)
|
||||||
|
|
||||||
|
### Step 6: Determine the Winner
|
||||||
|
|
||||||
|
Compare A and B based on (in priority order):
|
||||||
|
|
||||||
|
1. **Primary**: Overall rubric score (content + structure)
|
||||||
|
2. **Secondary**: Assertion pass rates (if applicable)
|
||||||
|
3. **Tiebreaker**: If truly equal, declare a TIE
|
||||||
|
|
||||||
|
Be decisive - ties should be rare. One output is usually better, even if marginally.
|
||||||
|
|
||||||
|
### Step 7: Write Comparison Results
|
||||||
|
|
||||||
|
Save results to a JSON file at the path specified (or `comparison.json` if not specified).
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Write a JSON file with this structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"winner": "A",
|
||||||
|
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||||
|
"rubric": {
|
||||||
|
"A": {
|
||||||
|
"content": {
|
||||||
|
"correctness": 5,
|
||||||
|
"completeness": 5,
|
||||||
|
"accuracy": 4
|
||||||
|
},
|
||||||
|
"structure": {
|
||||||
|
"organization": 4,
|
||||||
|
"formatting": 5,
|
||||||
|
"usability": 4
|
||||||
|
},
|
||||||
|
"content_score": 4.7,
|
||||||
|
"structure_score": 4.3,
|
||||||
|
"overall_score": 9.0
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"content": {
|
||||||
|
"correctness": 3,
|
||||||
|
"completeness": 2,
|
||||||
|
"accuracy": 3
|
||||||
|
},
|
||||||
|
"structure": {
|
||||||
|
"organization": 3,
|
||||||
|
"formatting": 2,
|
||||||
|
"usability": 3
|
||||||
|
},
|
||||||
|
"content_score": 2.7,
|
||||||
|
"structure_score": 2.7,
|
||||||
|
"overall_score": 5.4
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"output_quality": {
|
||||||
|
"A": {
|
||||||
|
"score": 9,
|
||||||
|
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||||
|
"weaknesses": ["Minor style inconsistency in header"]
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"score": 5,
|
||||||
|
"strengths": ["Readable output", "Correct basic structure"],
|
||||||
|
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"expectation_results": {
|
||||||
|
"A": {
|
||||||
|
"passed": 4,
|
||||||
|
"total": 5,
|
||||||
|
"pass_rate": 0.8,
|
||||||
|
"details": [
|
||||||
|
{ "text": "Output includes name", "passed": true },
|
||||||
|
{ "text": "Output includes date", "passed": true },
|
||||||
|
{ "text": "Format is PDF", "passed": true },
|
||||||
|
{ "text": "Contains signature", "passed": false },
|
||||||
|
{ "text": "Readable text", "passed": true }
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"passed": 3,
|
||||||
|
"total": 5,
|
||||||
|
"pass_rate": 0.6,
|
||||||
|
"details": [
|
||||||
|
{ "text": "Output includes name", "passed": true },
|
||||||
|
{ "text": "Output includes date", "passed": false },
|
||||||
|
{ "text": "Format is PDF", "passed": true },
|
||||||
|
{ "text": "Contains signature", "passed": false },
|
||||||
|
{ "text": "Readable text", "passed": true }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
If no expectations were provided, omit the `expectation_results` field entirely.
|
||||||
|
|
||||||
|
## Field Descriptions
|
||||||
|
|
||||||
|
- **winner**: "A", "B", or "TIE"
|
||||||
|
- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie)
|
||||||
|
- **rubric**: Structured rubric evaluation for each output
|
||||||
|
- **content**: Scores for content criteria (correctness, completeness, accuracy)
|
||||||
|
- **structure**: Scores for structure criteria (organization, formatting, usability)
|
||||||
|
- **content_score**: Average of content criteria (1-5)
|
||||||
|
- **structure_score**: Average of structure criteria (1-5)
|
||||||
|
- **overall_score**: Combined score scaled to 1-10
|
||||||
|
- **output_quality**: Summary quality assessment
|
||||||
|
- **score**: 1-10 rating (should match rubric overall_score)
|
||||||
|
- **strengths**: List of positive aspects
|
||||||
|
- **weaknesses**: List of issues or shortcomings
|
||||||
|
- **expectation_results**: (Only if expectations provided)
|
||||||
|
- **passed**: Number of expectations that passed
|
||||||
|
- **total**: Total number of expectations
|
||||||
|
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||||
|
- **details**: Individual expectation results
|
||||||
|
|
||||||
|
## Guidelines
|
||||||
|
|
||||||
|
- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality.
|
||||||
|
- **Be specific**: Cite specific examples when explaining strengths and weaknesses.
|
||||||
|
- **Be decisive**: Choose a winner unless outputs are genuinely equivalent.
|
||||||
|
- **Output quality first**: Assertion scores are secondary to overall task completion.
|
||||||
|
- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness.
|
||||||
|
- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner.
|
||||||
|
- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.
|
||||||
227
.agents/skills/skill-creator/agents/grader.md
Normal file
227
.agents/skills/skill-creator/agents/grader.md
Normal file
@@ -0,0 +1,227 @@
|
|||||||
|
# Grader Agent
|
||||||
|
|
||||||
|
Evaluate expectations against an execution transcript and outputs.
|
||||||
|
|
||||||
|
## Role
|
||||||
|
|
||||||
|
The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.
|
||||||
|
|
||||||
|
You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
You receive these parameters in your prompt:
|
||||||
|
|
||||||
|
- **expectations**: List of expectations to evaluate (strings)
|
||||||
|
- **transcript_path**: Path to the execution transcript (markdown file)
|
||||||
|
- **outputs_dir**: Directory containing output files from execution
|
||||||
|
|
||||||
|
## Process
|
||||||
|
|
||||||
|
### Step 1: Read the Transcript
|
||||||
|
|
||||||
|
1. Read the transcript file completely
|
||||||
|
2. Note the eval prompt, execution steps, and final result
|
||||||
|
3. Identify any issues or errors documented
|
||||||
|
|
||||||
|
### Step 2: Examine Output Files
|
||||||
|
|
||||||
|
1. List files in outputs_dir
|
||||||
|
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
|
||||||
|
3. Note contents, structure, and quality
|
||||||
|
|
||||||
|
### Step 3: Evaluate Each Assertion
|
||||||
|
|
||||||
|
For each expectation:
|
||||||
|
|
||||||
|
1. **Search for evidence** in the transcript and outputs
|
||||||
|
2. **Determine verdict**:
|
||||||
|
- **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
|
||||||
|
- **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
|
||||||
|
3. **Cite the evidence**: Quote the specific text or describe what you found
|
||||||
|
|
||||||
|
### Step 4: Extract and Verify Claims
|
||||||
|
|
||||||
|
Beyond the predefined expectations, extract implicit claims from the outputs and verify them:
|
||||||
|
|
||||||
|
1. **Extract claims** from the transcript and outputs:
|
||||||
|
- Factual statements ("The form has 12 fields")
|
||||||
|
- Process claims ("Used pypdf to fill the form")
|
||||||
|
- Quality claims ("All fields were filled correctly")
|
||||||
|
|
||||||
|
2. **Verify each claim**:
|
||||||
|
- **Factual claims**: Can be checked against the outputs or external sources
|
||||||
|
- **Process claims**: Can be verified from the transcript
|
||||||
|
- **Quality claims**: Evaluate whether the claim is justified
|
||||||
|
|
||||||
|
3. **Flag unverifiable claims**: Note claims that cannot be verified with available information
|
||||||
|
|
||||||
|
This catches issues that predefined expectations might miss.
|
||||||
|
|
||||||
|
### Step 5: Read User Notes
|
||||||
|
|
||||||
|
If `{outputs_dir}/user_notes.md` exists:
|
||||||
|
|
||||||
|
1. Read it and note any uncertainties or issues flagged by the executor
|
||||||
|
2. Include relevant concerns in the grading output
|
||||||
|
3. These may reveal problems even when expectations pass
|
||||||
|
|
||||||
|
### Step 6: Critique the Evals
|
||||||
|
|
||||||
|
After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.
|
||||||
|
|
||||||
|
Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion _discriminating_: it passes when the skill genuinely succeeds and fails when it doesn't.
|
||||||
|
|
||||||
|
Suggestions worth raising:
|
||||||
|
|
||||||
|
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
|
||||||
|
- An important outcome you observed — good or bad — that no assertion covers at all
|
||||||
|
- An assertion that can't actually be verified from the available outputs
|
||||||
|
|
||||||
|
Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.
|
||||||
|
|
||||||
|
### Step 7: Write Grading Results
|
||||||
|
|
||||||
|
Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).
|
||||||
|
|
||||||
|
## Grading Criteria
|
||||||
|
|
||||||
|
**PASS when**:
|
||||||
|
|
||||||
|
- The transcript or outputs clearly demonstrate the expectation is true
|
||||||
|
- Specific evidence can be cited
|
||||||
|
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)
|
||||||
|
|
||||||
|
**FAIL when**:
|
||||||
|
|
||||||
|
- No evidence found for the expectation
|
||||||
|
- Evidence contradicts the expectation
|
||||||
|
- The expectation cannot be verified from available information
|
||||||
|
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
|
||||||
|
- The output appears to meet the assertion by coincidence rather than by actually doing the work
|
||||||
|
|
||||||
|
**When uncertain**: The burden of proof to pass is on the expectation.
|
||||||
|
|
||||||
|
### Step 8: Read Executor Metrics and Timing
|
||||||
|
|
||||||
|
1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
|
||||||
|
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
Write a JSON file with this structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"expectations": [
|
||||||
|
{
|
||||||
|
"text": "The output includes the name 'John Smith'",
|
||||||
|
"passed": true,
|
||||||
|
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||||
|
"passed": false,
|
||||||
|
"evidence": "No spreadsheet was created. The output was a text file."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"text": "The assistant used the skill's OCR script",
|
||||||
|
"passed": true,
|
||||||
|
"evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"summary": {
|
||||||
|
"passed": 2,
|
||||||
|
"failed": 1,
|
||||||
|
"total": 3,
|
||||||
|
"pass_rate": 0.67
|
||||||
|
},
|
||||||
|
"execution_metrics": {
|
||||||
|
"tool_calls": {
|
||||||
|
"Read": 5,
|
||||||
|
"Write": 2,
|
||||||
|
"Bash": 8
|
||||||
|
},
|
||||||
|
"total_tool_calls": 15,
|
||||||
|
"total_steps": 6,
|
||||||
|
"errors_encountered": 0,
|
||||||
|
"output_chars": 12450,
|
||||||
|
"transcript_chars": 3200
|
||||||
|
},
|
||||||
|
"timing": {
|
||||||
|
"executor_duration_seconds": 165.0,
|
||||||
|
"grader_duration_seconds": 26.0,
|
||||||
|
"total_duration_seconds": 191.0
|
||||||
|
},
|
||||||
|
"claims": [
|
||||||
|
{
|
||||||
|
"claim": "The form has 12 fillable fields",
|
||||||
|
"type": "factual",
|
||||||
|
"verified": true,
|
||||||
|
"evidence": "Counted 12 fields in field_info.json"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"claim": "All required fields were populated",
|
||||||
|
"type": "quality",
|
||||||
|
"verified": false,
|
||||||
|
"evidence": "Reference section was left blank despite data being available"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"user_notes_summary": {
|
||||||
|
"uncertainties": ["Used 2023 data, may be stale"],
|
||||||
|
"needs_review": [],
|
||||||
|
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||||
|
},
|
||||||
|
"eval_feedback": {
|
||||||
|
"suggestions": [
|
||||||
|
{
|
||||||
|
"assertion": "The output includes the name 'John Smith'",
|
||||||
|
"reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"overall": "Assertions check presence but not correctness. Consider adding content verification."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Field Descriptions
|
||||||
|
|
||||||
|
- **expectations**: Array of graded expectations
|
||||||
|
- **text**: The original expectation text
|
||||||
|
- **passed**: Boolean - true if expectation passes
|
||||||
|
- **evidence**: Specific quote or description supporting the verdict
|
||||||
|
- **summary**: Aggregate statistics
|
||||||
|
- **passed**: Count of passed expectations
|
||||||
|
- **failed**: Count of failed expectations
|
||||||
|
- **total**: Total expectations evaluated
|
||||||
|
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||||
|
- **execution_metrics**: Copied from executor's metrics.json (if available)
|
||||||
|
- **output_chars**: Total character count of output files (proxy for tokens)
|
||||||
|
- **transcript_chars**: Character count of transcript
|
||||||
|
- **timing**: Wall clock timing from timing.json (if available)
|
||||||
|
- **executor_duration_seconds**: Time spent in executor subagent
|
||||||
|
- **total_duration_seconds**: Total elapsed time for the run
|
||||||
|
- **claims**: Extracted and verified claims from the output
|
||||||
|
- **claim**: The statement being verified
|
||||||
|
- **type**: "factual", "process", or "quality"
|
||||||
|
- **verified**: Boolean - whether the claim holds
|
||||||
|
- **evidence**: Supporting or contradicting evidence
|
||||||
|
- **user_notes_summary**: Issues flagged by the executor
|
||||||
|
- **uncertainties**: Things the executor wasn't sure about
|
||||||
|
- **needs_review**: Items requiring human attention
|
||||||
|
- **workarounds**: Places where the skill didn't work as expected
|
||||||
|
- **eval_feedback**: Improvement suggestions for the evals (only when warranted)
|
||||||
|
- **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
|
||||||
|
- **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag
|
||||||
|
|
||||||
|
## Guidelines
|
||||||
|
|
||||||
|
- **Be objective**: Base verdicts on evidence, not assumptions
|
||||||
|
- **Be specific**: Quote the exact text that supports your verdict
|
||||||
|
- **Be thorough**: Check both transcript and output files
|
||||||
|
- **Be consistent**: Apply the same standard to each expectation
|
||||||
|
- **Explain failures**: Make it clear why evidence was insufficient
|
||||||
|
- **No partial credit**: Each expectation is pass or fail, not partial
|
||||||
292
.agents/skills/skill-creator/assets/eval_review.html
Normal file
292
.agents/skills/skill-creator/assets/eval_review.html
Normal file
@@ -0,0 +1,292 @@
|
|||||||
|
<!doctype html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8" />
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
|
<title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
|
||||||
|
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||||
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||||||
|
<link
|
||||||
|
href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap"
|
||||||
|
rel="stylesheet"
|
||||||
|
/>
|
||||||
|
<style>
|
||||||
|
* {
|
||||||
|
box-sizing: border-box;
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
body {
|
||||||
|
font-family: 'Lora', Georgia, serif;
|
||||||
|
background: #faf9f5;
|
||||||
|
padding: 2rem;
|
||||||
|
color: #141413;
|
||||||
|
}
|
||||||
|
h1 {
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
margin-bottom: 0.5rem;
|
||||||
|
font-size: 1.5rem;
|
||||||
|
}
|
||||||
|
.description {
|
||||||
|
color: #b0aea5;
|
||||||
|
margin-bottom: 1.5rem;
|
||||||
|
font-style: italic;
|
||||||
|
max-width: 900px;
|
||||||
|
}
|
||||||
|
.controls {
|
||||||
|
margin-bottom: 1rem;
|
||||||
|
display: flex;
|
||||||
|
gap: 0.5rem;
|
||||||
|
}
|
||||||
|
.btn {
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
padding: 0.5rem 1rem;
|
||||||
|
border: none;
|
||||||
|
border-radius: 6px;
|
||||||
|
cursor: pointer;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
font-weight: 500;
|
||||||
|
}
|
||||||
|
.btn-add {
|
||||||
|
background: #6a9bcc;
|
||||||
|
color: white;
|
||||||
|
}
|
||||||
|
.btn-add:hover {
|
||||||
|
background: #5889b8;
|
||||||
|
}
|
||||||
|
.btn-export {
|
||||||
|
background: #d97757;
|
||||||
|
color: white;
|
||||||
|
}
|
||||||
|
.btn-export:hover {
|
||||||
|
background: #c4613f;
|
||||||
|
}
|
||||||
|
table {
|
||||||
|
width: 100%;
|
||||||
|
max-width: 1100px;
|
||||||
|
border-collapse: collapse;
|
||||||
|
background: white;
|
||||||
|
border-radius: 6px;
|
||||||
|
overflow: hidden;
|
||||||
|
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
|
||||||
|
}
|
||||||
|
th {
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
background: #141413;
|
||||||
|
color: #faf9f5;
|
||||||
|
padding: 0.75rem 1rem;
|
||||||
|
text-align: left;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
}
|
||||||
|
td {
|
||||||
|
padding: 0.75rem 1rem;
|
||||||
|
border-bottom: 1px solid #e8e6dc;
|
||||||
|
vertical-align: top;
|
||||||
|
}
|
||||||
|
tr:nth-child(even) td {
|
||||||
|
background: #faf9f5;
|
||||||
|
}
|
||||||
|
tr:hover td {
|
||||||
|
background: #f3f1ea;
|
||||||
|
}
|
||||||
|
.section-header td {
|
||||||
|
background: #e8e6dc;
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
font-weight: 500;
|
||||||
|
font-size: 0.8rem;
|
||||||
|
color: #141413;
|
||||||
|
text-transform: uppercase;
|
||||||
|
letter-spacing: 0.05em;
|
||||||
|
}
|
||||||
|
.query-input {
|
||||||
|
width: 100%;
|
||||||
|
padding: 0.4rem;
|
||||||
|
border: 1px solid #e8e6dc;
|
||||||
|
border-radius: 4px;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
font-family: 'Lora', Georgia, serif;
|
||||||
|
resize: vertical;
|
||||||
|
min-height: 60px;
|
||||||
|
}
|
||||||
|
.query-input:focus {
|
||||||
|
outline: none;
|
||||||
|
border-color: #d97757;
|
||||||
|
box-shadow: 0 0 0 2px rgba(217, 119, 87, 0.15);
|
||||||
|
}
|
||||||
|
.toggle {
|
||||||
|
position: relative;
|
||||||
|
display: inline-block;
|
||||||
|
width: 44px;
|
||||||
|
height: 24px;
|
||||||
|
}
|
||||||
|
.toggle input {
|
||||||
|
opacity: 0;
|
||||||
|
width: 0;
|
||||||
|
height: 0;
|
||||||
|
}
|
||||||
|
.toggle .slider {
|
||||||
|
position: absolute;
|
||||||
|
inset: 0;
|
||||||
|
background: #b0aea5;
|
||||||
|
border-radius: 24px;
|
||||||
|
cursor: pointer;
|
||||||
|
transition: 0.2s;
|
||||||
|
}
|
||||||
|
.toggle .slider::before {
|
||||||
|
content: '';
|
||||||
|
position: absolute;
|
||||||
|
width: 18px;
|
||||||
|
height: 18px;
|
||||||
|
left: 3px;
|
||||||
|
bottom: 3px;
|
||||||
|
background: white;
|
||||||
|
border-radius: 50%;
|
||||||
|
transition: 0.2s;
|
||||||
|
}
|
||||||
|
.toggle input:checked + .slider {
|
||||||
|
background: #d97757;
|
||||||
|
}
|
||||||
|
.toggle input:checked + .slider::before {
|
||||||
|
transform: translateX(20px);
|
||||||
|
}
|
||||||
|
.btn-delete {
|
||||||
|
background: #c44;
|
||||||
|
color: white;
|
||||||
|
padding: 0.3rem 0.6rem;
|
||||||
|
border: none;
|
||||||
|
border-radius: 4px;
|
||||||
|
cursor: pointer;
|
||||||
|
font-size: 0.75rem;
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
}
|
||||||
|
.btn-delete:hover {
|
||||||
|
background: #a33;
|
||||||
|
}
|
||||||
|
.summary {
|
||||||
|
margin-top: 1rem;
|
||||||
|
color: #b0aea5;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
|
||||||
|
<p class="description">
|
||||||
|
Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<div class="controls">
|
||||||
|
<button class="btn btn-add" onclick="addRow()">+ Add Query</button>
|
||||||
|
<button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th style="width: 65%">Query</th>
|
||||||
|
<th style="width: 18%">Should Trigger</th>
|
||||||
|
<th style="width: 10%">Actions</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody id="eval-body"></tbody>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<p class="summary" id="summary"></p>
|
||||||
|
|
||||||
|
<script>
|
||||||
|
const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;
|
||||||
|
|
||||||
|
let evalItems = [...EVAL_DATA];
|
||||||
|
|
||||||
|
function render() {
|
||||||
|
const tbody = document.getElementById('eval-body');
|
||||||
|
tbody.innerHTML = '';
|
||||||
|
|
||||||
|
// Sort: should-trigger first, then should-not-trigger
|
||||||
|
const sorted = evalItems
|
||||||
|
.map((item, origIdx) => ({ ...item, origIdx }))
|
||||||
|
.sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));
|
||||||
|
|
||||||
|
let lastGroup = null;
|
||||||
|
sorted.forEach((item) => {
|
||||||
|
const group = item.should_trigger ? 'trigger' : 'no-trigger';
|
||||||
|
if (group !== lastGroup) {
|
||||||
|
const headerRow = document.createElement('tr');
|
||||||
|
headerRow.className = 'section-header';
|
||||||
|
headerRow.innerHTML = `<td colspan="3">${item.should_trigger ? 'Should Trigger' : 'Should NOT Trigger'}</td>`;
|
||||||
|
tbody.appendChild(headerRow);
|
||||||
|
lastGroup = group;
|
||||||
|
}
|
||||||
|
|
||||||
|
const idx = item.origIdx;
|
||||||
|
const tr = document.createElement('tr');
|
||||||
|
tr.innerHTML = `
|
||||||
|
<td><textarea class="query-input" onchange="updateQuery(${idx}, this.value)">${escapeHtml(item.query)}</textarea></td>
|
||||||
|
<td>
|
||||||
|
<label class="toggle">
|
||||||
|
<input type="checkbox" ${item.should_trigger ? 'checked' : ''} onchange="updateTrigger(${idx}, this.checked)">
|
||||||
|
<span class="slider"></span>
|
||||||
|
</label>
|
||||||
|
<span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">${item.should_trigger ? 'Yes' : 'No'}</span>
|
||||||
|
</td>
|
||||||
|
<td><button class="btn-delete" onclick="deleteRow(${idx})">Delete</button></td>
|
||||||
|
`;
|
||||||
|
tbody.appendChild(tr);
|
||||||
|
});
|
||||||
|
updateSummary();
|
||||||
|
}
|
||||||
|
|
||||||
|
function escapeHtml(text) {
|
||||||
|
const div = document.createElement('div');
|
||||||
|
div.textContent = text;
|
||||||
|
return div.innerHTML;
|
||||||
|
}
|
||||||
|
|
||||||
|
function updateQuery(idx, value) {
|
||||||
|
evalItems[idx].query = value;
|
||||||
|
updateSummary();
|
||||||
|
}
|
||||||
|
function updateTrigger(idx, value) {
|
||||||
|
evalItems[idx].should_trigger = value;
|
||||||
|
render();
|
||||||
|
}
|
||||||
|
function deleteRow(idx) {
|
||||||
|
evalItems.splice(idx, 1);
|
||||||
|
render();
|
||||||
|
}
|
||||||
|
|
||||||
|
function addRow() {
|
||||||
|
evalItems.push({ query: '', should_trigger: true });
|
||||||
|
render();
|
||||||
|
const inputs = document.querySelectorAll('.query-input');
|
||||||
|
inputs[inputs.length - 1].focus();
|
||||||
|
}
|
||||||
|
|
||||||
|
function updateSummary() {
|
||||||
|
const trigger = evalItems.filter((i) => i.should_trigger).length;
|
||||||
|
const noTrigger = evalItems.filter((i) => !i.should_trigger).length;
|
||||||
|
document.getElementById('summary').textContent =
|
||||||
|
`${evalItems.length} queries total: ${trigger} should trigger, ${noTrigger} should not trigger`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function exportEvalSet() {
|
||||||
|
const valid = evalItems.filter((i) => i.query.trim() !== '');
|
||||||
|
const data = valid.map((i) => ({
|
||||||
|
query: i.query.trim(),
|
||||||
|
should_trigger: i.should_trigger
|
||||||
|
}));
|
||||||
|
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
|
||||||
|
const url = URL.createObjectURL(blob);
|
||||||
|
const a = document.createElement('a');
|
||||||
|
a.href = url;
|
||||||
|
a.download = 'eval_set.json';
|
||||||
|
document.body.appendChild(a);
|
||||||
|
a.click();
|
||||||
|
document.body.removeChild(a);
|
||||||
|
URL.revokeObjectURL(url);
|
||||||
|
}
|
||||||
|
|
||||||
|
render();
|
||||||
|
</script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
471
.agents/skills/skill-creator/eval-viewer/generate_review.py
Normal file
471
.agents/skills/skill-creator/eval-viewer/generate_review.py
Normal file
@@ -0,0 +1,471 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Generate and serve a review page for eval results.
|
||||||
|
|
||||||
|
Reads the workspace directory, discovers runs (directories with outputs/),
|
||||||
|
embeds all output data into a self-contained HTML page, and serves it via
|
||||||
|
a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME]
|
||||||
|
python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json
|
||||||
|
|
||||||
|
No dependencies beyond the Python stdlib are required.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import base64
|
||||||
|
import json
|
||||||
|
import mimetypes
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import signal
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import time
|
||||||
|
import webbrowser
|
||||||
|
from functools import partial
|
||||||
|
from http.server import HTTPServer, BaseHTTPRequestHandler
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
# Files to exclude from output listings
|
||||||
|
METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"}
|
||||||
|
|
||||||
|
# Extensions we render as inline text
|
||||||
|
TEXT_EXTENSIONS = {
|
||||||
|
".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx",
|
||||||
|
".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs",
|
||||||
|
".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml",
|
||||||
|
}
|
||||||
|
|
||||||
|
# Extensions we render as inline images
|
||||||
|
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
|
||||||
|
|
||||||
|
# MIME type overrides for common types
|
||||||
|
MIME_OVERRIDES = {
|
||||||
|
".svg": "image/svg+xml",
|
||||||
|
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||||
|
".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||||
|
".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def get_mime_type(path: Path) -> str:
|
||||||
|
ext = path.suffix.lower()
|
||||||
|
if ext in MIME_OVERRIDES:
|
||||||
|
return MIME_OVERRIDES[ext]
|
||||||
|
mime, _ = mimetypes.guess_type(str(path))
|
||||||
|
return mime or "application/octet-stream"
|
||||||
|
|
||||||
|
|
||||||
|
def find_runs(workspace: Path) -> list[dict]:
|
||||||
|
"""Recursively find directories that contain an outputs/ subdirectory."""
|
||||||
|
runs: list[dict] = []
|
||||||
|
_find_runs_recursive(workspace, workspace, runs)
|
||||||
|
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
|
||||||
|
return runs
|
||||||
|
|
||||||
|
|
||||||
|
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
|
||||||
|
if not current.is_dir():
|
||||||
|
return
|
||||||
|
|
||||||
|
outputs_dir = current / "outputs"
|
||||||
|
if outputs_dir.is_dir():
|
||||||
|
run = build_run(root, current)
|
||||||
|
if run:
|
||||||
|
runs.append(run)
|
||||||
|
return
|
||||||
|
|
||||||
|
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
|
||||||
|
for child in sorted(current.iterdir()):
|
||||||
|
if child.is_dir() and child.name not in skip:
|
||||||
|
_find_runs_recursive(root, child, runs)
|
||||||
|
|
||||||
|
|
||||||
|
def build_run(root: Path, run_dir: Path) -> dict | None:
|
||||||
|
"""Build a run dict with prompt, outputs, and grading data."""
|
||||||
|
prompt = ""
|
||||||
|
eval_id = None
|
||||||
|
|
||||||
|
# Try eval_metadata.json
|
||||||
|
for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
|
||||||
|
if candidate.exists():
|
||||||
|
try:
|
||||||
|
metadata = json.loads(candidate.read_text())
|
||||||
|
prompt = metadata.get("prompt", "")
|
||||||
|
eval_id = metadata.get("eval_id")
|
||||||
|
except (json.JSONDecodeError, OSError):
|
||||||
|
pass
|
||||||
|
if prompt:
|
||||||
|
break
|
||||||
|
|
||||||
|
# Fall back to transcript.md
|
||||||
|
if not prompt:
|
||||||
|
for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]:
|
||||||
|
if candidate.exists():
|
||||||
|
try:
|
||||||
|
text = candidate.read_text()
|
||||||
|
match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text)
|
||||||
|
if match:
|
||||||
|
prompt = match.group(1).strip()
|
||||||
|
except OSError:
|
||||||
|
pass
|
||||||
|
if prompt:
|
||||||
|
break
|
||||||
|
|
||||||
|
if not prompt:
|
||||||
|
prompt = "(No prompt found)"
|
||||||
|
|
||||||
|
run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-")
|
||||||
|
|
||||||
|
# Collect output files
|
||||||
|
outputs_dir = run_dir / "outputs"
|
||||||
|
output_files: list[dict] = []
|
||||||
|
if outputs_dir.is_dir():
|
||||||
|
for f in sorted(outputs_dir.iterdir()):
|
||||||
|
if f.is_file() and f.name not in METADATA_FILES:
|
||||||
|
output_files.append(embed_file(f))
|
||||||
|
|
||||||
|
# Load grading if present
|
||||||
|
grading = None
|
||||||
|
for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]:
|
||||||
|
if candidate.exists():
|
||||||
|
try:
|
||||||
|
grading = json.loads(candidate.read_text())
|
||||||
|
except (json.JSONDecodeError, OSError):
|
||||||
|
pass
|
||||||
|
if grading:
|
||||||
|
break
|
||||||
|
|
||||||
|
return {
|
||||||
|
"id": run_id,
|
||||||
|
"prompt": prompt,
|
||||||
|
"eval_id": eval_id,
|
||||||
|
"outputs": output_files,
|
||||||
|
"grading": grading,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def embed_file(path: Path) -> dict:
|
||||||
|
"""Read a file and return an embedded representation."""
|
||||||
|
ext = path.suffix.lower()
|
||||||
|
mime = get_mime_type(path)
|
||||||
|
|
||||||
|
if ext in TEXT_EXTENSIONS:
|
||||||
|
try:
|
||||||
|
content = path.read_text(errors="replace")
|
||||||
|
except OSError:
|
||||||
|
content = "(Error reading file)"
|
||||||
|
return {
|
||||||
|
"name": path.name,
|
||||||
|
"type": "text",
|
||||||
|
"content": content,
|
||||||
|
}
|
||||||
|
elif ext in IMAGE_EXTENSIONS:
|
||||||
|
try:
|
||||||
|
raw = path.read_bytes()
|
||||||
|
b64 = base64.b64encode(raw).decode("ascii")
|
||||||
|
except OSError:
|
||||||
|
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||||
|
return {
|
||||||
|
"name": path.name,
|
||||||
|
"type": "image",
|
||||||
|
"mime": mime,
|
||||||
|
"data_uri": f"data:{mime};base64,{b64}",
|
||||||
|
}
|
||||||
|
elif ext == ".pdf":
|
||||||
|
try:
|
||||||
|
raw = path.read_bytes()
|
||||||
|
b64 = base64.b64encode(raw).decode("ascii")
|
||||||
|
except OSError:
|
||||||
|
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||||
|
return {
|
||||||
|
"name": path.name,
|
||||||
|
"type": "pdf",
|
||||||
|
"data_uri": f"data:{mime};base64,{b64}",
|
||||||
|
}
|
||||||
|
elif ext == ".xlsx":
|
||||||
|
try:
|
||||||
|
raw = path.read_bytes()
|
||||||
|
b64 = base64.b64encode(raw).decode("ascii")
|
||||||
|
except OSError:
|
||||||
|
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||||
|
return {
|
||||||
|
"name": path.name,
|
||||||
|
"type": "xlsx",
|
||||||
|
"data_b64": b64,
|
||||||
|
}
|
||||||
|
else:
|
||||||
|
# Binary / unknown — base64 download link
|
||||||
|
try:
|
||||||
|
raw = path.read_bytes()
|
||||||
|
b64 = base64.b64encode(raw).decode("ascii")
|
||||||
|
except OSError:
|
||||||
|
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||||
|
return {
|
||||||
|
"name": path.name,
|
||||||
|
"type": "binary",
|
||||||
|
"mime": mime,
|
||||||
|
"data_uri": f"data:{mime};base64,{b64}",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def load_previous_iteration(workspace: Path) -> dict[str, dict]:
|
||||||
|
"""Load previous iteration's feedback and outputs.
|
||||||
|
|
||||||
|
Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}.
|
||||||
|
"""
|
||||||
|
result: dict[str, dict] = {}
|
||||||
|
|
||||||
|
# Load feedback
|
||||||
|
feedback_map: dict[str, str] = {}
|
||||||
|
feedback_path = workspace / "feedback.json"
|
||||||
|
if feedback_path.exists():
|
||||||
|
try:
|
||||||
|
data = json.loads(feedback_path.read_text())
|
||||||
|
feedback_map = {
|
||||||
|
r["run_id"]: r["feedback"]
|
||||||
|
for r in data.get("reviews", [])
|
||||||
|
if r.get("feedback", "").strip()
|
||||||
|
}
|
||||||
|
except (json.JSONDecodeError, OSError, KeyError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Load runs (to get outputs)
|
||||||
|
prev_runs = find_runs(workspace)
|
||||||
|
for run in prev_runs:
|
||||||
|
result[run["id"]] = {
|
||||||
|
"feedback": feedback_map.get(run["id"], ""),
|
||||||
|
"outputs": run.get("outputs", []),
|
||||||
|
}
|
||||||
|
|
||||||
|
# Also add feedback for run_ids that had feedback but no matching run
|
||||||
|
for run_id, fb in feedback_map.items():
|
||||||
|
if run_id not in result:
|
||||||
|
result[run_id] = {"feedback": fb, "outputs": []}
|
||||||
|
|
||||||
|
return result
|
||||||
|
|
||||||
|
|
||||||
|
def generate_html(
|
||||||
|
runs: list[dict],
|
||||||
|
skill_name: str,
|
||||||
|
previous: dict[str, dict] | None = None,
|
||||||
|
benchmark: dict | None = None,
|
||||||
|
) -> str:
|
||||||
|
"""Generate the complete standalone HTML page with embedded data."""
|
||||||
|
template_path = Path(__file__).parent / "viewer.html"
|
||||||
|
template = template_path.read_text()
|
||||||
|
|
||||||
|
# Build previous_feedback and previous_outputs maps for the template
|
||||||
|
previous_feedback: dict[str, str] = {}
|
||||||
|
previous_outputs: dict[str, list[dict]] = {}
|
||||||
|
if previous:
|
||||||
|
for run_id, data in previous.items():
|
||||||
|
if data.get("feedback"):
|
||||||
|
previous_feedback[run_id] = data["feedback"]
|
||||||
|
if data.get("outputs"):
|
||||||
|
previous_outputs[run_id] = data["outputs"]
|
||||||
|
|
||||||
|
embedded = {
|
||||||
|
"skill_name": skill_name,
|
||||||
|
"runs": runs,
|
||||||
|
"previous_feedback": previous_feedback,
|
||||||
|
"previous_outputs": previous_outputs,
|
||||||
|
}
|
||||||
|
if benchmark:
|
||||||
|
embedded["benchmark"] = benchmark
|
||||||
|
|
||||||
|
data_json = json.dumps(embedded)
|
||||||
|
|
||||||
|
return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")
|
||||||
|
|
||||||
|
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
# HTTP server (stdlib only, zero dependencies)
|
||||||
|
# ---------------------------------------------------------------------------
|
||||||
|
|
||||||
|
def _kill_port(port: int) -> None:
|
||||||
|
"""Kill any process listening on the given port."""
|
||||||
|
try:
|
||||||
|
result = subprocess.run(
|
||||||
|
["lsof", "-ti", f":{port}"],
|
||||||
|
capture_output=True, text=True, timeout=5,
|
||||||
|
)
|
||||||
|
for pid_str in result.stdout.strip().split("\n"):
|
||||||
|
if pid_str.strip():
|
||||||
|
try:
|
||||||
|
os.kill(int(pid_str.strip()), signal.SIGTERM)
|
||||||
|
except (ProcessLookupError, ValueError):
|
||||||
|
pass
|
||||||
|
if result.stdout.strip():
|
||||||
|
time.sleep(0.5)
|
||||||
|
except subprocess.TimeoutExpired:
|
||||||
|
pass
|
||||||
|
except FileNotFoundError:
|
||||||
|
print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
|
||||||
|
|
||||||
|
class ReviewHandler(BaseHTTPRequestHandler):
|
||||||
|
"""Serves the review HTML and handles feedback saves.
|
||||||
|
|
||||||
|
Regenerates the HTML on each page load so that refreshing the browser
|
||||||
|
picks up new eval outputs without restarting the server.
|
||||||
|
"""
|
||||||
|
|
||||||
|
def __init__(
|
||||||
|
self,
|
||||||
|
workspace: Path,
|
||||||
|
skill_name: str,
|
||||||
|
feedback_path: Path,
|
||||||
|
previous: dict[str, dict],
|
||||||
|
benchmark_path: Path | None,
|
||||||
|
*args,
|
||||||
|
**kwargs,
|
||||||
|
):
|
||||||
|
self.workspace = workspace
|
||||||
|
self.skill_name = skill_name
|
||||||
|
self.feedback_path = feedback_path
|
||||||
|
self.previous = previous
|
||||||
|
self.benchmark_path = benchmark_path
|
||||||
|
super().__init__(*args, **kwargs)
|
||||||
|
|
||||||
|
def do_GET(self) -> None:
|
||||||
|
if self.path == "/" or self.path == "/index.html":
|
||||||
|
# Regenerate HTML on each request (re-scans workspace for new outputs)
|
||||||
|
runs = find_runs(self.workspace)
|
||||||
|
benchmark = None
|
||||||
|
if self.benchmark_path and self.benchmark_path.exists():
|
||||||
|
try:
|
||||||
|
benchmark = json.loads(self.benchmark_path.read_text())
|
||||||
|
except (json.JSONDecodeError, OSError):
|
||||||
|
pass
|
||||||
|
html = generate_html(runs, self.skill_name, self.previous, benchmark)
|
||||||
|
content = html.encode("utf-8")
|
||||||
|
self.send_response(200)
|
||||||
|
self.send_header("Content-Type", "text/html; charset=utf-8")
|
||||||
|
self.send_header("Content-Length", str(len(content)))
|
||||||
|
self.end_headers()
|
||||||
|
self.wfile.write(content)
|
||||||
|
elif self.path == "/api/feedback":
|
||||||
|
data = b"{}"
|
||||||
|
if self.feedback_path.exists():
|
||||||
|
data = self.feedback_path.read_bytes()
|
||||||
|
self.send_response(200)
|
||||||
|
self.send_header("Content-Type", "application/json")
|
||||||
|
self.send_header("Content-Length", str(len(data)))
|
||||||
|
self.end_headers()
|
||||||
|
self.wfile.write(data)
|
||||||
|
else:
|
||||||
|
self.send_error(404)
|
||||||
|
|
||||||
|
def do_POST(self) -> None:
|
||||||
|
if self.path == "/api/feedback":
|
||||||
|
length = int(self.headers.get("Content-Length", 0))
|
||||||
|
body = self.rfile.read(length)
|
||||||
|
try:
|
||||||
|
data = json.loads(body)
|
||||||
|
if not isinstance(data, dict) or "reviews" not in data:
|
||||||
|
raise ValueError("Expected JSON object with 'reviews' key")
|
||||||
|
self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
|
||||||
|
resp = b'{"ok":true}'
|
||||||
|
self.send_response(200)
|
||||||
|
except (json.JSONDecodeError, OSError, ValueError) as e:
|
||||||
|
resp = json.dumps({"error": str(e)}).encode()
|
||||||
|
self.send_response(500)
|
||||||
|
self.send_header("Content-Type", "application/json")
|
||||||
|
self.send_header("Content-Length", str(len(resp)))
|
||||||
|
self.end_headers()
|
||||||
|
self.wfile.write(resp)
|
||||||
|
else:
|
||||||
|
self.send_error(404)
|
||||||
|
|
||||||
|
def log_message(self, format: str, *args: object) -> None:
|
||||||
|
# Suppress request logging to keep terminal clean
|
||||||
|
pass
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> None:
|
||||||
|
parser = argparse.ArgumentParser(description="Generate and serve eval review")
|
||||||
|
parser.add_argument("workspace", type=Path, help="Path to workspace directory")
|
||||||
|
parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)")
|
||||||
|
parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header")
|
||||||
|
parser.add_argument(
|
||||||
|
"--previous-workspace", type=Path, default=None,
|
||||||
|
help="Path to previous iteration's workspace (shows old outputs and feedback as context)",
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--benchmark", type=Path, default=None,
|
||||||
|
help="Path to benchmark.json to show in the Benchmark tab",
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--static", "-s", type=Path, default=None,
|
||||||
|
help="Write standalone HTML to this path instead of starting a server",
|
||||||
|
)
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
workspace = args.workspace.resolve()
|
||||||
|
if not workspace.is_dir():
|
||||||
|
print(f"Error: {workspace} is not a directory", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
runs = find_runs(workspace)
|
||||||
|
if not runs:
|
||||||
|
print(f"No runs found in {workspace}", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
skill_name = args.skill_name or workspace.name.replace("-workspace", "")
|
||||||
|
feedback_path = workspace / "feedback.json"
|
||||||
|
|
||||||
|
previous: dict[str, dict] = {}
|
||||||
|
if args.previous_workspace:
|
||||||
|
previous = load_previous_iteration(args.previous_workspace.resolve())
|
||||||
|
|
||||||
|
benchmark_path = args.benchmark.resolve() if args.benchmark else None
|
||||||
|
benchmark = None
|
||||||
|
if benchmark_path and benchmark_path.exists():
|
||||||
|
try:
|
||||||
|
benchmark = json.loads(benchmark_path.read_text())
|
||||||
|
except (json.JSONDecodeError, OSError):
|
||||||
|
pass
|
||||||
|
|
||||||
|
if args.static:
|
||||||
|
html = generate_html(runs, skill_name, previous, benchmark)
|
||||||
|
args.static.parent.mkdir(parents=True, exist_ok=True)
|
||||||
|
args.static.write_text(html)
|
||||||
|
print(f"\n Static viewer written to: {args.static}\n")
|
||||||
|
sys.exit(0)
|
||||||
|
|
||||||
|
# Kill any existing process on the target port
|
||||||
|
port = args.port
|
||||||
|
_kill_port(port)
|
||||||
|
handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
|
||||||
|
try:
|
||||||
|
server = HTTPServer(("127.0.0.1", port), handler)
|
||||||
|
except OSError:
|
||||||
|
# Port still in use after kill attempt — find a free one
|
||||||
|
server = HTTPServer(("127.0.0.1", 0), handler)
|
||||||
|
port = server.server_address[1]
|
||||||
|
|
||||||
|
url = f"http://localhost:{port}"
|
||||||
|
print(f"\n Eval Viewer")
|
||||||
|
print(f" ─────────────────────────────────")
|
||||||
|
print(f" URL: {url}")
|
||||||
|
print(f" Workspace: {workspace}")
|
||||||
|
print(f" Feedback: {feedback_path}")
|
||||||
|
if previous:
|
||||||
|
print(f" Previous: {args.previous_workspace} ({len(previous)} runs)")
|
||||||
|
if benchmark_path:
|
||||||
|
print(f" Benchmark: {benchmark_path}")
|
||||||
|
print(f"\n Press Ctrl+C to stop.\n")
|
||||||
|
|
||||||
|
webbrowser.open(url)
|
||||||
|
|
||||||
|
try:
|
||||||
|
server.serve_forever()
|
||||||
|
except KeyboardInterrupt:
|
||||||
|
print("\nStopped.")
|
||||||
|
server.server_close()
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
1478
.agents/skills/skill-creator/eval-viewer/viewer.html
Normal file
1478
.agents/skills/skill-creator/eval-viewer/viewer.html
Normal file
File diff suppressed because it is too large
Load Diff
423
.agents/skills/skill-creator/references/schemas.md
Normal file
423
.agents/skills/skill-creator/references/schemas.md
Normal file
@@ -0,0 +1,423 @@
|
|||||||
|
# JSON Schemas
|
||||||
|
|
||||||
|
This document defines the JSON schemas used by skill-creator.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## evals.json
|
||||||
|
|
||||||
|
Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"skill_name": "example-skill",
|
||||||
|
"evals": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"prompt": "User's example prompt",
|
||||||
|
"expected_output": "Description of expected result",
|
||||||
|
"files": ["evals/files/sample1.pdf"],
|
||||||
|
"expectations": ["The output includes X", "The skill used script Y"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
|
||||||
|
- `skill_name`: Name matching the skill's frontmatter
|
||||||
|
- `evals[].id`: Unique integer identifier
|
||||||
|
- `evals[].prompt`: The task to execute
|
||||||
|
- `evals[].expected_output`: Human-readable description of success
|
||||||
|
- `evals[].files`: Optional list of input file paths (relative to skill root)
|
||||||
|
- `evals[].expectations`: List of verifiable statements
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## history.json
|
||||||
|
|
||||||
|
Tracks version progression in Improve mode. Located at workspace root.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"started_at": "2026-01-15T10:30:00Z",
|
||||||
|
"skill_name": "pdf",
|
||||||
|
"current_best": "v2",
|
||||||
|
"iterations": [
|
||||||
|
{
|
||||||
|
"version": "v0",
|
||||||
|
"parent": null,
|
||||||
|
"expectation_pass_rate": 0.65,
|
||||||
|
"grading_result": "baseline",
|
||||||
|
"is_current_best": false
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"version": "v1",
|
||||||
|
"parent": "v0",
|
||||||
|
"expectation_pass_rate": 0.75,
|
||||||
|
"grading_result": "won",
|
||||||
|
"is_current_best": false
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"version": "v2",
|
||||||
|
"parent": "v1",
|
||||||
|
"expectation_pass_rate": 0.85,
|
||||||
|
"grading_result": "won",
|
||||||
|
"is_current_best": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
|
||||||
|
- `started_at`: ISO timestamp of when improvement started
|
||||||
|
- `skill_name`: Name of the skill being improved
|
||||||
|
- `current_best`: Version identifier of the best performer
|
||||||
|
- `iterations[].version`: Version identifier (v0, v1, ...)
|
||||||
|
- `iterations[].parent`: Parent version this was derived from
|
||||||
|
- `iterations[].expectation_pass_rate`: Pass rate from grading
|
||||||
|
- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
|
||||||
|
- `iterations[].is_current_best`: Whether this is the current best version
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## grading.json
|
||||||
|
|
||||||
|
Output from the grader agent. Located at `<run-dir>/grading.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"expectations": [
|
||||||
|
{
|
||||||
|
"text": "The output includes the name 'John Smith'",
|
||||||
|
"passed": true,
|
||||||
|
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||||
|
"passed": false,
|
||||||
|
"evidence": "No spreadsheet was created. The output was a text file."
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"summary": {
|
||||||
|
"passed": 2,
|
||||||
|
"failed": 1,
|
||||||
|
"total": 3,
|
||||||
|
"pass_rate": 0.67
|
||||||
|
},
|
||||||
|
"execution_metrics": {
|
||||||
|
"tool_calls": {
|
||||||
|
"Read": 5,
|
||||||
|
"Write": 2,
|
||||||
|
"Bash": 8
|
||||||
|
},
|
||||||
|
"total_tool_calls": 15,
|
||||||
|
"total_steps": 6,
|
||||||
|
"errors_encountered": 0,
|
||||||
|
"output_chars": 12450,
|
||||||
|
"transcript_chars": 3200
|
||||||
|
},
|
||||||
|
"timing": {
|
||||||
|
"executor_duration_seconds": 165.0,
|
||||||
|
"grader_duration_seconds": 26.0,
|
||||||
|
"total_duration_seconds": 191.0
|
||||||
|
},
|
||||||
|
"claims": [
|
||||||
|
{
|
||||||
|
"claim": "The form has 12 fillable fields",
|
||||||
|
"type": "factual",
|
||||||
|
"verified": true,
|
||||||
|
"evidence": "Counted 12 fields in field_info.json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"user_notes_summary": {
|
||||||
|
"uncertainties": ["Used 2023 data, may be stale"],
|
||||||
|
"needs_review": [],
|
||||||
|
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||||
|
},
|
||||||
|
"eval_feedback": {
|
||||||
|
"suggestions": [
|
||||||
|
{
|
||||||
|
"assertion": "The output includes the name 'John Smith'",
|
||||||
|
"reason": "A hallucinated document that mentions the name would also pass"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"overall": "Assertions check presence but not correctness."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
|
||||||
|
- `expectations[]`: Graded expectations with evidence
|
||||||
|
- `summary`: Aggregate pass/fail counts
|
||||||
|
- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
|
||||||
|
- `timing`: Wall clock timing (from timing.json)
|
||||||
|
- `claims`: Extracted and verified claims from the output
|
||||||
|
- `user_notes_summary`: Issues flagged by the executor
|
||||||
|
- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## metrics.json
|
||||||
|
|
||||||
|
Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool_calls": {
|
||||||
|
"Read": 5,
|
||||||
|
"Write": 2,
|
||||||
|
"Bash": 8,
|
||||||
|
"Edit": 1,
|
||||||
|
"Glob": 2,
|
||||||
|
"Grep": 0
|
||||||
|
},
|
||||||
|
"total_tool_calls": 18,
|
||||||
|
"total_steps": 6,
|
||||||
|
"files_created": ["filled_form.pdf", "field_values.json"],
|
||||||
|
"errors_encountered": 0,
|
||||||
|
"output_chars": 12450,
|
||||||
|
"transcript_chars": 3200
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
|
||||||
|
- `tool_calls`: Count per tool type
|
||||||
|
- `total_tool_calls`: Sum of all tool calls
|
||||||
|
- `total_steps`: Number of major execution steps
|
||||||
|
- `files_created`: List of output files created
|
||||||
|
- `errors_encountered`: Number of errors during execution
|
||||||
|
- `output_chars`: Total character count of output files
|
||||||
|
- `transcript_chars`: Character count of transcript
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## timing.json
|
||||||
|
|
||||||
|
Wall clock timing for a run. Located at `<run-dir>/timing.json`.
|
||||||
|
|
||||||
|
**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"total_tokens": 84852,
|
||||||
|
"duration_ms": 23332,
|
||||||
|
"total_duration_seconds": 23.3,
|
||||||
|
"executor_start": "2026-01-15T10:30:00Z",
|
||||||
|
"executor_end": "2026-01-15T10:32:45Z",
|
||||||
|
"executor_duration_seconds": 165.0,
|
||||||
|
"grader_start": "2026-01-15T10:32:46Z",
|
||||||
|
"grader_end": "2026-01-15T10:33:12Z",
|
||||||
|
"grader_duration_seconds": 26.0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## benchmark.json
|
||||||
|
|
||||||
|
Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"metadata": {
|
||||||
|
"skill_name": "pdf",
|
||||||
|
"skill_path": "/path/to/pdf",
|
||||||
|
"executor_model": "claude-sonnet-4-20250514",
|
||||||
|
"analyzer_model": "most-capable-model",
|
||||||
|
"timestamp": "2026-01-15T10:30:00Z",
|
||||||
|
"evals_run": [1, 2, 3],
|
||||||
|
"runs_per_configuration": 3
|
||||||
|
},
|
||||||
|
|
||||||
|
"runs": [
|
||||||
|
{
|
||||||
|
"eval_id": 1,
|
||||||
|
"eval_name": "Ocean",
|
||||||
|
"configuration": "with_skill",
|
||||||
|
"run_number": 1,
|
||||||
|
"result": {
|
||||||
|
"pass_rate": 0.85,
|
||||||
|
"passed": 6,
|
||||||
|
"failed": 1,
|
||||||
|
"total": 7,
|
||||||
|
"time_seconds": 42.5,
|
||||||
|
"tokens": 3800,
|
||||||
|
"tool_calls": 18,
|
||||||
|
"errors": 0
|
||||||
|
},
|
||||||
|
"expectations": [{ "text": "...", "passed": true, "evidence": "..." }],
|
||||||
|
"notes": ["Used 2023 data, may be stale", "Fell back to text overlay for non-fillable fields"]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
|
||||||
|
"run_summary": {
|
||||||
|
"with_skill": {
|
||||||
|
"pass_rate": { "mean": 0.85, "stddev": 0.05, "min": 0.8, "max": 0.9 },
|
||||||
|
"time_seconds": { "mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0 },
|
||||||
|
"tokens": { "mean": 3800, "stddev": 400, "min": 3200, "max": 4100 }
|
||||||
|
},
|
||||||
|
"without_skill": {
|
||||||
|
"pass_rate": { "mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45 },
|
||||||
|
"time_seconds": { "mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0 },
|
||||||
|
"tokens": { "mean": 2100, "stddev": 300, "min": 1800, "max": 2500 }
|
||||||
|
},
|
||||||
|
"delta": {
|
||||||
|
"pass_rate": "+0.50",
|
||||||
|
"time_seconds": "+13.0",
|
||||||
|
"tokens": "+1700"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
|
||||||
|
"notes": [
|
||||||
|
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||||
|
"Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent",
|
||||||
|
"Without-skill runs consistently fail on table extraction expectations",
|
||||||
|
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fields:**
|
||||||
|
|
||||||
|
- `metadata`: Information about the benchmark run
|
||||||
|
- `skill_name`: Name of the skill
|
||||||
|
- `timestamp`: When the benchmark was run
|
||||||
|
- `evals_run`: List of eval names or IDs
|
||||||
|
- `runs_per_configuration`: Number of runs per config (e.g. 3)
|
||||||
|
- `runs[]`: Individual run results
|
||||||
|
- `eval_id`: Numeric eval identifier
|
||||||
|
- `eval_name`: Human-readable eval name (used as section header in the viewer)
|
||||||
|
- `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
|
||||||
|
- `run_number`: Integer run number (1, 2, 3...)
|
||||||
|
- `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
|
||||||
|
- `run_summary`: Statistical aggregates per configuration
|
||||||
|
- `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
|
||||||
|
- `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
|
||||||
|
- `notes`: Freeform observations from the analyzer
|
||||||
|
|
||||||
|
**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## comparison.json
|
||||||
|
|
||||||
|
Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"winner": "A",
|
||||||
|
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||||
|
"rubric": {
|
||||||
|
"A": {
|
||||||
|
"content": {
|
||||||
|
"correctness": 5,
|
||||||
|
"completeness": 5,
|
||||||
|
"accuracy": 4
|
||||||
|
},
|
||||||
|
"structure": {
|
||||||
|
"organization": 4,
|
||||||
|
"formatting": 5,
|
||||||
|
"usability": 4
|
||||||
|
},
|
||||||
|
"content_score": 4.7,
|
||||||
|
"structure_score": 4.3,
|
||||||
|
"overall_score": 9.0
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"content": {
|
||||||
|
"correctness": 3,
|
||||||
|
"completeness": 2,
|
||||||
|
"accuracy": 3
|
||||||
|
},
|
||||||
|
"structure": {
|
||||||
|
"organization": 3,
|
||||||
|
"formatting": 2,
|
||||||
|
"usability": 3
|
||||||
|
},
|
||||||
|
"content_score": 2.7,
|
||||||
|
"structure_score": 2.7,
|
||||||
|
"overall_score": 5.4
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"output_quality": {
|
||||||
|
"A": {
|
||||||
|
"score": 9,
|
||||||
|
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||||
|
"weaknesses": ["Minor style inconsistency in header"]
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"score": 5,
|
||||||
|
"strengths": ["Readable output", "Correct basic structure"],
|
||||||
|
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"expectation_results": {
|
||||||
|
"A": {
|
||||||
|
"passed": 4,
|
||||||
|
"total": 5,
|
||||||
|
"pass_rate": 0.8,
|
||||||
|
"details": [{ "text": "Output includes name", "passed": true }]
|
||||||
|
},
|
||||||
|
"B": {
|
||||||
|
"passed": 3,
|
||||||
|
"total": 5,
|
||||||
|
"pass_rate": 0.6,
|
||||||
|
"details": [{ "text": "Output includes name", "passed": true }]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## analysis.json
|
||||||
|
|
||||||
|
Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"comparison_summary": {
|
||||||
|
"winner": "A",
|
||||||
|
"winner_skill": "path/to/winner/skill",
|
||||||
|
"loser_skill": "path/to/loser/skill",
|
||||||
|
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||||
|
},
|
||||||
|
"winner_strengths": [
|
||||||
|
"Clear step-by-step instructions for handling multi-page documents",
|
||||||
|
"Included validation script that caught formatting errors"
|
||||||
|
],
|
||||||
|
"loser_weaknesses": [
|
||||||
|
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||||
|
"No script for validation, agent had to improvise"
|
||||||
|
],
|
||||||
|
"instruction_following": {
|
||||||
|
"winner": {
|
||||||
|
"score": 9,
|
||||||
|
"issues": ["Minor: skipped optional logging step"]
|
||||||
|
},
|
||||||
|
"loser": {
|
||||||
|
"score": 6,
|
||||||
|
"issues": [
|
||||||
|
"Did not use the skill's formatting template",
|
||||||
|
"Invented own approach instead of following step 3"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"improvement_suggestions": [
|
||||||
|
{
|
||||||
|
"priority": "high",
|
||||||
|
"category": "instructions",
|
||||||
|
"suggestion": "Replace 'process the document appropriately' with explicit steps",
|
||||||
|
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"transcript_insights": {
|
||||||
|
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script",
|
||||||
|
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
0
.agents/skills/skill-creator/scripts/__init__.py
Normal file
0
.agents/skills/skill-creator/scripts/__init__.py
Normal file
401
.agents/skills/skill-creator/scripts/aggregate_benchmark.py
Normal file
401
.agents/skills/skill-creator/scripts/aggregate_benchmark.py
Normal file
@@ -0,0 +1,401 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Aggregate individual run results into benchmark summary statistics.
|
||||||
|
|
||||||
|
Reads grading.json files from run directories and produces:
|
||||||
|
- run_summary with mean, stddev, min, max for each metric
|
||||||
|
- delta between with_skill and without_skill configurations
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python aggregate_benchmark.py <benchmark_dir>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/
|
||||||
|
|
||||||
|
The script supports two directory layouts:
|
||||||
|
|
||||||
|
Workspace layout (from skill-creator iterations):
|
||||||
|
<benchmark_dir>/
|
||||||
|
└── eval-N/
|
||||||
|
├── with_skill/
|
||||||
|
│ ├── run-1/grading.json
|
||||||
|
│ └── run-2/grading.json
|
||||||
|
└── without_skill/
|
||||||
|
├── run-1/grading.json
|
||||||
|
└── run-2/grading.json
|
||||||
|
|
||||||
|
Legacy layout (with runs/ subdirectory):
|
||||||
|
<benchmark_dir>/
|
||||||
|
└── runs/
|
||||||
|
└── eval-N/
|
||||||
|
├── with_skill/
|
||||||
|
│ └── run-1/grading.json
|
||||||
|
└── without_skill/
|
||||||
|
└── run-1/grading.json
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import math
|
||||||
|
import sys
|
||||||
|
from datetime import datetime, timezone
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
|
||||||
|
def calculate_stats(values: list[float]) -> dict:
|
||||||
|
"""Calculate mean, stddev, min, max for a list of values."""
|
||||||
|
if not values:
|
||||||
|
return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}
|
||||||
|
|
||||||
|
n = len(values)
|
||||||
|
mean = sum(values) / n
|
||||||
|
|
||||||
|
if n > 1:
|
||||||
|
variance = sum((x - mean) ** 2 for x in values) / (n - 1)
|
||||||
|
stddev = math.sqrt(variance)
|
||||||
|
else:
|
||||||
|
stddev = 0.0
|
||||||
|
|
||||||
|
return {
|
||||||
|
"mean": round(mean, 4),
|
||||||
|
"stddev": round(stddev, 4),
|
||||||
|
"min": round(min(values), 4),
|
||||||
|
"max": round(max(values), 4)
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def load_run_results(benchmark_dir: Path) -> dict:
|
||||||
|
"""
|
||||||
|
Load all run results from a benchmark directory.
|
||||||
|
|
||||||
|
Returns dict keyed by config name (e.g. "with_skill"/"without_skill",
|
||||||
|
or "new_skill"/"old_skill"), each containing a list of run results.
|
||||||
|
"""
|
||||||
|
# Support both layouts: eval dirs directly under benchmark_dir, or under runs/
|
||||||
|
runs_dir = benchmark_dir / "runs"
|
||||||
|
if runs_dir.exists():
|
||||||
|
search_dir = runs_dir
|
||||||
|
elif list(benchmark_dir.glob("eval-*")):
|
||||||
|
search_dir = benchmark_dir
|
||||||
|
else:
|
||||||
|
print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
results: dict[str, list] = {}
|
||||||
|
|
||||||
|
for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))):
|
||||||
|
metadata_path = eval_dir / "eval_metadata.json"
|
||||||
|
if metadata_path.exists():
|
||||||
|
try:
|
||||||
|
with open(metadata_path) as mf:
|
||||||
|
eval_id = json.load(mf).get("eval_id", eval_idx)
|
||||||
|
except (json.JSONDecodeError, OSError):
|
||||||
|
eval_id = eval_idx
|
||||||
|
else:
|
||||||
|
try:
|
||||||
|
eval_id = int(eval_dir.name.split("-")[1])
|
||||||
|
except ValueError:
|
||||||
|
eval_id = eval_idx
|
||||||
|
|
||||||
|
# Discover config directories dynamically rather than hardcoding names
|
||||||
|
for config_dir in sorted(eval_dir.iterdir()):
|
||||||
|
if not config_dir.is_dir():
|
||||||
|
continue
|
||||||
|
# Skip non-config directories (inputs, outputs, etc.)
|
||||||
|
if not list(config_dir.glob("run-*")):
|
||||||
|
continue
|
||||||
|
config = config_dir.name
|
||||||
|
if config not in results:
|
||||||
|
results[config] = []
|
||||||
|
|
||||||
|
for run_dir in sorted(config_dir.glob("run-*")):
|
||||||
|
run_number = int(run_dir.name.split("-")[1])
|
||||||
|
grading_file = run_dir / "grading.json"
|
||||||
|
|
||||||
|
if not grading_file.exists():
|
||||||
|
print(f"Warning: grading.json not found in {run_dir}")
|
||||||
|
continue
|
||||||
|
|
||||||
|
try:
|
||||||
|
with open(grading_file) as f:
|
||||||
|
grading = json.load(f)
|
||||||
|
except json.JSONDecodeError as e:
|
||||||
|
print(f"Warning: Invalid JSON in {grading_file}: {e}")
|
||||||
|
continue
|
||||||
|
|
||||||
|
# Extract metrics
|
||||||
|
result = {
|
||||||
|
"eval_id": eval_id,
|
||||||
|
"run_number": run_number,
|
||||||
|
"pass_rate": grading.get("summary", {}).get("pass_rate", 0.0),
|
||||||
|
"passed": grading.get("summary", {}).get("passed", 0),
|
||||||
|
"failed": grading.get("summary", {}).get("failed", 0),
|
||||||
|
"total": grading.get("summary", {}).get("total", 0),
|
||||||
|
}
|
||||||
|
|
||||||
|
# Extract timing — check grading.json first, then sibling timing.json
|
||||||
|
timing = grading.get("timing", {})
|
||||||
|
result["time_seconds"] = timing.get("total_duration_seconds", 0.0)
|
||||||
|
timing_file = run_dir / "timing.json"
|
||||||
|
if result["time_seconds"] == 0.0 and timing_file.exists():
|
||||||
|
try:
|
||||||
|
with open(timing_file) as tf:
|
||||||
|
timing_data = json.load(tf)
|
||||||
|
result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0)
|
||||||
|
result["tokens"] = timing_data.get("total_tokens", 0)
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Extract metrics if available
|
||||||
|
metrics = grading.get("execution_metrics", {})
|
||||||
|
result["tool_calls"] = metrics.get("total_tool_calls", 0)
|
||||||
|
if not result.get("tokens"):
|
||||||
|
result["tokens"] = metrics.get("output_chars", 0)
|
||||||
|
result["errors"] = metrics.get("errors_encountered", 0)
|
||||||
|
|
||||||
|
# Extract expectations — viewer requires fields: text, passed, evidence
|
||||||
|
raw_expectations = grading.get("expectations", [])
|
||||||
|
for exp in raw_expectations:
|
||||||
|
if "text" not in exp or "passed" not in exp:
|
||||||
|
print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}")
|
||||||
|
result["expectations"] = raw_expectations
|
||||||
|
|
||||||
|
# Extract notes from user_notes_summary
|
||||||
|
notes_summary = grading.get("user_notes_summary", {})
|
||||||
|
notes = []
|
||||||
|
notes.extend(notes_summary.get("uncertainties", []))
|
||||||
|
notes.extend(notes_summary.get("needs_review", []))
|
||||||
|
notes.extend(notes_summary.get("workarounds", []))
|
||||||
|
result["notes"] = notes
|
||||||
|
|
||||||
|
results[config].append(result)
|
||||||
|
|
||||||
|
return results
|
||||||
|
|
||||||
|
|
||||||
|
def aggregate_results(results: dict) -> dict:
|
||||||
|
"""
|
||||||
|
Aggregate run results into summary statistics.
|
||||||
|
|
||||||
|
Returns run_summary with stats for each configuration and delta.
|
||||||
|
"""
|
||||||
|
run_summary = {}
|
||||||
|
configs = list(results.keys())
|
||||||
|
|
||||||
|
for config in configs:
|
||||||
|
runs = results.get(config, [])
|
||||||
|
|
||||||
|
if not runs:
|
||||||
|
run_summary[config] = {
|
||||||
|
"pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||||
|
"time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||||
|
"tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0}
|
||||||
|
}
|
||||||
|
continue
|
||||||
|
|
||||||
|
pass_rates = [r["pass_rate"] for r in runs]
|
||||||
|
times = [r["time_seconds"] for r in runs]
|
||||||
|
tokens = [r.get("tokens", 0) for r in runs]
|
||||||
|
|
||||||
|
run_summary[config] = {
|
||||||
|
"pass_rate": calculate_stats(pass_rates),
|
||||||
|
"time_seconds": calculate_stats(times),
|
||||||
|
"tokens": calculate_stats(tokens)
|
||||||
|
}
|
||||||
|
|
||||||
|
# Calculate delta between the first two configs (if two exist)
|
||||||
|
if len(configs) >= 2:
|
||||||
|
primary = run_summary.get(configs[0], {})
|
||||||
|
baseline = run_summary.get(configs[1], {})
|
||||||
|
else:
|
||||||
|
primary = run_summary.get(configs[0], {}) if configs else {}
|
||||||
|
baseline = {}
|
||||||
|
|
||||||
|
delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0)
|
||||||
|
delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0)
|
||||||
|
delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0)
|
||||||
|
|
||||||
|
run_summary["delta"] = {
|
||||||
|
"pass_rate": f"{delta_pass_rate:+.2f}",
|
||||||
|
"time_seconds": f"{delta_time:+.1f}",
|
||||||
|
"tokens": f"{delta_tokens:+.0f}"
|
||||||
|
}
|
||||||
|
|
||||||
|
return run_summary
|
||||||
|
|
||||||
|
|
||||||
|
def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict:
|
||||||
|
"""
|
||||||
|
Generate complete benchmark.json from run results.
|
||||||
|
"""
|
||||||
|
results = load_run_results(benchmark_dir)
|
||||||
|
run_summary = aggregate_results(results)
|
||||||
|
|
||||||
|
# Build runs array for benchmark.json
|
||||||
|
runs = []
|
||||||
|
for config in results:
|
||||||
|
for result in results[config]:
|
||||||
|
runs.append({
|
||||||
|
"eval_id": result["eval_id"],
|
||||||
|
"configuration": config,
|
||||||
|
"run_number": result["run_number"],
|
||||||
|
"result": {
|
||||||
|
"pass_rate": result["pass_rate"],
|
||||||
|
"passed": result["passed"],
|
||||||
|
"failed": result["failed"],
|
||||||
|
"total": result["total"],
|
||||||
|
"time_seconds": result["time_seconds"],
|
||||||
|
"tokens": result.get("tokens", 0),
|
||||||
|
"tool_calls": result.get("tool_calls", 0),
|
||||||
|
"errors": result.get("errors", 0)
|
||||||
|
},
|
||||||
|
"expectations": result["expectations"],
|
||||||
|
"notes": result["notes"]
|
||||||
|
})
|
||||||
|
|
||||||
|
# Determine eval IDs from results
|
||||||
|
eval_ids = sorted(set(
|
||||||
|
r["eval_id"]
|
||||||
|
for config in results.values()
|
||||||
|
for r in config
|
||||||
|
))
|
||||||
|
|
||||||
|
benchmark = {
|
||||||
|
"metadata": {
|
||||||
|
"skill_name": skill_name or "<skill-name>",
|
||||||
|
"skill_path": skill_path or "<path/to/skill>",
|
||||||
|
"executor_model": "<model-name>",
|
||||||
|
"analyzer_model": "<model-name>",
|
||||||
|
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
|
||||||
|
"evals_run": eval_ids,
|
||||||
|
"runs_per_configuration": 3
|
||||||
|
},
|
||||||
|
"runs": runs,
|
||||||
|
"run_summary": run_summary,
|
||||||
|
"notes": [] # To be filled by analyzer
|
||||||
|
}
|
||||||
|
|
||||||
|
return benchmark
|
||||||
|
|
||||||
|
|
||||||
|
def generate_markdown(benchmark: dict) -> str:
|
||||||
|
"""Generate human-readable benchmark.md from benchmark data."""
|
||||||
|
metadata = benchmark["metadata"]
|
||||||
|
run_summary = benchmark["run_summary"]
|
||||||
|
|
||||||
|
# Determine config names (excluding "delta")
|
||||||
|
configs = [k for k in run_summary if k != "delta"]
|
||||||
|
config_a = configs[0] if len(configs) >= 1 else "config_a"
|
||||||
|
config_b = configs[1] if len(configs) >= 2 else "config_b"
|
||||||
|
label_a = config_a.replace("_", " ").title()
|
||||||
|
label_b = config_b.replace("_", " ").title()
|
||||||
|
|
||||||
|
lines = [
|
||||||
|
f"# Skill Benchmark: {metadata['skill_name']}",
|
||||||
|
"",
|
||||||
|
f"**Model**: {metadata['executor_model']}",
|
||||||
|
f"**Date**: {metadata['timestamp']}",
|
||||||
|
f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)",
|
||||||
|
"",
|
||||||
|
"## Summary",
|
||||||
|
"",
|
||||||
|
f"| Metric | {label_a} | {label_b} | Delta |",
|
||||||
|
"|--------|------------|---------------|-------|",
|
||||||
|
]
|
||||||
|
|
||||||
|
a_summary = run_summary.get(config_a, {})
|
||||||
|
b_summary = run_summary.get(config_b, {})
|
||||||
|
delta = run_summary.get("delta", {})
|
||||||
|
|
||||||
|
# Format pass rate
|
||||||
|
a_pr = a_summary.get("pass_rate", {})
|
||||||
|
b_pr = b_summary.get("pass_rate", {})
|
||||||
|
lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |")
|
||||||
|
|
||||||
|
# Format time
|
||||||
|
a_time = a_summary.get("time_seconds", {})
|
||||||
|
b_time = b_summary.get("time_seconds", {})
|
||||||
|
lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |")
|
||||||
|
|
||||||
|
# Format tokens
|
||||||
|
a_tokens = a_summary.get("tokens", {})
|
||||||
|
b_tokens = b_summary.get("tokens", {})
|
||||||
|
lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |")
|
||||||
|
|
||||||
|
# Notes section
|
||||||
|
if benchmark.get("notes"):
|
||||||
|
lines.extend([
|
||||||
|
"",
|
||||||
|
"## Notes",
|
||||||
|
""
|
||||||
|
])
|
||||||
|
for note in benchmark["notes"]:
|
||||||
|
lines.append(f"- {note}")
|
||||||
|
|
||||||
|
return "\n".join(lines)
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(
|
||||||
|
description="Aggregate benchmark run results into summary statistics"
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"benchmark_dir",
|
||||||
|
type=Path,
|
||||||
|
help="Path to the benchmark directory"
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--skill-name",
|
||||||
|
default="",
|
||||||
|
help="Name of the skill being benchmarked"
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--skill-path",
|
||||||
|
default="",
|
||||||
|
help="Path to the skill being benchmarked"
|
||||||
|
)
|
||||||
|
parser.add_argument(
|
||||||
|
"--output", "-o",
|
||||||
|
type=Path,
|
||||||
|
help="Output path for benchmark.json (default: <benchmark_dir>/benchmark.json)"
|
||||||
|
)
|
||||||
|
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
if not args.benchmark_dir.exists():
|
||||||
|
print(f"Directory not found: {args.benchmark_dir}")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
# Generate benchmark
|
||||||
|
benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path)
|
||||||
|
|
||||||
|
# Determine output paths
|
||||||
|
output_json = args.output or (args.benchmark_dir / "benchmark.json")
|
||||||
|
output_md = output_json.with_suffix(".md")
|
||||||
|
|
||||||
|
# Write benchmark.json
|
||||||
|
with open(output_json, "w") as f:
|
||||||
|
json.dump(benchmark, f, indent=2)
|
||||||
|
print(f"Generated: {output_json}")
|
||||||
|
|
||||||
|
# Write benchmark.md
|
||||||
|
markdown = generate_markdown(benchmark)
|
||||||
|
with open(output_md, "w") as f:
|
||||||
|
f.write(markdown)
|
||||||
|
print(f"Generated: {output_md}")
|
||||||
|
|
||||||
|
# Print summary
|
||||||
|
run_summary = benchmark["run_summary"]
|
||||||
|
configs = [k for k in run_summary if k != "delta"]
|
||||||
|
delta = run_summary.get("delta", {})
|
||||||
|
|
||||||
|
print(f"\nSummary:")
|
||||||
|
for config in configs:
|
||||||
|
pr = run_summary[config]["pass_rate"]["mean"]
|
||||||
|
label = config.replace("_", " ").title()
|
||||||
|
print(f" {label}: {pr*100:.1f}% pass rate")
|
||||||
|
print(f" Delta: {delta.get('pass_rate', '—')}")
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
326
.agents/skills/skill-creator/scripts/generate_report.py
Normal file
326
.agents/skills/skill-creator/scripts/generate_report.py
Normal file
@@ -0,0 +1,326 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Generate an HTML report from run_loop.py output.
|
||||||
|
|
||||||
|
Takes the JSON output from run_loop.py and generates a visual HTML report
|
||||||
|
showing each description attempt with check/x for each test case.
|
||||||
|
Distinguishes between train and test queries.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import html
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
|
||||||
|
def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str:
|
||||||
|
"""Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag."""
|
||||||
|
history = data.get("history", [])
|
||||||
|
holdout = data.get("holdout", 0)
|
||||||
|
title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else ""
|
||||||
|
|
||||||
|
# Get all unique queries from train and test sets, with should_trigger info
|
||||||
|
train_queries: list[dict] = []
|
||||||
|
test_queries: list[dict] = []
|
||||||
|
if history:
|
||||||
|
for r in history[0].get("train_results", history[0].get("results", [])):
|
||||||
|
train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||||
|
if history[0].get("test_results"):
|
||||||
|
for r in history[0].get("test_results", []):
|
||||||
|
test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||||
|
|
||||||
|
refresh_tag = ' <meta http-equiv="refresh" content="5">\n' if auto_refresh else ""
|
||||||
|
|
||||||
|
html_parts = ["""<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
""" + refresh_tag + """ <title>""" + title_prefix + """Skill Description Optimization</title>
|
||||||
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||||
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||||
|
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||||
|
<style>
|
||||||
|
body {
|
||||||
|
font-family: 'Lora', Georgia, serif;
|
||||||
|
max-width: 100%;
|
||||||
|
margin: 0 auto;
|
||||||
|
padding: 20px;
|
||||||
|
background: #faf9f5;
|
||||||
|
color: #141413;
|
||||||
|
}
|
||||||
|
h1 { font-family: 'Poppins', sans-serif; color: #141413; }
|
||||||
|
.explainer {
|
||||||
|
background: white;
|
||||||
|
padding: 15px;
|
||||||
|
border-radius: 6px;
|
||||||
|
margin-bottom: 20px;
|
||||||
|
border: 1px solid #e8e6dc;
|
||||||
|
color: #b0aea5;
|
||||||
|
font-size: 0.875rem;
|
||||||
|
line-height: 1.6;
|
||||||
|
}
|
||||||
|
.summary {
|
||||||
|
background: white;
|
||||||
|
padding: 15px;
|
||||||
|
border-radius: 6px;
|
||||||
|
margin-bottom: 20px;
|
||||||
|
border: 1px solid #e8e6dc;
|
||||||
|
}
|
||||||
|
.summary p { margin: 5px 0; }
|
||||||
|
.best { color: #788c5d; font-weight: bold; }
|
||||||
|
.table-container {
|
||||||
|
overflow-x: auto;
|
||||||
|
width: 100%;
|
||||||
|
}
|
||||||
|
table {
|
||||||
|
border-collapse: collapse;
|
||||||
|
background: white;
|
||||||
|
border: 1px solid #e8e6dc;
|
||||||
|
border-radius: 6px;
|
||||||
|
font-size: 12px;
|
||||||
|
min-width: 100%;
|
||||||
|
}
|
||||||
|
th, td {
|
||||||
|
padding: 8px;
|
||||||
|
text-align: left;
|
||||||
|
border: 1px solid #e8e6dc;
|
||||||
|
white-space: normal;
|
||||||
|
word-wrap: break-word;
|
||||||
|
}
|
||||||
|
th {
|
||||||
|
font-family: 'Poppins', sans-serif;
|
||||||
|
background: #141413;
|
||||||
|
color: #faf9f5;
|
||||||
|
font-weight: 500;
|
||||||
|
}
|
||||||
|
th.test-col {
|
||||||
|
background: #6a9bcc;
|
||||||
|
}
|
||||||
|
th.query-col { min-width: 200px; }
|
||||||
|
td.description {
|
||||||
|
font-family: monospace;
|
||||||
|
font-size: 11px;
|
||||||
|
word-wrap: break-word;
|
||||||
|
max-width: 400px;
|
||||||
|
}
|
||||||
|
td.result {
|
||||||
|
text-align: center;
|
||||||
|
font-size: 16px;
|
||||||
|
min-width: 40px;
|
||||||
|
}
|
||||||
|
td.test-result {
|
||||||
|
background: #f0f6fc;
|
||||||
|
}
|
||||||
|
.pass { color: #788c5d; }
|
||||||
|
.fail { color: #c44; }
|
||||||
|
.rate {
|
||||||
|
font-size: 9px;
|
||||||
|
color: #b0aea5;
|
||||||
|
display: block;
|
||||||
|
}
|
||||||
|
tr:hover { background: #faf9f5; }
|
||||||
|
.score {
|
||||||
|
display: inline-block;
|
||||||
|
padding: 2px 6px;
|
||||||
|
border-radius: 4px;
|
||||||
|
font-weight: bold;
|
||||||
|
font-size: 11px;
|
||||||
|
}
|
||||||
|
.score-good { background: #eef2e8; color: #788c5d; }
|
||||||
|
.score-ok { background: #fef3c7; color: #d97706; }
|
||||||
|
.score-bad { background: #fceaea; color: #c44; }
|
||||||
|
.train-label { color: #b0aea5; font-size: 10px; }
|
||||||
|
.test-label { color: #6a9bcc; font-size: 10px; font-weight: bold; }
|
||||||
|
.best-row { background: #f5f8f2; }
|
||||||
|
th.positive-col { border-bottom: 3px solid #788c5d; }
|
||||||
|
th.negative-col { border-bottom: 3px solid #c44; }
|
||||||
|
th.test-col.positive-col { border-bottom: 3px solid #788c5d; }
|
||||||
|
th.test-col.negative-col { border-bottom: 3px solid #c44; }
|
||||||
|
.legend { font-family: 'Poppins', sans-serif; display: flex; gap: 20px; margin-bottom: 10px; font-size: 13px; align-items: center; }
|
||||||
|
.legend-item { display: flex; align-items: center; gap: 6px; }
|
||||||
|
.legend-swatch { width: 16px; height: 16px; border-radius: 3px; display: inline-block; }
|
||||||
|
.swatch-positive { background: #141413; border-bottom: 3px solid #788c5d; }
|
||||||
|
.swatch-negative { background: #141413; border-bottom: 3px solid #c44; }
|
||||||
|
.swatch-test { background: #6a9bcc; }
|
||||||
|
.swatch-train { background: #141413; }
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<h1>""" + title_prefix + """Skill Description Optimization</h1>
|
||||||
|
<div class="explainer">
|
||||||
|
<strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
|
||||||
|
</div>
|
||||||
|
"""]
|
||||||
|
|
||||||
|
# Summary section
|
||||||
|
best_test_score = data.get('best_test_score')
|
||||||
|
best_train_score = data.get('best_train_score')
|
||||||
|
html_parts.append(f"""
|
||||||
|
<div class="summary">
|
||||||
|
<p><strong>Original:</strong> {html.escape(data.get('original_description', 'N/A'))}</p>
|
||||||
|
<p class="best"><strong>Best:</strong> {html.escape(data.get('best_description', 'N/A'))}</p>
|
||||||
|
<p><strong>Best Score:</strong> {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}</p>
|
||||||
|
<p><strong>Iterations:</strong> {data.get('iterations_run', 0)} | <strong>Train:</strong> {data.get('train_size', '?')} | <strong>Test:</strong> {data.get('test_size', '?')}</p>
|
||||||
|
</div>
|
||||||
|
""")
|
||||||
|
|
||||||
|
# Legend
|
||||||
|
html_parts.append("""
|
||||||
|
<div class="legend">
|
||||||
|
<span style="font-weight:600">Query columns:</span>
|
||||||
|
<span class="legend-item"><span class="legend-swatch swatch-positive"></span> Should trigger</span>
|
||||||
|
<span class="legend-item"><span class="legend-swatch swatch-negative"></span> Should NOT trigger</span>
|
||||||
|
<span class="legend-item"><span class="legend-swatch swatch-train"></span> Train</span>
|
||||||
|
<span class="legend-item"><span class="legend-swatch swatch-test"></span> Test</span>
|
||||||
|
</div>
|
||||||
|
""")
|
||||||
|
|
||||||
|
# Table header
|
||||||
|
html_parts.append("""
|
||||||
|
<div class="table-container">
|
||||||
|
<table>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th>Iter</th>
|
||||||
|
<th>Train</th>
|
||||||
|
<th>Test</th>
|
||||||
|
<th class="query-col">Description</th>
|
||||||
|
""")
|
||||||
|
|
||||||
|
# Add column headers for train queries
|
||||||
|
for qinfo in train_queries:
|
||||||
|
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||||
|
html_parts.append(f' <th class="{polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||||
|
|
||||||
|
# Add column headers for test queries (different color)
|
||||||
|
for qinfo in test_queries:
|
||||||
|
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||||
|
html_parts.append(f' <th class="test-col {polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||||
|
|
||||||
|
html_parts.append(""" </tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
""")
|
||||||
|
|
||||||
|
# Find best iteration for highlighting
|
||||||
|
if test_queries:
|
||||||
|
best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration")
|
||||||
|
else:
|
||||||
|
best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration")
|
||||||
|
|
||||||
|
# Add rows for each iteration
|
||||||
|
for h in history:
|
||||||
|
iteration = h.get("iteration", "?")
|
||||||
|
train_passed = h.get("train_passed", h.get("passed", 0))
|
||||||
|
train_total = h.get("train_total", h.get("total", 0))
|
||||||
|
test_passed = h.get("test_passed")
|
||||||
|
test_total = h.get("test_total")
|
||||||
|
description = h.get("description", "")
|
||||||
|
train_results = h.get("train_results", h.get("results", []))
|
||||||
|
test_results = h.get("test_results", [])
|
||||||
|
|
||||||
|
# Create lookups for results by query
|
||||||
|
train_by_query = {r["query"]: r for r in train_results}
|
||||||
|
test_by_query = {r["query"]: r for r in test_results} if test_results else {}
|
||||||
|
|
||||||
|
# Compute aggregate correct/total runs across all retries
|
||||||
|
def aggregate_runs(results: list[dict]) -> tuple[int, int]:
|
||||||
|
correct = 0
|
||||||
|
total = 0
|
||||||
|
for r in results:
|
||||||
|
runs = r.get("runs", 0)
|
||||||
|
triggers = r.get("triggers", 0)
|
||||||
|
total += runs
|
||||||
|
if r.get("should_trigger", True):
|
||||||
|
correct += triggers
|
||||||
|
else:
|
||||||
|
correct += runs - triggers
|
||||||
|
return correct, total
|
||||||
|
|
||||||
|
train_correct, train_runs = aggregate_runs(train_results)
|
||||||
|
test_correct, test_runs = aggregate_runs(test_results)
|
||||||
|
|
||||||
|
# Determine score classes
|
||||||
|
def score_class(correct: int, total: int) -> str:
|
||||||
|
if total > 0:
|
||||||
|
ratio = correct / total
|
||||||
|
if ratio >= 0.8:
|
||||||
|
return "score-good"
|
||||||
|
elif ratio >= 0.5:
|
||||||
|
return "score-ok"
|
||||||
|
return "score-bad"
|
||||||
|
|
||||||
|
train_class = score_class(train_correct, train_runs)
|
||||||
|
test_class = score_class(test_correct, test_runs)
|
||||||
|
|
||||||
|
row_class = "best-row" if iteration == best_iter else ""
|
||||||
|
|
||||||
|
html_parts.append(f""" <tr class="{row_class}">
|
||||||
|
<td>{iteration}</td>
|
||||||
|
<td><span class="score {train_class}">{train_correct}/{train_runs}</span></td>
|
||||||
|
<td><span class="score {test_class}">{test_correct}/{test_runs}</span></td>
|
||||||
|
<td class="description">{html.escape(description)}</td>
|
||||||
|
""")
|
||||||
|
|
||||||
|
# Add result for each train query
|
||||||
|
for qinfo in train_queries:
|
||||||
|
r = train_by_query.get(qinfo["query"], {})
|
||||||
|
did_pass = r.get("pass", False)
|
||||||
|
triggers = r.get("triggers", 0)
|
||||||
|
runs = r.get("runs", 0)
|
||||||
|
|
||||||
|
icon = "✓" if did_pass else "✗"
|
||||||
|
css_class = "pass" if did_pass else "fail"
|
||||||
|
|
||||||
|
html_parts.append(f' <td class="result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||||
|
|
||||||
|
# Add result for each test query (with different background)
|
||||||
|
for qinfo in test_queries:
|
||||||
|
r = test_by_query.get(qinfo["query"], {})
|
||||||
|
did_pass = r.get("pass", False)
|
||||||
|
triggers = r.get("triggers", 0)
|
||||||
|
runs = r.get("runs", 0)
|
||||||
|
|
||||||
|
icon = "✓" if did_pass else "✗"
|
||||||
|
css_class = "pass" if did_pass else "fail"
|
||||||
|
|
||||||
|
html_parts.append(f' <td class="result test-result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||||
|
|
||||||
|
html_parts.append(" </tr>\n")
|
||||||
|
|
||||||
|
html_parts.append(""" </tbody>
|
||||||
|
</table>
|
||||||
|
</div>
|
||||||
|
""")
|
||||||
|
|
||||||
|
html_parts.append("""
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
""")
|
||||||
|
|
||||||
|
return "".join(html_parts)
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output")
|
||||||
|
parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)")
|
||||||
|
parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)")
|
||||||
|
parser.add_argument("--skill-name", default="", help="Skill name to include in the report title")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
if args.input == "-":
|
||||||
|
data = json.load(sys.stdin)
|
||||||
|
else:
|
||||||
|
data = json.loads(Path(args.input).read_text())
|
||||||
|
|
||||||
|
html_output = generate_html(data, skill_name=args.skill_name)
|
||||||
|
|
||||||
|
if args.output:
|
||||||
|
Path(args.output).write_text(html_output)
|
||||||
|
print(f"Report written to {args.output}", file=sys.stderr)
|
||||||
|
else:
|
||||||
|
print(html_output)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
247
.agents/skills/skill-creator/scripts/improve_description.py
Normal file
247
.agents/skills/skill-creator/scripts/improve_description.py
Normal file
@@ -0,0 +1,247 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Improve a skill description based on eval results.
|
||||||
|
|
||||||
|
Takes eval results (from run_eval.py) and generates an improved description
|
||||||
|
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
|
||||||
|
uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from scripts.utils import parse_skill_md
|
||||||
|
|
||||||
|
|
||||||
|
def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
|
||||||
|
"""Run `claude -p` with the prompt on stdin and return the text response.
|
||||||
|
|
||||||
|
Prompt goes over stdin (not argv) because it embeds the full SKILL.md
|
||||||
|
body and can easily exceed comfortable argv length.
|
||||||
|
"""
|
||||||
|
cmd = ["claude", "-p", "--output-format", "text"]
|
||||||
|
if model:
|
||||||
|
cmd.extend(["--model", model])
|
||||||
|
|
||||||
|
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||||
|
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||||
|
# programmatic subprocess usage is safe. Same pattern as run_eval.py.
|
||||||
|
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||||
|
|
||||||
|
result = subprocess.run(
|
||||||
|
cmd,
|
||||||
|
input=prompt,
|
||||||
|
capture_output=True,
|
||||||
|
text=True,
|
||||||
|
env=env,
|
||||||
|
timeout=timeout,
|
||||||
|
)
|
||||||
|
if result.returncode != 0:
|
||||||
|
raise RuntimeError(
|
||||||
|
f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
|
||||||
|
)
|
||||||
|
return result.stdout
|
||||||
|
|
||||||
|
|
||||||
|
def improve_description(
|
||||||
|
skill_name: str,
|
||||||
|
skill_content: str,
|
||||||
|
current_description: str,
|
||||||
|
eval_results: dict,
|
||||||
|
history: list[dict],
|
||||||
|
model: str,
|
||||||
|
test_results: dict | None = None,
|
||||||
|
log_dir: Path | None = None,
|
||||||
|
iteration: int | None = None,
|
||||||
|
) -> str:
|
||||||
|
"""Call Claude to improve the description based on eval results."""
|
||||||
|
failed_triggers = [
|
||||||
|
r for r in eval_results["results"]
|
||||||
|
if r["should_trigger"] and not r["pass"]
|
||||||
|
]
|
||||||
|
false_triggers = [
|
||||||
|
r for r in eval_results["results"]
|
||||||
|
if not r["should_trigger"] and not r["pass"]
|
||||||
|
]
|
||||||
|
|
||||||
|
# Build scores summary
|
||||||
|
train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
|
||||||
|
if test_results:
|
||||||
|
test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
|
||||||
|
scores_summary = f"Train: {train_score}, Test: {test_score}"
|
||||||
|
else:
|
||||||
|
scores_summary = f"Train: {train_score}"
|
||||||
|
|
||||||
|
prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
|
||||||
|
|
||||||
|
The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
|
||||||
|
|
||||||
|
Here's the current description:
|
||||||
|
<current_description>
|
||||||
|
"{current_description}"
|
||||||
|
</current_description>
|
||||||
|
|
||||||
|
Current scores ({scores_summary}):
|
||||||
|
<scores_summary>
|
||||||
|
"""
|
||||||
|
if failed_triggers:
|
||||||
|
prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n"
|
||||||
|
for r in failed_triggers:
|
||||||
|
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||||
|
prompt += "\n"
|
||||||
|
|
||||||
|
if false_triggers:
|
||||||
|
prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n"
|
||||||
|
for r in false_triggers:
|
||||||
|
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||||
|
prompt += "\n"
|
||||||
|
|
||||||
|
if history:
|
||||||
|
prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n"
|
||||||
|
for h in history:
|
||||||
|
train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}"
|
||||||
|
test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None
|
||||||
|
score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "")
|
||||||
|
prompt += f'<attempt {score_str}>\n'
|
||||||
|
prompt += f'Description: "{h["description"]}"\n'
|
||||||
|
if "results" in h:
|
||||||
|
prompt += "Train results:\n"
|
||||||
|
for r in h["results"]:
|
||||||
|
status = "PASS" if r["pass"] else "FAIL"
|
||||||
|
prompt += f' [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n'
|
||||||
|
if h.get("note"):
|
||||||
|
prompt += f'Note: {h["note"]}\n'
|
||||||
|
prompt += "</attempt>\n\n"
|
||||||
|
|
||||||
|
prompt += f"""</scores_summary>
|
||||||
|
|
||||||
|
Skill content (for context on what the skill does):
|
||||||
|
<skill_content>
|
||||||
|
{skill_content}
|
||||||
|
</skill_content>
|
||||||
|
|
||||||
|
Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:
|
||||||
|
|
||||||
|
1. Avoid overfitting
|
||||||
|
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
|
||||||
|
|
||||||
|
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
|
||||||
|
|
||||||
|
Here are some tips that we've found to work well in writing these descriptions:
|
||||||
|
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
|
||||||
|
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
|
||||||
|
- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
|
||||||
|
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
|
||||||
|
|
||||||
|
I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.
|
||||||
|
|
||||||
|
Please respond with only the new description text in <new_description> tags, nothing else."""
|
||||||
|
|
||||||
|
text = _call_claude(prompt, model)
|
||||||
|
|
||||||
|
match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
|
||||||
|
description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
|
||||||
|
|
||||||
|
transcript: dict = {
|
||||||
|
"iteration": iteration,
|
||||||
|
"prompt": prompt,
|
||||||
|
"response": text,
|
||||||
|
"parsed_description": description,
|
||||||
|
"char_count": len(description),
|
||||||
|
"over_limit": len(description) > 1024,
|
||||||
|
}
|
||||||
|
|
||||||
|
# Safety net: the prompt already states the 1024-char hard limit, but if
|
||||||
|
# the model blew past it anyway, make one fresh single-turn call that
|
||||||
|
# quotes the too-long version and asks for a shorter rewrite. (The old
|
||||||
|
# SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
|
||||||
|
# inline the prior output into the new prompt instead.)
|
||||||
|
if len(description) > 1024:
|
||||||
|
shorten_prompt = (
|
||||||
|
f"{prompt}\n\n"
|
||||||
|
f"---\n\n"
|
||||||
|
f"A previous attempt produced this description, which at "
|
||||||
|
f"{len(description)} characters is over the 1024-character hard limit:\n\n"
|
||||||
|
f'"{description}"\n\n'
|
||||||
|
f"Rewrite it to be under 1024 characters while keeping the most "
|
||||||
|
f"important trigger words and intent coverage. Respond with only "
|
||||||
|
f"the new description in <new_description> tags."
|
||||||
|
)
|
||||||
|
shorten_text = _call_claude(shorten_prompt, model)
|
||||||
|
match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
|
||||||
|
shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
|
||||||
|
|
||||||
|
transcript["rewrite_prompt"] = shorten_prompt
|
||||||
|
transcript["rewrite_response"] = shorten_text
|
||||||
|
transcript["rewrite_description"] = shortened
|
||||||
|
transcript["rewrite_char_count"] = len(shortened)
|
||||||
|
description = shortened
|
||||||
|
|
||||||
|
transcript["final_description"] = description
|
||||||
|
|
||||||
|
if log_dir:
|
||||||
|
log_dir.mkdir(parents=True, exist_ok=True)
|
||||||
|
log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json"
|
||||||
|
log_file.write_text(json.dumps(transcript, indent=2))
|
||||||
|
|
||||||
|
return description
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Improve a skill description based on eval results")
|
||||||
|
parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)")
|
||||||
|
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||||
|
parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)")
|
||||||
|
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||||
|
parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
skill_path = Path(args.skill_path)
|
||||||
|
if not (skill_path / "SKILL.md").exists():
|
||||||
|
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
eval_results = json.loads(Path(args.eval_results).read_text())
|
||||||
|
history = []
|
||||||
|
if args.history:
|
||||||
|
history = json.loads(Path(args.history).read_text())
|
||||||
|
|
||||||
|
name, _, content = parse_skill_md(skill_path)
|
||||||
|
current_description = eval_results["description"]
|
||||||
|
|
||||||
|
if args.verbose:
|
||||||
|
print(f"Current: {current_description}", file=sys.stderr)
|
||||||
|
print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)
|
||||||
|
|
||||||
|
new_description = improve_description(
|
||||||
|
skill_name=name,
|
||||||
|
skill_content=content,
|
||||||
|
current_description=current_description,
|
||||||
|
eval_results=eval_results,
|
||||||
|
history=history,
|
||||||
|
model=args.model,
|
||||||
|
)
|
||||||
|
|
||||||
|
if args.verbose:
|
||||||
|
print(f"Improved: {new_description}", file=sys.stderr)
|
||||||
|
|
||||||
|
# Output as JSON with both the new description and updated history
|
||||||
|
output = {
|
||||||
|
"description": new_description,
|
||||||
|
"history": history + [{
|
||||||
|
"description": current_description,
|
||||||
|
"passed": eval_results["summary"]["passed"],
|
||||||
|
"failed": eval_results["summary"]["failed"],
|
||||||
|
"total": eval_results["summary"]["total"],
|
||||||
|
"results": eval_results["results"],
|
||||||
|
}],
|
||||||
|
}
|
||||||
|
print(json.dumps(output, indent=2))
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
136
.agents/skills/skill-creator/scripts/package_skill.py
Normal file
136
.agents/skills/skill-creator/scripts/package_skill.py
Normal file
@@ -0,0 +1,136 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Skill Packager - Creates a distributable .skill file of a skill folder
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python utils/package_skill.py <path/to/skill-folder> [output-directory]
|
||||||
|
|
||||||
|
Example:
|
||||||
|
python utils/package_skill.py skills/public/my-skill
|
||||||
|
python utils/package_skill.py skills/public/my-skill ./dist
|
||||||
|
"""
|
||||||
|
|
||||||
|
import fnmatch
|
||||||
|
import sys
|
||||||
|
import zipfile
|
||||||
|
from pathlib import Path
|
||||||
|
from scripts.quick_validate import validate_skill
|
||||||
|
|
||||||
|
# Patterns to exclude when packaging skills.
|
||||||
|
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
|
||||||
|
EXCLUDE_GLOBS = {"*.pyc"}
|
||||||
|
EXCLUDE_FILES = {".DS_Store"}
|
||||||
|
# Directories excluded only at the skill root (not when nested deeper).
|
||||||
|
ROOT_EXCLUDE_DIRS = {"evals"}
|
||||||
|
|
||||||
|
|
||||||
|
def should_exclude(rel_path: Path) -> bool:
|
||||||
|
"""Check if a path should be excluded from packaging."""
|
||||||
|
parts = rel_path.parts
|
||||||
|
if any(part in EXCLUDE_DIRS for part in parts):
|
||||||
|
return True
|
||||||
|
# rel_path is relative to skill_path.parent, so parts[0] is the skill
|
||||||
|
# folder name and parts[1] (if present) is the first subdir.
|
||||||
|
if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
|
||||||
|
return True
|
||||||
|
name = rel_path.name
|
||||||
|
if name in EXCLUDE_FILES:
|
||||||
|
return True
|
||||||
|
return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
|
||||||
|
|
||||||
|
|
||||||
|
def package_skill(skill_path, output_dir=None):
|
||||||
|
"""
|
||||||
|
Package a skill folder into a .skill file.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
skill_path: Path to the skill folder
|
||||||
|
output_dir: Optional output directory for the .skill file (defaults to current directory)
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
Path to the created .skill file, or None if error
|
||||||
|
"""
|
||||||
|
skill_path = Path(skill_path).resolve()
|
||||||
|
|
||||||
|
# Validate skill folder exists
|
||||||
|
if not skill_path.exists():
|
||||||
|
print(f"❌ Error: Skill folder not found: {skill_path}")
|
||||||
|
return None
|
||||||
|
|
||||||
|
if not skill_path.is_dir():
|
||||||
|
print(f"❌ Error: Path is not a directory: {skill_path}")
|
||||||
|
return None
|
||||||
|
|
||||||
|
# Validate SKILL.md exists
|
||||||
|
skill_md = skill_path / "SKILL.md"
|
||||||
|
if not skill_md.exists():
|
||||||
|
print(f"❌ Error: SKILL.md not found in {skill_path}")
|
||||||
|
return None
|
||||||
|
|
||||||
|
# Run validation before packaging
|
||||||
|
print("🔍 Validating skill...")
|
||||||
|
valid, message = validate_skill(skill_path)
|
||||||
|
if not valid:
|
||||||
|
print(f"❌ Validation failed: {message}")
|
||||||
|
print(" Please fix the validation errors before packaging.")
|
||||||
|
return None
|
||||||
|
print(f"✅ {message}\n")
|
||||||
|
|
||||||
|
# Determine output location
|
||||||
|
skill_name = skill_path.name
|
||||||
|
if output_dir:
|
||||||
|
output_path = Path(output_dir).resolve()
|
||||||
|
output_path.mkdir(parents=True, exist_ok=True)
|
||||||
|
else:
|
||||||
|
output_path = Path.cwd()
|
||||||
|
|
||||||
|
skill_filename = output_path / f"{skill_name}.skill"
|
||||||
|
|
||||||
|
# Create the .skill file (zip format)
|
||||||
|
try:
|
||||||
|
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||||
|
# Walk through the skill directory, excluding build artifacts
|
||||||
|
for file_path in skill_path.rglob('*'):
|
||||||
|
if not file_path.is_file():
|
||||||
|
continue
|
||||||
|
arcname = file_path.relative_to(skill_path.parent)
|
||||||
|
if should_exclude(arcname):
|
||||||
|
print(f" Skipped: {arcname}")
|
||||||
|
continue
|
||||||
|
zipf.write(file_path, arcname)
|
||||||
|
print(f" Added: {arcname}")
|
||||||
|
|
||||||
|
print(f"\n✅ Successfully packaged skill to: {skill_filename}")
|
||||||
|
return skill_filename
|
||||||
|
|
||||||
|
except Exception as e:
|
||||||
|
print(f"❌ Error creating .skill file: {e}")
|
||||||
|
return None
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
if len(sys.argv) < 2:
|
||||||
|
print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
|
||||||
|
print("\nExample:")
|
||||||
|
print(" python utils/package_skill.py skills/public/my-skill")
|
||||||
|
print(" python utils/package_skill.py skills/public/my-skill ./dist")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
skill_path = sys.argv[1]
|
||||||
|
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
|
||||||
|
|
||||||
|
print(f"📦 Packaging skill: {skill_path}")
|
||||||
|
if output_dir:
|
||||||
|
print(f" Output directory: {output_dir}")
|
||||||
|
print()
|
||||||
|
|
||||||
|
result = package_skill(skill_path, output_dir)
|
||||||
|
|
||||||
|
if result:
|
||||||
|
sys.exit(0)
|
||||||
|
else:
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
103
.agents/skills/skill-creator/scripts/quick_validate.py
Normal file
103
.agents/skills/skill-creator/scripts/quick_validate.py
Normal file
@@ -0,0 +1,103 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Quick validation script for skills - minimal version
|
||||||
|
"""
|
||||||
|
|
||||||
|
import sys
|
||||||
|
import os
|
||||||
|
import re
|
||||||
|
import yaml
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
def validate_skill(skill_path):
|
||||||
|
"""Basic validation of a skill"""
|
||||||
|
skill_path = Path(skill_path)
|
||||||
|
|
||||||
|
# Check SKILL.md exists
|
||||||
|
skill_md = skill_path / 'SKILL.md'
|
||||||
|
if not skill_md.exists():
|
||||||
|
return False, "SKILL.md not found"
|
||||||
|
|
||||||
|
# Read and validate frontmatter
|
||||||
|
content = skill_md.read_text()
|
||||||
|
if not content.startswith('---'):
|
||||||
|
return False, "No YAML frontmatter found"
|
||||||
|
|
||||||
|
# Extract frontmatter
|
||||||
|
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||||
|
if not match:
|
||||||
|
return False, "Invalid frontmatter format"
|
||||||
|
|
||||||
|
frontmatter_text = match.group(1)
|
||||||
|
|
||||||
|
# Parse YAML frontmatter
|
||||||
|
try:
|
||||||
|
frontmatter = yaml.safe_load(frontmatter_text)
|
||||||
|
if not isinstance(frontmatter, dict):
|
||||||
|
return False, "Frontmatter must be a YAML dictionary"
|
||||||
|
except yaml.YAMLError as e:
|
||||||
|
return False, f"Invalid YAML in frontmatter: {e}"
|
||||||
|
|
||||||
|
# Define allowed properties
|
||||||
|
ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
|
||||||
|
|
||||||
|
# Check for unexpected properties (excluding nested keys under metadata)
|
||||||
|
unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
|
||||||
|
if unexpected_keys:
|
||||||
|
return False, (
|
||||||
|
f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
|
||||||
|
f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
|
||||||
|
)
|
||||||
|
|
||||||
|
# Check required fields
|
||||||
|
if 'name' not in frontmatter:
|
||||||
|
return False, "Missing 'name' in frontmatter"
|
||||||
|
if 'description' not in frontmatter:
|
||||||
|
return False, "Missing 'description' in frontmatter"
|
||||||
|
|
||||||
|
# Extract name for validation
|
||||||
|
name = frontmatter.get('name', '')
|
||||||
|
if not isinstance(name, str):
|
||||||
|
return False, f"Name must be a string, got {type(name).__name__}"
|
||||||
|
name = name.strip()
|
||||||
|
if name:
|
||||||
|
# Check naming convention (kebab-case: lowercase with hyphens)
|
||||||
|
if not re.match(r'^[a-z0-9-]+$', name):
|
||||||
|
return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
|
||||||
|
if name.startswith('-') or name.endswith('-') or '--' in name:
|
||||||
|
return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
|
||||||
|
# Check name length (max 64 characters per spec)
|
||||||
|
if len(name) > 64:
|
||||||
|
return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
|
||||||
|
|
||||||
|
# Extract and validate description
|
||||||
|
description = frontmatter.get('description', '')
|
||||||
|
if not isinstance(description, str):
|
||||||
|
return False, f"Description must be a string, got {type(description).__name__}"
|
||||||
|
description = description.strip()
|
||||||
|
if description:
|
||||||
|
# Check for angle brackets
|
||||||
|
if '<' in description or '>' in description:
|
||||||
|
return False, "Description cannot contain angle brackets (< or >)"
|
||||||
|
# Check description length (max 1024 characters per spec)
|
||||||
|
if len(description) > 1024:
|
||||||
|
return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
|
||||||
|
|
||||||
|
# Validate compatibility field if present (optional)
|
||||||
|
compatibility = frontmatter.get('compatibility', '')
|
||||||
|
if compatibility:
|
||||||
|
if not isinstance(compatibility, str):
|
||||||
|
return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
|
||||||
|
if len(compatibility) > 500:
|
||||||
|
return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
|
||||||
|
|
||||||
|
return True, "Skill is valid!"
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
if len(sys.argv) != 2:
|
||||||
|
print("Usage: python quick_validate.py <skill_directory>")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
valid, message = validate_skill(sys.argv[1])
|
||||||
|
print(message)
|
||||||
|
sys.exit(0 if valid else 1)
|
||||||
310
.agents/skills/skill-creator/scripts/run_eval.py
Normal file
310
.agents/skills/skill-creator/scripts/run_eval.py
Normal file
@@ -0,0 +1,310 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Run trigger evaluation for a skill description.
|
||||||
|
|
||||||
|
Tests whether a skill's description causes Claude to trigger (read the skill)
|
||||||
|
for a set of queries. Outputs results as JSON.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import os
|
||||||
|
import select
|
||||||
|
import subprocess
|
||||||
|
import sys
|
||||||
|
import time
|
||||||
|
import uuid
|
||||||
|
from concurrent.futures import ProcessPoolExecutor, as_completed
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from scripts.utils import parse_skill_md
|
||||||
|
|
||||||
|
|
||||||
|
def find_project_root() -> Path:
|
||||||
|
"""Find the project root by walking up from cwd looking for .claude/.
|
||||||
|
|
||||||
|
Mimics how Claude Code discovers its project root, so the command file
|
||||||
|
we create ends up where claude -p will look for it.
|
||||||
|
"""
|
||||||
|
current = Path.cwd()
|
||||||
|
for parent in [current, *current.parents]:
|
||||||
|
if (parent / ".claude").is_dir():
|
||||||
|
return parent
|
||||||
|
return current
|
||||||
|
|
||||||
|
|
||||||
|
def run_single_query(
|
||||||
|
query: str,
|
||||||
|
skill_name: str,
|
||||||
|
skill_description: str,
|
||||||
|
timeout: int,
|
||||||
|
project_root: str,
|
||||||
|
model: str | None = None,
|
||||||
|
) -> bool:
|
||||||
|
"""Run a single query and return whether the skill was triggered.
|
||||||
|
|
||||||
|
Creates a command file in .claude/commands/ so it appears in Claude's
|
||||||
|
available_skills list, then runs `claude -p` with the raw query.
|
||||||
|
Uses --include-partial-messages to detect triggering early from
|
||||||
|
stream events (content_block_start) rather than waiting for the
|
||||||
|
full assistant message, which only arrives after tool execution.
|
||||||
|
"""
|
||||||
|
unique_id = uuid.uuid4().hex[:8]
|
||||||
|
clean_name = f"{skill_name}-skill-{unique_id}"
|
||||||
|
project_commands_dir = Path(project_root) / ".claude" / "commands"
|
||||||
|
command_file = project_commands_dir / f"{clean_name}.md"
|
||||||
|
|
||||||
|
try:
|
||||||
|
project_commands_dir.mkdir(parents=True, exist_ok=True)
|
||||||
|
# Use YAML block scalar to avoid breaking on quotes in description
|
||||||
|
indented_desc = "\n ".join(skill_description.split("\n"))
|
||||||
|
command_content = (
|
||||||
|
f"---\n"
|
||||||
|
f"description: |\n"
|
||||||
|
f" {indented_desc}\n"
|
||||||
|
f"---\n\n"
|
||||||
|
f"# {skill_name}\n\n"
|
||||||
|
f"This skill handles: {skill_description}\n"
|
||||||
|
)
|
||||||
|
command_file.write_text(command_content)
|
||||||
|
|
||||||
|
cmd = [
|
||||||
|
"claude",
|
||||||
|
"-p", query,
|
||||||
|
"--output-format", "stream-json",
|
||||||
|
"--verbose",
|
||||||
|
"--include-partial-messages",
|
||||||
|
]
|
||||||
|
if model:
|
||||||
|
cmd.extend(["--model", model])
|
||||||
|
|
||||||
|
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||||
|
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||||
|
# programmatic subprocess usage is safe.
|
||||||
|
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||||
|
|
||||||
|
process = subprocess.Popen(
|
||||||
|
cmd,
|
||||||
|
stdout=subprocess.PIPE,
|
||||||
|
stderr=subprocess.DEVNULL,
|
||||||
|
cwd=project_root,
|
||||||
|
env=env,
|
||||||
|
)
|
||||||
|
|
||||||
|
triggered = False
|
||||||
|
start_time = time.time()
|
||||||
|
buffer = ""
|
||||||
|
# Track state for stream event detection
|
||||||
|
pending_tool_name = None
|
||||||
|
accumulated_json = ""
|
||||||
|
|
||||||
|
try:
|
||||||
|
while time.time() - start_time < timeout:
|
||||||
|
if process.poll() is not None:
|
||||||
|
remaining = process.stdout.read()
|
||||||
|
if remaining:
|
||||||
|
buffer += remaining.decode("utf-8", errors="replace")
|
||||||
|
break
|
||||||
|
|
||||||
|
ready, _, _ = select.select([process.stdout], [], [], 1.0)
|
||||||
|
if not ready:
|
||||||
|
continue
|
||||||
|
|
||||||
|
chunk = os.read(process.stdout.fileno(), 8192)
|
||||||
|
if not chunk:
|
||||||
|
break
|
||||||
|
buffer += chunk.decode("utf-8", errors="replace")
|
||||||
|
|
||||||
|
while "\n" in buffer:
|
||||||
|
line, buffer = buffer.split("\n", 1)
|
||||||
|
line = line.strip()
|
||||||
|
if not line:
|
||||||
|
continue
|
||||||
|
|
||||||
|
try:
|
||||||
|
event = json.loads(line)
|
||||||
|
except json.JSONDecodeError:
|
||||||
|
continue
|
||||||
|
|
||||||
|
# Early detection via stream events
|
||||||
|
if event.get("type") == "stream_event":
|
||||||
|
se = event.get("event", {})
|
||||||
|
se_type = se.get("type", "")
|
||||||
|
|
||||||
|
if se_type == "content_block_start":
|
||||||
|
cb = se.get("content_block", {})
|
||||||
|
if cb.get("type") == "tool_use":
|
||||||
|
tool_name = cb.get("name", "")
|
||||||
|
if tool_name in ("Skill", "Read"):
|
||||||
|
pending_tool_name = tool_name
|
||||||
|
accumulated_json = ""
|
||||||
|
else:
|
||||||
|
return False
|
||||||
|
|
||||||
|
elif se_type == "content_block_delta" and pending_tool_name:
|
||||||
|
delta = se.get("delta", {})
|
||||||
|
if delta.get("type") == "input_json_delta":
|
||||||
|
accumulated_json += delta.get("partial_json", "")
|
||||||
|
if clean_name in accumulated_json:
|
||||||
|
return True
|
||||||
|
|
||||||
|
elif se_type in ("content_block_stop", "message_stop"):
|
||||||
|
if pending_tool_name:
|
||||||
|
return clean_name in accumulated_json
|
||||||
|
if se_type == "message_stop":
|
||||||
|
return False
|
||||||
|
|
||||||
|
# Fallback: full assistant message
|
||||||
|
elif event.get("type") == "assistant":
|
||||||
|
message = event.get("message", {})
|
||||||
|
for content_item in message.get("content", []):
|
||||||
|
if content_item.get("type") != "tool_use":
|
||||||
|
continue
|
||||||
|
tool_name = content_item.get("name", "")
|
||||||
|
tool_input = content_item.get("input", {})
|
||||||
|
if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
|
||||||
|
triggered = True
|
||||||
|
elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
|
||||||
|
triggered = True
|
||||||
|
return triggered
|
||||||
|
|
||||||
|
elif event.get("type") == "result":
|
||||||
|
return triggered
|
||||||
|
finally:
|
||||||
|
# Clean up process on any exit path (return, exception, timeout)
|
||||||
|
if process.poll() is None:
|
||||||
|
process.kill()
|
||||||
|
process.wait()
|
||||||
|
|
||||||
|
return triggered
|
||||||
|
finally:
|
||||||
|
if command_file.exists():
|
||||||
|
command_file.unlink()
|
||||||
|
|
||||||
|
|
||||||
|
def run_eval(
|
||||||
|
eval_set: list[dict],
|
||||||
|
skill_name: str,
|
||||||
|
description: str,
|
||||||
|
num_workers: int,
|
||||||
|
timeout: int,
|
||||||
|
project_root: Path,
|
||||||
|
runs_per_query: int = 1,
|
||||||
|
trigger_threshold: float = 0.5,
|
||||||
|
model: str | None = None,
|
||||||
|
) -> dict:
|
||||||
|
"""Run the full eval set and return results."""
|
||||||
|
results = []
|
||||||
|
|
||||||
|
with ProcessPoolExecutor(max_workers=num_workers) as executor:
|
||||||
|
future_to_info = {}
|
||||||
|
for item in eval_set:
|
||||||
|
for run_idx in range(runs_per_query):
|
||||||
|
future = executor.submit(
|
||||||
|
run_single_query,
|
||||||
|
item["query"],
|
||||||
|
skill_name,
|
||||||
|
description,
|
||||||
|
timeout,
|
||||||
|
str(project_root),
|
||||||
|
model,
|
||||||
|
)
|
||||||
|
future_to_info[future] = (item, run_idx)
|
||||||
|
|
||||||
|
query_triggers: dict[str, list[bool]] = {}
|
||||||
|
query_items: dict[str, dict] = {}
|
||||||
|
for future in as_completed(future_to_info):
|
||||||
|
item, _ = future_to_info[future]
|
||||||
|
query = item["query"]
|
||||||
|
query_items[query] = item
|
||||||
|
if query not in query_triggers:
|
||||||
|
query_triggers[query] = []
|
||||||
|
try:
|
||||||
|
query_triggers[query].append(future.result())
|
||||||
|
except Exception as e:
|
||||||
|
print(f"Warning: query failed: {e}", file=sys.stderr)
|
||||||
|
query_triggers[query].append(False)
|
||||||
|
|
||||||
|
for query, triggers in query_triggers.items():
|
||||||
|
item = query_items[query]
|
||||||
|
trigger_rate = sum(triggers) / len(triggers)
|
||||||
|
should_trigger = item["should_trigger"]
|
||||||
|
if should_trigger:
|
||||||
|
did_pass = trigger_rate >= trigger_threshold
|
||||||
|
else:
|
||||||
|
did_pass = trigger_rate < trigger_threshold
|
||||||
|
results.append({
|
||||||
|
"query": query,
|
||||||
|
"should_trigger": should_trigger,
|
||||||
|
"trigger_rate": trigger_rate,
|
||||||
|
"triggers": sum(triggers),
|
||||||
|
"runs": len(triggers),
|
||||||
|
"pass": did_pass,
|
||||||
|
})
|
||||||
|
|
||||||
|
passed = sum(1 for r in results if r["pass"])
|
||||||
|
total = len(results)
|
||||||
|
|
||||||
|
return {
|
||||||
|
"skill_name": skill_name,
|
||||||
|
"description": description,
|
||||||
|
"results": results,
|
||||||
|
"summary": {
|
||||||
|
"total": total,
|
||||||
|
"passed": passed,
|
||||||
|
"failed": total - passed,
|
||||||
|
},
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
|
||||||
|
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||||
|
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||||
|
parser.add_argument("--description", default=None, help="Override description to test")
|
||||||
|
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||||
|
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||||
|
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||||
|
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||||
|
parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
|
||||||
|
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||||
|
skill_path = Path(args.skill_path)
|
||||||
|
|
||||||
|
if not (skill_path / "SKILL.md").exists():
|
||||||
|
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
name, original_description, content = parse_skill_md(skill_path)
|
||||||
|
description = args.description or original_description
|
||||||
|
project_root = find_project_root()
|
||||||
|
|
||||||
|
if args.verbose:
|
||||||
|
print(f"Evaluating: {description}", file=sys.stderr)
|
||||||
|
|
||||||
|
output = run_eval(
|
||||||
|
eval_set=eval_set,
|
||||||
|
skill_name=name,
|
||||||
|
description=description,
|
||||||
|
num_workers=args.num_workers,
|
||||||
|
timeout=args.timeout,
|
||||||
|
project_root=project_root,
|
||||||
|
runs_per_query=args.runs_per_query,
|
||||||
|
trigger_threshold=args.trigger_threshold,
|
||||||
|
model=args.model,
|
||||||
|
)
|
||||||
|
|
||||||
|
if args.verbose:
|
||||||
|
summary = output["summary"]
|
||||||
|
print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
|
||||||
|
for r in output["results"]:
|
||||||
|
status = "PASS" if r["pass"] else "FAIL"
|
||||||
|
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||||
|
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)
|
||||||
|
|
||||||
|
print(json.dumps(output, indent=2))
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
328
.agents/skills/skill-creator/scripts/run_loop.py
Normal file
328
.agents/skills/skill-creator/scripts/run_loop.py
Normal file
@@ -0,0 +1,328 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Run the eval + improve loop until all pass or max iterations reached.
|
||||||
|
|
||||||
|
Combines run_eval.py and improve_description.py in a loop, tracking history
|
||||||
|
and returning the best description found. Supports train/test split to prevent
|
||||||
|
overfitting.
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import random
|
||||||
|
import sys
|
||||||
|
import tempfile
|
||||||
|
import time
|
||||||
|
import webbrowser
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
from scripts.generate_report import generate_html
|
||||||
|
from scripts.improve_description import improve_description
|
||||||
|
from scripts.run_eval import find_project_root, run_eval
|
||||||
|
from scripts.utils import parse_skill_md
|
||||||
|
|
||||||
|
|
||||||
|
def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
|
||||||
|
"""Split eval set into train and test sets, stratified by should_trigger."""
|
||||||
|
random.seed(seed)
|
||||||
|
|
||||||
|
# Separate by should_trigger
|
||||||
|
trigger = [e for e in eval_set if e["should_trigger"]]
|
||||||
|
no_trigger = [e for e in eval_set if not e["should_trigger"]]
|
||||||
|
|
||||||
|
# Shuffle each group
|
||||||
|
random.shuffle(trigger)
|
||||||
|
random.shuffle(no_trigger)
|
||||||
|
|
||||||
|
# Calculate split points
|
||||||
|
n_trigger_test = max(1, int(len(trigger) * holdout))
|
||||||
|
n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
|
||||||
|
|
||||||
|
# Split
|
||||||
|
test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
|
||||||
|
train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
|
||||||
|
|
||||||
|
return train_set, test_set
|
||||||
|
|
||||||
|
|
||||||
|
def run_loop(
|
||||||
|
eval_set: list[dict],
|
||||||
|
skill_path: Path,
|
||||||
|
description_override: str | None,
|
||||||
|
num_workers: int,
|
||||||
|
timeout: int,
|
||||||
|
max_iterations: int,
|
||||||
|
runs_per_query: int,
|
||||||
|
trigger_threshold: float,
|
||||||
|
holdout: float,
|
||||||
|
model: str,
|
||||||
|
verbose: bool,
|
||||||
|
live_report_path: Path | None = None,
|
||||||
|
log_dir: Path | None = None,
|
||||||
|
) -> dict:
|
||||||
|
"""Run the eval + improvement loop."""
|
||||||
|
project_root = find_project_root()
|
||||||
|
name, original_description, content = parse_skill_md(skill_path)
|
||||||
|
current_description = description_override or original_description
|
||||||
|
|
||||||
|
# Split into train/test if holdout > 0
|
||||||
|
if holdout > 0:
|
||||||
|
train_set, test_set = split_eval_set(eval_set, holdout)
|
||||||
|
if verbose:
|
||||||
|
print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
|
||||||
|
else:
|
||||||
|
train_set = eval_set
|
||||||
|
test_set = []
|
||||||
|
|
||||||
|
history = []
|
||||||
|
exit_reason = "unknown"
|
||||||
|
|
||||||
|
for iteration in range(1, max_iterations + 1):
|
||||||
|
if verbose:
|
||||||
|
print(f"\n{'='*60}", file=sys.stderr)
|
||||||
|
print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
|
||||||
|
print(f"Description: {current_description}", file=sys.stderr)
|
||||||
|
print(f"{'='*60}", file=sys.stderr)
|
||||||
|
|
||||||
|
# Evaluate train + test together in one batch for parallelism
|
||||||
|
all_queries = train_set + test_set
|
||||||
|
t0 = time.time()
|
||||||
|
all_results = run_eval(
|
||||||
|
eval_set=all_queries,
|
||||||
|
skill_name=name,
|
||||||
|
description=current_description,
|
||||||
|
num_workers=num_workers,
|
||||||
|
timeout=timeout,
|
||||||
|
project_root=project_root,
|
||||||
|
runs_per_query=runs_per_query,
|
||||||
|
trigger_threshold=trigger_threshold,
|
||||||
|
model=model,
|
||||||
|
)
|
||||||
|
eval_elapsed = time.time() - t0
|
||||||
|
|
||||||
|
# Split results back into train/test by matching queries
|
||||||
|
train_queries_set = {q["query"] for q in train_set}
|
||||||
|
train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
|
||||||
|
test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
|
||||||
|
|
||||||
|
train_passed = sum(1 for r in train_result_list if r["pass"])
|
||||||
|
train_total = len(train_result_list)
|
||||||
|
train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
|
||||||
|
train_results = {"results": train_result_list, "summary": train_summary}
|
||||||
|
|
||||||
|
if test_set:
|
||||||
|
test_passed = sum(1 for r in test_result_list if r["pass"])
|
||||||
|
test_total = len(test_result_list)
|
||||||
|
test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
|
||||||
|
test_results = {"results": test_result_list, "summary": test_summary}
|
||||||
|
else:
|
||||||
|
test_results = None
|
||||||
|
test_summary = None
|
||||||
|
|
||||||
|
history.append({
|
||||||
|
"iteration": iteration,
|
||||||
|
"description": current_description,
|
||||||
|
"train_passed": train_summary["passed"],
|
||||||
|
"train_failed": train_summary["failed"],
|
||||||
|
"train_total": train_summary["total"],
|
||||||
|
"train_results": train_results["results"],
|
||||||
|
"test_passed": test_summary["passed"] if test_summary else None,
|
||||||
|
"test_failed": test_summary["failed"] if test_summary else None,
|
||||||
|
"test_total": test_summary["total"] if test_summary else None,
|
||||||
|
"test_results": test_results["results"] if test_results else None,
|
||||||
|
# For backward compat with report generator
|
||||||
|
"passed": train_summary["passed"],
|
||||||
|
"failed": train_summary["failed"],
|
||||||
|
"total": train_summary["total"],
|
||||||
|
"results": train_results["results"],
|
||||||
|
})
|
||||||
|
|
||||||
|
# Write live report if path provided
|
||||||
|
if live_report_path:
|
||||||
|
partial_output = {
|
||||||
|
"original_description": original_description,
|
||||||
|
"best_description": current_description,
|
||||||
|
"best_score": "in progress",
|
||||||
|
"iterations_run": len(history),
|
||||||
|
"holdout": holdout,
|
||||||
|
"train_size": len(train_set),
|
||||||
|
"test_size": len(test_set),
|
||||||
|
"history": history,
|
||||||
|
}
|
||||||
|
live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
|
||||||
|
|
||||||
|
if verbose:
|
||||||
|
def print_eval_stats(label, results, elapsed):
|
||||||
|
pos = [r for r in results if r["should_trigger"]]
|
||||||
|
neg = [r for r in results if not r["should_trigger"]]
|
||||||
|
tp = sum(r["triggers"] for r in pos)
|
||||||
|
pos_runs = sum(r["runs"] for r in pos)
|
||||||
|
fn = pos_runs - tp
|
||||||
|
fp = sum(r["triggers"] for r in neg)
|
||||||
|
neg_runs = sum(r["runs"] for r in neg)
|
||||||
|
tn = neg_runs - fp
|
||||||
|
total = tp + tn + fp + fn
|
||||||
|
precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
|
||||||
|
recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
|
||||||
|
accuracy = (tp + tn) / total if total > 0 else 0.0
|
||||||
|
print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
|
||||||
|
for r in results:
|
||||||
|
status = "PASS" if r["pass"] else "FAIL"
|
||||||
|
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||||
|
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
|
||||||
|
|
||||||
|
print_eval_stats("Train", train_results["results"], eval_elapsed)
|
||||||
|
if test_summary:
|
||||||
|
print_eval_stats("Test ", test_results["results"], 0)
|
||||||
|
|
||||||
|
if train_summary["failed"] == 0:
|
||||||
|
exit_reason = f"all_passed (iteration {iteration})"
|
||||||
|
if verbose:
|
||||||
|
print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
|
||||||
|
break
|
||||||
|
|
||||||
|
if iteration == max_iterations:
|
||||||
|
exit_reason = f"max_iterations ({max_iterations})"
|
||||||
|
if verbose:
|
||||||
|
print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
|
||||||
|
break
|
||||||
|
|
||||||
|
# Improve the description based on train results
|
||||||
|
if verbose:
|
||||||
|
print(f"\nImproving description...", file=sys.stderr)
|
||||||
|
|
||||||
|
t0 = time.time()
|
||||||
|
# Strip test scores from history so improvement model can't see them
|
||||||
|
blinded_history = [
|
||||||
|
{k: v for k, v in h.items() if not k.startswith("test_")}
|
||||||
|
for h in history
|
||||||
|
]
|
||||||
|
new_description = improve_description(
|
||||||
|
skill_name=name,
|
||||||
|
skill_content=content,
|
||||||
|
current_description=current_description,
|
||||||
|
eval_results=train_results,
|
||||||
|
history=blinded_history,
|
||||||
|
model=model,
|
||||||
|
log_dir=log_dir,
|
||||||
|
iteration=iteration,
|
||||||
|
)
|
||||||
|
improve_elapsed = time.time() - t0
|
||||||
|
|
||||||
|
if verbose:
|
||||||
|
print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
|
||||||
|
|
||||||
|
current_description = new_description
|
||||||
|
|
||||||
|
# Find the best iteration by TEST score (or train if no test set)
|
||||||
|
if test_set:
|
||||||
|
best = max(history, key=lambda h: h["test_passed"] or 0)
|
||||||
|
best_score = f"{best['test_passed']}/{best['test_total']}"
|
||||||
|
else:
|
||||||
|
best = max(history, key=lambda h: h["train_passed"])
|
||||||
|
best_score = f"{best['train_passed']}/{best['train_total']}"
|
||||||
|
|
||||||
|
if verbose:
|
||||||
|
print(f"\nExit reason: {exit_reason}", file=sys.stderr)
|
||||||
|
print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
|
||||||
|
|
||||||
|
return {
|
||||||
|
"exit_reason": exit_reason,
|
||||||
|
"original_description": original_description,
|
||||||
|
"best_description": best["description"],
|
||||||
|
"best_score": best_score,
|
||||||
|
"best_train_score": f"{best['train_passed']}/{best['train_total']}",
|
||||||
|
"best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
|
||||||
|
"final_description": current_description,
|
||||||
|
"iterations_run": len(history),
|
||||||
|
"holdout": holdout,
|
||||||
|
"train_size": len(train_set),
|
||||||
|
"test_size": len(test_set),
|
||||||
|
"history": history,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Run eval + improve loop")
|
||||||
|
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||||
|
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||||
|
parser.add_argument("--description", default=None, help="Override starting description")
|
||||||
|
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||||
|
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||||
|
parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
|
||||||
|
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||||
|
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||||
|
parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
|
||||||
|
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||||
|
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||||
|
parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
|
||||||
|
parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||||
|
skill_path = Path(args.skill_path)
|
||||||
|
|
||||||
|
if not (skill_path / "SKILL.md").exists():
|
||||||
|
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
name, _, _ = parse_skill_md(skill_path)
|
||||||
|
|
||||||
|
# Set up live report path
|
||||||
|
if args.report != "none":
|
||||||
|
if args.report == "auto":
|
||||||
|
timestamp = time.strftime("%Y%m%d_%H%M%S")
|
||||||
|
live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
|
||||||
|
else:
|
||||||
|
live_report_path = Path(args.report)
|
||||||
|
# Open the report immediately so the user can watch
|
||||||
|
live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
|
||||||
|
webbrowser.open(str(live_report_path))
|
||||||
|
else:
|
||||||
|
live_report_path = None
|
||||||
|
|
||||||
|
# Determine output directory (create before run_loop so logs can be written)
|
||||||
|
if args.results_dir:
|
||||||
|
timestamp = time.strftime("%Y-%m-%d_%H%M%S")
|
||||||
|
results_dir = Path(args.results_dir) / timestamp
|
||||||
|
results_dir.mkdir(parents=True, exist_ok=True)
|
||||||
|
else:
|
||||||
|
results_dir = None
|
||||||
|
|
||||||
|
log_dir = results_dir / "logs" if results_dir else None
|
||||||
|
|
||||||
|
output = run_loop(
|
||||||
|
eval_set=eval_set,
|
||||||
|
skill_path=skill_path,
|
||||||
|
description_override=args.description,
|
||||||
|
num_workers=args.num_workers,
|
||||||
|
timeout=args.timeout,
|
||||||
|
max_iterations=args.max_iterations,
|
||||||
|
runs_per_query=args.runs_per_query,
|
||||||
|
trigger_threshold=args.trigger_threshold,
|
||||||
|
holdout=args.holdout,
|
||||||
|
model=args.model,
|
||||||
|
verbose=args.verbose,
|
||||||
|
live_report_path=live_report_path,
|
||||||
|
log_dir=log_dir,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Save JSON output
|
||||||
|
json_output = json.dumps(output, indent=2)
|
||||||
|
print(json_output)
|
||||||
|
if results_dir:
|
||||||
|
(results_dir / "results.json").write_text(json_output)
|
||||||
|
|
||||||
|
# Write final HTML report (without auto-refresh)
|
||||||
|
if live_report_path:
|
||||||
|
live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||||
|
print(f"\nReport: {live_report_path}", file=sys.stderr)
|
||||||
|
|
||||||
|
if results_dir and live_report_path:
|
||||||
|
(results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||||
|
|
||||||
|
if results_dir:
|
||||||
|
print(f"Results saved to: {results_dir}", file=sys.stderr)
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
47
.agents/skills/skill-creator/scripts/utils.py
Normal file
47
.agents/skills/skill-creator/scripts/utils.py
Normal file
@@ -0,0 +1,47 @@
|
|||||||
|
"""Shared utilities for skill-creator scripts."""
|
||||||
|
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
|
||||||
|
"""Parse a SKILL.md file, returning (name, description, full_content)."""
|
||||||
|
content = (skill_path / "SKILL.md").read_text()
|
||||||
|
lines = content.split("\n")
|
||||||
|
|
||||||
|
if lines[0].strip() != "---":
|
||||||
|
raise ValueError("SKILL.md missing frontmatter (no opening ---)")
|
||||||
|
|
||||||
|
end_idx = None
|
||||||
|
for i, line in enumerate(lines[1:], start=1):
|
||||||
|
if line.strip() == "---":
|
||||||
|
end_idx = i
|
||||||
|
break
|
||||||
|
|
||||||
|
if end_idx is None:
|
||||||
|
raise ValueError("SKILL.md missing frontmatter (no closing ---)")
|
||||||
|
|
||||||
|
name = ""
|
||||||
|
description = ""
|
||||||
|
frontmatter_lines = lines[1:end_idx]
|
||||||
|
i = 0
|
||||||
|
while i < len(frontmatter_lines):
|
||||||
|
line = frontmatter_lines[i]
|
||||||
|
if line.startswith("name:"):
|
||||||
|
name = line[len("name:"):].strip().strip('"').strip("'")
|
||||||
|
elif line.startswith("description:"):
|
||||||
|
value = line[len("description:"):].strip()
|
||||||
|
# Handle YAML multiline indicators (>, |, >-, |-)
|
||||||
|
if value in (">", "|", ">-", "|-"):
|
||||||
|
continuation_lines: list[str] = []
|
||||||
|
i += 1
|
||||||
|
while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith(" ") or frontmatter_lines[i].startswith("\t")):
|
||||||
|
continuation_lines.append(frontmatter_lines[i].strip())
|
||||||
|
i += 1
|
||||||
|
description = " ".join(continuation_lines)
|
||||||
|
continue
|
||||||
|
else:
|
||||||
|
description = value.strip('"').strip("'")
|
||||||
|
i += 1
|
||||||
|
|
||||||
|
return name, description, content
|
||||||
417
.agents/skills/tanstack-form/SKILL.md
Normal file
417
.agents/skills/tanstack-form/SKILL.md
Normal file
@@ -0,0 +1,417 @@
|
|||||||
|
---
|
||||||
|
name: tanstack-form
|
||||||
|
description: Headless, performant, and type-safe form state management for TS/JS, React, Vue, Angular, Solid, Lit, and Svelte.
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
TanStack Form is a headless form library with deep TypeScript integration. It provides field-level and form-level validation (sync/async), array fields, linked/dependent fields, fine-grained reactivity, and schema validation adapter support (Zod, Valibot, Yup).
|
||||||
|
|
||||||
|
**Package:** `@tanstack/react-form`
|
||||||
|
**Adapters:** `@tanstack/zod-form-adapter`, `@tanstack/valibot-form-adapter`
|
||||||
|
**Status:** Stable (v1)
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @tanstack/react-form
|
||||||
|
# Optional schema adapters:
|
||||||
|
npm install @tanstack/zod-form-adapter zod
|
||||||
|
npm install @tanstack/valibot-form-adapter valibot
|
||||||
|
```
|
||||||
|
|
||||||
|
## Core: useForm
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useForm } from '@tanstack/react-form';
|
||||||
|
|
||||||
|
function MyForm() {
|
||||||
|
const form = useForm({
|
||||||
|
defaultValues: {
|
||||||
|
firstName: '',
|
||||||
|
lastName: '',
|
||||||
|
email: '',
|
||||||
|
age: 0
|
||||||
|
},
|
||||||
|
onSubmit: async ({ value }) => {
|
||||||
|
// value is fully typed
|
||||||
|
await submitToServer(value);
|
||||||
|
},
|
||||||
|
onSubmitInvalid: ({ value, formApi }) => {
|
||||||
|
console.log('Validation failed:', formApi.state.errors);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
return (
|
||||||
|
<form
|
||||||
|
onSubmit={(e) => {
|
||||||
|
e.preventDefault();
|
||||||
|
e.stopPropagation();
|
||||||
|
form.handleSubmit();
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{/* Fields */}
|
||||||
|
<form.Subscribe
|
||||||
|
selector={(state) => ({ canSubmit: state.canSubmit, isSubmitting: state.isSubmitting })}
|
||||||
|
children={({ canSubmit, isSubmitting }) => (
|
||||||
|
<button type='submit' disabled={!canSubmit}>
|
||||||
|
{isSubmitting ? 'Submitting...' : 'Submit'}
|
||||||
|
</button>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Fields (form.Field)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field
|
||||||
|
name="firstName"
|
||||||
|
validators={{
|
||||||
|
onChange: ({ value }) =>
|
||||||
|
value.length < 3 ? 'Must be at least 3 characters' : undefined,
|
||||||
|
}}
|
||||||
|
children={(field) => (
|
||||||
|
<div>
|
||||||
|
<label htmlFor={field.name}>First Name</label>
|
||||||
|
<input
|
||||||
|
id={field.name}
|
||||||
|
name={field.name}
|
||||||
|
value={field.state.value}
|
||||||
|
onBlur={field.handleBlur}
|
||||||
|
onChange={(e) => field.handleChange(e.target.value)}
|
||||||
|
/>
|
||||||
|
{field.state.meta.isTouched && field.state.meta.errors.length > 0 && (
|
||||||
|
<em>{field.state.meta.errors.join(', ')}</em>
|
||||||
|
)}
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
/>
|
||||||
|
|
||||||
|
<!-- Nested fields use dot notation -->
|
||||||
|
<form.Field name="address.city">
|
||||||
|
{(field) => (
|
||||||
|
<input
|
||||||
|
value={field.state.value}
|
||||||
|
onChange={(e) => field.handleChange(e.target.value)}
|
||||||
|
onBlur={field.handleBlur}
|
||||||
|
/>
|
||||||
|
)}
|
||||||
|
</form.Field>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
### Validation Timing
|
||||||
|
|
||||||
|
| Cause | When |
|
||||||
|
| ---------- | ------------------------ |
|
||||||
|
| `onChange` | After every value change |
|
||||||
|
| `onBlur` | When field loses focus |
|
||||||
|
| `onSubmit` | During submission |
|
||||||
|
| `onMount` | When field mounts |
|
||||||
|
|
||||||
|
### Synchronous Validation
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field
|
||||||
|
name='age'
|
||||||
|
validators={{
|
||||||
|
onChange: ({ value }) => {
|
||||||
|
if (value < 18) return 'Must be 18 or older';
|
||||||
|
return undefined; // undefined = valid
|
||||||
|
},
|
||||||
|
onBlur: ({ value }) => {
|
||||||
|
if (!value) return 'Required';
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Asynchronous Validation
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field
|
||||||
|
name='username'
|
||||||
|
asyncDebounceMs={500}
|
||||||
|
validators={{
|
||||||
|
onChangeAsync: async ({ value }) => {
|
||||||
|
const res = await fetch(`/api/check-username?q=${value}`);
|
||||||
|
const { available } = await res.json();
|
||||||
|
if (!available) return 'Username taken';
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{(field) => (
|
||||||
|
<>
|
||||||
|
<input value={field.state.value} onChange={(e) => field.handleChange(e.target.value)} />
|
||||||
|
{field.state.meta.isValidating && <span>Checking...</span>}
|
||||||
|
</>
|
||||||
|
)}
|
||||||
|
</form.Field>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Schema Validation (Zod)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { zodValidator } from '@tanstack/zod-form-adapter'
|
||||||
|
import { z } from 'zod'
|
||||||
|
|
||||||
|
const form = useForm({
|
||||||
|
defaultValues: { email: '', age: 0 },
|
||||||
|
validatorAdapter: zodValidator(),
|
||||||
|
onSubmit: async ({ value }) => { /* ... */ },
|
||||||
|
})
|
||||||
|
|
||||||
|
<form.Field
|
||||||
|
name="email"
|
||||||
|
validators={{
|
||||||
|
onChange: z.string().email('Invalid email'),
|
||||||
|
onBlur: z.string().min(1, 'Required'),
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
|
||||||
|
<form.Field
|
||||||
|
name="age"
|
||||||
|
validators={{
|
||||||
|
onChange: z.number().min(18, 'Must be 18+'),
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form-Level Validation
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const form = useForm({
|
||||||
|
defaultValues: { password: '', confirmPassword: '' },
|
||||||
|
validators: {
|
||||||
|
onChange: ({ value }) => {
|
||||||
|
if (value.password !== value.confirmPassword) {
|
||||||
|
return 'Passwords do not match';
|
||||||
|
}
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linked/Dependent Fields
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field
|
||||||
|
name='confirmPassword'
|
||||||
|
validators={{
|
||||||
|
onChangeListenTo: ['password'], // Re-validate when password changes
|
||||||
|
onChange: ({ value, fieldApi }) => {
|
||||||
|
const password = fieldApi.form.getFieldValue('password');
|
||||||
|
if (value !== password) return 'Passwords do not match';
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Array Fields
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field name='people' mode='array'>
|
||||||
|
{(field) => (
|
||||||
|
<div>
|
||||||
|
{field.state.value.map((_, index) => (
|
||||||
|
<div key={index}>
|
||||||
|
<form.Field name={`people[${index}].name`}>
|
||||||
|
{(subField) => (
|
||||||
|
<input
|
||||||
|
value={subField.state.value}
|
||||||
|
onChange={(e) => subField.handleChange(e.target.value)}
|
||||||
|
/>
|
||||||
|
)}
|
||||||
|
</form.Field>
|
||||||
|
<button type='button' onClick={() => field.removeValue(index)}>
|
||||||
|
Remove
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
))}
|
||||||
|
<button type='button' onClick={() => field.pushValue({ name: '', age: 0 })}>
|
||||||
|
Add Person
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
</form.Field>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Array Methods
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
field.pushValue(item); // Add to end
|
||||||
|
field.insertValue(index, item); // Insert at index
|
||||||
|
field.replaceValue(index, item); // Replace at index
|
||||||
|
field.removeValue(index); // Remove at index
|
||||||
|
field.swapValues(indexA, indexB); // Swap positions
|
||||||
|
field.moveValue(from, to); // Move position
|
||||||
|
```
|
||||||
|
|
||||||
|
## Listeners (Side Effects)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<form.Field
|
||||||
|
name='country'
|
||||||
|
listeners={{
|
||||||
|
onChange: ({ value }) => {
|
||||||
|
// Side effect: reset dependent fields
|
||||||
|
form.setFieldValue('state', '');
|
||||||
|
form.setFieldValue('postalCode', '');
|
||||||
|
}
|
||||||
|
}}
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Reactivity (form.Subscribe & useStore)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Render-prop subscription (fine-grained)
|
||||||
|
<form.Subscribe
|
||||||
|
selector={(state) => ({ canSubmit: state.canSubmit, isDirty: state.isDirty })}
|
||||||
|
children={({ canSubmit, isDirty }) => (
|
||||||
|
<div>
|
||||||
|
{isDirty && <span>Unsaved changes</span>}
|
||||||
|
<button disabled={!canSubmit}>Save</button>
|
||||||
|
</div>
|
||||||
|
)}
|
||||||
|
/>;
|
||||||
|
|
||||||
|
// Hook-based subscription
|
||||||
|
function FormStatus() {
|
||||||
|
const isValid = form.useStore((s) => s.isValid);
|
||||||
|
return isValid ? null : <p>Fix errors</p>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Form State
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface FormState {
|
||||||
|
values: TFormData;
|
||||||
|
errors: ValidationError[];
|
||||||
|
errorMap: Record<string, ValidationError>;
|
||||||
|
isFormValid: boolean;
|
||||||
|
isFieldsValid: boolean;
|
||||||
|
isValid: boolean; // isFormValid && isFieldsValid
|
||||||
|
isTouched: boolean;
|
||||||
|
isPristine: boolean;
|
||||||
|
isDirty: boolean;
|
||||||
|
isSubmitting: boolean;
|
||||||
|
isSubmitted: boolean;
|
||||||
|
isSubmitSuccessful: boolean;
|
||||||
|
submissionAttempts: number;
|
||||||
|
canSubmit: boolean; // isValid && !isSubmitting
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Field State
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
interface FieldState<TData> {
|
||||||
|
value: TData;
|
||||||
|
meta: {
|
||||||
|
isTouched: boolean;
|
||||||
|
isDirty: boolean;
|
||||||
|
isPristine: boolean;
|
||||||
|
isValidating: boolean;
|
||||||
|
errors: ValidationError[];
|
||||||
|
errorMap: Record<ValidationCause, ValidationError>;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## FormApi Methods
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
form.handleSubmit();
|
||||||
|
form.reset();
|
||||||
|
form.getFieldValue(field);
|
||||||
|
form.setFieldValue(field, value);
|
||||||
|
form.getFieldMeta(field);
|
||||||
|
form.setFieldMeta(field, updater);
|
||||||
|
form.validateAllFields(cause);
|
||||||
|
form.validateField(field, cause);
|
||||||
|
form.deleteField(field);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Shared Form Options (formOptions)
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { formOptions } from '@tanstack/react-form';
|
||||||
|
|
||||||
|
const sharedOpts = formOptions({
|
||||||
|
defaultValues: { firstName: '', lastName: '' }
|
||||||
|
});
|
||||||
|
|
||||||
|
// Reuse across components
|
||||||
|
const form = useForm({
|
||||||
|
...sharedOpts,
|
||||||
|
onSubmit: async ({ value }) => {
|
||||||
|
/* ... */
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Server-Side Validation
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// TanStack Start / Next.js server action
|
||||||
|
import { ServerValidateError } from '@tanstack/react-form/nextjs';
|
||||||
|
|
||||||
|
export async function validateForm(data: FormData) {
|
||||||
|
const email = data.get('email') as string;
|
||||||
|
if (await checkEmailExists(email)) {
|
||||||
|
throw new ServerValidateError({
|
||||||
|
form: 'Submission failed',
|
||||||
|
fields: { email: 'Email already registered' }
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## TypeScript Integration
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Type-safe field paths with DeepKeys
|
||||||
|
interface UserForm {
|
||||||
|
name: string
|
||||||
|
address: { street: string; city: string }
|
||||||
|
tags: string[]
|
||||||
|
contacts: Array<{ name: string; phone: string }>
|
||||||
|
}
|
||||||
|
|
||||||
|
// TypeScript auto-completes all valid paths:
|
||||||
|
// 'name', 'address', 'address.street', 'address.city', 'tags', 'contacts'
|
||||||
|
<form.Field name="address.city" /> // OK
|
||||||
|
<form.Field name="nonexistent" /> // Type Error!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Always call `e.preventDefault()` and `e.stopPropagation()`** on form submit
|
||||||
|
2. **Always attach `onBlur={field.handleBlur}`** for blur validation and isTouched tracking
|
||||||
|
3. **Use `mode="array"`** for array fields to get array methods
|
||||||
|
4. **Return `undefined`** (not null/false) for valid validators
|
||||||
|
5. **Use `asyncDebounceMs`** for async validators to prevent API spam
|
||||||
|
6. **Check `isTouched` before showing errors** for better UX
|
||||||
|
7. **Use `form.Subscribe` with selectors** to minimize re-renders
|
||||||
|
8. **Use `formOptions`** for shared configuration across components
|
||||||
|
9. **Use schema validators** (Zod/Valibot) for complex validation rules
|
||||||
|
10. **Use `onChangeListenTo`** for cross-field validation dependencies
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
- Forgetting `e.preventDefault()` on form submit (causes page reload)
|
||||||
|
- Not attaching `onBlur` to inputs (breaks blur validation and isTouched)
|
||||||
|
- Returning `null` or `false` instead of `undefined` for valid fields
|
||||||
|
- Using `mode="array"` incorrectly (only needed on the array field itself, not sub-fields)
|
||||||
|
- Subscribing to entire form state instead of using selectors (unnecessary re-renders)
|
||||||
|
- Not using `asyncDebounceMs` with async validators (fires on every keystroke)
|
||||||
472
.agents/skills/tanstack-query/SKILL.md
Normal file
472
.agents/skills/tanstack-query/SKILL.md
Normal file
@@ -0,0 +1,472 @@
|
|||||||
|
---
|
||||||
|
name: tanstack-query
|
||||||
|
description: TanStack Query v5 data fetching patterns including useSuspenseQuery, useQuery, mutations, cache management, and API service integration. Use when fetching data, managing server state, or working with TanStack Query hooks.
|
||||||
|
---
|
||||||
|
|
||||||
|
# TanStack Query Patterns
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Modern data fetching with TanStack Query v5 (latest: 5.90.5, November 2025), emphasizing Suspense-based queries, cache-first strategies, and centralized API services.
|
||||||
|
|
||||||
|
**Note**: v5 (released October 2023) has breaking changes from v4:
|
||||||
|
|
||||||
|
- `isLoading` → `isPending` for status
|
||||||
|
- `cacheTime` → `gcTime` (garbage collection time)
|
||||||
|
- React 18.0+ required
|
||||||
|
- Callbacks removed from useQuery (onError, onSuccess, onSettled)
|
||||||
|
- `keepPreviousData` replaced with `placeholderData` function
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
- Fetching data with TanStack Query
|
||||||
|
- Using useSuspenseQuery or useQuery
|
||||||
|
- Managing mutations
|
||||||
|
- Cache invalidation and updates
|
||||||
|
- API service patterns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Primary Pattern: useSuspenseQuery
|
||||||
|
|
||||||
|
For **all new components**, use `useSuspenseQuery`:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useSuspenseQuery } from '@tanstack/react-query';
|
||||||
|
import { postsApi } from '~/features/posts/api/postsApi';
|
||||||
|
|
||||||
|
function PostList() {
|
||||||
|
const { data: posts } = useSuspenseQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: postsApi.getAll,
|
||||||
|
});
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
{posts.map(post => (
|
||||||
|
<PostCard key={post.id} post={post} />
|
||||||
|
))}
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Wrap with Suspense
|
||||||
|
<Suspense fallback={<PostsSkeleton />}>
|
||||||
|
<PostList />
|
||||||
|
</Suspense>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Benefits:**
|
||||||
|
|
||||||
|
- No `isLoading` checks needed
|
||||||
|
- Integrates with Suspense boundaries
|
||||||
|
- Cleaner component code
|
||||||
|
- Consistent loading UX
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## useSuspenseQuery Patterns
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['user', userId],
|
||||||
|
queryFn: () => userApi.get(userId),
|
||||||
|
});
|
||||||
|
|
||||||
|
// data is never undefined - guaranteed by Suspense
|
||||||
|
return <div>{data.name}</div>;
|
||||||
|
```
|
||||||
|
|
||||||
|
### With Parameters
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
function UserPosts({ userId }: { userId: string }) {
|
||||||
|
const { data: posts } = useSuspenseQuery({
|
||||||
|
queryKey: ['users', userId, 'posts'],
|
||||||
|
queryFn: () => postsApi.getByUser(userId),
|
||||||
|
});
|
||||||
|
|
||||||
|
return <div>{posts.length} posts</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dependent Queries
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
function PostDetails({ postId }: { postId: string }) {
|
||||||
|
// First query
|
||||||
|
const { data: post } = useSuspenseQuery({
|
||||||
|
queryKey: ['posts', postId],
|
||||||
|
queryFn: () => postsApi.get(postId),
|
||||||
|
});
|
||||||
|
|
||||||
|
// Second query depends on first
|
||||||
|
const { data: author } = useSuspenseQuery({
|
||||||
|
queryKey: ['users', post.authorId],
|
||||||
|
queryFn: () => userApi.get(post.authorId),
|
||||||
|
});
|
||||||
|
|
||||||
|
return <div>{author.name} wrote {post.title}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## useQuery (Legacy Pattern)
|
||||||
|
|
||||||
|
Use `useQuery` only when you need loading/error states in the component:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useQuery } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
function Component() {
|
||||||
|
const { data, isPending, error } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: postsApi.getAll,
|
||||||
|
});
|
||||||
|
|
||||||
|
if (isPending) return <Spinner />;
|
||||||
|
if (error) return <Error error={error} />;
|
||||||
|
|
||||||
|
return <div>{data.map(...)}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**When to use `useQuery` vs `useSuspenseQuery`:**
|
||||||
|
|
||||||
|
- Use `useSuspenseQuery` by default (preferred)
|
||||||
|
- Use `useQuery` only when you need component-level loading states
|
||||||
|
- Most cases should use `useSuspenseQuery` + Suspense boundaries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mutations
|
||||||
|
|
||||||
|
### Basic Mutation
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useMutation, useQueryClient } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
function CreatePostButton() {
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
const mutation = useMutation({
|
||||||
|
mutationFn: postsApi.create,
|
||||||
|
onSuccess: () => {
|
||||||
|
// Invalidate and refetch
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
const handleCreate = () => {
|
||||||
|
mutation.mutate({
|
||||||
|
title: 'New Post',
|
||||||
|
content: 'Content here',
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<button onClick={handleCreate} disabled={mutation.isPending}>
|
||||||
|
{mutation.isPending ? 'Creating...' : 'Create Post'}
|
||||||
|
</button>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Optimistic Updates
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const mutation = useMutation({
|
||||||
|
mutationFn: postsApi.update,
|
||||||
|
onMutate: async (updatedPost) => {
|
||||||
|
// Cancel outgoing refetches
|
||||||
|
await queryClient.cancelQueries({ queryKey: ['posts', updatedPost.id] });
|
||||||
|
|
||||||
|
// Snapshot previous value
|
||||||
|
const previousPost = queryClient.getQueryData(['posts', updatedPost.id]);
|
||||||
|
|
||||||
|
// Optimistically update
|
||||||
|
queryClient.setQueryData(['posts', updatedPost.id], updatedPost);
|
||||||
|
|
||||||
|
// Return context with snapshot
|
||||||
|
return { previousPost };
|
||||||
|
},
|
||||||
|
onError: (err, updatedPost, context) => {
|
||||||
|
// Rollback on error
|
||||||
|
queryClient.setQueryData(['posts', updatedPost.id], context.previousPost);
|
||||||
|
},
|
||||||
|
onSettled: (data, error, variables) => {
|
||||||
|
// Refetch after mutation
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts', variables.id] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Cache Management
|
||||||
|
|
||||||
|
### Invalidation
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useQueryClient } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
// Invalidate all posts queries
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
|
||||||
|
// Invalidate specific post
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts', postId] });
|
||||||
|
|
||||||
|
// Invalidate all queries
|
||||||
|
queryClient.invalidateQueries();
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual Updates
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Update cache directly
|
||||||
|
queryClient.setQueryData(['posts', postId], newPost);
|
||||||
|
|
||||||
|
// Update with function
|
||||||
|
queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost]);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prefetching
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Prefetch data
|
||||||
|
await queryClient.prefetchQuery({
|
||||||
|
queryKey: ['posts', postId],
|
||||||
|
queryFn: () => postsApi.get(postId),
|
||||||
|
});
|
||||||
|
|
||||||
|
// In a component
|
||||||
|
const prefetchPost = (postId: string) => {
|
||||||
|
queryClient.prefetchQuery({
|
||||||
|
queryKey: ['posts', postId],
|
||||||
|
queryFn: () => postsApi.get(postId),
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
<Link
|
||||||
|
to={`/posts/${post.id}`}
|
||||||
|
onMouseEnter={() => prefetchPost(post.id)}
|
||||||
|
>
|
||||||
|
{post.title}
|
||||||
|
</Link>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Service Pattern
|
||||||
|
|
||||||
|
### Centralized API Service
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// features/posts/api/postsApi.ts
|
||||||
|
import { apiClient } from '@/lib/apiClient';
|
||||||
|
import type { Post, CreatePostDto, UpdatePostDto } from '~/types/post';
|
||||||
|
|
||||||
|
export const postsApi = {
|
||||||
|
getAll: async (): Promise<Post[]> => {
|
||||||
|
const response = await apiClient.get('/posts');
|
||||||
|
return response.data;
|
||||||
|
},
|
||||||
|
|
||||||
|
get: async (id: string): Promise<Post> => {
|
||||||
|
const response = await apiClient.get(`/posts/${id}`);
|
||||||
|
return response.data;
|
||||||
|
},
|
||||||
|
|
||||||
|
create: async (data: CreatePostDto): Promise<Post> => {
|
||||||
|
const response = await apiClient.post('/posts', data);
|
||||||
|
return response.data;
|
||||||
|
},
|
||||||
|
|
||||||
|
update: async (id: string, data: UpdatePostDto): Promise<Post> => {
|
||||||
|
const response = await apiClient.put(`/posts/${id}`, data);
|
||||||
|
return response.data;
|
||||||
|
},
|
||||||
|
|
||||||
|
delete: async (id: string): Promise<void> => {
|
||||||
|
await apiClient.delete(`/posts/${id}`);
|
||||||
|
},
|
||||||
|
|
||||||
|
getByUser: async (userId: string): Promise<Post[]> => {
|
||||||
|
const response = await apiClient.get(`/users/${userId}/posts`);
|
||||||
|
return response.data;
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage in Components
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { postsApi } from '~/features/posts/api/postsApi';
|
||||||
|
|
||||||
|
// In query
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: postsApi.getAll
|
||||||
|
});
|
||||||
|
|
||||||
|
// In mutation
|
||||||
|
const mutation = useMutation({
|
||||||
|
mutationFn: postsApi.create
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Query Keys
|
||||||
|
|
||||||
|
### Key Structure
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// List queries
|
||||||
|
['posts'][('posts', { status: 'published' })][ // All posts // Filtered posts
|
||||||
|
// Detail queries
|
||||||
|
('posts', postId)
|
||||||
|
][('posts', postId, 'comments')][ // Single post // Post comments
|
||||||
|
// Nested resources
|
||||||
|
('users', userId, 'posts')
|
||||||
|
][('users', userId, 'posts', postId)]; // User's posts // Specific user post
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Factories
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// features/posts/api/postKeys.ts
|
||||||
|
export const postKeys = {
|
||||||
|
all: ['posts'] as const,
|
||||||
|
lists: () => [...postKeys.all, 'list'] as const,
|
||||||
|
list: (filters: string) => [...postKeys.lists(), { filters }] as const,
|
||||||
|
details: () => [...postKeys.all, 'detail'] as const,
|
||||||
|
detail: (id: string) => [...postKeys.details(), id] as const,
|
||||||
|
comments: (id: string) => [...postKeys.detail(id), 'comments'] as const
|
||||||
|
};
|
||||||
|
|
||||||
|
// Usage
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: postKeys.detail(postId),
|
||||||
|
queryFn: () => postsApi.get(postId)
|
||||||
|
});
|
||||||
|
|
||||||
|
// Invalidate all post lists
|
||||||
|
queryClient.invalidateQueries({ queryKey: postKeys.lists() });
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### With Error Boundaries
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { ErrorBoundary } from 'react-error-boundary';
|
||||||
|
|
||||||
|
<ErrorBoundary fallback={<ErrorFallback />}>
|
||||||
|
<Suspense fallback={<Loading />}>
|
||||||
|
<DataComponent />
|
||||||
|
</Suspense>
|
||||||
|
</ErrorBoundary>
|
||||||
|
|
||||||
|
// In component
|
||||||
|
function DataComponent() {
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['data'],
|
||||||
|
queryFn: fetchData,
|
||||||
|
// Errors automatically caught by ErrorBoundary
|
||||||
|
});
|
||||||
|
|
||||||
|
return <div>{data}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Retry and Cache Configuration
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: postsApi.getAll,
|
||||||
|
retry: 3, // Retry 3 times
|
||||||
|
retryDelay: 1000, // Wait 1s between retries
|
||||||
|
gcTime: 5 * 60 * 1000 // Garbage collection time: 5 minutes (v5: was 'cacheTime')
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### 1. Use Suspense by Default
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ✅ Good: useSuspenseQuery + Suspense
|
||||||
|
<Suspense fallback={<Skeleton />}>
|
||||||
|
<DataComponent />
|
||||||
|
</Suspense>
|
||||||
|
|
||||||
|
function DataComponent() {
|
||||||
|
const { data } = useSuspenseQuery({...});
|
||||||
|
return <div>{data}</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ❌ Avoid: useQuery with manual loading
|
||||||
|
function DataComponent() {
|
||||||
|
const { data, isPending } = useQuery({...});
|
||||||
|
if (isPending) return <Spinner />;
|
||||||
|
return <div>{data}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Consistent Query Keys
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ✅ Good: Use key factories
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: postKeys.detail(id),
|
||||||
|
queryFn: () => postsApi.get(id)
|
||||||
|
});
|
||||||
|
|
||||||
|
// ❌ Avoid: Inconsistent keys
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['post', id], // Different format
|
||||||
|
queryFn: () => postsApi.get(id)
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Centralized API Services
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// ✅ Good: API service
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: postsApi.getAll
|
||||||
|
});
|
||||||
|
|
||||||
|
// ❌ Avoid: Inline fetching
|
||||||
|
const { data } = useSuspenseQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: async () => {
|
||||||
|
const res = await fetch('/api/posts');
|
||||||
|
return res.json();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Additional Resources
|
||||||
|
|
||||||
|
For more patterns, see:
|
||||||
|
|
||||||
|
- [data-fetching.md](resources/data-fetching.md) - Advanced patterns
|
||||||
|
- [cache-strategies.md](resources/cache-strategies.md) - Cache management
|
||||||
|
- [mutation-patterns.md](resources/mutation-patterns.md) - Complex mutations
|
||||||
252
.agents/skills/tanstack-query/resources/cache-strategies.md
Normal file
252
.agents/skills/tanstack-query/resources/cache-strategies.md
Normal file
@@ -0,0 +1,252 @@
|
|||||||
|
# Cache Management Strategies
|
||||||
|
|
||||||
|
## Cache Time Configuration
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: fetchPosts,
|
||||||
|
staleTime: 5 * 60 * 1000, // Consider fresh for 5 minutes
|
||||||
|
gcTime: 10 * 60 * 1000 // Keep in cache for 10 minutes (formerly cacheTime)
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cache Invalidation
|
||||||
|
|
||||||
|
### Invalidate Specific Queries
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
// Invalidate all post queries
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
|
||||||
|
// Invalidate specific post
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['post', postId] });
|
||||||
|
|
||||||
|
// Invalidate with exact match
|
||||||
|
queryClient.invalidateQueries({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
exact: true // Only ['posts'], not ['posts', 'list']
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Invalidate on Mutation
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onSuccess: () => {
|
||||||
|
// Invalidate and refetch
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Manual Cache Updates
|
||||||
|
|
||||||
|
### Set Query Data
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Update cache directly
|
||||||
|
queryClient.setQueryData(['post', postId], (oldData) => ({
|
||||||
|
...oldData,
|
||||||
|
title: 'New Title'
|
||||||
|
}));
|
||||||
|
|
||||||
|
// Set new data
|
||||||
|
queryClient.setQueryData(['post', postId], newPost);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get Query Data
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Read from cache
|
||||||
|
const cachedPost = queryClient.getQueryData(['post', postId]);
|
||||||
|
|
||||||
|
// Use in initialData
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId),
|
||||||
|
initialData: () => queryClient.getQueryData(['posts'])?.find((p) => p.id === postId)
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Refetch Strategies
|
||||||
|
|
||||||
|
### Refetch on Window Focus
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: fetchPosts,
|
||||||
|
refetchOnWindowFocus: true // Refetch when tab regains focus
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Refetch on Reconnect
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: fetchPosts,
|
||||||
|
refetchOnReconnect: true // Refetch when internet reconnects
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Refetch Intervals
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['live-data'],
|
||||||
|
queryFn: fetchLiveData,
|
||||||
|
refetchInterval: 5000, // Refetch every 5 seconds
|
||||||
|
refetchIntervalInBackground: false // Pause when tab not active
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cache Persistence
|
||||||
|
|
||||||
|
### Persist to localStorage
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { QueryClient } from '@tanstack/react-query';
|
||||||
|
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
|
||||||
|
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
|
||||||
|
|
||||||
|
const queryClient = new QueryClient({
|
||||||
|
defaultOptions: {
|
||||||
|
queries: {
|
||||||
|
gcTime: 1000 * 60 * 60 * 24 // 24 hours
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
const persister = createSyncStoragePersister({
|
||||||
|
storage: window.localStorage
|
||||||
|
});
|
||||||
|
|
||||||
|
<PersistQueryClientProvider
|
||||||
|
client={queryClient}
|
||||||
|
persister={persister}
|
||||||
|
>
|
||||||
|
<App />
|
||||||
|
</PersistQueryClientProvider>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cache Deduplication
|
||||||
|
|
||||||
|
### Automatic Request Deduplication
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Both components will share the same request
|
||||||
|
function Component1() {
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: fetchPosts
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function Component2() {
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['posts'], // Same key = same request
|
||||||
|
queryFn: fetchPosts
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cache Preloading
|
||||||
|
|
||||||
|
### Prefetch Queries
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
// Prefetch before navigation
|
||||||
|
const handleMouseEnter = () => {
|
||||||
|
queryClient.prefetchQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId)
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
// Prefetch in loader
|
||||||
|
router.beforeEach(async (to, from, next) => {
|
||||||
|
await queryClient.prefetchQuery({
|
||||||
|
queryKey: ['user', to.params.userId],
|
||||||
|
queryFn: () => fetchUser(to.params.userId)
|
||||||
|
});
|
||||||
|
next();
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ensure Query Data
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Fetch if not in cache, otherwise use cached
|
||||||
|
await queryClient.ensureQueryData({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId)
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Selective Cache Updates
|
||||||
|
|
||||||
|
### Update Nested Data
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
queryClient.setQueryData(['posts'], (oldPosts) => {
|
||||||
|
return oldPosts.map((post) => (post.id === updatedPost.id ? updatedPost : post));
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Add to List Cache
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// After creating a post
|
||||||
|
queryClient.setQueryData(['posts'], (oldPosts = []) => {
|
||||||
|
return [newPost, ...oldPosts];
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Remove from List Cache
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// After deleting a post
|
||||||
|
queryClient.setQueryData(['posts'], (oldPosts) => {
|
||||||
|
return oldPosts.filter((post) => post.id !== deletedPostId);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Cache Debugging
|
||||||
|
|
||||||
|
### React Query Devtools
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
|
||||||
|
|
||||||
|
<QueryClientProvider client={queryClient}>
|
||||||
|
<App />
|
||||||
|
<ReactQueryDevtools initialIsOpen={false} />
|
||||||
|
</QueryClientProvider>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Query Cache Events
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const queryCache = queryClient.getQueryCache();
|
||||||
|
|
||||||
|
queryCache.subscribe((event) => {
|
||||||
|
console.log('Query cache event:', event.type, event.query.queryKey);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Set Appropriate staleTime** - Balance freshness vs performance
|
||||||
|
2. **Use Invalidation Over Refetch** - Let queries refetch when needed
|
||||||
|
3. **Prefetch Predictably** - Preload data on hover/intent
|
||||||
|
4. **Update Cache on Mutations** - Keep UI in sync
|
||||||
|
5. **Use Devtools** - Debug cache issues visually
|
||||||
|
6. **Persist Important Data** - Save to localStorage for offline support
|
||||||
|
7. **Deduplicate Requests** - Rely on automatic deduplication
|
||||||
240
.agents/skills/tanstack-query/resources/data-fetching.md
Normal file
240
.agents/skills/tanstack-query/resources/data-fetching.md
Normal file
@@ -0,0 +1,240 @@
|
|||||||
|
# Advanced Data Fetching Patterns with TanStack Query
|
||||||
|
|
||||||
|
## Dependent Queries
|
||||||
|
|
||||||
|
Queries that depend on data from other queries:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// First query - Get user ID
|
||||||
|
const { data: user } = useQuery({
|
||||||
|
queryKey: ['user'],
|
||||||
|
queryFn: fetchCurrentUser
|
||||||
|
});
|
||||||
|
|
||||||
|
// Second query - Depends on user ID
|
||||||
|
const { data: posts } = useQuery({
|
||||||
|
queryKey: ['posts', user?.id],
|
||||||
|
queryFn: () => fetchUserPosts(user!.id),
|
||||||
|
enabled: !!user // Only run when user is available
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parallel Queries
|
||||||
|
|
||||||
|
Fetch multiple independent queries simultaneously:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
function Dashboard() {
|
||||||
|
const queries = useQueries({
|
||||||
|
queries: [
|
||||||
|
{ queryKey: ['stats'], queryFn: fetchStats },
|
||||||
|
{ queryKey: ['recentPosts'], queryFn: fetchRecentPosts },
|
||||||
|
{ queryKey: ['notifications'], queryFn: fetchNotifications }
|
||||||
|
]
|
||||||
|
});
|
||||||
|
|
||||||
|
const [statsQuery, postsQuery, notificationsQuery] = queries;
|
||||||
|
|
||||||
|
if (queries.some(q => q.isLoading)) return <Loading />;
|
||||||
|
|
||||||
|
return <Dashboard
|
||||||
|
stats={statsQuery.data}
|
||||||
|
posts={postsQuery.data}
|
||||||
|
notifications={notificationsQuery.data}
|
||||||
|
/>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Infinite Queries
|
||||||
|
|
||||||
|
For pagination and infinite scroll:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const {
|
||||||
|
data,
|
||||||
|
fetchNextPage,
|
||||||
|
hasNextPage,
|
||||||
|
isFetchingNextPage
|
||||||
|
} = useInfiniteQuery({
|
||||||
|
queryKey: ['posts'],
|
||||||
|
queryFn: ({ pageParam = 1 }) => fetchPosts(pageParam),
|
||||||
|
getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
|
||||||
|
initialPageParam: 1
|
||||||
|
});
|
||||||
|
|
||||||
|
// Flatten pages
|
||||||
|
const allPosts = data?.pages.flatMap(page => page.posts) ?? [];
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
{allPosts.map(post => <PostCard key={post.id} post={post} />)}
|
||||||
|
{hasNextPage && (
|
||||||
|
<button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
|
||||||
|
{isFetchingNextPage ? 'Loading...' : 'Load More'}
|
||||||
|
</button>
|
||||||
|
)}
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prefetching
|
||||||
|
|
||||||
|
Preload data before it's needed:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useQueryClient } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
function PostLink({ postId }: { postId: string }) {
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
const handleMouseEnter = () => {
|
||||||
|
queryClient.prefetchQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId)
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Link to={`/posts/${postId}`} onMouseEnter={handleMouseEnter}>
|
||||||
|
View Post
|
||||||
|
</Link>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Suspense Mode
|
||||||
|
|
||||||
|
Use with React Suspense:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useSuspenseQuery } from '@tanstack/react-query';
|
||||||
|
|
||||||
|
function PostDetails({ postId }: { postId: string }) {
|
||||||
|
// Throws promise on loading, error on error
|
||||||
|
const { data: post } = useSuspenseQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId)
|
||||||
|
});
|
||||||
|
|
||||||
|
return <div>{post.title}</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Wrap with Suspense
|
||||||
|
<Suspense fallback={<Loading />}>
|
||||||
|
<PostDetails postId="123" />
|
||||||
|
</Suspense>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Query Cancellation
|
||||||
|
|
||||||
|
Cancel queries when component unmounts:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data, isLoading } = useQuery({
|
||||||
|
queryKey: ['search', searchTerm],
|
||||||
|
queryFn: async ({ signal }) => {
|
||||||
|
const response = await fetch(`/api/search?q=${searchTerm}`, { signal });
|
||||||
|
return response.json();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Initial Data
|
||||||
|
|
||||||
|
Provide initial data to avoid loading state:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId),
|
||||||
|
initialData: () => {
|
||||||
|
// Get from cache or other source
|
||||||
|
return queryClient.getQueryData(['posts'])?.find((post) => post.id === postId);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Placeholder Data
|
||||||
|
|
||||||
|
Show placeholder while loading:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data, isPlaceholderData } = useQuery({
|
||||||
|
queryKey: ['posts', page],
|
||||||
|
queryFn: () => fetchPosts(page),
|
||||||
|
placeholderData: (previousData) => previousData // Keep previous page while loading
|
||||||
|
});
|
||||||
|
|
||||||
|
// Or provide static placeholder
|
||||||
|
placeholderData: { posts: [], total: 0 }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Optimistic Updates with Queries
|
||||||
|
|
||||||
|
Update UI immediately, rollback on error:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const queryClient = useQueryClient();
|
||||||
|
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: updatePost,
|
||||||
|
onMutate: async (newPost) => {
|
||||||
|
// Cancel outgoing queries
|
||||||
|
await queryClient.cancelQueries({ queryKey: ['post', newPost.id] });
|
||||||
|
|
||||||
|
// Snapshot current value
|
||||||
|
const previousPost = queryClient.getQueryData(['post', newPost.id]);
|
||||||
|
|
||||||
|
// Optimistically update
|
||||||
|
queryClient.setQueryData(['post', newPost.id], newPost);
|
||||||
|
|
||||||
|
return { previousPost };
|
||||||
|
},
|
||||||
|
onError: (err, newPost, context) => {
|
||||||
|
// Rollback on error
|
||||||
|
queryClient.setQueryData(['post', newPost.id], context?.previousPost);
|
||||||
|
},
|
||||||
|
onSettled: (newPost) => {
|
||||||
|
// Refetch after success or error
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['post', newPost.id] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Query Retries
|
||||||
|
|
||||||
|
Configure retry behavior:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data } = useQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId),
|
||||||
|
retry: 3, // Retry 3 times
|
||||||
|
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000) // Exponential backoff
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
Handle query errors:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { data, error, isError } = useQuery({
|
||||||
|
queryKey: ['post', postId],
|
||||||
|
queryFn: () => fetchPost(postId),
|
||||||
|
throwOnError: false // Don't throw, just set error
|
||||||
|
});
|
||||||
|
|
||||||
|
if (isError) {
|
||||||
|
return <ErrorMessage error={error} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Use Suspense** - Better loading UX with React Suspense
|
||||||
|
2. **Prefetch on Intent** - Preload data on hover/focus
|
||||||
|
3. **Enable Queries Conditionally** - Use `enabled` option
|
||||||
|
4. **Cancel on Unmount** - Use abort signals
|
||||||
|
5. **Handle Errors Gracefully** - Show error states
|
||||||
|
6. **Optimize with Placeholders** - Show previous data while loading
|
||||||
344
.agents/skills/tanstack-query/resources/mutation-patterns.md
Normal file
344
.agents/skills/tanstack-query/resources/mutation-patterns.md
Normal file
@@ -0,0 +1,344 @@
|
|||||||
|
# Complex Mutation Patterns
|
||||||
|
|
||||||
|
## Basic Mutations
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate, isPending, isError, error } = useMutation({
|
||||||
|
mutationFn: (newPost: CreatePostDto) => createPost(newPost),
|
||||||
|
onSuccess: (data) => {
|
||||||
|
console.log('Post created:', data);
|
||||||
|
},
|
||||||
|
onError: (error) => {
|
||||||
|
console.error('Failed to create post:', error);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Trigger mutation
|
||||||
|
mutate({ title: 'New Post', content: '...' });
|
||||||
|
```
|
||||||
|
|
||||||
|
## Optimistic Updates
|
||||||
|
|
||||||
|
Update UI immediately, rollback on error:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: updatePost,
|
||||||
|
onMutate: async (newPost) => {
|
||||||
|
// Cancel outgoing refetches
|
||||||
|
await queryClient.cancelQueries({ queryKey: ['posts'] });
|
||||||
|
|
||||||
|
// Snapshot previous value
|
||||||
|
const previousPosts = queryClient.getQueryData(['posts']);
|
||||||
|
|
||||||
|
// Optimistically update to the new value
|
||||||
|
queryClient.setQueryData(['posts'], (old) =>
|
||||||
|
old.map((post) => (post.id === newPost.id ? newPost : post))
|
||||||
|
);
|
||||||
|
|
||||||
|
// Return context with snapshot
|
||||||
|
return { previousPosts };
|
||||||
|
},
|
||||||
|
onError: (err, newPost, context) => {
|
||||||
|
// Rollback to previous value
|
||||||
|
queryClient.setQueryData(['posts'], context.previousPosts);
|
||||||
|
},
|
||||||
|
onSettled: () => {
|
||||||
|
// Always refetch after error or success
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Sequential Mutations
|
||||||
|
|
||||||
|
Run mutations in sequence:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const createAndPublish = async (postData) => {
|
||||||
|
// Create post
|
||||||
|
const post = await createPostMutation.mutateAsync(postData);
|
||||||
|
|
||||||
|
// Publish post
|
||||||
|
const published = await publishPostMutation.mutateAsync(post.id);
|
||||||
|
|
||||||
|
return published;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parallel Mutations
|
||||||
|
|
||||||
|
Run multiple mutations simultaneously:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: async (updates) => {
|
||||||
|
const results = await Promise.all([
|
||||||
|
updateProfile(updates.profile),
|
||||||
|
updateSettings(updates.settings),
|
||||||
|
updatePreferences(updates.preferences)
|
||||||
|
]);
|
||||||
|
return results;
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation with Invalidation
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onSuccess: () => {
|
||||||
|
// Invalidate and refetch
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['posts'] });
|
||||||
|
|
||||||
|
// Or update cache directly
|
||||||
|
queryClient.setQueryData(['posts'], (old) => [newPost, ...old]);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation with Multiple Cache Updates
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: deletePost,
|
||||||
|
onSuccess: (_, deletedPostId) => {
|
||||||
|
// Update posts list
|
||||||
|
queryClient.setQueryData(['posts'], (old) => old.filter((post) => post.id !== deletedPostId));
|
||||||
|
|
||||||
|
// Update post count
|
||||||
|
queryClient.setQueryData(['postsCount'], (old) => old - 1);
|
||||||
|
|
||||||
|
// Invalidate related queries
|
||||||
|
queryClient.invalidateQueries({ queryKey: ['user', 'stats'] });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate, isError, error, reset } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onError: (error) => {
|
||||||
|
if (error.code === 'VALIDATION_ERROR') {
|
||||||
|
setFormErrors(error.fields);
|
||||||
|
} else if (error.code === 'NETWORK_ERROR') {
|
||||||
|
showRetryDialog();
|
||||||
|
} else {
|
||||||
|
showGenericError();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// Clear error state
|
||||||
|
reset();
|
||||||
|
```
|
||||||
|
|
||||||
|
## Retry Failed Mutations
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
retry: 3, // Retry 3 times on failure
|
||||||
|
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000) // Exponential backoff
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation with Loading State
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
function CreatePostForm() {
|
||||||
|
const { mutate, isPending } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onSuccess: () => {
|
||||||
|
navigate('/posts');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
const handleSubmit = (data) => {
|
||||||
|
mutate(data);
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<form onSubmit={handleSubmit}>
|
||||||
|
{/* form fields */}
|
||||||
|
<button type="submit" disabled={isPending}>
|
||||||
|
{isPending ? 'Creating...' : 'Create Post'}
|
||||||
|
</button>
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation with Variables
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate, variables } = useMutation({
|
||||||
|
mutationFn: updatePost
|
||||||
|
});
|
||||||
|
|
||||||
|
// Access last mutation variables
|
||||||
|
console.log('Last updated post:', variables);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation Callbacks
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onMutate: (variables) => {
|
||||||
|
console.log('Starting mutation with:', variables);
|
||||||
|
},
|
||||||
|
onSuccess: (data, variables, context) => {
|
||||||
|
console.log('Success!', data);
|
||||||
|
},
|
||||||
|
onError: (error, variables, context) => {
|
||||||
|
console.error('Error!', error);
|
||||||
|
},
|
||||||
|
onSettled: (data, error, variables, context) => {
|
||||||
|
console.log('Mutation finished (success or error)');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation with Form Integration
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { useForm } from 'react-hook-form';
|
||||||
|
|
||||||
|
function CreatePostForm() {
|
||||||
|
const { register, handleSubmit, reset } = useForm();
|
||||||
|
|
||||||
|
const { mutate, isPending, isError, error } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onSuccess: () => {
|
||||||
|
reset(); // Clear form
|
||||||
|
toast.success('Post created!');
|
||||||
|
},
|
||||||
|
onError: (error) => {
|
||||||
|
toast.error(error.message);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
const onSubmit = (data) => {
|
||||||
|
mutate(data);
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<form onSubmit={handleSubmit(onSubmit)}>
|
||||||
|
<input {...register('title')} />
|
||||||
|
<textarea {...register('content')} />
|
||||||
|
<button type="submit" disabled={isPending}>
|
||||||
|
Submit
|
||||||
|
</button>
|
||||||
|
{isError && <ErrorMessage error={error} />}
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation State Reset
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate, data, error, reset } = useMutation({
|
||||||
|
mutationFn: createPost
|
||||||
|
});
|
||||||
|
|
||||||
|
// Clear mutation state
|
||||||
|
const handleReset = () => {
|
||||||
|
reset(); // Clears data, error, status, etc.
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Global Mutation Configuration
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const queryClient = new QueryClient({
|
||||||
|
defaultOptions: {
|
||||||
|
mutations: {
|
||||||
|
retry: 3,
|
||||||
|
retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
|
||||||
|
onError: (error) => {
|
||||||
|
// Global error handler
|
||||||
|
console.error('Mutation error:', error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Mutation Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐
|
||||||
|
│ idle │
|
||||||
|
└──────┬──────┘
|
||||||
|
│ mutate()
|
||||||
|
▼
|
||||||
|
┌─────────────┐
|
||||||
|
│ pending │ ─── onMutate()
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
├─ success ──► onSuccess() ──┐
|
||||||
|
│ │
|
||||||
|
└─ error ────► onError() ────┤
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
onSettled()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Use Optimistic Updates** - Better UX for fast operations
|
||||||
|
2. **Always Handle Errors** - Show clear error messages
|
||||||
|
3. **Invalidate Related Queries** - Keep cache in sync
|
||||||
|
4. **Use onSettled** - For cleanup that runs regardless of success/error
|
||||||
|
5. **Reset on Unmount** - Clear mutation state when component unmounts
|
||||||
|
6. **Retry Network Errors** - Configure retry for transient failures
|
||||||
|
7. **Show Loading States** - Disable buttons during mutation
|
||||||
|
8. **Rollback on Error** - Revert optimistic updates if mutation fails
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Create with Redirect
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: createPost,
|
||||||
|
onSuccess: (newPost) => {
|
||||||
|
navigate(`/posts/${newPost.id}`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Update with Toast
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: updatePost,
|
||||||
|
onSuccess: () => {
|
||||||
|
toast.success('Post updated!');
|
||||||
|
},
|
||||||
|
onError: () => {
|
||||||
|
toast.error('Failed to update post');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Delete with Confirmation
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const { mutate } = useMutation({
|
||||||
|
mutationFn: deletePost,
|
||||||
|
onMutate: async () => {
|
||||||
|
const confirmed = await confirm('Are you sure?');
|
||||||
|
if (!confirmed) throw new Error('Cancelled');
|
||||||
|
},
|
||||||
|
onSuccess: () => {
|
||||||
|
toast.success('Post deleted');
|
||||||
|
navigate('/posts');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
86
.agents/skills/tanstack-query/skill-rules-fragment.json
Normal file
86
.agents/skills/tanstack-query/skill-rules-fragment.json
Normal file
@@ -0,0 +1,86 @@
|
|||||||
|
{
|
||||||
|
"tanstack-query": {
|
||||||
|
"type": "domain",
|
||||||
|
"enforcement": "suggest",
|
||||||
|
"priority": "high",
|
||||||
|
"promptTriggers": {
|
||||||
|
"keywords": [
|
||||||
|
"tanstack query",
|
||||||
|
"react query",
|
||||||
|
"@tanstack/react-query",
|
||||||
|
"useQuery",
|
||||||
|
"useMutation",
|
||||||
|
"useSuspenseQuery",
|
||||||
|
"useInfiniteQuery",
|
||||||
|
"useQueries",
|
||||||
|
"useQueryClient",
|
||||||
|
"useIsFetching",
|
||||||
|
"useIsMutating",
|
||||||
|
"useMutationState",
|
||||||
|
"QueryClient",
|
||||||
|
"QueryClientProvider",
|
||||||
|
"queryKey",
|
||||||
|
"queryFn",
|
||||||
|
"mutationFn",
|
||||||
|
"invalidateQueries",
|
||||||
|
"setQueryData",
|
||||||
|
"getQueryData",
|
||||||
|
"removeQueries",
|
||||||
|
"resetQueries",
|
||||||
|
"staleTime",
|
||||||
|
"cacheTime",
|
||||||
|
"refetchInterval",
|
||||||
|
"refetchOnWindowFocus",
|
||||||
|
"refetchOnReconnect",
|
||||||
|
"isLoading",
|
||||||
|
"isError",
|
||||||
|
"isFetching",
|
||||||
|
"isSuccess",
|
||||||
|
"queryCache",
|
||||||
|
"mutationCache"
|
||||||
|
],
|
||||||
|
"intentPatterns": [
|
||||||
|
"use.*tanstack.*query",
|
||||||
|
"use.*react.*query",
|
||||||
|
"create.*tanstack.*(query|mutation)",
|
||||||
|
"invalidate.*query.*cache",
|
||||||
|
"invalidate.*tanstack.*queries",
|
||||||
|
"prefetch.*query",
|
||||||
|
"setup.*query.*client",
|
||||||
|
"configure.*tanstack.*query",
|
||||||
|
"use.*(useQuery|useMutation|useInfiniteQuery)",
|
||||||
|
"implement.*query.*invalidation",
|
||||||
|
"add.*query.*key",
|
||||||
|
"set.*query.*data"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"fileTriggers": {
|
||||||
|
"pathPatterns": [
|
||||||
|
"**/api/**/*.ts",
|
||||||
|
"**/api/**/*.tsx",
|
||||||
|
"**/queries/**/*.ts",
|
||||||
|
"**/queries/**/*.tsx",
|
||||||
|
"**/hooks/**/*.ts",
|
||||||
|
"**/hooks/**/*.tsx",
|
||||||
|
"**/mutations/**/*.ts",
|
||||||
|
"**/mutations/**/*.tsx"
|
||||||
|
],
|
||||||
|
"contentPatterns": [
|
||||||
|
"useQuery\\(",
|
||||||
|
"useMutation\\(",
|
||||||
|
"useSuspenseQuery\\(",
|
||||||
|
"useInfiniteQuery\\(",
|
||||||
|
"useQueryClient\\(",
|
||||||
|
"queryClient\\.",
|
||||||
|
"import.*@tanstack/react-query",
|
||||||
|
"from '@tanstack/react-query'",
|
||||||
|
"QueryClientProvider",
|
||||||
|
"new QueryClient\\(",
|
||||||
|
"invalidateQueries\\(",
|
||||||
|
"setQueryData\\(",
|
||||||
|
"queryKey:",
|
||||||
|
"queryFn:"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
917
.agents/skills/vercel-composition-patterns/AGENTS.md
Normal file
917
.agents/skills/vercel-composition-patterns/AGENTS.md
Normal file
@@ -0,0 +1,917 @@
|
|||||||
|
# React Composition Patterns
|
||||||
|
|
||||||
|
**Version 1.0.0**
|
||||||
|
Engineering
|
||||||
|
January 2026
|
||||||
|
|
||||||
|
> **Note:**
|
||||||
|
> This document is mainly for agents and LLMs to follow when maintaining,
|
||||||
|
> generating, or refactoring React codebases using composition. Humans
|
||||||
|
> may also find it useful, but guidance here is optimized for automation
|
||||||
|
> and consistency by AI-assisted workflows.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Abstract
|
||||||
|
|
||||||
|
Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Component Architecture](#1-component-architecture) — **HIGH**
|
||||||
|
- 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
|
||||||
|
- 1.2 [Use Compound Components](#12-use-compound-components)
|
||||||
|
2. [State Management](#2-state-management) — **MEDIUM**
|
||||||
|
- 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
|
||||||
|
- 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
|
||||||
|
- 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
|
||||||
|
3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
|
||||||
|
- 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
|
||||||
|
- 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
|
||||||
|
4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
|
||||||
|
- 4.1 [React 19 API Changes](#41-react-19-api-changes)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Component Architecture
|
||||||
|
|
||||||
|
**Impact: HIGH**
|
||||||
|
|
||||||
|
Fundamental patterns for structuring components to avoid prop
|
||||||
|
proliferation and enable flexible composition.
|
||||||
|
|
||||||
|
### 1.1 Avoid Boolean Prop Proliferation
|
||||||
|
|
||||||
|
**Impact: CRITICAL (prevents unmaintainable component variants)**
|
||||||
|
|
||||||
|
Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
|
||||||
|
|
||||||
|
component behavior. Each boolean doubles possible states and creates
|
||||||
|
|
||||||
|
unmaintainable conditional logic. Use composition instead.
|
||||||
|
|
||||||
|
**Incorrect: boolean props create exponential complexity**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
onSubmit,
|
||||||
|
isThread,
|
||||||
|
channelId,
|
||||||
|
isDMThread,
|
||||||
|
dmId,
|
||||||
|
isEditing,
|
||||||
|
isForwarding
|
||||||
|
}: Props) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
<Header />
|
||||||
|
<Input />
|
||||||
|
{isDMThread ? (
|
||||||
|
<AlsoSendToDMField id={dmId} />
|
||||||
|
) : isThread ? (
|
||||||
|
<AlsoSendToChannelField id={channelId} />
|
||||||
|
) : null}
|
||||||
|
{isEditing ? <EditActions /> : isForwarding ? <ForwardActions /> : <DefaultActions />}
|
||||||
|
<Footer onSubmit={onSubmit} />
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: composition eliminates conditionals**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Channel composer
|
||||||
|
function ChannelComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Attachments />
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Thread composer - adds "also send to channel" field
|
||||||
|
function ThreadComposer({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<AlsoSendToChannelField id={channelId} />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Edit composer - different footer actions
|
||||||
|
function EditComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.CancelEdit />
|
||||||
|
<Composer.SaveEdit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each variant is explicit about what it renders. We can share internals without
|
||||||
|
|
||||||
|
sharing a single monolithic parent.
|
||||||
|
|
||||||
|
### 1.2 Use Compound Components
|
||||||
|
|
||||||
|
**Impact: HIGH (enables flexible composition without prop drilling)**
|
||||||
|
|
||||||
|
Structure complex components as compound components with a shared context. Each
|
||||||
|
|
||||||
|
subcomponent accesses shared state via context, not props. Consumers compose the
|
||||||
|
|
||||||
|
pieces they need.
|
||||||
|
|
||||||
|
**Incorrect: monolithic component with render props**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
renderHeader,
|
||||||
|
renderFooter,
|
||||||
|
renderActions,
|
||||||
|
showAttachments,
|
||||||
|
showFormatting,
|
||||||
|
showEmojis
|
||||||
|
}: Props) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
{renderHeader?.()}
|
||||||
|
<Input />
|
||||||
|
{showAttachments && <Attachments />}
|
||||||
|
{renderFooter ? (
|
||||||
|
renderFooter()
|
||||||
|
) : (
|
||||||
|
<Footer>
|
||||||
|
{showFormatting && <Formatting />}
|
||||||
|
{showEmojis && <Emojis />}
|
||||||
|
{renderActions?.()}
|
||||||
|
</Footer>
|
||||||
|
)}
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: compound components with shared context**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const ComposerContext = createContext<ComposerContextValue | null>(null);
|
||||||
|
|
||||||
|
function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
|
||||||
|
return <ComposerContext value={{ state, actions, meta }}>{children}</ComposerContext>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerFrame({ children }: { children: React.ReactNode }) {
|
||||||
|
return <form>{children}</form>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerInput() {
|
||||||
|
const {
|
||||||
|
state,
|
||||||
|
actions: { update },
|
||||||
|
meta: { inputRef }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return (
|
||||||
|
<TextInput
|
||||||
|
ref={inputRef}
|
||||||
|
value={state.input}
|
||||||
|
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerSubmit() {
|
||||||
|
const {
|
||||||
|
actions: { submit }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return <Button onPress={submit}>Send</Button>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Export as compound component
|
||||||
|
const Composer = {
|
||||||
|
Provider: ComposerProvider,
|
||||||
|
Frame: ComposerFrame,
|
||||||
|
Input: ComposerInput,
|
||||||
|
Submit: ComposerSubmit,
|
||||||
|
Header: ComposerHeader,
|
||||||
|
Footer: ComposerFooter,
|
||||||
|
Attachments: ComposerAttachments,
|
||||||
|
Formatting: ComposerFormatting,
|
||||||
|
Emojis: ComposerEmojis
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Composer.Provider state={state} actions={actions} meta={meta}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</Composer.Provider>
|
||||||
|
```
|
||||||
|
|
||||||
|
Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. State Management
|
||||||
|
|
||||||
|
**Impact: MEDIUM**
|
||||||
|
|
||||||
|
Patterns for lifting state and managing shared context across
|
||||||
|
composed components.
|
||||||
|
|
||||||
|
### 2.1 Decouple State Management from UI
|
||||||
|
|
||||||
|
**Impact: MEDIUM (enables swapping state implementations without changing UI)**
|
||||||
|
|
||||||
|
The provider component should be the only place that knows how state is managed.
|
||||||
|
|
||||||
|
UI components consume the context interface—they don't know if state comes from
|
||||||
|
|
||||||
|
useState, Zustand, or a server sync.
|
||||||
|
|
||||||
|
**Incorrect: UI coupled to state implementation**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ChannelComposer({ channelId }: { channelId: string }) {
|
||||||
|
// UI component knows about global state implementation
|
||||||
|
const state = useGlobalChannelState(channelId);
|
||||||
|
const { submit, updateInput } = useChannelSync(channelId);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input value={state.input} onChange={(text) => sync.updateInput(text)} />
|
||||||
|
<Composer.Submit onPress={() => sync.submit()} />
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: state management isolated in provider**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Provider handles all state management details
|
||||||
|
function ChannelProvider({
|
||||||
|
channelId,
|
||||||
|
children
|
||||||
|
}: {
|
||||||
|
channelId: string;
|
||||||
|
children: React.ReactNode;
|
||||||
|
}) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update, submit }} meta={{ inputRef }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// UI component only knows about the context interface
|
||||||
|
function ChannelComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage
|
||||||
|
function Channel({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<ChannelProvider channelId={channelId}>
|
||||||
|
<ChannelComposer />
|
||||||
|
</ChannelProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Different providers, same UI:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Local state for ephemeral forms
|
||||||
|
function ForwardMessageProvider({ children }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update: setState, submit: forwardMessage }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Global synced state for channels
|
||||||
|
function ChannelProvider({ channelId, children }) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update, submit }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The same `Composer.Input` component works with both providers because it only
|
||||||
|
|
||||||
|
depends on the context interface, not the implementation.
|
||||||
|
|
||||||
|
### 2.2 Define Generic Context Interfaces for Dependency Injection
|
||||||
|
|
||||||
|
**Impact: HIGH (enables dependency-injectable state across use-cases)**
|
||||||
|
|
||||||
|
Define a **generic interface** for your component context with three parts:
|
||||||
|
|
||||||
|
`state`, `actions`, and `meta`. This interface is a contract that any provider
|
||||||
|
|
||||||
|
can implement—enabling the same UI components to work with completely different
|
||||||
|
|
||||||
|
state implementations.
|
||||||
|
|
||||||
|
**Core principle:** Lift state, compose internals, make state
|
||||||
|
|
||||||
|
dependency-injectable.
|
||||||
|
|
||||||
|
**Incorrect: UI coupled to specific state implementation**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput() {
|
||||||
|
// Tightly coupled to a specific hook
|
||||||
|
const { input, setInput } = useChannelComposerState();
|
||||||
|
return <TextInput value={input} onChangeText={setInput} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: generic interface enables dependency injection**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Define a GENERIC interface that any provider can implement
|
||||||
|
interface ComposerState {
|
||||||
|
input: string;
|
||||||
|
attachments: Attachment[];
|
||||||
|
isSubmitting: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerActions {
|
||||||
|
update: (updater: (state: ComposerState) => ComposerState) => void;
|
||||||
|
submit: () => void;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerMeta {
|
||||||
|
inputRef: React.RefObject<TextInput>;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerContextValue {
|
||||||
|
state: ComposerState;
|
||||||
|
actions: ComposerActions;
|
||||||
|
meta: ComposerMeta;
|
||||||
|
}
|
||||||
|
|
||||||
|
const ComposerContext = createContext<ComposerContextValue | null>(null);
|
||||||
|
```
|
||||||
|
|
||||||
|
**UI components consume the interface, not the implementation:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput() {
|
||||||
|
const {
|
||||||
|
state,
|
||||||
|
actions: { update },
|
||||||
|
meta
|
||||||
|
} = use(ComposerContext);
|
||||||
|
|
||||||
|
// This component works with ANY provider that implements the interface
|
||||||
|
return (
|
||||||
|
<TextInput
|
||||||
|
ref={meta.inputRef}
|
||||||
|
value={state.input}
|
||||||
|
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Different providers implement the same interface:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Provider A: Local state for ephemeral forms
|
||||||
|
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
const submit = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ComposerContext
|
||||||
|
value={{
|
||||||
|
state,
|
||||||
|
actions: { update: setState, submit },
|
||||||
|
meta: { inputRef }
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</ComposerContext>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Provider B: Global synced state for channels
|
||||||
|
function ChannelProvider({ channelId, children }: Props) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ComposerContext
|
||||||
|
value={{
|
||||||
|
state,
|
||||||
|
actions: { update, submit },
|
||||||
|
meta: { inputRef }
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</ComposerContext>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**The same composed UI works with both:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Works with ForwardMessageProvider (local state)
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Frame>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
|
||||||
|
// Works with ChannelProvider (global synced state)
|
||||||
|
<ChannelProvider channelId="abc">
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Frame>
|
||||||
|
</ChannelProvider>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Custom UI outside the component can access state and actions:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Dialog>
|
||||||
|
{/* The composer UI */}
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input placeholder="Add a message, if you'd like." />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
|
||||||
|
{/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
|
||||||
|
<MessagePreview />
|
||||||
|
|
||||||
|
{/* Actions at the bottom of the dialog */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton />
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
|
||||||
|
function ForwardButton() {
|
||||||
|
const {
|
||||||
|
actions: { submit }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return <Button onPress={submit}>Forward</Button>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// This preview lives OUTSIDE Composer.Frame but can read composer's state!
|
||||||
|
function MessagePreview() {
|
||||||
|
const { state } = use(ComposerContext);
|
||||||
|
return <Preview message={state.input} attachments={state.attachments} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The provider boundary is what matters—not the visual nesting. Components that
|
||||||
|
|
||||||
|
need shared state don't have to be inside the `Composer.Frame`. They just need
|
||||||
|
|
||||||
|
to be within the provider.
|
||||||
|
|
||||||
|
The `ForwardButton` and `MessagePreview` are not visually inside the composer
|
||||||
|
|
||||||
|
box, but they can still access its state and actions. This is the power of
|
||||||
|
|
||||||
|
lifting state into providers.
|
||||||
|
|
||||||
|
The UI is reusable bits you compose together. The state is dependency-injected
|
||||||
|
|
||||||
|
by the provider. Swap the provider, keep the UI.
|
||||||
|
|
||||||
|
### 2.3 Lift State into Provider Components
|
||||||
|
|
||||||
|
**Impact: HIGH (enables state sharing outside component boundaries)**
|
||||||
|
|
||||||
|
Move state management into dedicated provider components. This allows sibling
|
||||||
|
|
||||||
|
components outside the main UI to access and modify state without prop drilling
|
||||||
|
|
||||||
|
or awkward refs.
|
||||||
|
|
||||||
|
**Incorrect: state trapped inside component**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageComposer() {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer />
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Problem: How does this button access composer state?
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer />
|
||||||
|
<MessagePreview /> {/* Needs composer state */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton /> {/* Needs to call submit */}
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect: useEffect to sync state up**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
const [input, setInput] = useState('');
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer onInputChange={setInput} />
|
||||||
|
<MessagePreview input={input} />
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageComposer({ onInputChange }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
useEffect(() => {
|
||||||
|
onInputChange(state.input); // Sync on every change 😬
|
||||||
|
}, [state.input]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect: reading state from ref on submit**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
const stateRef = useRef(null);
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer stateRef={stateRef} />
|
||||||
|
<ForwardButton onPress={() => submit(stateRef.current)} />
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: state lifted to provider**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider
|
||||||
|
state={state}
|
||||||
|
actions={{ update: setState, submit: forwardMessage }}
|
||||||
|
meta={{ inputRef }}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer />
|
||||||
|
<MessagePreview /> {/* Custom components can access state and actions */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton /> {/* Custom components can access state and actions */}
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardButton() {
|
||||||
|
const { actions } = use(Composer.Context);
|
||||||
|
return <Button onPress={actions.submit}>Forward</Button>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The ForwardButton lives outside the Composer.Frame but still has access to the
|
||||||
|
|
||||||
|
submit action because it's within the provider. Even though it's a one-off
|
||||||
|
|
||||||
|
component, it can still access the composer's state and actions from outside the
|
||||||
|
|
||||||
|
UI itself.
|
||||||
|
|
||||||
|
**Key insight:** Components that need shared state don't have to be visually
|
||||||
|
|
||||||
|
nested inside each other—they just need to be within the same provider.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Implementation Patterns
|
||||||
|
|
||||||
|
**Impact: MEDIUM**
|
||||||
|
|
||||||
|
Specific techniques for implementing compound components and
|
||||||
|
context providers.
|
||||||
|
|
||||||
|
### 3.1 Create Explicit Component Variants
|
||||||
|
|
||||||
|
**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
|
||||||
|
|
||||||
|
Instead of one component with many boolean props, create explicit variant
|
||||||
|
|
||||||
|
components. Each variant composes the pieces it needs. The code documents
|
||||||
|
|
||||||
|
itself.
|
||||||
|
|
||||||
|
**Incorrect: one component, many modes**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// What does this component actually render?
|
||||||
|
<Composer isThread isEditing={false} channelId='abc' showAttachments showFormatting={false} />
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: explicit variants**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Immediately clear what this renders
|
||||||
|
<ThreadComposer channelId="abc" />
|
||||||
|
|
||||||
|
// Or
|
||||||
|
<EditMessageComposer messageId="xyz" />
|
||||||
|
|
||||||
|
// Or
|
||||||
|
<ForwardMessageComposer messageId="123" />
|
||||||
|
```
|
||||||
|
|
||||||
|
Each implementation is unique, explicit and self-contained. Yet they can each
|
||||||
|
|
||||||
|
use shared parts.
|
||||||
|
|
||||||
|
**Implementation:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ThreadComposer({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<ThreadProvider channelId={channelId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<AlsoSendToChannelField channelId={channelId} />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</ThreadProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function EditMessageComposer({ messageId }: { messageId: string }) {
|
||||||
|
return (
|
||||||
|
<EditMessageProvider messageId={messageId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.CancelEdit />
|
||||||
|
<Composer.SaveEdit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</EditMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageComposer({ messageId }: { messageId: string }) {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider messageId={messageId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input placeholder="Add a message, if you'd like." />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Mentions />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each variant is explicit about:
|
||||||
|
|
||||||
|
- What provider/state it uses
|
||||||
|
|
||||||
|
- What UI elements it includes
|
||||||
|
|
||||||
|
- What actions are available
|
||||||
|
|
||||||
|
No boolean prop combinations to reason about. No impossible states.
|
||||||
|
|
||||||
|
### 3.2 Prefer Composing Children Over Render Props
|
||||||
|
|
||||||
|
**Impact: MEDIUM (cleaner composition, better readability)**
|
||||||
|
|
||||||
|
Use `children` for composition instead of `renderX` props. Children are more
|
||||||
|
|
||||||
|
readable, compose naturally, and don't require understanding callback
|
||||||
|
|
||||||
|
signatures.
|
||||||
|
|
||||||
|
**Incorrect: render props**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
renderHeader,
|
||||||
|
renderFooter,
|
||||||
|
renderActions
|
||||||
|
}: {
|
||||||
|
renderHeader?: () => React.ReactNode;
|
||||||
|
renderFooter?: () => React.ReactNode;
|
||||||
|
renderActions?: () => React.ReactNode;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
{renderHeader?.()}
|
||||||
|
<Input />
|
||||||
|
{renderFooter ? renderFooter() : <DefaultFooter />}
|
||||||
|
{renderActions?.()}
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage is awkward and inflexible
|
||||||
|
return (
|
||||||
|
<Composer
|
||||||
|
renderHeader={() => <CustomHeader />}
|
||||||
|
renderFooter={() => (
|
||||||
|
<>
|
||||||
|
<Formatting />
|
||||||
|
<Emojis />
|
||||||
|
</>
|
||||||
|
)}
|
||||||
|
renderActions={() => <SubmitButton />}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: compound components with children**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerFrame({ children }: { children: React.ReactNode }) {
|
||||||
|
return <form>{children}</form>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerFooter({ children }: { children: React.ReactNode }) {
|
||||||
|
return <footer className='flex'>{children}</footer>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage is flexible
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<CustomHeader />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<SubmitButton />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**When render props are appropriate:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Render props work well when you need to pass data back
|
||||||
|
<List data={items} renderItem={({ item, index }) => <Item item={item} index={index} />} />
|
||||||
|
```
|
||||||
|
|
||||||
|
Use render props when the parent needs to provide data or state to the child.
|
||||||
|
|
||||||
|
Use children when composing static structure.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. React 19 APIs
|
||||||
|
|
||||||
|
**Impact: MEDIUM**
|
||||||
|
|
||||||
|
React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
|
||||||
|
|
||||||
|
### 4.1 React 19 API Changes
|
||||||
|
|
||||||
|
**Impact: MEDIUM (cleaner component definitions and context usage)**
|
||||||
|
|
||||||
|
> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
|
||||||
|
|
||||||
|
In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
|
||||||
|
|
||||||
|
**Incorrect: forwardRef in React 19**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
|
||||||
|
return <TextInput ref={ref} {...props} />;
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: ref as a regular prop**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
|
||||||
|
return <TextInput ref={ref} {...props} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect: useContext in React 19**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const value = useContext(MyContext);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct: use instead of useContext**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const value = use(MyContext);
|
||||||
|
```
|
||||||
|
|
||||||
|
`use()` can also be called conditionally, unlike `useContext()`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
1. [https://react.dev](https://react.dev)
|
||||||
|
2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)
|
||||||
|
3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)
|
||||||
60
.agents/skills/vercel-composition-patterns/README.md
Normal file
60
.agents/skills/vercel-composition-patterns/README.md
Normal file
@@ -0,0 +1,60 @@
|
|||||||
|
# React Composition Patterns
|
||||||
|
|
||||||
|
A structured repository for React composition patterns that scale. These
|
||||||
|
patterns help avoid boolean prop proliferation by using compound components,
|
||||||
|
lifting state, and composing internals.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
- `rules/` - Individual rule files (one per rule)
|
||||||
|
- `_sections.md` - Section metadata (titles, impacts, descriptions)
|
||||||
|
- `_template.md` - Template for creating new rules
|
||||||
|
- `area-description.md` - Individual rule files
|
||||||
|
- `metadata.json` - Document metadata (version, organization, abstract)
|
||||||
|
- **`AGENTS.md`** - Compiled output (generated)
|
||||||
|
|
||||||
|
## Rules
|
||||||
|
|
||||||
|
### Component Architecture (CRITICAL)
|
||||||
|
|
||||||
|
- `architecture-avoid-boolean-props.md` - Don't add boolean props to customize
|
||||||
|
behavior
|
||||||
|
- `architecture-compound-components.md` - Structure as compound components with
|
||||||
|
shared context
|
||||||
|
|
||||||
|
### State Management (HIGH)
|
||||||
|
|
||||||
|
- `state-lift-state.md` - Lift state into provider components
|
||||||
|
- `state-context-interface.md` - Define clear context interfaces
|
||||||
|
(state/actions/meta)
|
||||||
|
- `state-decouple-implementation.md` - Decouple state management from UI
|
||||||
|
|
||||||
|
### Implementation Patterns (MEDIUM)
|
||||||
|
|
||||||
|
- `patterns-children-over-render-props.md` - Prefer children over renderX props
|
||||||
|
- `patterns-explicit-variants.md` - Create explicit component variants
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
1. **Composition over configuration** — Instead of adding props, let consumers
|
||||||
|
compose
|
||||||
|
2. **Lift your state** — State in providers, not trapped in components
|
||||||
|
3. **Compose your internals** — Subcomponents access context, not props
|
||||||
|
4. **Explicit variants** — Create ThreadComposer, EditComposer, not Composer
|
||||||
|
with isThread
|
||||||
|
|
||||||
|
## Creating a New Rule
|
||||||
|
|
||||||
|
1. Copy `rules/_template.md` to `rules/area-description.md`
|
||||||
|
2. Choose the appropriate area prefix:
|
||||||
|
- `architecture-` for Component Architecture
|
||||||
|
- `state-` for State Management
|
||||||
|
- `patterns-` for Implementation Patterns
|
||||||
|
3. Fill in the frontmatter and content
|
||||||
|
4. Ensure you have clear examples with explanations
|
||||||
|
|
||||||
|
## Impact Levels
|
||||||
|
|
||||||
|
- `CRITICAL` - Foundational patterns, prevents unmaintainable code
|
||||||
|
- `HIGH` - Significant maintainability improvements
|
||||||
|
- `MEDIUM` - Good practices for cleaner code
|
||||||
88
.agents/skills/vercel-composition-patterns/SKILL.md
Normal file
88
.agents/skills/vercel-composition-patterns/SKILL.md
Normal file
@@ -0,0 +1,88 @@
|
|||||||
|
---
|
||||||
|
name: vercel-composition-patterns
|
||||||
|
description: React composition patterns that scale. Use when refactoring components with
|
||||||
|
boolean prop proliferation, building flexible component libraries, or
|
||||||
|
designing reusable APIs. Triggers on tasks involving compound components,
|
||||||
|
render props, context providers, or component architecture. Includes React 19
|
||||||
|
API changes.
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: vercel
|
||||||
|
version: '1.0.0'
|
||||||
|
---
|
||||||
|
|
||||||
|
# React Composition Patterns
|
||||||
|
|
||||||
|
Composition patterns for building flexible, maintainable React components. Avoid
|
||||||
|
boolean prop proliferation by using compound components, lifting state, and
|
||||||
|
composing internals. These patterns make codebases easier for both humans and AI
|
||||||
|
agents to work with as they scale.
|
||||||
|
|
||||||
|
## When to Apply
|
||||||
|
|
||||||
|
Reference these guidelines when:
|
||||||
|
|
||||||
|
- Refactoring components with many boolean props
|
||||||
|
- Building reusable component libraries
|
||||||
|
- Designing flexible component APIs
|
||||||
|
- Reviewing component architecture
|
||||||
|
- Working with compound components or context providers
|
||||||
|
|
||||||
|
## Rule Categories by Priority
|
||||||
|
|
||||||
|
| Priority | Category | Impact | Prefix |
|
||||||
|
| -------- | ----------------------- | ------ | --------------- |
|
||||||
|
| 1 | Component Architecture | HIGH | `architecture-` |
|
||||||
|
| 2 | State Management | MEDIUM | `state-` |
|
||||||
|
| 3 | Implementation Patterns | MEDIUM | `patterns-` |
|
||||||
|
| 4 | React 19 APIs | MEDIUM | `react19-` |
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
### 1. Component Architecture (HIGH)
|
||||||
|
|
||||||
|
- `architecture-avoid-boolean-props` - Don't add boolean props to customize
|
||||||
|
behavior; use composition
|
||||||
|
- `architecture-compound-components` - Structure complex components with shared
|
||||||
|
context
|
||||||
|
|
||||||
|
### 2. State Management (MEDIUM)
|
||||||
|
|
||||||
|
- `state-decouple-implementation` - Provider is the only place that knows how
|
||||||
|
state is managed
|
||||||
|
- `state-context-interface` - Define generic interface with state, actions, meta
|
||||||
|
for dependency injection
|
||||||
|
- `state-lift-state` - Move state into provider components for sibling access
|
||||||
|
|
||||||
|
### 3. Implementation Patterns (MEDIUM)
|
||||||
|
|
||||||
|
- `patterns-explicit-variants` - Create explicit variant components instead of
|
||||||
|
boolean modes
|
||||||
|
- `patterns-children-over-render-props` - Use children for composition instead
|
||||||
|
of renderX props
|
||||||
|
|
||||||
|
### 4. React 19 APIs (MEDIUM)
|
||||||
|
|
||||||
|
> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
|
||||||
|
|
||||||
|
- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
|
||||||
|
|
||||||
|
## How to Use
|
||||||
|
|
||||||
|
Read individual rule files for detailed explanations and code examples:
|
||||||
|
|
||||||
|
```
|
||||||
|
rules/architecture-avoid-boolean-props.md
|
||||||
|
rules/state-context-interface.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Each rule file contains:
|
||||||
|
|
||||||
|
- Brief explanation of why it matters
|
||||||
|
- Incorrect code example with explanation
|
||||||
|
- Correct code example with explanation
|
||||||
|
- Additional context and references
|
||||||
|
|
||||||
|
## Full Compiled Document
|
||||||
|
|
||||||
|
For the complete guide with all rules expanded: `AGENTS.md`
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Sections
|
||||||
|
|
||||||
|
This file defines all sections, their ordering, impact levels, and descriptions.
|
||||||
|
The section ID (in parentheses) is the filename prefix used to group rules.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Component Architecture (architecture)
|
||||||
|
|
||||||
|
**Impact:** HIGH
|
||||||
|
**Description:** Fundamental patterns for structuring components to avoid prop
|
||||||
|
proliferation and enable flexible composition.
|
||||||
|
|
||||||
|
## 2. State Management (state)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM
|
||||||
|
**Description:** Patterns for lifting state and managing shared context across
|
||||||
|
composed components.
|
||||||
|
|
||||||
|
## 3. Implementation Patterns (patterns)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM
|
||||||
|
**Description:** Specific techniques for implementing compound components and
|
||||||
|
context providers.
|
||||||
|
|
||||||
|
## 4. React 19 APIs (react19)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM
|
||||||
|
**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
|
||||||
@@ -0,0 +1,24 @@
|
|||||||
|
---
|
||||||
|
title: Rule Title Here
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: brief description of impact
|
||||||
|
tags: composition, components
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rule Title Here
|
||||||
|
|
||||||
|
Brief explanation of the rule and why it matters.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Bad code example
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Good code example
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: [Link](https://example.com)
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
---
|
||||||
|
title: Avoid Boolean Prop Proliferation
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: prevents unmaintainable component variants
|
||||||
|
tags: composition, props, architecture
|
||||||
|
---
|
||||||
|
|
||||||
|
## Avoid Boolean Prop Proliferation
|
||||||
|
|
||||||
|
Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
|
||||||
|
component behavior. Each boolean doubles possible states and creates
|
||||||
|
unmaintainable conditional logic. Use composition instead.
|
||||||
|
|
||||||
|
**Incorrect (boolean props create exponential complexity):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
onSubmit,
|
||||||
|
isThread,
|
||||||
|
channelId,
|
||||||
|
isDMThread,
|
||||||
|
dmId,
|
||||||
|
isEditing,
|
||||||
|
isForwarding
|
||||||
|
}: Props) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
<Header />
|
||||||
|
<Input />
|
||||||
|
{isDMThread ? (
|
||||||
|
<AlsoSendToDMField id={dmId} />
|
||||||
|
) : isThread ? (
|
||||||
|
<AlsoSendToChannelField id={channelId} />
|
||||||
|
) : null}
|
||||||
|
{isEditing ? <EditActions /> : isForwarding ? <ForwardActions /> : <DefaultActions />}
|
||||||
|
<Footer onSubmit={onSubmit} />
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (composition eliminates conditionals):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Channel composer
|
||||||
|
function ChannelComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Attachments />
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Thread composer - adds "also send to channel" field
|
||||||
|
function ThreadComposer({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<AlsoSendToChannelField id={channelId} />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Edit composer - different footer actions
|
||||||
|
function EditComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.CancelEdit />
|
||||||
|
<Composer.SaveEdit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each variant is explicit about what it renders. We can share internals without
|
||||||
|
sharing a single monolithic parent.
|
||||||
@@ -0,0 +1,108 @@
|
|||||||
|
---
|
||||||
|
title: Use Compound Components
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: enables flexible composition without prop drilling
|
||||||
|
tags: composition, compound-components, architecture
|
||||||
|
---
|
||||||
|
|
||||||
|
## Use Compound Components
|
||||||
|
|
||||||
|
Structure complex components as compound components with a shared context. Each
|
||||||
|
subcomponent accesses shared state via context, not props. Consumers compose the
|
||||||
|
pieces they need.
|
||||||
|
|
||||||
|
**Incorrect (monolithic component with render props):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
renderHeader,
|
||||||
|
renderFooter,
|
||||||
|
renderActions,
|
||||||
|
showAttachments,
|
||||||
|
showFormatting,
|
||||||
|
showEmojis
|
||||||
|
}: Props) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
{renderHeader?.()}
|
||||||
|
<Input />
|
||||||
|
{showAttachments && <Attachments />}
|
||||||
|
{renderFooter ? (
|
||||||
|
renderFooter()
|
||||||
|
) : (
|
||||||
|
<Footer>
|
||||||
|
{showFormatting && <Formatting />}
|
||||||
|
{showEmojis && <Emojis />}
|
||||||
|
{renderActions?.()}
|
||||||
|
</Footer>
|
||||||
|
)}
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (compound components with shared context):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const ComposerContext = createContext<ComposerContextValue | null>(null);
|
||||||
|
|
||||||
|
function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
|
||||||
|
return <ComposerContext value={{ state, actions, meta }}>{children}</ComposerContext>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerFrame({ children }: { children: React.ReactNode }) {
|
||||||
|
return <form>{children}</form>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerInput() {
|
||||||
|
const {
|
||||||
|
state,
|
||||||
|
actions: { update },
|
||||||
|
meta: { inputRef }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return (
|
||||||
|
<TextInput
|
||||||
|
ref={inputRef}
|
||||||
|
value={state.input}
|
||||||
|
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerSubmit() {
|
||||||
|
const {
|
||||||
|
actions: { submit }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return <Button onPress={submit}>Send</Button>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Export as compound component
|
||||||
|
const Composer = {
|
||||||
|
Provider: ComposerProvider,
|
||||||
|
Frame: ComposerFrame,
|
||||||
|
Input: ComposerInput,
|
||||||
|
Submit: ComposerSubmit,
|
||||||
|
Header: ComposerHeader,
|
||||||
|
Footer: ComposerFooter,
|
||||||
|
Attachments: ComposerAttachments,
|
||||||
|
Formatting: ComposerFormatting,
|
||||||
|
Emojis: ComposerEmojis
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
**Usage:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
<Composer.Provider state={state} actions={actions} meta={meta}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</Composer.Provider>
|
||||||
|
```
|
||||||
|
|
||||||
|
Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
|
||||||
@@ -0,0 +1,84 @@
|
|||||||
|
---
|
||||||
|
title: Prefer Composing Children Over Render Props
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: cleaner composition, better readability
|
||||||
|
tags: composition, children, render-props
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prefer Children Over Render Props
|
||||||
|
|
||||||
|
Use `children` for composition instead of `renderX` props. Children are more
|
||||||
|
readable, compose naturally, and don't require understanding callback
|
||||||
|
signatures.
|
||||||
|
|
||||||
|
**Incorrect (render props):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Composer({
|
||||||
|
renderHeader,
|
||||||
|
renderFooter,
|
||||||
|
renderActions
|
||||||
|
}: {
|
||||||
|
renderHeader?: () => React.ReactNode;
|
||||||
|
renderFooter?: () => React.ReactNode;
|
||||||
|
renderActions?: () => React.ReactNode;
|
||||||
|
}) {
|
||||||
|
return (
|
||||||
|
<form>
|
||||||
|
{renderHeader?.()}
|
||||||
|
<Input />
|
||||||
|
{renderFooter ? renderFooter() : <DefaultFooter />}
|
||||||
|
{renderActions?.()}
|
||||||
|
</form>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage is awkward and inflexible
|
||||||
|
return (
|
||||||
|
<Composer
|
||||||
|
renderHeader={() => <CustomHeader />}
|
||||||
|
renderFooter={() => (
|
||||||
|
<>
|
||||||
|
<Formatting />
|
||||||
|
<Emojis />
|
||||||
|
</>
|
||||||
|
)}
|
||||||
|
renderActions={() => <SubmitButton />}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (compound components with children):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerFrame({ children }: { children: React.ReactNode }) {
|
||||||
|
return <form>{children}</form>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function ComposerFooter({ children }: { children: React.ReactNode }) {
|
||||||
|
return <footer className='flex'>{children}</footer>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage is flexible
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<CustomHeader />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<SubmitButton />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
**When render props are appropriate:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Render props work well when you need to pass data back
|
||||||
|
<List data={items} renderItem={({ item, index }) => <Item item={item} index={index} />} />
|
||||||
|
```
|
||||||
|
|
||||||
|
Use render props when the parent needs to provide data or state to the child.
|
||||||
|
Use children when composing static structure.
|
||||||
@@ -0,0 +1,94 @@
|
|||||||
|
---
|
||||||
|
title: Create Explicit Component Variants
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: self-documenting code, no hidden conditionals
|
||||||
|
tags: composition, variants, architecture
|
||||||
|
---
|
||||||
|
|
||||||
|
## Create Explicit Component Variants
|
||||||
|
|
||||||
|
Instead of one component with many boolean props, create explicit variant
|
||||||
|
components. Each variant composes the pieces it needs. The code documents
|
||||||
|
itself.
|
||||||
|
|
||||||
|
**Incorrect (one component, many modes):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// What does this component actually render?
|
||||||
|
<Composer isThread isEditing={false} channelId='abc' showAttachments showFormatting={false} />
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (explicit variants):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Immediately clear what this renders
|
||||||
|
<ThreadComposer channelId="abc" />
|
||||||
|
|
||||||
|
// Or
|
||||||
|
<EditMessageComposer messageId="xyz" />
|
||||||
|
|
||||||
|
// Or
|
||||||
|
<ForwardMessageComposer messageId="123" />
|
||||||
|
```
|
||||||
|
|
||||||
|
Each implementation is unique, explicit and self-contained. Yet they can each
|
||||||
|
use shared parts.
|
||||||
|
|
||||||
|
**Implementation:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ThreadComposer({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<ThreadProvider channelId={channelId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<AlsoSendToChannelField channelId={channelId} />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</ThreadProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function EditMessageComposer({ messageId }: { messageId: string }) {
|
||||||
|
return (
|
||||||
|
<EditMessageProvider messageId={messageId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.CancelEdit />
|
||||||
|
<Composer.SaveEdit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</EditMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageComposer({ messageId }: { messageId: string }) {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider messageId={messageId}>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input placeholder="Add a message, if you'd like." />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
<Composer.Mentions />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each variant is explicit about:
|
||||||
|
|
||||||
|
- What provider/state it uses
|
||||||
|
- What UI elements it includes
|
||||||
|
- What actions are available
|
||||||
|
|
||||||
|
No boolean prop combinations to reason about. No impossible states.
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
title: React 19 API Changes
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: cleaner component definitions and context usage
|
||||||
|
tags: react19, refs, context, hooks
|
||||||
|
---
|
||||||
|
|
||||||
|
## React 19 API Changes
|
||||||
|
|
||||||
|
> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
|
||||||
|
|
||||||
|
In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
|
||||||
|
|
||||||
|
**Incorrect (forwardRef in React 19):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
|
||||||
|
return <TextInput ref={ref} {...props} />;
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (ref as a regular prop):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
|
||||||
|
return <TextInput ref={ref} {...props} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect (useContext in React 19):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const value = useContext(MyContext);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (use instead of useContext):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const value = use(MyContext);
|
||||||
|
```
|
||||||
|
|
||||||
|
`use()` can also be called conditionally, unlike `useContext()`.
|
||||||
@@ -0,0 +1,191 @@
|
|||||||
|
---
|
||||||
|
title: Define Generic Context Interfaces for Dependency Injection
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: enables dependency-injectable state across use-cases
|
||||||
|
tags: composition, context, state, typescript, dependency-injection
|
||||||
|
---
|
||||||
|
|
||||||
|
## Define Generic Context Interfaces for Dependency Injection
|
||||||
|
|
||||||
|
Define a **generic interface** for your component context with three parts:
|
||||||
|
`state`, `actions`, and `meta`. This interface is a contract that any provider
|
||||||
|
can implement—enabling the same UI components to work with completely different
|
||||||
|
state implementations.
|
||||||
|
|
||||||
|
**Core principle:** Lift state, compose internals, make state
|
||||||
|
dependency-injectable.
|
||||||
|
|
||||||
|
**Incorrect (UI coupled to specific state implementation):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput() {
|
||||||
|
// Tightly coupled to a specific hook
|
||||||
|
const { input, setInput } = useChannelComposerState();
|
||||||
|
return <TextInput value={input} onChangeText={setInput} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (generic interface enables dependency injection):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Define a GENERIC interface that any provider can implement
|
||||||
|
interface ComposerState {
|
||||||
|
input: string;
|
||||||
|
attachments: Attachment[];
|
||||||
|
isSubmitting: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerActions {
|
||||||
|
update: (updater: (state: ComposerState) => ComposerState) => void;
|
||||||
|
submit: () => void;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerMeta {
|
||||||
|
inputRef: React.RefObject<TextInput>;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface ComposerContextValue {
|
||||||
|
state: ComposerState;
|
||||||
|
actions: ComposerActions;
|
||||||
|
meta: ComposerMeta;
|
||||||
|
}
|
||||||
|
|
||||||
|
const ComposerContext = createContext<ComposerContextValue | null>(null);
|
||||||
|
```
|
||||||
|
|
||||||
|
**UI components consume the interface, not the implementation:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ComposerInput() {
|
||||||
|
const {
|
||||||
|
state,
|
||||||
|
actions: { update },
|
||||||
|
meta
|
||||||
|
} = use(ComposerContext);
|
||||||
|
|
||||||
|
// This component works with ANY provider that implements the interface
|
||||||
|
return (
|
||||||
|
<TextInput
|
||||||
|
ref={meta.inputRef}
|
||||||
|
value={state.input}
|
||||||
|
onChangeText={(text) => update((s) => ({ ...s, input: text }))}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Different providers implement the same interface:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Provider A: Local state for ephemeral forms
|
||||||
|
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
const submit = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ComposerContext
|
||||||
|
value={{
|
||||||
|
state,
|
||||||
|
actions: { update: setState, submit },
|
||||||
|
meta: { inputRef }
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</ComposerContext>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Provider B: Global synced state for channels
|
||||||
|
function ChannelProvider({ channelId, children }: Props) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<ComposerContext
|
||||||
|
value={{
|
||||||
|
state,
|
||||||
|
actions: { update, submit },
|
||||||
|
meta: { inputRef }
|
||||||
|
}}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</ComposerContext>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**The same composed UI works with both:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Works with ForwardMessageProvider (local state)
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Frame>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
|
||||||
|
// Works with ChannelProvider (global synced state)
|
||||||
|
<ChannelProvider channelId="abc">
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Frame>
|
||||||
|
</ChannelProvider>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Custom UI outside the component can access state and actions:**
|
||||||
|
|
||||||
|
The provider boundary is what matters—not the visual nesting. Components that
|
||||||
|
need shared state don't have to be inside the `Composer.Frame`. They just need
|
||||||
|
to be within the provider.
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Dialog>
|
||||||
|
{/* The composer UI */}
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input placeholder="Add a message, if you'd like." />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Formatting />
|
||||||
|
<Composer.Emojis />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
|
||||||
|
{/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
|
||||||
|
<MessagePreview />
|
||||||
|
|
||||||
|
{/* Actions at the bottom of the dialog */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton />
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
|
||||||
|
function ForwardButton() {
|
||||||
|
const {
|
||||||
|
actions: { submit }
|
||||||
|
} = use(ComposerContext);
|
||||||
|
return <Button onPress={submit}>Forward</Button>;
|
||||||
|
}
|
||||||
|
|
||||||
|
// This preview lives OUTSIDE Composer.Frame but can read composer's state!
|
||||||
|
function MessagePreview() {
|
||||||
|
const { state } = use(ComposerContext);
|
||||||
|
return <Preview message={state.input} attachments={state.attachments} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `ForwardButton` and `MessagePreview` are not visually inside the composer
|
||||||
|
box, but they can still access its state and actions. This is the power of
|
||||||
|
lifting state into providers.
|
||||||
|
|
||||||
|
The UI is reusable bits you compose together. The state is dependency-injected
|
||||||
|
by the provider. Swap the provider, keep the UI.
|
||||||
@@ -0,0 +1,103 @@
|
|||||||
|
---
|
||||||
|
title: Decouple State Management from UI
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: enables swapping state implementations without changing UI
|
||||||
|
tags: composition, state, architecture
|
||||||
|
---
|
||||||
|
|
||||||
|
## Decouple State Management from UI
|
||||||
|
|
||||||
|
The provider component should be the only place that knows how state is managed.
|
||||||
|
UI components consume the context interface—they don't know if state comes from
|
||||||
|
useState, Zustand, or a server sync.
|
||||||
|
|
||||||
|
**Incorrect (UI coupled to state implementation):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ChannelComposer({ channelId }: { channelId: string }) {
|
||||||
|
// UI component knows about global state implementation
|
||||||
|
const state = useGlobalChannelState(channelId);
|
||||||
|
const { submit, updateInput } = useChannelSync(channelId);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input value={state.input} onChange={(text) => sync.updateInput(text)} />
|
||||||
|
<Composer.Submit onPress={() => sync.submit()} />
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (state management isolated in provider):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Provider handles all state management details
|
||||||
|
function ChannelProvider({
|
||||||
|
channelId,
|
||||||
|
children
|
||||||
|
}: {
|
||||||
|
channelId: string;
|
||||||
|
children: React.ReactNode;
|
||||||
|
}) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update, submit }} meta={{ inputRef }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// UI component only knows about the context interface
|
||||||
|
function ChannelComposer() {
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Header />
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer>
|
||||||
|
<Composer.Submit />
|
||||||
|
</Composer.Footer>
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Usage
|
||||||
|
function Channel({ channelId }: { channelId: string }) {
|
||||||
|
return (
|
||||||
|
<ChannelProvider channelId={channelId}>
|
||||||
|
<ChannelComposer />
|
||||||
|
</ChannelProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Different providers, same UI:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
// Local state for ephemeral forms
|
||||||
|
function ForwardMessageProvider({ children }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update: setState, submit: forwardMessage }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Global synced state for channels
|
||||||
|
function ChannelProvider({ channelId, children }) {
|
||||||
|
const { state, update, submit } = useGlobalChannel(channelId);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider state={state} actions={{ update, submit }}>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The same `Composer.Input` component works with both providers because it only
|
||||||
|
depends on the context interface, not the implementation.
|
||||||
@@ -0,0 +1,125 @@
|
|||||||
|
---
|
||||||
|
title: Lift State into Provider Components
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: enables state sharing outside component boundaries
|
||||||
|
tags: composition, state, context, providers
|
||||||
|
---
|
||||||
|
|
||||||
|
## Lift State into Provider Components
|
||||||
|
|
||||||
|
Move state management into dedicated provider components. This allows sibling
|
||||||
|
components outside the main UI to access and modify state without prop drilling
|
||||||
|
or awkward refs.
|
||||||
|
|
||||||
|
**Incorrect (state trapped inside component):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageComposer() {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Frame>
|
||||||
|
<Composer.Input />
|
||||||
|
<Composer.Footer />
|
||||||
|
</Composer.Frame>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Problem: How does this button access composer state?
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer />
|
||||||
|
<MessagePreview /> {/* Needs composer state */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton /> {/* Needs to call submit */}
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect (useEffect to sync state up):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
const [input, setInput] = useState('');
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer onInputChange={setInput} />
|
||||||
|
<MessagePreview input={input} />
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageComposer({ onInputChange }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
useEffect(() => {
|
||||||
|
onInputChange(state.input); // Sync on every change 😬
|
||||||
|
}, [state.input]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Incorrect (reading state from ref on submit):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
const stateRef = useRef(null);
|
||||||
|
return (
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer stateRef={stateRef} />
|
||||||
|
<ForwardButton onPress={() => submit(stateRef.current)} />
|
||||||
|
</Dialog>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (state lifted to provider):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
|
||||||
|
const [state, setState] = useState(initialState);
|
||||||
|
const forwardMessage = useForwardMessage();
|
||||||
|
const inputRef = useRef(null);
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Composer.Provider
|
||||||
|
state={state}
|
||||||
|
actions={{ update: setState, submit: forwardMessage }}
|
||||||
|
meta={{ inputRef }}
|
||||||
|
>
|
||||||
|
{children}
|
||||||
|
</Composer.Provider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardMessageDialog() {
|
||||||
|
return (
|
||||||
|
<ForwardMessageProvider>
|
||||||
|
<Dialog>
|
||||||
|
<ForwardMessageComposer />
|
||||||
|
<MessagePreview /> {/* Custom components can access state and actions */}
|
||||||
|
<DialogActions>
|
||||||
|
<CancelButton />
|
||||||
|
<ForwardButton /> {/* Custom components can access state and actions */}
|
||||||
|
</DialogActions>
|
||||||
|
</Dialog>
|
||||||
|
</ForwardMessageProvider>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function ForwardButton() {
|
||||||
|
const { actions } = use(Composer.Context);
|
||||||
|
return <Button onPress={actions.submit}>Forward</Button>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The ForwardButton lives outside the Composer.Frame but still has access to the
|
||||||
|
submit action because it's within the provider. Even though it's a one-off
|
||||||
|
component, it can still access the composer's state and actions from outside the
|
||||||
|
UI itself.
|
||||||
|
|
||||||
|
**Key insight:** Components that need shared state don't have to be visually
|
||||||
|
nested inside each other—they just need to be within the same provider.
|
||||||
3304
.agents/skills/vercel-react-best-practices/AGENTS.md
Normal file
3304
.agents/skills/vercel-react-best-practices/AGENTS.md
Normal file
File diff suppressed because it is too large
Load Diff
127
.agents/skills/vercel-react-best-practices/README.md
Normal file
127
.agents/skills/vercel-react-best-practices/README.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
# React Best Practices
|
||||||
|
|
||||||
|
A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
- `rules/` - Individual rule files (one per rule)
|
||||||
|
- `_sections.md` - Section metadata (titles, impacts, descriptions)
|
||||||
|
- `_template.md` - Template for creating new rules
|
||||||
|
- `area-description.md` - Individual rule files
|
||||||
|
- `src/` - Build scripts and utilities
|
||||||
|
- `metadata.json` - Document metadata (version, organization, abstract)
|
||||||
|
- **`AGENTS.md`** - Compiled output (generated)
|
||||||
|
- **`test-cases.json`** - Test cases for LLM evaluation (generated)
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
|
1. Install dependencies:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm install
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Build AGENTS.md from rules:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm build
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Validate rule files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm validate
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Extract test cases:
|
||||||
|
```bash
|
||||||
|
pnpm extract-tests
|
||||||
|
```
|
||||||
|
|
||||||
|
## Creating a New Rule
|
||||||
|
|
||||||
|
1. Copy `rules/_template.md` to `rules/area-description.md`
|
||||||
|
2. Choose the appropriate area prefix:
|
||||||
|
- `async-` for Eliminating Waterfalls (Section 1)
|
||||||
|
- `bundle-` for Bundle Size Optimization (Section 2)
|
||||||
|
- `server-` for Server-Side Performance (Section 3)
|
||||||
|
- `client-` for Client-Side Data Fetching (Section 4)
|
||||||
|
- `rerender-` for Re-render Optimization (Section 5)
|
||||||
|
- `rendering-` for Rendering Performance (Section 6)
|
||||||
|
- `js-` for JavaScript Performance (Section 7)
|
||||||
|
- `advanced-` for Advanced Patterns (Section 8)
|
||||||
|
3. Fill in the frontmatter and content
|
||||||
|
4. Ensure you have clear examples with explanations
|
||||||
|
5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
|
||||||
|
|
||||||
|
## Rule File Structure
|
||||||
|
|
||||||
|
Each rule file should follow this structure:
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
---
|
||||||
|
title: Rule Title Here
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: Optional description
|
||||||
|
tags: tag1, tag2, tag3
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rule Title Here
|
||||||
|
|
||||||
|
Brief explanation of the rule and why it matters.
|
||||||
|
|
||||||
|
**Incorrect (description of what's wrong):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Bad code example
|
||||||
|
```
|
||||||
|
````
|
||||||
|
|
||||||
|
**Correct (description of what's right):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Good code example
|
||||||
|
```
|
||||||
|
|
||||||
|
Optional explanatory text after examples.
|
||||||
|
|
||||||
|
Reference: [Link](https://example.com)
|
||||||
|
|
||||||
|
## File Naming Convention
|
||||||
|
|
||||||
|
- Files starting with `_` are special (excluded from build)
|
||||||
|
- Rule files: `area-description.md` (e.g., `async-parallel.md`)
|
||||||
|
- Section is automatically inferred from filename prefix
|
||||||
|
- Rules are sorted alphabetically by title within each section
|
||||||
|
- IDs (e.g., 1.1, 1.2) are auto-generated during build
|
||||||
|
|
||||||
|
## Impact Levels
|
||||||
|
|
||||||
|
- `CRITICAL` - Highest priority, major performance gains
|
||||||
|
- `HIGH` - Significant performance improvements
|
||||||
|
- `MEDIUM-HIGH` - Moderate-high gains
|
||||||
|
- `MEDIUM` - Moderate performance improvements
|
||||||
|
- `LOW-MEDIUM` - Low-medium gains
|
||||||
|
- `LOW` - Incremental improvements
|
||||||
|
|
||||||
|
## Scripts
|
||||||
|
|
||||||
|
- `pnpm build` - Compile rules into AGENTS.md
|
||||||
|
- `pnpm validate` - Validate all rule files
|
||||||
|
- `pnpm extract-tests` - Extract test cases for LLM evaluation
|
||||||
|
- `pnpm dev` - Build and validate
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
When adding or modifying rules:
|
||||||
|
|
||||||
|
1. Use the correct filename prefix for your section
|
||||||
|
2. Follow the `_template.md` structure
|
||||||
|
3. Include clear bad/good examples with explanations
|
||||||
|
4. Add appropriate tags
|
||||||
|
5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
|
||||||
|
6. Rules are automatically sorted by title - no need to manage numbers!
|
||||||
|
|
||||||
|
## Acknowledgments
|
||||||
|
|
||||||
|
Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
|
||||||
145
.agents/skills/vercel-react-best-practices/SKILL.md
Normal file
145
.agents/skills/vercel-react-best-practices/SKILL.md
Normal file
@@ -0,0 +1,145 @@
|
|||||||
|
---
|
||||||
|
name: vercel-react-best-practices
|
||||||
|
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: vercel
|
||||||
|
version: '1.0.0'
|
||||||
|
---
|
||||||
|
|
||||||
|
# Vercel React Best Practices
|
||||||
|
|
||||||
|
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 64 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
|
||||||
|
|
||||||
|
## When to Apply
|
||||||
|
|
||||||
|
Reference these guidelines when:
|
||||||
|
|
||||||
|
- Writing new React components or Next.js pages
|
||||||
|
- Implementing data fetching (client or server-side)
|
||||||
|
- Reviewing code for performance issues
|
||||||
|
- Refactoring existing React/Next.js code
|
||||||
|
- Optimizing bundle size or load times
|
||||||
|
|
||||||
|
## Rule Categories by Priority
|
||||||
|
|
||||||
|
| Priority | Category | Impact | Prefix |
|
||||||
|
| -------- | ------------------------- | ----------- | ------------ |
|
||||||
|
| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
|
||||||
|
| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
|
||||||
|
| 3 | Server-Side Performance | HIGH | `server-` |
|
||||||
|
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
|
||||||
|
| 5 | Re-render Optimization | MEDIUM | `rerender-` |
|
||||||
|
| 6 | Rendering Performance | MEDIUM | `rendering-` |
|
||||||
|
| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
|
||||||
|
| 8 | Advanced Patterns | LOW | `advanced-` |
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
### 1. Eliminating Waterfalls (CRITICAL)
|
||||||
|
|
||||||
|
- `async-defer-await` - Move await into branches where actually used
|
||||||
|
- `async-parallel` - Use Promise.all() for independent operations
|
||||||
|
- `async-dependencies` - Use better-all for partial dependencies
|
||||||
|
- `async-api-routes` - Start promises early, await late in API routes
|
||||||
|
- `async-suspense-boundaries` - Use Suspense to stream content
|
||||||
|
|
||||||
|
### 2. Bundle Size Optimization (CRITICAL)
|
||||||
|
|
||||||
|
- `bundle-barrel-imports` - Import directly, avoid barrel files
|
||||||
|
- `bundle-dynamic-imports` - Use next/dynamic for heavy components
|
||||||
|
- `bundle-defer-third-party` - Load analytics/logging after hydration
|
||||||
|
- `bundle-conditional` - Load modules only when feature is activated
|
||||||
|
- `bundle-preload` - Preload on hover/focus for perceived speed
|
||||||
|
|
||||||
|
### 3. Server-Side Performance (HIGH)
|
||||||
|
|
||||||
|
- `server-auth-actions` - Authenticate server actions like API routes
|
||||||
|
- `server-cache-react` - Use React.cache() for per-request deduplication
|
||||||
|
- `server-cache-lru` - Use LRU cache for cross-request caching
|
||||||
|
- `server-dedup-props` - Avoid duplicate serialization in RSC props
|
||||||
|
- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
|
||||||
|
- `server-serialization` - Minimize data passed to client components
|
||||||
|
- `server-parallel-fetching` - Restructure components to parallelize fetches
|
||||||
|
- `server-after-nonblocking` - Use after() for non-blocking operations
|
||||||
|
|
||||||
|
### 4. Client-Side Data Fetching (MEDIUM-HIGH)
|
||||||
|
|
||||||
|
- `client-swr-dedup` - Use SWR for automatic request deduplication
|
||||||
|
- `client-event-listeners` - Deduplicate global event listeners
|
||||||
|
- `client-passive-event-listeners` - Use passive listeners for scroll
|
||||||
|
- `client-localstorage-schema` - Version and minimize localStorage data
|
||||||
|
|
||||||
|
### 5. Re-render Optimization (MEDIUM)
|
||||||
|
|
||||||
|
- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
|
||||||
|
- `rerender-memo` - Extract expensive work into memoized components
|
||||||
|
- `rerender-memo-with-default-value` - Hoist default non-primitive props
|
||||||
|
- `rerender-dependencies` - Use primitive dependencies in effects
|
||||||
|
- `rerender-derived-state` - Subscribe to derived booleans, not raw values
|
||||||
|
- `rerender-derived-state-no-effect` - Derive state during render, not effects
|
||||||
|
- `rerender-functional-setstate` - Use functional setState for stable callbacks
|
||||||
|
- `rerender-lazy-state-init` - Pass function to useState for expensive values
|
||||||
|
- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
|
||||||
|
- `rerender-split-combined-hooks` - Split hooks with independent dependencies
|
||||||
|
- `rerender-move-effect-to-event` - Put interaction logic in event handlers
|
||||||
|
- `rerender-transitions` - Use startTransition for non-urgent updates
|
||||||
|
- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
|
||||||
|
- `rerender-use-ref-transient-values` - Use refs for transient frequent values
|
||||||
|
- `rerender-no-inline-components` - Don't define components inside components
|
||||||
|
|
||||||
|
### 6. Rendering Performance (MEDIUM)
|
||||||
|
|
||||||
|
- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
|
||||||
|
- `rendering-content-visibility` - Use content-visibility for long lists
|
||||||
|
- `rendering-hoist-jsx` - Extract static JSX outside components
|
||||||
|
- `rendering-svg-precision` - Reduce SVG coordinate precision
|
||||||
|
- `rendering-hydration-no-flicker` - Use inline script for client-only data
|
||||||
|
- `rendering-hydration-suppress-warning` - Suppress expected mismatches
|
||||||
|
- `rendering-activity` - Use Activity component for show/hide
|
||||||
|
- `rendering-conditional-render` - Use ternary, not && for conditionals
|
||||||
|
- `rendering-usetransition-loading` - Prefer useTransition for loading state
|
||||||
|
- `rendering-resource-hints` - Use React DOM resource hints for preloading
|
||||||
|
- `rendering-script-defer-async` - Use defer or async on script tags
|
||||||
|
|
||||||
|
### 7. JavaScript Performance (LOW-MEDIUM)
|
||||||
|
|
||||||
|
- `js-batch-dom-css` - Group CSS changes via classes or cssText
|
||||||
|
- `js-index-maps` - Build Map for repeated lookups
|
||||||
|
- `js-cache-property-access` - Cache object properties in loops
|
||||||
|
- `js-cache-function-results` - Cache function results in module-level Map
|
||||||
|
- `js-cache-storage` - Cache localStorage/sessionStorage reads
|
||||||
|
- `js-combine-iterations` - Combine multiple filter/map into one loop
|
||||||
|
- `js-length-check-first` - Check array length before expensive comparison
|
||||||
|
- `js-early-exit` - Return early from functions
|
||||||
|
- `js-hoist-regexp` - Hoist RegExp creation outside loops
|
||||||
|
- `js-min-max-loop` - Use loop for min/max instead of sort
|
||||||
|
- `js-set-map-lookups` - Use Set/Map for O(1) lookups
|
||||||
|
- `js-tosorted-immutable` - Use toSorted() for immutability
|
||||||
|
- `js-flatmap-filter` - Use flatMap to map and filter in one pass
|
||||||
|
|
||||||
|
### 8. Advanced Patterns (LOW)
|
||||||
|
|
||||||
|
- `advanced-event-handler-refs` - Store event handlers in refs
|
||||||
|
- `advanced-init-once` - Initialize app once per app load
|
||||||
|
- `advanced-use-latest` - useLatest for stable callback refs
|
||||||
|
|
||||||
|
## How to Use
|
||||||
|
|
||||||
|
Read individual rule files for detailed explanations and code examples:
|
||||||
|
|
||||||
|
```
|
||||||
|
rules/async-parallel.md
|
||||||
|
rules/bundle-barrel-imports.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Each rule file contains:
|
||||||
|
|
||||||
|
- Brief explanation of why it matters
|
||||||
|
- Incorrect code example with explanation
|
||||||
|
- Correct code example with explanation
|
||||||
|
- Additional context and references
|
||||||
|
|
||||||
|
## Full Compiled Document
|
||||||
|
|
||||||
|
For the complete guide with all rules expanded: `AGENTS.md`
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
# Sections
|
||||||
|
|
||||||
|
This file defines all sections, their ordering, impact levels, and descriptions.
|
||||||
|
The section ID (in parentheses) is the filename prefix used to group rules.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Eliminating Waterfalls (async)
|
||||||
|
|
||||||
|
**Impact:** CRITICAL
|
||||||
|
**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
|
||||||
|
|
||||||
|
## 2. Bundle Size Optimization (bundle)
|
||||||
|
|
||||||
|
**Impact:** CRITICAL
|
||||||
|
**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
|
||||||
|
|
||||||
|
## 3. Server-Side Performance (server)
|
||||||
|
|
||||||
|
**Impact:** HIGH
|
||||||
|
**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
|
||||||
|
|
||||||
|
## 4. Client-Side Data Fetching (client)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM-HIGH
|
||||||
|
**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
|
||||||
|
|
||||||
|
## 5. Re-render Optimization (rerender)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM
|
||||||
|
**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
|
||||||
|
|
||||||
|
## 6. Rendering Performance (rendering)
|
||||||
|
|
||||||
|
**Impact:** MEDIUM
|
||||||
|
**Description:** Optimizing the rendering process reduces the work the browser needs to do.
|
||||||
|
|
||||||
|
## 7. JavaScript Performance (js)
|
||||||
|
|
||||||
|
**Impact:** LOW-MEDIUM
|
||||||
|
**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
|
||||||
|
|
||||||
|
## 8. Advanced Patterns (advanced)
|
||||||
|
|
||||||
|
**Impact:** LOW
|
||||||
|
**Description:** Advanced patterns for specific cases that require careful implementation.
|
||||||
@@ -0,0 +1,28 @@
|
|||||||
|
---
|
||||||
|
title: Rule Title Here
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: Optional description of impact (e.g., "20-50% improvement")
|
||||||
|
tags: tag1, tag2
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rule Title Here
|
||||||
|
|
||||||
|
**Impact: MEDIUM (optional impact description)**
|
||||||
|
|
||||||
|
Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
|
||||||
|
|
||||||
|
**Incorrect (description of what's wrong):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Bad code example here
|
||||||
|
const bad = example();
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (description of what's right):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Good code example here
|
||||||
|
const good = example();
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: [Link to documentation or resource](https://example.com)
|
||||||
@@ -0,0 +1,55 @@
|
|||||||
|
---
|
||||||
|
title: Store Event Handlers in Refs
|
||||||
|
impact: LOW
|
||||||
|
impactDescription: stable subscriptions
|
||||||
|
tags: advanced, hooks, refs, event-handlers, optimization
|
||||||
|
---
|
||||||
|
|
||||||
|
## Store Event Handlers in Refs
|
||||||
|
|
||||||
|
Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
|
||||||
|
|
||||||
|
**Incorrect (re-subscribes on every render):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function useWindowEvent(event: string, handler: (e) => void) {
|
||||||
|
useEffect(() => {
|
||||||
|
window.addEventListener(event, handler);
|
||||||
|
return () => window.removeEventListener(event, handler);
|
||||||
|
}, [event, handler]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (stable subscription):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function useWindowEvent(event: string, handler: (e) => void) {
|
||||||
|
const handlerRef = useRef(handler);
|
||||||
|
useEffect(() => {
|
||||||
|
handlerRef.current = handler;
|
||||||
|
}, [handler]);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
const listener = (e) => handlerRef.current(e);
|
||||||
|
window.addEventListener(event, listener);
|
||||||
|
return () => window.removeEventListener(event, listener);
|
||||||
|
}, [event]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Alternative: use `useEffectEvent` if you're on latest React:**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useEffectEvent } from 'react';
|
||||||
|
|
||||||
|
function useWindowEvent(event: string, handler: (e) => void) {
|
||||||
|
const onEvent = useEffectEvent(handler);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
window.addEventListener(event, onEvent);
|
||||||
|
return () => window.removeEventListener(event, onEvent);
|
||||||
|
}, [event]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
title: Initialize App Once, Not Per Mount
|
||||||
|
impact: LOW-MEDIUM
|
||||||
|
impactDescription: avoids duplicate init in development
|
||||||
|
tags: initialization, useEffect, app-startup, side-effects
|
||||||
|
---
|
||||||
|
|
||||||
|
## Initialize App Once, Not Per Mount
|
||||||
|
|
||||||
|
Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
|
||||||
|
|
||||||
|
**Incorrect (runs twice in dev, re-runs on remount):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Comp() {
|
||||||
|
useEffect(() => {
|
||||||
|
loadFromStorage();
|
||||||
|
checkAuthToken();
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (once per app load):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
let didInit = false;
|
||||||
|
|
||||||
|
function Comp() {
|
||||||
|
useEffect(() => {
|
||||||
|
if (didInit) return;
|
||||||
|
didInit = true;
|
||||||
|
loadFromStorage();
|
||||||
|
checkAuthToken();
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
|
||||||
@@ -0,0 +1,39 @@
|
|||||||
|
---
|
||||||
|
title: useEffectEvent for Stable Callback Refs
|
||||||
|
impact: LOW
|
||||||
|
impactDescription: prevents effect re-runs
|
||||||
|
tags: advanced, hooks, useEffectEvent, refs, optimization
|
||||||
|
---
|
||||||
|
|
||||||
|
## useEffectEvent for Stable Callback Refs
|
||||||
|
|
||||||
|
Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
|
||||||
|
|
||||||
|
**Incorrect (effect re-runs on every callback change):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
|
||||||
|
const [query, setQuery] = useState('');
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
const timeout = setTimeout(() => onSearch(query), 300);
|
||||||
|
return () => clearTimeout(timeout);
|
||||||
|
}, [query, onSearch]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (using React's useEffectEvent):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useEffectEvent } from 'react';
|
||||||
|
|
||||||
|
function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
|
||||||
|
const [query, setQuery] = useState('');
|
||||||
|
const onSearchEvent = useEffectEvent(onSearch);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
const timeout = setTimeout(() => onSearchEvent(query), 300);
|
||||||
|
return () => clearTimeout(timeout);
|
||||||
|
}, [query]);
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,35 @@
|
|||||||
|
---
|
||||||
|
title: Prevent Waterfall Chains in API Routes
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: 2-10× improvement
|
||||||
|
tags: api-routes, server-actions, waterfalls, parallelization
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prevent Waterfall Chains in API Routes
|
||||||
|
|
||||||
|
In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
|
||||||
|
|
||||||
|
**Incorrect (config waits for auth, data waits for both):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export async function GET(request: Request) {
|
||||||
|
const session = await auth();
|
||||||
|
const config = await fetchConfig();
|
||||||
|
const data = await fetchData(session.user.id);
|
||||||
|
return Response.json({ data, config });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (auth and config start immediately):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
export async function GET(request: Request) {
|
||||||
|
const sessionPromise = auth();
|
||||||
|
const configPromise = fetchConfig();
|
||||||
|
const session = await sessionPromise;
|
||||||
|
const [config, data] = await Promise.all([configPromise, fetchData(session.user.id)]);
|
||||||
|
return Response.json({ data, config });
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
---
|
||||||
|
title: Defer Await Until Needed
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: avoids blocking unused code paths
|
||||||
|
tags: async, await, conditional, optimization
|
||||||
|
---
|
||||||
|
|
||||||
|
## Defer Await Until Needed
|
||||||
|
|
||||||
|
Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
|
||||||
|
|
||||||
|
**Incorrect (blocks both branches):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
async function handleRequest(userId: string, skipProcessing: boolean) {
|
||||||
|
const userData = await fetchUserData(userId);
|
||||||
|
|
||||||
|
if (skipProcessing) {
|
||||||
|
// Returns immediately but still waited for userData
|
||||||
|
return { skipped: true };
|
||||||
|
}
|
||||||
|
|
||||||
|
// Only this branch uses userData
|
||||||
|
return processUserData(userData);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (only blocks when needed):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
async function handleRequest(userId: string, skipProcessing: boolean) {
|
||||||
|
if (skipProcessing) {
|
||||||
|
// Returns immediately without waiting
|
||||||
|
return { skipped: true };
|
||||||
|
}
|
||||||
|
|
||||||
|
// Fetch only when needed
|
||||||
|
const userData = await fetchUserData(userId);
|
||||||
|
return processUserData(userData);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Another example (early return optimization):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Incorrect: always fetches permissions
|
||||||
|
async function updateResource(resourceId: string, userId: string) {
|
||||||
|
const permissions = await fetchPermissions(userId);
|
||||||
|
const resource = await getResource(resourceId);
|
||||||
|
|
||||||
|
if (!resource) {
|
||||||
|
return { error: 'Not found' };
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!permissions.canEdit) {
|
||||||
|
return { error: 'Forbidden' };
|
||||||
|
}
|
||||||
|
|
||||||
|
return await updateResourceData(resource, permissions);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Correct: fetches only when needed
|
||||||
|
async function updateResource(resourceId: string, userId: string) {
|
||||||
|
const resource = await getResource(resourceId);
|
||||||
|
|
||||||
|
if (!resource) {
|
||||||
|
return { error: 'Not found' };
|
||||||
|
}
|
||||||
|
|
||||||
|
const permissions = await fetchPermissions(userId);
|
||||||
|
|
||||||
|
if (!permissions.canEdit) {
|
||||||
|
return { error: 'Forbidden' };
|
||||||
|
}
|
||||||
|
|
||||||
|
return await updateResourceData(resource, permissions);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
|
||||||
@@ -0,0 +1,48 @@
|
|||||||
|
---
|
||||||
|
title: Dependency-Based Parallelization
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: 2-10× improvement
|
||||||
|
tags: async, parallelization, dependencies, better-all
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dependency-Based Parallelization
|
||||||
|
|
||||||
|
For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
|
||||||
|
|
||||||
|
**Incorrect (profile waits for config unnecessarily):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const [user, config] = await Promise.all([fetchUser(), fetchConfig()]);
|
||||||
|
const profile = await fetchProfile(user.id);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (config and profile run in parallel):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { all } from 'better-all';
|
||||||
|
|
||||||
|
const { user, config, profile } = await all({
|
||||||
|
async user() {
|
||||||
|
return fetchUser();
|
||||||
|
},
|
||||||
|
async config() {
|
||||||
|
return fetchConfig();
|
||||||
|
},
|
||||||
|
async profile() {
|
||||||
|
return fetchProfile((await this.$.user).id);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**Alternative without extra dependencies:**
|
||||||
|
|
||||||
|
We can also create all the promises first, and do `Promise.all()` at the end.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const userPromise = fetchUser();
|
||||||
|
const profilePromise = userPromise.then((user) => fetchProfile(user.id));
|
||||||
|
|
||||||
|
const [user, config, profile] = await Promise.all([userPromise, fetchConfig(), profilePromise]);
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
|
||||||
@@ -0,0 +1,24 @@
|
|||||||
|
---
|
||||||
|
title: Promise.all() for Independent Operations
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: 2-10× improvement
|
||||||
|
tags: async, parallelization, promises, waterfalls
|
||||||
|
---
|
||||||
|
|
||||||
|
## Promise.all() for Independent Operations
|
||||||
|
|
||||||
|
When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
|
||||||
|
|
||||||
|
**Incorrect (sequential execution, 3 round trips):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const user = await fetchUser();
|
||||||
|
const posts = await fetchPosts();
|
||||||
|
const comments = await fetchComments();
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (parallel execution, 1 round trip):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const [user, posts, comments] = await Promise.all([fetchUser(), fetchPosts(), fetchComments()]);
|
||||||
|
```
|
||||||
@@ -0,0 +1,99 @@
|
|||||||
|
---
|
||||||
|
title: Strategic Suspense Boundaries
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: faster initial paint
|
||||||
|
tags: async, suspense, streaming, layout-shift
|
||||||
|
---
|
||||||
|
|
||||||
|
## Strategic Suspense Boundaries
|
||||||
|
|
||||||
|
Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
|
||||||
|
|
||||||
|
**Incorrect (wrapper blocked by data fetching):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
async function Page() {
|
||||||
|
const data = await fetchData(); // Blocks entire page
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<div>Sidebar</div>
|
||||||
|
<div>Header</div>
|
||||||
|
<div>
|
||||||
|
<DataDisplay data={data} />
|
||||||
|
</div>
|
||||||
|
<div>Footer</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The entire layout waits for data even though only the middle section needs it.
|
||||||
|
|
||||||
|
**Correct (wrapper shows immediately, data streams in):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Page() {
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<div>Sidebar</div>
|
||||||
|
<div>Header</div>
|
||||||
|
<div>
|
||||||
|
<Suspense fallback={<Skeleton />}>
|
||||||
|
<DataDisplay />
|
||||||
|
</Suspense>
|
||||||
|
</div>
|
||||||
|
<div>Footer</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function DataDisplay() {
|
||||||
|
const data = await fetchData(); // Only blocks this component
|
||||||
|
return <div>{data.content}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
|
||||||
|
|
||||||
|
**Alternative (share promise across components):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function Page() {
|
||||||
|
// Start fetch immediately, but don't await
|
||||||
|
const dataPromise = fetchData();
|
||||||
|
|
||||||
|
return (
|
||||||
|
<div>
|
||||||
|
<div>Sidebar</div>
|
||||||
|
<div>Header</div>
|
||||||
|
<Suspense fallback={<Skeleton />}>
|
||||||
|
<DataDisplay dataPromise={dataPromise} />
|
||||||
|
<DataSummary dataPromise={dataPromise} />
|
||||||
|
</Suspense>
|
||||||
|
<div>Footer</div>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
|
||||||
|
const data = use(dataPromise); // Unwraps the promise
|
||||||
|
return <div>{data.content}</div>;
|
||||||
|
}
|
||||||
|
|
||||||
|
function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
|
||||||
|
const data = use(dataPromise); // Reuses the same promise
|
||||||
|
return <div>{data.summary}</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
|
||||||
|
|
||||||
|
**When NOT to use this pattern:**
|
||||||
|
|
||||||
|
- Critical data needed for layout decisions (affects positioning)
|
||||||
|
- SEO-critical content above the fold
|
||||||
|
- Small, fast queries where suspense overhead isn't worth it
|
||||||
|
- When you want to avoid layout shift (loading → content jump)
|
||||||
|
|
||||||
|
**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
|
||||||
@@ -0,0 +1,59 @@
|
|||||||
|
---
|
||||||
|
title: Avoid Barrel File Imports
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: 200-800ms import cost, slow builds
|
||||||
|
tags: bundle, imports, tree-shaking, barrel-files, performance
|
||||||
|
---
|
||||||
|
|
||||||
|
## Avoid Barrel File Imports
|
||||||
|
|
||||||
|
Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
|
||||||
|
|
||||||
|
Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
|
||||||
|
|
||||||
|
**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
|
||||||
|
|
||||||
|
**Incorrect (imports entire library):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { Check, X, Menu } from 'lucide-react';
|
||||||
|
// Loads 1,583 modules, takes ~2.8s extra in dev
|
||||||
|
// Runtime cost: 200-800ms on every cold start
|
||||||
|
|
||||||
|
import { Button, TextField } from '@mui/material';
|
||||||
|
// Loads 2,225 modules, takes ~4.2s extra in dev
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (imports only what you need):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import Check from 'lucide-react/dist/esm/icons/check';
|
||||||
|
import X from 'lucide-react/dist/esm/icons/x';
|
||||||
|
import Menu from 'lucide-react/dist/esm/icons/menu';
|
||||||
|
// Loads only 3 modules (~2KB vs ~1MB)
|
||||||
|
|
||||||
|
import Button from '@mui/material/Button';
|
||||||
|
import TextField from '@mui/material/TextField';
|
||||||
|
// Loads only what you use
|
||||||
|
```
|
||||||
|
|
||||||
|
**Alternative (Next.js 13.5+):**
|
||||||
|
|
||||||
|
```js
|
||||||
|
// next.config.js - use optimizePackageImports
|
||||||
|
module.exports = {
|
||||||
|
experimental: {
|
||||||
|
optimizePackageImports: ['lucide-react', '@mui/material']
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
// Then you can keep the ergonomic barrel imports:
|
||||||
|
import { Check, X, Menu } from 'lucide-react';
|
||||||
|
// Automatically transformed to direct imports at build time
|
||||||
|
```
|
||||||
|
|
||||||
|
Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
|
||||||
|
|
||||||
|
Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
|
||||||
|
|
||||||
|
Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
|
||||||
@@ -0,0 +1,37 @@
|
|||||||
|
---
|
||||||
|
title: Conditional Module Loading
|
||||||
|
impact: HIGH
|
||||||
|
impactDescription: loads large data only when needed
|
||||||
|
tags: bundle, conditional-loading, lazy-loading
|
||||||
|
---
|
||||||
|
|
||||||
|
## Conditional Module Loading
|
||||||
|
|
||||||
|
Load large data or modules only when a feature is activated.
|
||||||
|
|
||||||
|
**Example (lazy-load animation frames):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function AnimationPlayer({
|
||||||
|
enabled,
|
||||||
|
setEnabled
|
||||||
|
}: {
|
||||||
|
enabled: boolean;
|
||||||
|
setEnabled: React.Dispatch<React.SetStateAction<boolean>>;
|
||||||
|
}) {
|
||||||
|
const [frames, setFrames] = useState<Frame[] | null>(null);
|
||||||
|
|
||||||
|
useEffect(() => {
|
||||||
|
if (enabled && !frames && typeof window !== 'undefined') {
|
||||||
|
import('./animation-frames.js')
|
||||||
|
.then((mod) => setFrames(mod.frames))
|
||||||
|
.catch(() => setEnabled(false));
|
||||||
|
}
|
||||||
|
}, [enabled, frames, setEnabled]);
|
||||||
|
|
||||||
|
if (!frames) return <Skeleton />;
|
||||||
|
return <Canvas frames={frames} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
|
||||||
@@ -0,0 +1,48 @@
|
|||||||
|
---
|
||||||
|
title: Defer Non-Critical Third-Party Libraries
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: loads after hydration
|
||||||
|
tags: bundle, third-party, analytics, defer
|
||||||
|
---
|
||||||
|
|
||||||
|
## Defer Non-Critical Third-Party Libraries
|
||||||
|
|
||||||
|
Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
|
||||||
|
|
||||||
|
**Incorrect (blocks initial bundle):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { Analytics } from '@vercel/analytics/react';
|
||||||
|
|
||||||
|
export default function RootLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<body>
|
||||||
|
{children}
|
||||||
|
<Analytics />
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (loads after hydration):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import dynamic from 'next/dynamic';
|
||||||
|
|
||||||
|
const Analytics = dynamic(() => import('@vercel/analytics/react').then((m) => m.Analytics), {
|
||||||
|
ssr: false
|
||||||
|
});
|
||||||
|
|
||||||
|
export default function RootLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<html>
|
||||||
|
<body>
|
||||||
|
{children}
|
||||||
|
<Analytics />
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,34 @@
|
|||||||
|
---
|
||||||
|
title: Dynamic Imports for Heavy Components
|
||||||
|
impact: CRITICAL
|
||||||
|
impactDescription: directly affects TTI and LCP
|
||||||
|
tags: bundle, dynamic-import, code-splitting, next-dynamic
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dynamic Imports for Heavy Components
|
||||||
|
|
||||||
|
Use `next/dynamic` to lazy-load large components not needed on initial render.
|
||||||
|
|
||||||
|
**Incorrect (Monaco bundles with main chunk ~300KB):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { MonacoEditor } from './monaco-editor';
|
||||||
|
|
||||||
|
function CodePanel({ code }: { code: string }) {
|
||||||
|
return <MonacoEditor value={code} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct (Monaco loads on demand):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import dynamic from 'next/dynamic';
|
||||||
|
|
||||||
|
const MonacoEditor = dynamic(() => import('./monaco-editor').then((m) => m.MonacoEditor), {
|
||||||
|
ssr: false
|
||||||
|
});
|
||||||
|
|
||||||
|
function CodePanel({ code }: { code: string }) {
|
||||||
|
return <MonacoEditor value={code} />;
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,44 @@
|
|||||||
|
---
|
||||||
|
title: Preload Based on User Intent
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: reduces perceived latency
|
||||||
|
tags: bundle, preload, user-intent, hover
|
||||||
|
---
|
||||||
|
|
||||||
|
## Preload Based on User Intent
|
||||||
|
|
||||||
|
Preload heavy bundles before they're needed to reduce perceived latency.
|
||||||
|
|
||||||
|
**Example (preload on hover/focus):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function EditorButton({ onClick }: { onClick: () => void }) {
|
||||||
|
const preload = () => {
|
||||||
|
if (typeof window !== 'undefined') {
|
||||||
|
void import('./monaco-editor');
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
return (
|
||||||
|
<button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
|
||||||
|
Open Editor
|
||||||
|
</button>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example (preload when feature flag is enabled):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function FlagsProvider({ children, flags }: Props) {
|
||||||
|
useEffect(() => {
|
||||||
|
if (flags.editorEnabled && typeof window !== 'undefined') {
|
||||||
|
void import('./monaco-editor').then((mod) => mod.init());
|
||||||
|
}
|
||||||
|
}, [flags.editorEnabled]);
|
||||||
|
|
||||||
|
return <FlagsContext.Provider value={flags}>{children}</FlagsContext.Provider>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
|
||||||
@@ -0,0 +1,78 @@
|
|||||||
|
---
|
||||||
|
title: Deduplicate Global Event Listeners
|
||||||
|
impact: LOW
|
||||||
|
impactDescription: single listener for N components
|
||||||
|
tags: client, swr, event-listeners, subscription
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deduplicate Global Event Listeners
|
||||||
|
|
||||||
|
Use `useSWRSubscription()` to share global event listeners across component instances.
|
||||||
|
|
||||||
|
**Incorrect (N instances = N listeners):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
function useKeyboardShortcut(key: string, callback: () => void) {
|
||||||
|
useEffect(() => {
|
||||||
|
const handler = (e: KeyboardEvent) => {
|
||||||
|
if (e.metaKey && e.key === key) {
|
||||||
|
callback();
|
||||||
|
}
|
||||||
|
};
|
||||||
|
window.addEventListener('keydown', handler);
|
||||||
|
return () => window.removeEventListener('keydown', handler);
|
||||||
|
}, [key, callback]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
|
||||||
|
|
||||||
|
**Correct (N instances = 1 listener):**
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import useSWRSubscription from 'swr/subscription';
|
||||||
|
|
||||||
|
// Module-level Map to track callbacks per key
|
||||||
|
const keyCallbacks = new Map<string, Set<() => void>>();
|
||||||
|
|
||||||
|
function useKeyboardShortcut(key: string, callback: () => void) {
|
||||||
|
// Register this callback in the Map
|
||||||
|
useEffect(() => {
|
||||||
|
if (!keyCallbacks.has(key)) {
|
||||||
|
keyCallbacks.set(key, new Set());
|
||||||
|
}
|
||||||
|
keyCallbacks.get(key)!.add(callback);
|
||||||
|
|
||||||
|
return () => {
|
||||||
|
const set = keyCallbacks.get(key);
|
||||||
|
if (set) {
|
||||||
|
set.delete(callback);
|
||||||
|
if (set.size === 0) {
|
||||||
|
keyCallbacks.delete(key);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
}, [key, callback]);
|
||||||
|
|
||||||
|
useSWRSubscription('global-keydown', () => {
|
||||||
|
const handler = (e: KeyboardEvent) => {
|
||||||
|
if (e.metaKey && keyCallbacks.has(e.key)) {
|
||||||
|
keyCallbacks.get(e.key)!.forEach((cb) => cb());
|
||||||
|
}
|
||||||
|
};
|
||||||
|
window.addEventListener('keydown', handler);
|
||||||
|
return () => window.removeEventListener('keydown', handler);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function Profile() {
|
||||||
|
// Multiple shortcuts will share the same listener
|
||||||
|
useKeyboardShortcut('p', () => {
|
||||||
|
/* ... */
|
||||||
|
});
|
||||||
|
useKeyboardShortcut('k', () => {
|
||||||
|
/* ... */
|
||||||
|
});
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,74 @@
|
|||||||
|
---
|
||||||
|
title: Version and Minimize localStorage Data
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: prevents schema conflicts, reduces storage size
|
||||||
|
tags: client, localStorage, storage, versioning, data-minimization
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version and Minimize localStorage Data
|
||||||
|
|
||||||
|
Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// No version, stores everything, no error handling
|
||||||
|
localStorage.setItem('userConfig', JSON.stringify(fullUserObject));
|
||||||
|
const data = localStorage.getItem('userConfig');
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const VERSION = 'v2';
|
||||||
|
|
||||||
|
function saveConfig(config: { theme: string; language: string }) {
|
||||||
|
try {
|
||||||
|
localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config));
|
||||||
|
} catch {
|
||||||
|
// Throws in incognito/private browsing, quota exceeded, or disabled
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadConfig() {
|
||||||
|
try {
|
||||||
|
const data = localStorage.getItem(`userConfig:${VERSION}`);
|
||||||
|
return data ? JSON.parse(data) : null;
|
||||||
|
} catch {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Migration from v1 to v2
|
||||||
|
function migrate() {
|
||||||
|
try {
|
||||||
|
const v1 = localStorage.getItem('userConfig:v1');
|
||||||
|
if (v1) {
|
||||||
|
const old = JSON.parse(v1);
|
||||||
|
saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang });
|
||||||
|
localStorage.removeItem('userConfig:v1');
|
||||||
|
}
|
||||||
|
} catch {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Store minimal fields from server responses:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// User object has 20+ fields, only store what UI needs
|
||||||
|
function cachePrefs(user: FullUser) {
|
||||||
|
try {
|
||||||
|
localStorage.setItem(
|
||||||
|
'prefs:v1',
|
||||||
|
JSON.stringify({
|
||||||
|
theme: user.preferences.theme,
|
||||||
|
notifications: user.preferences.notifications
|
||||||
|
})
|
||||||
|
);
|
||||||
|
} catch {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
|
||||||
|
|
||||||
|
**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
|
||||||
@@ -0,0 +1,48 @@
|
|||||||
|
---
|
||||||
|
title: Use Passive Event Listeners for Scrolling Performance
|
||||||
|
impact: MEDIUM
|
||||||
|
impactDescription: eliminates scroll delay caused by event listeners
|
||||||
|
tags: client, event-listeners, scrolling, performance, touch, wheel
|
||||||
|
---
|
||||||
|
|
||||||
|
## Use Passive Event Listeners for Scrolling Performance
|
||||||
|
|
||||||
|
Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
|
||||||
|
|
||||||
|
**Incorrect:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
useEffect(() => {
|
||||||
|
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX);
|
||||||
|
const handleWheel = (e: WheelEvent) => console.log(e.deltaY);
|
||||||
|
|
||||||
|
document.addEventListener('touchstart', handleTouch);
|
||||||
|
document.addEventListener('wheel', handleWheel);
|
||||||
|
|
||||||
|
return () => {
|
||||||
|
document.removeEventListener('touchstart', handleTouch);
|
||||||
|
document.removeEventListener('wheel', handleWheel);
|
||||||
|
};
|
||||||
|
}, []);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Correct:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
useEffect(() => {
|
||||||
|
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX);
|
||||||
|
const handleWheel = (e: WheelEvent) => console.log(e.deltaY);
|
||||||
|
|
||||||
|
document.addEventListener('touchstart', handleTouch, { passive: true });
|
||||||
|
document.addEventListener('wheel', handleWheel, { passive: true });
|
||||||
|
|
||||||
|
return () => {
|
||||||
|
document.removeEventListener('touchstart', handleTouch);
|
||||||
|
document.removeEventListener('wheel', handleWheel);
|
||||||
|
};
|
||||||
|
}, []);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
|
||||||
|
|
||||||
|
**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user