raycast-extensions

name	raycast-extensions
description	Build and maintain Raycast extensions using the Raycast API. Triggers on @raycast/api, List, Grid, Detail, Form, AI.ask, LocalStorage, Cache, showToast, and BrowserExtension. Use this repo's references/api/*.md files as the primary source of truth for component specs and API usage.

Raycast Extensions Skill

Build powerful extensions with React, TypeScript, and the Raycast API.

Repository Conventions

• When updating CHANGELOG.md for the Raycast extensions repository, always use {PR_MERGE_DATE} as the date placeholder.
• Never write a literal calendar date in CHANGELOG.md.

Quick Start (Agent Workflow)

Follow these steps when tasked with implementing or fixing Raycast features:

1. Identify the core component: Determine if the UI needs a List, Grid, Detail, or Form.
2. Consult Reference: Open and read the corresponding file in references/api/ (e.g., references/api/list.md).
3. Use Defaults:
   • Feedback: Use showToast for Loading/Success/Failure. Use showHUD only for quick background completions.
   • Data: Use Cache for frequent/transient data, LocalStorage for persistent user data.
   • Access: Always check environment.canAccess(AI) or environment.canAccess(BrowserExtension) before use.
   • Changelog: When updating CHANGELOG.md for the Raycast extensions repository, always use {PR_MERGE_DATE} as the date placeholder. Never write a literal calendar date.
4. Implementation: Provide a concise implementation using @raycast/api components.
5. Citing: Link back to the specific references/api/*.md file you used.

Cookbook Patterns

1. List & Grid (Searchable UI)

Use List for text-heavy data and Grid for image-heavy data.

• List Reference | Grid Reference

<List isLoading={isLoading} searchBarPlaceholder="Search items..." throttle>
  <List.Item
    title="Item Title"
    subtitle="Subtitle"
    accessories={[{ text: "Tag" }]}
    actions={
      <ActionPanel>
        <Action.Push title="View Details" target={<Detail markdown="# Details" />} />
        <Action.CopyToClipboard title="Copy" content="value" />
      </ActionPanel>
    }
  />
</List>

2. Detail (Rich Markdown)

Use for displaying long-form content or item details.

• Detail Reference

<Detail
  isLoading={isLoading}
  markdown="# Heading\nContent here."
  metadata={
    <Detail.Metadata>
      <Detail.Metadata.Label title="Status" text="Active" icon={Icon.Checkmark} />
    </Detail.Metadata>
  }
/>

3. Form (User Input)

Always include a SubmitForm action.

• Form Reference

<Form
  actions={
    <ActionPanel>
      <Action.SubmitForm onSubmit={(values) => console.log(values)} />
    </ActionPanel>
  }
>
  <Form.TextField id="title" title="Title" placeholder="Enter title" />
  <Form.TextArea id="description" title="Description" />
</Form>

4. Feedback & Interactivity

Prefer showToast for most feedback.

• Toast Reference | HUD Reference

// Success/Failure
await showToast({ style: Toast.Style.Success, title: "Success!" });

// HUD (Overlay)
await showHUD("Done!");

5. Data Persistence

Use Cache for performance, LocalStorage for persistence.

• Cache Reference | Storage Reference

// Cache (Sync/Transient)
const cache = new Cache();
cache.set("key", "value");

// LocalStorage (Async/Persistent)
await LocalStorage.setItem("key", "value");

6. AI & Browser Extension (Restricted APIs)

Always wrap in environment.canAccess checks.

• AI Reference | Browser Reference

if (environment.canAccess(AI)) {
  const result = await AI.ask("Prompt");
}

if (environment.canAccess(BrowserExtension)) {
  const tabs = await BrowserExtension.getTabs();
}

Additional Resources

API Reference Tree

• UI Components
  • Action Panel
  • Detail
  • Form
  • Grid
  • List
  • User Interface
• Interactivity
  • Actions
  • Alert
  • Keyboard
  • Navigation
  • Raycast Window Search Bar
• Utilities & Services
  • AI
  • Browser Extension
  • Clipboard
  • Environment
  • Feedback & HUD
    • HUD
    • Toast
  • OAuth
  • System Utilities
• Data & Configuration
  • Caching
  • Colors
  • Icons & Images
  • Preferences
  • Storage
• Advanced
  • Command Related Utilities
  • Menu Bar Commands
  • Tool
  • Window Management

Examples

For end-to-end examples combining multiple components and APIs, see examples.md.