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.

4. Automation & Local Execution

When an extension requires triggering local MacOS functionality (where external APIs fall short or aren't applicable):

• AppleScript & Keyboard Maestro: Use Node's child_process.exec to run osascript.
  • Example: exec('osascript -e \'tell application "Keyboard Maestro Engine" to do script "MACRO_ID"\'')
• Clipboard Operations: Always use the native Clipboard utilities from @raycast/api (e.g., Clipboard.copy(text)) rather than custom bash scripts.

5. Preferences & Authentication

When building an extension that requires an external API (like Notion or Spotify):

• Add the required secrets/tokens to the preferences array in package.json.

• User Instructions: You must proactively remind the user to configure the token when they first load the extension. For example, provide a short snippet:

  ⚠️ Integration Required You need to provide this extension with an API Token.

  1. Go to [Link to API dashboard]
  2. Create a new token.
  3. Open Raycast, run this new command, and paste the Token in the preferences when prompted.