Index of every page on this site: llms.txt
All skills
z2014 avatar

/frontend-dev

@75d8037
by 2014z2014/skills3 stars
Run it yourself

React frontend conventions: Vite, TypeScript, Tailwind v4, shadcn/ui, React Router, axios, TanStack Query, Zustand, React Hook Form + Zod, ESLint (eslint-config-tencent) + Prettier, pnpm, and a modules/common/api/store project layout. Use when creating or changing React frontend code, pages, components, styles, state, or frontend tooling. React 前端开发规范:在新建或修改 React 页面、组件、样式、状态管理或前端工程配置时使用。

Use this Skill: https://skilld.dev/gh/z2014/skills/frontend-dev

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈120 tokens for metadata: the name and description. ≈2k when used: this file.

Description uses 5.1% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈406 characters, or 5.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

React 前端开发

新项目使用下面的默认技术栈和项目结构。已有项目沿用现有的技术选型和约定;没有用户要求时,不引入替代方案,也不迁移现有工具。与 dev-principles 同时适用。

默认技术栈

方面 默认选择
构建与开发服务器 Vite
语言 TypeScript(strict)
样式 Tailwind CSS v4,通过 @tailwindcss/vite 引入
组件 shadcn/ui
路由 React Router
网络请求 axios(全局唯一实例)
服务端数据 TanStack Query
全局客户端状态 Zustand
表单与校验 React Hook Form + Zod
代码检查与格式化 ESLint(eslint-config-tencent、react-hooks)+ Prettier(prettier-plugin-tailwindcss)
包管理 pnpm;已有项目按 lockfile 使用对应的包管理器

需要服务端渲染、SEO 或全栈能力时,不默认使用 Vite 单页应用,先与用户确认框架。

项目结构

src/
├── main.tsx              # 应用入口,挂载全局 Provider
├── router/index.tsx      # 路由表,每个路由指向 modules 下的模块
├── modules/              # 每个路由一个模块
│   └── <module>/
│       ├── index.tsx     # 页面组件(路由入口)
│       ├── components/   # 仅本模块使用的组件
│       ├── hooks/        # 本模块的 hooks
│       └── store/        # 本模块的页面状态(需要时)
├── common/
│   ├── components/       # 全局公共组件;shadcn/ui 组件放在 common/components/ui
│   └── utils/            # 全局公共工具函数,包括 cn()
├── api/                  # client/ 为全局 axios 实例;其他子目录按业务领域存放请求函数、Zod schema、query key
└── store/                # 只存放全局状态(Zustand)
  • 每个路由对应 modules/ 下的一个模块。嵌套路由的子页面放在父模块内部的子目录中。
  • 只在一个模块里使用的组件、hooks 和状态,放在该模块内部。两个及以上模块要用时,再提取到 common/。
  • 依赖方向:modules → api、store、common;api、store → common/utils。common 不依赖 modules、api 或 store。
  • 模块之间不互相 import。需要共享的内容提取到 common/;需要共享的状态放进 store/。
  • 配置 shadcn/ui 的 components.json,把组件路径设为 @/common/components/ui,工具函数路径设为 @/common/utils。

按职责划分目录

  • 每个职责目录都通过 index.ts(包含 JSX 时为 index.tsx)暴露公共接口。外部代码只能通过这个入口导入,不能深入导入目录内部的文件。
  • 只有一个文件的职责也要有自己的目录。实现直接写在 index.ts 中,不另建文件再用一行代码重新导出。

状态

按状态类型选择存放位置:

  • 服务端数据使用 TanStack Query,不复制到 Zustand 或组件 state 中。query key 和请求函数定义在 api/ 中,模块中调用 useQuery / useMutation。
  • store/ 只存放跨页面共享的全局状态,例如登录态、主题、全局配置。每个 store 只负责一个领域。
  • 页面状态放在所属模块内部:简单状态用 useState / useReducer;模块内多个组件共享的状态,放在模块的 store/ 中。
  • 筛选条件、分页和当前标签页放在 URL 参数中。
  • 能从已有状态计算出来的值,直接计算,不另外存储。

网络请求

  • 统一使用 axios,全局只有一个实例,放在 src/api/client/。其他代码不直接调用 axios 或 fetch。
  • 请求头、错误日志、错误提示等通用逻辑,统一在这个实例中处理,不分散到各个请求或页面。
  • 后端响应统一为 { code, data, message },在实例中统一解包,并把各类失败转换为统一的错误类型。
  • api 不反向依赖 store 或界面层;需要的 token、提示等能力由应用入口注入。

