Claude CodeでRaycast拡張を作る — React/TypeScript開発ガイド
Raycast拡張をClaude Codeで実装する手順です。ひな形生成、コマンドモードの選び方、ストア公開のガイドラインをまとめます。
Raycast拡張とClaude Codeの組み合わせ
Raycastはランチャーアプリで、拡張機能はReactとTypeScriptで書き、@raycast/apiが提供するコンポーネントでUIを組み立てます。コマンドを1つ実行するたびにNode.jsのプロセスが立ち上がり、Reactのレンダリング結果をRaycast本体が描画する仕組みです。
この構成はClaude Codeとの相性が良好です。ファイル編集・npm run devの実行・ターミナル出力の読み取りを、Claude Codeが一括で担当できます。src/配下のコンポーネントを書きながら、その場でRaycast上の表示を確認して修正を指示する往復が、コマンドラインだけで完結します。React/TypeScriptの経験が浅くても、実装そのものをClaude Codeに任せつつ、仕様と動作確認を担当する進め方が可能です。
前提条件を揃える
拡張を作り始める前に、次の環境を用意します。
- Raycast 1.26.0以上(macOS版)
- Node.js 22.14以上(fnmやnvmでのバージョン管理を推奨)
- npm 7以上
- Raycastアカウントへのサインイン(拡張のひな形生成に必要)
サインインすると、Raycast内で「Store」「Create Extension」「Import Extension」「Manage Extensions」の4つのコマンドが使えるようになります。今回使うのは「Create Extension」で、ひな形の生成から始めます。
ステップ1: ひな形を生成する
Raycastで「Create Extension」コマンドを開き、拡張名(例: "Hello World")を入力し、テンプレート(例: "Detail")を選びます。保存先のフォルダを指定して実行すると、そのフォルダに拡張のプロジェクト一式が生成されます。
生成されたディレクトリで依存関係をインストールし、開発モードを起動します。
cd my-extension
npm install && npm run devnpm run devはホットリロード付きの開発モードで、エラー内容もターミナルにそのまま出力されます。Raycastを開いて拡張名で検索すると、生成直後のコマンドが一覧の先頭に表示されます。この状態でエントリーポイントのsrc/index.tsxを開き、以降の実装をClaude Codeに任せます。
ステップ2: Claude Codeで実装を進める
package.jsonとsrc/index.tsxを開いた状態でClaude Codeに要件を伝えると、@raycast/apiのコンポーネント(List・Detail・Form・ActionPanelなど)を使ったコードを書かせられます。コマンドの入出力を先に短い仕様として書き出してからClaude Codeに渡すと、生成されるコードと意図のズレが減ります。この進め方はcc-sddを使った仕様駆動開発とも共通する考え方です。
拡張の挙動はpackage.jsonのcommands配列で定義します。各コマンドにはmodeプロパティが必須で、値によって動作が大きく変わります。
| mode | 動作 | 主な用途 |
|---|---|---|
view | 動作メイン画面を表示する | 主な用途リスト検索・詳細表示・フォーム入力 |
no-view | 動作画面を表示せず即座に処理する | 主な用途URLを開く・クリップボード操作など |
menu-bar | 動作メニューバーに常駐表示する | 主な用途ステータス表示・定期実行の結果表示 |
no-viewとmenu-barのコマンドにはintervalを指定でき、90秒(90s)や1時間(1h)といった間隔でバックグラウンド実行させられます。最小値は1分(1m)です。API連携やログイン情報を扱う拡張では、preferencesで必須の設定値をユーザーに入力させる設計も検討します。typeにはtextfield・password・checkbox・dropdown・appPicker・file・directoryが選べます。required: trueにすると、値が入力されるまでコマンドが開きません。APIキーの取得手順のような追加説明が要る場合は、package.jsonと同じ階層にhelp.mdを置きます。未設定時の入力画面にそのMarkdownがそのまま表示されます。
状態を保存する場合はLocalStorageを使います。
import { LocalStorage } from "@raycast/api";
export default async function Command() {
await LocalStorage.setItem("favorite-fruit", "apple");
const item = await LocalStorage.getItem<string>("favorite-fruit");
}公式ドキュメントは、LocalStorageを大量データの保存には使わない設計にしています。大きなファイルやキャッシュを持たせたい場合は、Node.js標準のfsで拡張のサポートディレクトリに書き込む方式を案内しています。
一覧の各項目に操作を追加するときはActionPanelを使います。最初と2番目のアクションは自動的に主アクション・副アクションとして扱われ、List・Grid・Detailでは↵と⌘``↵、Formでは⌘``↵と⌘``⇧``↵のショートカットが既定で割り当たります。
import { ActionPanel, Action, List } from "@raycast/api";
export default function Command() {
return (
<List>
<List.Item
title="Docs: Update API Reference"
subtitle="#1"
actions={
<ActionPanel>
<Action.OpenInBrowser url="https://github.com/raycast/extensions/pull/1" />
<Action.CopyToClipboard content="https://github.com/raycast/extensions/pull/1" />
</ActionPanel>
}
/>
</List>
);
}この並び順自体が挙動を決めるため、Claude Codeにアクションを追加させるときは「どれを主アクションにしたいか」を先頭の順序で明示すると、意図通りのショートカット割り当てになります。
ステップ3: 動作確認とデバッグ
npm run devを動かしたままsrc/index.tsxを保存すると、Raycast側の表示がホットリロードされます。ターミナルに出たエラーメッセージをそのままClaude Codeに渡せば、型エラーや@raycast/apiの呼び出しミスをその場で直させられます。ターミナルはCtrl Cで停止できますが、拡張自体はRaycastにインストールされたままなので、開発モードを閉じても普段使いに支障はありません。
ストアに出す前提がなくても、npm run buildは一度実行しておくと安全です。配布用ビルドと同じ型チェックが走るため、開発モードでは気づきにくいエラーを早期に見つけられます。Claude Codeが生成したコードは一見動いているように見えても、型定義から外れた呼び出しが残っていることがあるため、npm run buildとnpm run lintをコミット前の確認手順に組み込んでおくと安心です。
npm run build
npm run lintステップ4: ストア公開に向けて整える
Raycast Storeへの公開を考えている場合、package.jsonのメタデータをレビュー基準に合わせて整えます。authorにはRaycastアカウントのユーザー名、licenseはMITを指定し、platformsは拡張が対応するOS(macOSまたはWindows)に絞ります。拡張名・コマンド名はApple Style Guideに沿ったタイトルケースが求められ、拡張タイトルは動詞よりも名詞を優先します(例: Emoji SearchがSearch Emojiより良い例です)。コマンドタイトルでは冠詞を避ける規則もあり、Search Emojiが良い例でSearch an Emojiは避ける対象です。アクションパネルの項目名も同様にタイトルケースで統一し、サブメニューを持つ項目には末尾に…を付けます。
アイコンはPNG形式・512×512ピクセルで、ダークテーマ用にicon@dark.pngのような@darkサフィックス付きの画像を追加できます。カテゴリはApplications・Communication・Data・Developer Tools・Productivity・Systemなど15種類から最低1つ選びます。指定先はpackage.jsonのcategories配列か、拡張作成時のダイアログのどちらでも構いません。追加の設定手順が必要な拡張には、リポジトリにREADME.mdを用意します。
UIまわりでは、画面遷移にNavigation APIを使い、独自のナビゲーションスタックを実装しないことがレビュー通過の条件になっています。一覧が空になる瞬間に「No results」が一瞬表示される、いわゆるチラつきも指摘対象です。データ取得中はローディング表示を挟み、空配列をそのまま描画しないようにします。ルートコマンドのnavigationTitleは変更せず、詳細画面など下位の画面でだけ文脈を補うために使います。ローカライズは現状US Englishのみが対象で、独自の多言語対応は導入しない方針が明記されています。
ステップ5: 拡張を公開する
検証が済んだら、拡張ディレクトリで公開コマンドを実行します。
npm run publish初回実行時はGitHub認証を求められます。認証が済むと、raycast/extensionsリポジトリへのプルリクエストが自動的に作成されます。他の人がGitHub上で直接コードを編集した場合、次回のnpm run publishが失敗することがあります。その際は次のコマンドで変更を取り込んでから再実行します。
npx @raycast/api@latest pull-contributionsnpm run publishスクリプトを使わず、フォークしたリポジトリへ直接プルリクエストを送る手動フローも選べます。いずれの方法でも、プルリクエストが開かれた後はRaycastチームによるレビューを経て、マージされると自動的にストアへ公開されます。プライベートに使うだけであれば、この公開ステップ自体は不要です。
よくあるつまずき
Claude Codeに実装を任せる際、@raycast/apiに存在しないメソッド名やプロパティを提案してくることがあります。npm run devを起動した状態で保存すると型エラーとしてすぐ表面化するので、コード生成のたびに一度ビルドを通す習慣が事故を防ぎます。バージョンによる型定義の違いを確認したい場合は、拡張ディレクトリで自動生成されるraycast-env.d.tsを参照すると、実際に使えるPreferencesの型を確認できます。
npm run devを止めたまま設定ファイルだけを編集し、「変更が反映されない」と感じるケースも起きやすいつまずきです。開発モードを再起動するか、保存のたびにホットリロードされているかをRaycast側の表示で確認してください。
必須プリファレンスを1つも設定せずに公開申請すると、レビューで差し戻されます。required: trueのプリファレンスがある拡張は、初回起動時に設定画面が出ることを自分でも一度確認しておくと安全です。アイコンのダークテーマ用画像やカテゴリの未設定も、よくある差し戻し理由です。
CI環境やリモートの開発マシンからもClaude Codeで同じチェックを回したい場合は、Claude apps gatewayをCIやリモート開発機から使う設定が参考になります。npm run lintやnpm run buildの結果をClaude Codeに継続的に見せる運用を組みやすくなります。
まとめ
Raycast拡張の開発は、Raycast本体の「Create Extension」コマンドでひな形を作り、npm run devのホットリロードで動作を確かめながら、Claude Codeに実装とデバッグを任せる流れが基本になります。コマンドのmodeやプリファレンスの設計はpackage.jsonのマニフェストで決まるため、ここを先に固めてからコードを書かせると手戻りが少なくなります。ストア公開まで見据える場合は、命名規則・アイコン・カテゴリといったレビュー基準をnpm run buildの前に一通り満たしているか確認してからnpm run publishを実行してください。RaycastのList/Detailはランチャー内で完結するUIですが、チャット側にインタラクティブなUIを埋め込むMCP Appsのように、拡張のUIをどこに置くかという設計判断は他のClaude関連ツールでも共通して出てくる論点です。