Raycast API：カスタム拡張機能の作り方（開発者ガイド 2026年）

2026年2月28日公開 • 約10分で読めます

Raycast が Spotlight や Alfred などの他の macOS ランチャーと一線を画しているのが拡張機能エコシステムです。Raycast Store にはコミュニティが作った 1,000 以上の拡張機能があり、ほぼすべてのことに対応するツールが揃っています。でも、カスタムのものが必要な場合は？Raycast API を使えば、ほとんどの開発者がすでに知っている React と TypeScript で独自の拡張機能を作れます。

このガイドでは、2026年に Raycast 拡張機能を構築、テスト、公開するために必要なすべてのことを解説します。チームの内部ツールを作りたい、繰り返し作業を自動化したい、オープンソースの Store に貢献したい、どんな目的でもここが出発点です。Raycast が何をできるかをまだ探っている場合は、カスタム拡張機能と相性の良い AI 機能を解放できる現在の Raycast Pro のディールもご確認ください。

Raycast API で作れるもの

Raycast API はランチャー UI とシステム統合レイヤーへの完全なアクセスを提供します。拡張機能でできること：

  • リストとグリッドの表示 — 検索・フィルタリング可能なアイテムのリスト（リポジトリ、タスク、ブックマーク、何でも）
  • 詳細ビューの表示 — メタデータサイドバー付きのリッチな Markdown レンダリングコンテンツ
  • フォームのレンダリング — データ入力のための入力フィールド、ドロップダウン、日付ピッカー、ファイルセレクター
  • アクションの実行 — URL を開く、テキストをコピー、シェルコマンドの実行、API コールのトリガー
  • メニューバーとの統合 — 常設のステータスインジケーターとクイックアクセスメニュー
  • 設定とデータの保存 — 設定、キャッシュ、ユーザーデータのためのローカルストレージ
  • システム API へのアクセス — クリップボード、通知、選択された Finder ファイル、フォアグラウンドアプリケーション

API で構築された人気の拡張機能には、GitHub 拡張機能、Jira 統合、Notion クイックキャプチャ、Spotify コントロールなど数百以上があります。おすすめ Raycast 拡張機能一覧ですべて見ることができます。

テックスタック：React + TypeScript

React の Web アプリを作ったことがあれば、Raycast の開発体験はすぐに馴染みやすく感じるでしょう。拡張機能は TypeScript（または JavaScript、ただし TypeScript を強く推奨）で書かれ、@raycast/api パッケージが提供する React コンポーネントを使います。

Web の React との主な違い：DOM にレンダリングしません。Raycast は独自の UI コンポーネント — List、Detail、Form、Grid、ActionPanel — を提供し、これらが Raycast ウィンドウ内にネイティブにレンダリングされます。つまり、CSS を一行も書かずに、一貫したスタイル、キーボードナビゲーション、スムーズなパフォーマンスが得られます。

リストを表示する最小限の拡張機能はこのようになります：

import { List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item title="Hello World" subtitle="最初の拡張機能" />
      <List.Item title="別のアイテム" subtitle="アイコン付き" icon="star.png" />
    </List>
  );
}

これだけです。webpack の設定も、CSS も、ビルドツールの設定も不要です。Raycast がレンダリング、キーボードナビゲーション、検索フィルタリングを自動的に処理します。

始め方：最初の拡張機能を作る

前提条件

  • Mac に Raycast がインストールされていること（開発には無料プランで OK）
  • Node.js バージョン 16 以上
  • コードエディタ（VS Code 推奨 — Raycast には開発用の公式 VS Code 拡張機能あり）

ステップ 1：拡張機能を作成する

Raycast を開いて「Create Extension（拡張機能を作成）」コマンドを実行します。インタラクティブなウィザードが起動し、以下を選択します：

  • 拡張機能名と説明
  • テンプレート（List、Detail、Form、または空白）
  • プロジェクトを作成するディレクトリ

または、CLI を使用します：

npx create-raycast-extension my-extension

これで TypeScript 設定、package.json、サンプルコマンドを含む完全なプロジェクトが生成されます。

ステップ 2：プロジェクト構造を理解する

Raycast 拡張機能プロジェクトの構造はこのようになっています：

my-extension/
  src/
    index.tsx          # メインコマンド
    other-command.tsx   # 追加コマンド
  assets/              # アイコンと画像
  package.json         # 依存関係と Raycast メタデータ
  tsconfig.json        # TypeScript 設定

package.json には raycast キーの下に Raycast 固有のメタデータが含まれています：拡張機能名、説明、コマンド、設定、必要な権限。

ステップ 3：ホットリロードで開発する

