Raycast API: How to Build Custom Extensions (Developer Guide 2026)

One of the things that sets Raycast apart from other macOS launchers like Spotlight or Alfred is its extension ecosystem. With over 1,000 community-built extensions in the Raycast Store, there's a tool for almost everything. But what if you need something custom? The Raycast API lets you build your own extensions using React and TypeScript — a stack most developers already know.

In this guide, I'll walk through everything you need to build, test, and publish a Raycast extension in 2026. Whether you want to create an internal tool for your team, automate a repetitive workflow, or contribute to the open-source Store, this is your starting point. And if you're still exploring what Raycast can do, check out the current Raycast Pro deal to unlock AI features that pair well with custom extensions.

What You Can Build with the Raycast API

The Raycast API gives you access to the full launcher UI and system integration layer. Extensions can:

• Display lists and grids — searchable, filterable lists of items (repos, tasks, bookmarks, anything)
• Show detail views — rich markdown-rendered content with metadata sidebars
• Render forms — input fields, dropdowns, date pickers, file selectors for data entry
• Execute actions — open URLs, copy text, run shell commands, trigger API calls
• Integrate with the menu bar — persistent status indicators and quick-access menus
• Store preferences and data — local storage for settings, cache, and user data
• Access system APIs — clipboard, notifications, selected Finder files, frontmost application

Popular extensions built with the API include the GitHub extension, Jira integration, Notion quick capture, Spotify controls, and hundreds more. You can browse them all in the best Raycast extensions roundup.

The Tech Stack: React + TypeScript

If you've built React web apps, the Raycast development experience will feel immediately familiar. Extensions are written in TypeScript (or JavaScript, though TypeScript is strongly recommended) and use React components provided by the @raycast/api package.

The key difference from web React: you're not rendering to the DOM. Raycast provides its own UI components — List, Detail, Form, Grid, ActionPanel — that render natively inside the Raycast window. This means you get consistent styling, keyboard navigation, and smooth performance without writing any CSS.

Here's a minimal extension that displays a list:

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

export default function Command() {
  return (
    <List>
      <List.Item title="Hello World" subtitle="My first extension" />
      <List.Item title="Another Item" subtitle="With an icon" icon="star.png" />
    </List>
  );
}

That's it. No webpack config, no CSS, no build tooling to set up. Raycast handles the rendering, keyboard navigation, and search filtering automatically.

Getting Started: Your First Extension

Prerequisites

• Raycast installed on your Mac (free plan is fine for development)
• Node.js version 16 or later
• A code editor (VS Code recommended — Raycast has an official VS Code extension for development)

Step 1: Create the Extension

Open Raycast and run the "Create Extension" command. This launches an interactive wizard where you choose:

• Extension name and description
• Template (List, Detail, Form, or empty)
• Directory where the project will be created

Alternatively, use the CLI:

npx create-raycast-extension my-extension

This scaffolds a complete project with TypeScript config, package.json, and a sample command.

Step 2: Understand the Project Structure

A Raycast extension project looks like this:

my-extension/
  src/
    index.tsx          # Your main command
    other-command.tsx   # Additional commands
  assets/              # Icons and images
  package.json         # Dependencies and Raycast metadata
  tsconfig.json        # TypeScript configuration

The package.json contains Raycast-specific metadata under the raycast key: extension name, description, commands, preferences, and required permissions.

Step 3: Develop with Hot Reload

Run the development server:

npm run dev

This starts a watcher that recompiles on file changes. Back in Raycast, your development extension appears automatically. Every time you save a file, the extension reloads in Raycast — you get near-instant feedback, similar to hot module replacement in web development.

Step 4: Build and Test

The development environment is also your testing environment. Interact with your extension directly in Raycast as you build it. There's no separate simulator or emulator — you test against the real thing.

For debugging, use console.log() statements that appear in the Raycast developer console (accessible via the "Toggle Developer Tools" command), or use the VS Code debugger with Raycast's debug configuration.

Key API Components

List

The most common component. Displays a searchable list of items with titles, subtitles, icons, and accessories. Supports sections, filtering, and pagination. Most Raycast extensions are List-based.

Detail

Shows rich content rendered from Markdown. Perfect for displaying README files, API responses, documentation, or any detailed information. Supports a metadata sidebar for structured data.

Form

Input forms with text fields, text areas, dropdowns, checkboxes, date pickers, and file selectors. Use these when your extension needs to collect information from the user — like creating an issue, composing a message, or configuring settings.

Grid

A visual grid layout for image-heavy content. Used by extensions like Unsplash, icon pickers, and color palette tools. Each grid item can display an image with a title and subtitle.

ActionPanel

The action menu that appears when a user presses Enter or Cmd+K on a list item. Actions can open URLs, copy text to clipboard, push new views, run functions, and more. This is where most user interactions happen.

