raycast

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Raycast Extension Development

Raycast扩展开发

Scope

适用范围

Use when writing or modifying a Raycast extension. To open or prepare a PR to raycast/extensions, use pr-raycast
instead.

Overrides global lint/commit defaults in extension directories.

适用于编写或修改Raycast扩展的场景。若要向raycast/extensions发起或准备PR，请改用**

pr-raycast

**。

会覆盖扩展目录中的全局lint/提交默认设置。

Official resources

官方资源

Linting & Formatting

代码检查与格式化

Order: lintro first → Raycast last. Raycast wins on conflicts.

bash

undefined

执行顺序： 先运行lintro → 最后运行Raycast工具链。若规则冲突，以Raycast的规则为准。

bash

undefined

1. Repo root (when lintro is configured)

1. 仓库根目录（配置lintro后）

uv run lintro fmt && uv run lintro chk

2. extensions/<name>/ — required before commit

2. extensions/<name>/ — 提交前必须执行

npm run lint npm run fix-lint && npm run lint # only if lint failed npm run build # distribution build; CI uses npm bun run dev # local dev only


Prettier: `printWidth: 120`, `singleQuote: false`. ESLint: `@raycast/eslint-config`.

npm run lint npm run fix-lint && npm run lint # 仅当lint失败时执行 npm run build # 发布构建；CI使用npm bun run dev # 仅用于本地开发


Prettier配置：`printWidth: 120`，`singleQuote: false`。ESLint使用`@raycast/eslint-config`。

Package Management

包管理

Local dev:
```
bun install
```
,
```
bun run <script>
```
CI/store validation:
```
npm run lint
```
,
```
npm run build
```

本地开发：
```
bun install
```
，
```
bun run <script>
```
CI/商店验证：
```
npm run lint
```
，
```
npm run build
```

Project Structure

项目结构

text

src/
├── <command>.tsx
├── components/
├── hooks/
├── lib/
└── types/

One command file per

package.json

commands entry. Extract testable logic to

lib/

. Vitest optional; manual test via

bun run dev

text

src/
├── <command>.tsx
├── components/
├── hooks/
├── lib/
└── types/

每个

package.json

中的命令对应一个命令文件。可测试逻辑提取到

lib/

目录。Vitest为可选工具；可通过

bun run dev

进行手动测试。

Code patterns

代码模式

getPreferenceValues<Preferences.<Command>>()

— never manual

Preferences

interfaces

```
trash()
```
for user file deletion;
```
fs/promises
```
only (no sync fs, no AppleScript)
```
execFile
```
with arg arrays — no shell string interpolation for paths

使用

getPreferenceValues<Preferences.<Command>>()

——切勿手动定义

Preferences

接口

用户文件删除使用
```
trash()
```
；仅使用
```
fs/promises
```
（禁止同步文件系统操作，禁止AppleScript）
使用带参数数组的
```
execFile
```
——路径禁止使用Shell字符串插值

Constraints

约束条件

Max 12 keywords; MIT license; US English UI strings
Max filename length 255 (macOS)

最多12个关键词；采用MIT许可证；UI字符串使用美式英语
文件名最大长度为255（macOS限制）

Store readiness checklist

商店上架准备清单

Verify before asking to open a PR (full workflow in pr-raycast
).

发起PR前需完成以下验证（完整工作流见**

pr-raycast

**）。

package.json

Fields:

name

title

description

icon

author

platforms

categories

license: MIT

Scripts:

build

dev

lint

fix-lint

publish

(

npx @raycast/api@latest publish

)

Command titles: Title Case (Apple Style Guide)
```
package-lock.json
```
committed; no bun/yarn/pnpm lockfiles

字段：

name

、

title

、

description

、

icon

、

author

、

platforms

、

categories

，

license

需设为MIT

脚本：

build

、

dev

、

lint

、

fix-lint

、

publish

（执行

npx @raycast/api@latest publish

）

命令标题：采用标题大小写格式（遵循Apple风格指南）
需提交
```
package-lock.json
```
；禁止提交bun/yarn/pnpm的锁文件

Assets

资源文件

Icon (guide, Icon Maker)

512×512 PNG in
```
assets/
```
; readable on light and dark UI; not default Raycast icon

Screenshots (specs)

```
metadata/{extension-name}-{N}.png
```
, 2000×1250 PNG, max 6 (≥3 recommended)
Window Capture + Save to Metadata in dev mode; one theme; no sensitive data

图标 (指南, Icon Maker)

尺寸为512×512的PNG图片，存放于
```
assets/
```
目录；在浅色和深色UI下均清晰可读；禁止使用Raycast默认图标

截图（规范）

命名格式为
```
metadata/{extension-name}-{N}.png
```
，尺寸2000×1250，最多6张（建议至少3张）
在开发模式下使用窗口捕获 + 保存到元数据功能；统一使用一种主题；禁止包含敏感数据

Docs

文档

```
CHANGELOG.md
```
: top entry uses
```
{PR_MERGE_DATE}
```
; accurate features only
```
README.md
```
: required if setup needed; README media in
```
media/
```
, not
```
metadata/
```

```
CHANGELOG.md
```
：最新条目需使用
```
{PR_MERGE_DATE}
```
；仅记录准确的功能变更
```
README.md
```
：若需要配置说明则必须提供；README中的媒体文件存放于
```
media/
```
目录，而非
```
metadata/
```

Contributing to extensions you don't own

贡献非自己维护的扩展

Add yourself to

contributors

package.json

; update

CHANGELOG.md

将自己添加到

package.json

的

contributors

字段中；更新

CHANGELOG.md

。