raycast-extensions

Raycast Extension Development

Build Raycast extensions using React, TypeScript, and Node.js.

Quick Start

1. Create extension: Run "Create Extension" command in Raycast
2. Install & develop: npm install && npm run dev
3. Edit: Modify src/index.tsx, changes hot-reload automatically
4. Test: Extension appears at top of Raycast root search

Choosing a UI Primitive

Need	Component
Searchable list of items	List
Image gallery/grid	Grid
User input collection	Form
Rich content display	Detail
Status bar presence	MenuBarExtra

Decision Tree

1. Displaying items the user searches/filters?

   • Text-focused → List
   • Image-focused → Grid

2. Collecting user input? → Form

3. Showing detailed content? → Detail (supports markdown + metadata)

4. Always-visible status bar? → MenuBarExtra

Core Patterns

List with ActionPanel

import { ActionPanel, Action, List } from "@raycast/api";

export default function Command() {
  return (
    <List>
      <List.Item
        title="Item"
        actions={
          <ActionPanel>
            <Action.CopyToClipboard content="Copied!" />
            <Action.OpenInBrowser url="https://raycast.com" />
          </ActionPanel>
        }
      />
    </List>
  );
}

Data Fetching

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

export default function Command() {
  const { data, isLoading } = useFetch<Item[]>("https://api.example.com/items");
  
  return (
    <List isLoading={isLoading}>
      {data?.map((item) => <List.Item key={item.id} title={item.name} />)}
    </List>
  );
}

AI Integration

import { AI, Clipboard } from "@raycast/api";

export default async function Command() {
  const answer = await AI.ask("Summarize this text");
  await Clipboard.copy(answer);
}

Note

AI requires Raycast Pro. Check access with environment.canAccess(AI).

References

For detailed documentation, see:

• UI Components: references/ui-components.md - List, Detail, Form, Grid, ActionPanel, MenuBarExtra
• Hooks & Utilities: references/hooks-utilities.md - useFetch, LocalStorage, Clipboard, OAuth, runAppleScript
• AI API: references/ai-api.md - AI.ask, useAI, model selection, streaming
• Package Structure: references/package-structure.md - manifest, commands, preferences

Examples

Runnable examples in examples/:

File	Pattern
list-with-actions.tsx	List + ActionPanel basics
list-with-detail.tsx	List with detail panel
form-with-validation.tsx	Form + useForm validation
detail-with-metadata.tsx	Detail markdown + metadata
grid-with-images.tsx	Grid layout
data-fetching.tsx	useFetch patterns
ai-integration.tsx	AI.ask with streaming
menubar-extra.tsx	MenuBarExtra interactions