raycast

Raycast Extension Development

This skill defines the preferred workflow and best practices for building, modifying, and troubleshooting custom Raycast extensions.

1. Scaffolding & Setup

• Preferred Method (Duplication): The fastest way to start a new extension is often duplicating the folder of an existing extension. If you do this, you must carefully update the package.json:
  • "name"
  • "title"
  • "description"
  • "author"
  • "commands" array (update name, title, and description).
• Standard Method: If not duplicating, use npx @raycast/api@latest create.
• Local Dev: After creating/duplicating, run npm install followed by npm run dev. This automatically installs the extension in the user's Raycast app locally and starts the build watcher.

2. General UI & UX Requirements

When modifying or creating forms and commands, adhere to these standards:

• Clean Inputs: Do not set defaultValue with placeholder characters (e.g., - for bullet points) unless explicitly requested.
• Auto-Close on Success: After successfully completing an action (like adding a Notion page, running a system script, etc.), the extension should disappear and return the user to the root Raycast search, rather than retaining the form on-screen.
  • Import: import { popToRoot } from "@raycast/api";
  • Execute: await popToRoot({ clearSearchBar: true });
• Icon Changes: If an extension's icon is modified (e.g., extension-icon.png), the Raycast app must be fully restarted to reflect the change. Always explicitly alert the user to "Restart Raycast" when you modify an icon.

3. Data Fetching & State

• Use @raycast/utils: For dynamic data fetching (e.g., loading dropdown options from a Notion database, or fetching Spotify tracks), rely on useCachedPromise from the @raycast/utils library. This ensures fast initial loads and proper caching.
• Dynamic Forms: For fields like Notion's select, multi_select, or integrations with existing playlists, dynamic Form.TagPicker or Form.Dropdown components should be populated via useCachedPromise rather than hardcoding.