跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 react

React

使用 em qualquer talbalho 软件 反应 + Vite + TypeScript: criar projeto ou 特征, estrutura de pastas, camada de API, estado, formulários, tratamento de mrocho, qualidade, tests, runtime 配置, 容器, 部署 em supath e 遥测. Este o paderão do projeto—— aplique-o em vez decidir caso a coso. 中国植物物种信息数据库.

6 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

使用 em qualquer talbalho 软件 反应 + Vite + TypeScript: criar projeto ou 特征, estrutura de pastas, camada de API, estado, formulários, tratamento de mrocho, qualidade, tests, runtime 配置, 容器, 部署 em supath e 遥测. Este o paderão do projeto—— aplique-o em vez decidir caso a coso. 中国植物物种信息数据库.

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Padrão React、Stack fechada、Estrutura、Fronteiras、Imports e nomes、Camada de API。

文件分析

文件分析:除 SKILL.md 外,正文引用了 assets/eslint.config.js、references/runtime-and-container.md、references/telemetry.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Use em qualquer trabalho React + Vite + TypeScript: criar projeto ou feature, estrutura de pastas, camada de API, estado, formulários, tratamento de erro, qualidade, testes, runtime config, container, deploy em subpath e telemetria. Este é o padrão do projeto — aplique-o em vez de decidir caso a caso.

Padrão ReactStack fechadaEstruturaFronteirasImports e nomesCamada de APIEstadoFormuláriosRotasErrosQualidadeTestes

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
react
description
Use em qualquer trabalho React + Vite + TypeScript: criar projeto ou feature, estrutura de pastas, camada de API, estado, formulários, tratamento de erro, qualidade, testes, runtime config, container, deploy em subpath e telemetria. Este é o padrão do projeto — aplique-o em vez de decidir caso a caso.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 3
  • assets/eslint.config.js
  • references/runtime-and-container.md
  • references/telemetry.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「react」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-949fa79c518da85b-%E5%8F%8D%E5%BA%94.html
请存为 .cursor/skills/react/SKILL.md 或 .claude/skills/react/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/tassosgomes/my-skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/tassosgomes/my-skills' --list