開発サーバーを起動します：

npm run dev

ファイルの変更を監視して再コンパイルするウォッチャーが起動します。Raycast に戻ると、開発中の拡張機能が自動的に表示されます。ファイルを保存するたびに Raycast 内で拡張機能がリロードされ、Web 開発のホットモジュール置換に似たほぼ即座のフィードバックが得られます。

ステップ 4：ビルドとテスト

開発環境がテスト環境でもあります。構築しながら Raycast で直接拡張機能を操作します。別のシミュレーターやエミュレーターはありません — 実際のものに対してテストします。

デバッグには、Raycast の開発者コンソールに表示される console.log() 文（「Toggle Developer Tools（開発者ツールの切り替え）」コマンドでアクセス）、または Raycast のデバッグ設定を使った VS Code デバッガーを使用します。

主要な API コンポーネント

List

最も一般的なコンポーネント。タイトル、サブタイトル、アイコン、アクセサリーを持つアイテムの検索可能なリストを表示します。セクション、フィルタリング、ページネーションをサポートします。ほとんどの Raycast 拡張機能は List ベースです。

Detail

Markdown からレンダリングされたリッチコンテンツを表示します。README ファイル、API レスポンス、ドキュメント、または詳細情報の表示に最適です。構造化データのためのメタデータサイドバーをサポートします。

Form

テキストフィールド、テキストエリア、ドロップダウン、チェックボックス、日付ピッカー、ファイルセレクターを持つ入力フォーム。拡張機能がユーザーから情報を収集する必要がある場合 — 問題の作成、メッセージの作成、設定の変更など — に使用します。

Grid

画像が多いコンテンツのためのビジュアルグリッドレイアウト。Unsplash、アイコンピッカー、カラーパレットツールなどの拡張機能で使用されます。各グリッドアイテムはタイトルとサブタイトル付きの画像を表示できます。

ActionPanel

ユーザーがリストアイテムで Enter または Cmd+K を押したときに表示されるアクションメニュー。アクションは URL を開く、テキストをクリップボードにコピーする、新しいビューをプッシュする、関数を実行するなどができます。ここがほとんどのユーザーインタラクションが発生する場所です。

設定とストレージ

API はユーザーが設定可能な設定（API キー、デフォルトオプション）のための設定システムと、セッション間でデータを永続化するためのローカルストレージ API を提供します。設定は package.json で定義され、Raycast の設定フォームとして自動的にレンダリングされます。

Raycast Store：拡張機能を公開する

Raycast Store は拡張機能がユーザーに届く方法です。公開は無料ですが、レビュープロセスが必要です。仕組みはこうです：

  1. extensions リポジトリをフォーク — すべての Store 拡張機能は raycast/extensions GitHub リポジトリにあります
  2. 拡張機能を追加 — extensions/ フォルダに拡張機能のディレクトリを配置
  3. プルリクエストを開く — レビュー用に拡張機能を提出
  4. レビュープロセス — Raycast チームが品質、セキュリティ、ガイドラインの遵守についてレビュー（通常 3〜7 営業日）
  5. 公開 — 承認されると、拡張機能が Store に表示されすべての Raycast ユーザーが利用可能になります

レビューガイドライン

Raycast は Store 拡張機能に明確な品質基準を設けています：

  • 拡張機能には明確な目的があり、信頼性高く動作すること
  • コードの品質が重要 — クリーンな TypeScript、適切なエラー処理、ローディング状態
  • UI は Raycast デザインパターンに従うこと（内蔵コンポーネントを使用し、フレームワークと戦わない）
  • 悪意のある動作、データ収集、不必要な権限なし
  • README に良い説明、スクリーンショット、ドキュメントがあること

レビュープロセスは徹底的ですが公平です。変更が要求された場合、レビュアーは明確なフィードバックを提供します。ほとんどの拡張機能は 1 週間以内に承認されます。

API で構築された人気拡張機能の例

何が可能かを感じるために、Store の優れた拡張機能をいくつか紹介します：

  • Brew — Raycast から Homebrew パッケージを検索、インストール、管理します。検索付きの List、アクション、シェルコマンド実行を示しています。
  • Notion — Notion データベースへのクイックキャプチャ、ページ検索、新しいページの作成。Form の使用と API 統合を示しています。
  • Spotify Player — メニューバーに現在再生中の情報を表示する完全な音楽コントロール。メニューバー統合とリアルタイム更新を示しています。
  • Clipboard History — Raycast の組み込み拡張機能の一つで、セクション付き List、検索、クリップボードアクションが連携する仕組みを示しています。
  • Color Picker — フォーマット変換機能付きのシステム全体のカラーピッカー。拡張機能が macOS システム機能にアクセスする方法を示しています。