数据与 API

  • 所有后端请求通过 src/api/ 中的全局 axios 实例发出,模块和组件不直接调用 axios 或 fetch。
  • 在 api/ 中使用 Zod 校验响应数据,并从 schema 推导 TypeScript 类型。
  • 每个数据视图都要处理加载中、空数据和出错三种状态。在路由层设置错误边界(Error Boundary)。
  • 修改数据后,使相关 query 失效或更新缓存,不手动同步多份数据。

组件与样式

  • 优先使用 shadcn/ui 组件,并在其基础上组合。需要新的基础组件时,通过 shadcn CLI 添加,不重复手写。
  • 设计变量(颜色、间距、圆角、字体)定义在 CSS 的 @theme 中。不散落硬编码的颜色值;少用任意值(如 w-[437px])。
  • 使用 cn()(clsx + tailwind-merge)合并类名。条件样式通过 cn() 或组件变体实现。
  • 同一组类名重复出现时,提取为组件,而不是使用 @apply。
  • 组件接收数据和回调作为 props;数据请求和全局状态的访问放在页面组件或 hooks 中。

可访问性

  • 使用语义化 HTML:按钮用 <button>,链接用 <a>,不给 <div> 绑定点击事件代替按钮。
  • 表单控件都有对应的 label;图标按钮提供 aria-label。
  • 所有交互都可以通过键盘完成,焦点状态清晰可见。

性能

  • 不预防性地添加 useMemo、useCallback 或 memo。只在测量到性能问题,或项目约定要求时使用;项目启用 React Compiler 时,交给编译器处理。
  • 路由级页面按需加载(lazy)。
  • 长列表考虑虚拟滚动;图片指定尺寸并延迟加载。

安全

  • 以 VITE_ 开头的环境变量会打包进前端代码,不在其中存放密钥。
  • 不使用 dangerouslySetInnerHTML 渲染未经清理的内容。

代码检查与格式化

  • ESLint 以 eslint-config-tencent 为基础规则,使用它的 flat 配置(JavaScript、import/export、TypeScript 规则)。规则包不含 React 规则,另加 eslint-plugin-react-hooks。
  • 格式交给 Prettier:配置最后加入 eslint-config-prettier,关闭与 Prettier 冲突的格式规则。Prettier 选项与腾讯规范一致:singleQuote: true、printWidth: 120,其余用默认值。
  • 依赖:eslint、eslint-config-tencent、@babel/core(7.x,规则包的 peer 依赖)、eslint-plugin-react-hooks、eslint-config-prettier、globals、prettier、prettier-plugin-tailwindcss。
  • TypeScript 规则需要类型信息,每个被检查的 .ts / .tsx 文件都必须属于某个 tsconfig,否则会报解析错误。Vite 模板的根 tsconfig.json 只有 references,需把 project 设为各个子配置。
  • 项目只在此基础上按需收紧或覆盖个别规则,并注明原因;不整体关闭规则包。

eslint.config.js:

import tencent from 'eslint-config-tencent/flat';
import prettier from 'eslint-config-prettier/flat';
import reactHooks from 'eslint-plugin-react-hooks';
import globals from 'globals';

export default [
  { ignores: ['dist'] },
  ...tencent({
    tsconfigRootDir: import.meta.dirname,
    project: ['./tsconfig.app.json', './tsconfig.node.json'],
  }),
  { files: ['**/*.{ts,tsx}'], languageOptions: { globals: globals.browser } },
  reactHooks.configs.flat.recommended,
  prettier,
];

.prettierrc:

{ "singleQuote": true, "printWidth": 120, "plugins": ["prettier-plugin-tailwindcss"] }

验证

完成前执行:

  1. 类型检查和 lint 全部通过。
  2. 启动开发服务器,在浏览器中检查修改过的页面:正常状态、加载中、空数据、出错,以及窄屏布局。

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill provides standard architectural guidelines and best practices for React frontend development using modern, industry-standard tools like Vite, Tailwind CSS, and TanStack Query. It includes sections on project structure, security, and performance with no malicious patterns detected.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 75d8037. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated last month

README badge

README badge for z2014/skills/frontend-dev