Preferences and Storage

The API provides a preferences system for user-configurable settings (API keys, default options) and a local storage API for persisting data between sessions. Preferences are defined in package.json and automatically rendered as a settings form in Raycast.

The Raycast Store: Publishing Your Extension

The Raycast Store is how extensions reach users. Publishing is free but requires a review process. Here's how it works:

1. Fork the extensions repository — all Store extensions live in the raycast/extensions GitHub repo
2. Add your extension — place your extension directory in the extensions/ folder
3. Open a pull request — submit your extension for review
4. Review process — the Raycast team reviews for quality, security, and guideline compliance (typically 3-7 business days)
5. Publication — once approved, your extension appears in the Store for all Raycast users

Review Guidelines

Raycast has clear quality standards for Store extensions:

• Extension must serve a clear purpose and work reliably
• Code quality matters — clean TypeScript, proper error handling, loading states
• UI should follow Raycast design patterns (use built-in components, don't fight the framework)
• No malicious behavior, data harvesting, or unnecessary permissions
• Good description, screenshots, and documentation in the README

The review process is thorough but fair. If changes are requested, the reviewers provide clear feedback. Most extensions are approved within a week.

Examples of Popular Extensions Built with the API

To get a sense of what's possible, here are some standout extensions from the Store:

• Brew — search, install, and manage Homebrew packages from Raycast. Demonstrates List with search, actions, and shell command execution.
• Notion — quick capture to Notion databases, search pages, and create new pages. Shows Form usage and API integration.
• Spotify Player — full music controls with now-playing info in the menu bar. Demonstrates menu bar integration and real-time updates.
• Clipboard History — one of Raycast's built-in extensions, showing how List with sections, search, and clipboard actions work together.
• Color Picker — system-wide color picker with format conversion. Shows how extensions can access macOS system features.

All of these are open source in the raycast/extensions repository, so you can read the source code for reference and inspiration.

Tips for Building Great Extensions

Start Simple

Your first extension doesn't need to be complex. Start with a single command that solves one problem well. You can always add more commands and features later. The best extensions in the Store often do one thing exceptionally.

Handle Loading and Errors Gracefully

Use the isLoading prop on List and Detail components to show loading indicators. Wrap API calls in try-catch blocks and display meaningful error messages with showToast(). Users should never see a blank screen or cryptic error.

Use TypeScript Strictly

Enable strict mode in your tsconfig.json. The Raycast API is fully typed, and TypeScript will catch most bugs before you even run the extension. The auto-completion in VS Code is excellent when types are properly defined.

Leverage Caching

If your extension fetches data from an API, use Raycast's Cache API to store responses locally. This makes the extension feel instant on subsequent launches while fresh data loads in the background.

Study Existing Extensions

The best way to learn patterns is by reading the source of established extensions. The raycast/extensions repo has over 1,000 extensions to learn from. Find one similar to what you're building and study its architecture.

Building Extensions with Raycast Pro Features

If you're a Raycast Pro subscriber, your extensions can leverage additional capabilities. Raycast AI can be used alongside custom extensions for intelligent autocomplete, content generation, and natural language processing within your tools. Cloud Sync ensures your extension preferences are consistent across all your Macs.

Building extensions is free on any plan, but using them with Pro features like AI takes them to the next level. If you haven't tried Pro yet, get 80% off with a free trial — it's the best deal available right now.

For more on what Raycast is and how it fits into the macOS productivity landscape, read our guide to what Raycast is.

Frequently Asked Questions

Do I need to know React to build Raycast extensions?

Basic React knowledge is helpful since Raycast extensions use React components, but you don't need to be an expert. The API provides pre-built UI components — List, Detail, Form, ActionPanel — that handle most of the layout and interaction. If you know JavaScript and understand JSX syntax, you can build functional extensions quickly. The official docs include plenty of copy-paste examples to get you started.

What is the extension review process like?

After submitting your extension via a pull request to the raycast/extensions GitHub repository, the Raycast team reviews it for quality, security, and adherence to their guidelines. Reviews typically take 3-7 business days. The team may request changes before approval — feedback is constructive and specific. Once approved, your extension is published to the Raycast Store and available to all users.

Can I monetize Raycast extensions?

Currently, Raycast does not offer a direct monetization mechanism for Store extensions. All published extensions are free for users to install. However, you can build extensions that integrate with your paid services or SaaS products, effectively using extensions as a distribution channel. Some developers also build private, custom extensions for clients as paid consulting work.

Is the Raycast API free to use?

Yes, completely. The Raycast API, development tools, CLI scaffolding, and Store publishing are all free. You don't need Raycast Pro to develop or publish extensions — the free plan includes full extension development capabilities. The only costs you might encounter are related to third-party APIs your extension integrates with (like OpenAI, databases, etc.).