これらはすべて raycast/extensions リポジトリでオープンソースなので、参考とインスピレーションのためにソースコードを読むことができます。

優れた拡張機能を作るためのヒント

シンプルに始める

最初の拡張機能は複雑である必要はありません。一つの問題をうまく解決する単一のコマンドから始めましょう。後でコマンドと機能を追加することはいつでもできます。Store の最良の拡張機能はしばしば一つのことを卓越した形で行います。

ローディングとエラーを適切に処理する

List と Detail コンポーネントの isLoading プロップを使ってローディングインジケーターを表示します。API 呼び出しを try-catch ブロックでラップし、showToast() で意味のあるエラーメッセージを表示します。ユーザーは空白の画面や暗号のようなエラーを見るべきではありません。

TypeScript を厳格に使う

tsconfig.json でストリクトモードを有効にします。Raycast API は完全に型付けされており、TypeScript は拡張機能を実行する前にほとんどのバグを捉えます。型が適切に定義されていると、VS Code のオートコンプリートが優れています。

キャッシュを活用する

拡張機能が API からデータをフェッチする場合、Raycast の Cache API を使ってレスポンスをローカルに保存します。これにより、新しいデータがバックグラウンドでロードされる間、拡張機能が後続の起動時に即座に感じられるようになります。

既存の拡張機能を学ぶ

パターンを学ぶ最良の方法は、確立された拡張機能のソースを読むことです。raycast/extensions リポジトリには学べる 1,000 以上の拡張機能があります。作ろうとしているものに似た拡張機能を見つけて、そのアーキテクチャを研究しましょう。

Raycast Pro 機能を使った拡張機能の構築

Raycast Pro サブスクライバーであれば、拡張機能で追加機能を活用できます。Raycast AI をカスタム拡張機能と組み合わせて、ツール内でインテリジェントなオートコンプリート、コンテンツ生成、自然言語処理を行うことができます。クラウド同期により、すべての Mac で拡張機能の設定が一致します。

拡張機能の構築はどのプランでも無料ですが、AI などの Pro 機能と組み合わせると次のレベルに進みます。まだ Pro を試していない場合は、無料トライアル付きで 80% オフで入手できます — 現在利用可能な最良のディールです。

Raycast とは何か、macOS の生産性環境でどのような位置づけにあるかについては、Raycast とは何かのガイドをご覧ください。

よくある質問

Raycast 拡張機能を作るために React の知識は必要ですか？

Raycast 拡張機能は React コンポーネントを使うため、基本的な React の知識があると役立ちますが、エキスパートである必要はありません。API はレイアウトとインタラクションの大部分を処理する組み込み UI コンポーネント — List、Detail、Form、ActionPanel — を提供しています。JavaScript を知っていて JSX 構文を理解していれば、すぐに機能する拡張機能を作れます。公式ドキュメントにはコピー＆ペーストできる例が豊富にあります。

拡張機能のレビュープロセスはどのようなものですか？

raycast/extensions GitHub リポジトリへのプルリクエストで拡張機能を提出した後、Raycast チームが品質、セキュリティ、ガイドラインへの準拠についてレビューします。レビューには通常 3〜7 営業日かかります。変更が要求される場合があります — フィードバックは建設的で具体的です。承認されると、拡張機能が Raycast Store に公開されすべてのユーザーが利用できます。

Raycast 拡張機能を収益化できますか？

現在、Raycast は Store 拡張機能の直接収益化の仕組みを提供していません。公開された拡張機能はすべてユーザーが無料でインストールできます。ただし、有料サービスや SaaS 製品と統合する拡張機能を作ることで、効果的に拡張機能を配布チャンネルとして使えます。プライベートなカスタム拡張機能をクライアント向けの有料コンサルティング作業として作る開発者もいます。

Raycast API の使用は無料ですか？

はい、完全に無料です。Raycast API、開発ツール、CLI スキャフォールディング、Store での公開はすべて無料です。拡張機能の開発や公開に Raycast Pro は不要 — 無料プランに完全な拡張機能開発機能が含まれています。発生する可能性があるコストは、拡張機能が統合するサードパーティ API（OpenAI、データベースなど）のみです。

Raycast Pro を 80% オフで入手

14日間の無料トライアル付き。クーポンコード不要。割引は自動適用。

割引を取得 →

関連記事

2026年 開発者に最適な Raycast 拡張機能ベスト10

すべての開発者がインストールすべき必須の Raycast 拡張機能。

Raycast とは何か？macOS ランチャー完全解説

Raycast についての知識と開発者が愛用する理由のすべて。