# Drupal Canvas 开发模板

`Drupal` `前端开发` `AI辅助开发` `组件库` `模板`

# Nebula

Nebula 提供了一个模板仓库，供 [`@drupal-canvas/create`](https://www.npmjs.com/package/@drupal-canvas/create) 使用，用于脚手架搭建基于 [Drupal Canvas 代码组件](https://project.pages.drupalcode.org/canvas/code-components) 的新代码库。该代码库作为开发环境，已完整配置好工具链和示例，支持 AI 辅助开发工作流。

## 快速开始

无需克隆本仓库，直接通过交互方式创建新项目：

```
npx @drupal-canvas/create@latest
```

## AI 辅助开发

[Agent 技能](https://agentskills.io) 位于 `.agents/skills/` 目录下。

- `nebula-*` 技能提供本仓库特有的约定和工作流。
- `canvas-*` 技能是通用的 Canvas 代码组件指引，安装自 [`drupal-canvas/skills`](https://github.com/drupal-canvas/skills)。

### 配置

以下编码智能体无需任何配置，可直接读取 `.agents/skills/` 目录：Amp、Codex、Gemini CLI、GitHub Copilot、Kimi Code CLI、OpenCode。（此列表可能很快过时；当你看到这里时，可能已有更多编码智能体支持该目录。）

如果你的编码智能体不支持该目录（例如 Cursor 或 Claude Code），请手动将相关技能从 `.agents/skills/` 创建符号链接：

```bash
# 适用于 Claude Code
ln -s .agents/skills/<技能名称> .claude/skills/<技能名称>

# 适用于 Cursor
ln -s .agents/skills/<技能名称> .cursor/skills/<技能名称>
```

### 添加新技能

从 [skills.sh](https://skills.sh) 安装新技能，例如：

```bash
npx skills add vercel-labs/agent-skills
```

### 更新技能

重新添加并选择全部技能，以更新 Drupal Canvas 技能：

```bash
npx skills add drupal-canvas/skills
```

一旦 [vercel-labs/skills#337](https://github.com/vercel-labs/skills/issues/337) 解决后，你将可以使用 `npx skills check` 和 `npx skills update` 更高效地检查和应用更新。

## 功能特性

- 已安装 [`@drupal-canvas/create`](https://www.npmjs.com/package/@drupal-canvas/cli)
  - 包含针对本代码库的 `.env.example` 文件及使用说明
- 已配置 [`@drupal-canvas/eslint-config`](https://www.npmjs.com/package/@drupal-canvas/eslint-config)
  - 在组件在 Drupal Canvas 中正常运行所需的必要校验之上，额外添加了推荐规则
- 使用 [Storybook](https://storybook.js.org) 开发和展示组件
  - 已配置 [Viewports](https://storybook.js.org/docs/essentials/viewport) 以匹配 Drupal Canvas 使用的视口尺寸
- 通过 [`@vitejs/plugin-react-swc`](https://www.npmjs.com/package/@vitejs/plugin-react-swc) 使用 [SWC](https://swc.rs) 编译（Drupal Canvas 使用 [`@swc/wasm-web`](https://swc.rs/docs/usage/wasm)）
- 使用 [Tailwind CSS v4](https://tailwindcss.com) 进行样式开发
- 已配置 [Prettier](https://prettier.io/) 及插件
  - [`prettier-plugin-tailwindcss`](https://www.npmjs.com/package/prettier-plugin-tailwindcss)
  - [`@ianvs/prettier-plugin-sort-imports`](https://www.npmjs.com/package/@ianvs/prettier-plugin-sort-imports)
- 使用 [Husky](https://typicode.github.io/husky) 配置预提交钩子，通过 [`lint-staged`](https://www.npmjs.com/package/lint-staged) 对暂存文件进行代码检查和格式化
- [GitHub Actions](https://github.com/features/actions) 工作流：
  - 静态代码检查
  - 根据[约定式提交规范](https://www.conventionalcommits.org/en/v1.0.0)校验 PR 标题（如不需要可删除 `.github/workflows/lint-pr.yml`）
- 示例组件

## 命令

| 命令 | 说明 |
| ---- | ---- |
| `npx canvas [命令] [选项]` | 运行 Drupal Canvas CLI 命令 <br>（`npx canvas` 列出所有可用命令） |
| `npm run dev` | 启动 Storybook 开发服务器 |
| `npm run storybook` | `dev` 命令的别名 |
| `npm run build-storybook` | 构建静态 Storybook |
| `npm run code:check` | 运行所有代码检查 |
| `npm run code:check:prettier` | 使用 Prettier 检查代码格式 |
| `npm run code:check:eslint` | 使用 ESLint 检查代码 |
| `npm run code:fix` | 运行所有代码修复 |
| `npm run code:fix:prettier` | 使用 Prettier 修复代码格式 |
| `npm run code:fix:eslint` | 使用 ESLint 修复代码 |