npx skills add 'https://github.com/tassosgomes/my-skills' --skill 'react'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: react description: "Use em qualquer trabalho React + Vite + TypeScript: criar projeto ou feature, estrutura de pastas, camada de API, estado, formulários, tratamento de erro, qualidade, testes, runtime config, container, deploy em subpath e telemetria. Este é o padrão do projeto — aplique-o em vez de decidir caso a caso." metadata: group: react --- # Padrão React Este documento é a decisão, não o tutorial. Você sabe escrever o código; o que está aqui é **qual** das alternativas equivalentes este projeto usa e **onde** cada coisa mora. Quando o padrão e o hábito divergirem, o padrão vence. Divergir dele exige dizer por quê no PR. Arquitetura derivada do [bulletproof-react](https://github.com/alan2207/bulletproof-react), com dois desvios deliberados marcados como **DESVIO** ao longo do texto. ## Stack fechada | Papel | Escolha | Não use | |---|---|---| | Build | Vite 8 + `@vitejs/plugin-react-swc` | CRA, Webpack manual | | Linguagem | TypeScript 7, `strict: true` | JS, `strict: false` | | Router | `react-router` 8 (pacote sem o `-dom`) | `react-router-dom` | | Server cache | `@tanstack/react-query` 5 | fetch solto no `useEffect`, dado de API em store global | | Estado de app | `zustand` 5 | Redux, Context como store global | | HTTP | `axios` 1, instância única | `fetch` espalhado, uma instância por feature | | Formulário | `react-hook-form` 7 + `zod` 4 | form controlado na mão, validação ad hoc | | Validação/schema | `zod` 4 | yup, validação manual | | Teste | `vitest` 5 + Testing Library + `msw` 2 | Jest, mock de `fetch`/axios | | E2E | `@playwright/test` | Cypress | | Lint | ESLint 10 flat config (`eslint.config.js`) | `.eslintrc.*` | As versões são piso, não teto: suba de minor/patch à vontade, trate major como decisão. ## Estrutura Um único alvo. Não existe "estrutura para projeto pequeno" — uma POC que nasce assim cresce sem reboot, e o custo de já começar aqui é uma pasta vazia a mais. ```text src/ app/ # composição: router, providers, rotas. Só aqui pode importar de features/ assets/ components/ # UI compartilhada, sem conhecimento de domínio config/ # env.ts (tipado) e paths.ts (rotas) features/ # o mapa de negócio; cada pasta é um domínio hooks/ # hooks compartilhados lib/ # bibliotecas pré-configuradas (api-client, react-query, ...) stores/ # stores globais testing/ # utilitários de teste e mocks MSW types/ utils/ ``` Uma feature usa só as subpastas de que precisa, sem placeholder vazio: ```text src/features// api/ assets/ components/ hooks/ stores/ types/ utils/ ``` - Lógica de domínio mora em `features/*`. Se algo em `components/`, `hooks/` ou `utils/` cita um domínio pelo nome, está no lugar errado. - Não existe `shared/`. O nível raiz de `src/` já é o compartilhado. - Não existe `features/*/pages/`. Rota é composição e vive em `app/routes/`. ## Fronteiras Três invariantes. Nenhuma depende de você lembrar — `assets/eslint.config.js` falha o build. 1. **Fluxo unidirecional:** `compartilhado → features → app`. `app/` importa de tudo; `features/` importa só do compartilhado; o compartilhado não importa de ninguém. 2. **Sem import entre features.** `features/a` não enxerga `features/b`. Composição de dois domínios acontece em `app/`. 3. **Sem barrel.** Feature não tem `index.ts` de API pública; importe o arquivo direto (`@/features/users/api/get-users`). **DESVIO do hábito comum:** barrel quebra tree-shaking no Vite e o `index.ts` só simulava fronteira — quem faz a fronteira é o lint. O arquivo de zonas do bulletproof-react lista uma entrada por feature, escrita à mão. O nosso lê `src/features/` e gera as zonas, então feature nova já nasce isolada. ## Imports e nomes - **Um alias só:** `@/*` → `./src/*`. Nada de `@features`, `@shared`, `@components`. - **`baseUrl` não existe mais** — foi removido no TypeScript 7. Declare só `paths`, com substituição relativa: `"paths": { "@/*": ["./src/*"] }`. - **`kebab-case` em tudo**: arquivos e pastas, inclusive componentes (`user-profile.tsx` exporta `UserProfile`). Garantido por `eslint-plugin-check-file`. - Import relativo só dentro da mesma pasta; para qualquer outro lugar, `@/`. ## Camada de API Cliente único em `lib/api-client.ts`: uma instância axios, interceptor de request para auth e interceptor de response que desembrulha `response.data`, notifica o erro e trata 401. Cada arquivo em `features//api/` cobre **um** endpoint e exporta três coisas nesta ordem: 1. o schema Zod do input (quando há input) e os tipos inferidos dele; 2. a função que chama o endpoint, tipada no retorno; 3. o hook React Query que consome a função. Query expõe também suas `queryOptions`, para que outra chamada possa reusar a `queryKey`: ```ts // features/discussions/api/get-discussions.ts export const getDiscussions = (page = 1): Promise<{ data: Discussion[]; meta: Meta }> => api.get('/discussions', { params: { page } }); export const getDiscussionsQueryOptions = ({ page }: { page?: number } = {}) => queryOptions({ queryKey: page ? ['discussions', { page }] : ['discussions'], queryFn: () => getDiscussions(page), }); export const useDiscussions = ({ page, queryConfig }: UseDiscussionsOptions) => useQuery({ ...getDiscussionsQueryOptions({ page }), ...queryConfig }); ``` Mutation invalida pela `queryKey` das options, nunca por string literal repetida, e recebe `mutationConfig` para que o chamador acrescente seu `onSuccess` sem perder o do hook. Regras: nada de chamada declarada no meio do componente; nada de `useEffect` buscando dado. ## Estado Escolha pela natureza do dado, não pela conveniência. Comece local e suba só quando outro lugar precisar. | Natureza | Onde | |---|---| | Estado de um componente | `useState`; `useReducer` quando uma ação muda vários campos | | Global da aplicação (tema, modal, notificação) | store `zustand` em `stores/` ou na feature | | Dado que veio do servidor | React Query, sempre | | Estado de formulário | `react-hook-form` | | Estado que o usuário deve poder colar num link | URL, via router | **Dado de servidor nunca entra em store global.** Cache, revalidação e estados de carregamento são do React Query; duplicar isso numa store recria bugs de sincronização já resolvidos. ## Formulários `react-hook-form` com resolver Zod. O schema de input do endpoint é o mesmo schema do formulário — não escreva duas validações para o mesmo payload. Os campos são componentes de `components/ui/form` que encapsulam a biblioteca; a feature não importa `react-hook-form` direto nos seus componentes. ## Rotas `config/paths.ts` centraliza toda rota, cada uma com `path` e `getHref()` tipado. Ninguém monta URL concatenando string. Isso é o que permite o app rodar em subpath sem caçar link quebrado. ## Erros - **Erro de API:** tratado no interceptor do `api-client` — notifica, e em 401 redireciona para login. Componente não repete esse tratamento. - **Erro de render:** error boundary **por rota ou por área**, não um único global. Um gráfico que quebra não derruba a página inteira. - **Erro em produção:** reportado ao rastreador com source maps publicados. Erro engolido em silêncio é bug. ## Qualidade O que o lint e o compilador não pegam sozinhos: - Componente é função. Sem classe. - `any` é proibido; use `unknown` e estreite. `as` só com comentário dizendo por que é seguro. - Props tipadas por `type`, nomeada `Props`. - Componente concentra apresentação; decisão e efeito saem para hook, `api/` ou util. - Código, nomes e comentários em inglês. - Não há limite de linhas por componente. Extraia quando houver uma responsabilidade separável, não quando cruzar um número. ## Testes Integração é o centro de gravidade. Um teste que renderiza a rota com MSW respondendo vale mais que dez testes de componente isolado. - **Unitário** para util, hook compartilhado e componente de `components/ui` com lógica própria. - **Integração** para o fluxo da feature, renderizando a partir da rota em `app/routes/`. - **E2E (Playwright)** para os caminhos críticos de negócio, rodando em headless no CI. Regras: - **MSW é a única fronteira de mock.** Não faça mock de `fetch`, de axios ou de módulo de `api/`. Handlers e modelos de dados vivem em `testing/`. - Consulte por papel e por texto acessível (`getByRole`, `getByLabelText`). `getByTestId` é último recurso e pede justificativa. - Interação com `userEvent`, não `fireEvent`. - Teste o que o usuário observa. Se o teste quebra num refactor que não mudou a tela, ele testava implementação. - O nome do teste diz cenário e resultado esperado. ## Referências sob demanda Leia só quando a tarefa for essa: - [`references/runtime-and-container.md`](references/runtime-and-container.md) — config que muda por ambiente sem rebuild (`window.RUNTIME_ENV`), Dockerfile, Nginx e deploy em subpath. - [`references/telemetry.md`](references/telemetry.md) — OpenTelemetry Web, propagação W3C para a API e atributos proibidos. - `assets/` — `eslint.config.js`, `tsconfig.json`, `Dockerfile`, `nginx.conf.template`, `docker/40-runtime-env.sh` e `ingress.yaml` prontos para copiar.

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…