developers.raycast.com

developers.raycast.com is the official documentation site for the Raycast API. It's where developers learn to build and share Raycast extensions using TypeScript, React, and Node.js. If you want to create a custom tool that runs inside Raycast, or publish one for the wider community, this is the starting point.

What the site is for

The documentation exists to support two related goals:

• Building extensions — writing code against the Raycast API to create new commands and interfaces.
• Sharing extensions — publishing what you build so others (or your team) can install and use it.

The site describes the Raycast Platform as having two parts: the API, which lets you build rich extensions with React, Node.js, and TypeScript, and the Store, which lets you distribute those extensions to all Raycast users.

Key features the docs highlight

The introduction calls out several things that shape how development works:

How the documentation is organized

The overview maps out where to find different kinds of content:

• Basics — step-by-step guides for building extensions.
• Teams — building and sharing extensions with teammates to speed up common workflows.
• Examples — open-source starting points you can learn from as you build.
• Information — background knowledge for understanding the platform.
• API Reference — detailed reference material with code snippets.
• Utilities — helpers that streamline common patterns and operations.

The site also notes that a complete documentation index is available via llms.txt, and pages can be viewed as Markdown.

When this site is useful to you

Reach for developers.raycast.com when you want to:

• Start your first Raycast extension and need a guided path.
• Look up a specific API method or component in the reference.
• Find a working example to adapt rather than starting from scratch.
• Understand how publishing to the Store works.
• Build internal extensions to share with your team.

If you're only a Raycast user looking to install extensions, this site is aimed at developers rather than end users. The natural next step once you've read the introduction is the "Getting Started" guide, which begins the hands-on build process.

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

Raycast extensions reach two different audiences through two different paths. To share with the entire Raycast user base, you publish to the Raycast Store. To share with coworkers, you build and distribute extensions for your team. The official documentation at developers.raycast.com covers both, with a dedicated publishing guide for the Store and a Teams section for internal sharing.

Sharing With the Community: The Raycast Store

The Raycast platform is split into two parts, and the Store is the one built for distribution:

• API — lets developers build extensions with React, Node.js, and TypeScript.
• Store — lets developers share their extensions with all Raycast users.

The documentation states directly that you'll learn how to publish your extension, so publishing is a documented, supported workflow rather than an informal handoff. The docs describe the Store as the place where you "share your extensions with all Raycast users," which is the community-facing distribution channel.

What the community path gives you

• Reach — your extension is available to the full Raycast user base, not just people you know.
• Collaboration and inspiration — the docs frame the ecosystem as one where you "build your extension, share it with our community, and get inspired by others."
• Open-source examples — the Examples section lets you "kickstart your extension by using an open-source example and learn as you go," which is also how you see how other developers structured and shipped their work.

Sharing With Your Team

Team sharing is a separate concern from Store publishing, and the docs give it its own section. The Teams section is described as the place to "build and share extensions with your teammates to speed up common workflows."

The practical distinction:

If your extension encodes internal processes, private endpoints, or company-specific tooling, the Teams path is the relevant one. If it solves a general problem other Raycast users would want, the Store is the relevant one.

Where to Find the Details

The documentation overview maps out the sections you'll need:

• Basics — step-by-step guides for building extensions.
• Teams — building and sharing extensions with teammates.
• Examples — open-source starting points.
• Information — background knowledge about the platform.
• API Reference — detailed reference with code snippets.
• Utilities — helpers for common patterns and operations.

The publishing workflow itself lives in the Store-related documentation, and the docs note a complete documentation index is available via llms.txt, with pages also available as Markdown.

What Makes Sharing Practical

Two platform features lower the friction of getting an extension in front of others:

• Familiar tooling — extensions use TypeScript, React, and Node, so you can lean on npm's ecosystem instead of learning a bespoke stack.
• Built-in UI components — you focus on logic while Raycast handles the pixels, which keeps your extension visually consistent with everything else in the Store.

A strongly typed API, hot-reloading, and modern tooling round out the developer experience, and the platform is described as "easy to start, flexible to scale" — a simple script, a static UI, or a full React build are all valid starting points.

Next Step

Start with the Basics guides to build the extension, then choose your distribution path: the Store publishing documentation for community release, or the Teams section for internal sharing. If you want a head start, pull an open-source example first and adapt it.

Raycast extensions are built with TypeScript, React, and Node.js, using the Raycast API for platform integration and npm for third-party dependencies. If you're already comfortable with a modern TypeScript/React stack, you have everything you need to start — there's no proprietary language or custom build system to learn.

The Core Stack

The Raycast API documentation states that extensions are built with three technologies working together:

Because these are mainstream tools, you can reuse existing knowledge, patterns, and libraries rather than learning a Raycast-specific framework.

TypeScript and a Strongly Typed API

The API is described as strongly typed, which means your editor can surface available commands, props, and return types as you write code. This reduces guesswork when wiring up commands and catching mistakes before runtime.

React for UI

Raycast supplies built-in UI components, so you don't design pixels from scratch. The documented approach is: "You concentrate on the logic, we push the pixels." Using the provided components also keeps your extension visually consistent with the rest of Raycast.

Node.js and the npm Ecosystem

Extensions run on Node.js, so you can pull in packages from npm to handle tasks like parsing, HTTP requests, or data transformation instead of writing them yourself.

Developer Experience and Tooling

Beyond the language stack, the platform emphasizes tooling that speeds up iteration:

• Hot-reloading — see changes without a full restart cycle
• Modern tooling — a development setup aligned with current front-end practices
• Strong typing — editor-assisted discovery of the API surface

The docs also describe a flexible starting point: you can begin with a simple script, add a static UI, or go further with React — "anything goes."

What You Need Before Starting

To build a Raycast extension, you should be able to:

1. Write and structure TypeScript code.
2. Build components with React (or be willing to learn the basics).
3. Run Node.js tooling locally and install npm dependencies.

If any of those are unfamiliar, the step-by-step guides in the Basics section of the documentation are the intended entry point.

Where to Go Next in the Docs

The documentation is organized so you can find what you need quickly:

• Basics — step-by-step guides for building extensions
• Teams — building and sharing extensions with teammates
• Examples — open-source starting points to learn from
• Information — background concepts for the platform
• API Reference — detailed reference with code snippets
• Utilities — helpers for common patterns and operations

Once your extension works, the Store lets you publish and share it with all Raycast users.

Raycast extensions are built with TypeScript, React, and Node.js, so if you already work in that stack, you can start building without learning a proprietary language or framework. The platform handles UI rendering through built-in components, which means you write logic and let Raycast push the pixels. This page covers what the tooling gives you, how the docs are organized, and where to start.

Familiar Tooling, No New Language

The Raycast API is designed around tools most web and Node developers already know:

• TypeScript — the API is strongly typed, so you get autocomplete and compile-time checks as you build.
• React — extensions use React for UI composition, so component patterns carry over directly.
• Node.js — you can pull from the npm ecosystem to add functionality quickly.

Because extensions run on this stack, you can reuse existing npm packages rather than rewriting utilities from scratch.

UI Is Handled For You

One of the more distinctive parts of the experience: you don't build the interface from scratch. Raycast provides built-in UI components, and the platform renders them. The stated design goal is that you "concentrate on the logic" while Raycast handles the pixels.

The practical effect is consistency — your extension looks and behaves like other Raycast extensions without you matching styles manually. It also lowers the barrier if you're stronger on backend logic than on front-end design.

Developer Experience Features

The docs highlight several things aimed at making development fast to iterate on:

Easy to Start, Flexible to Scale

The platform is explicitly designed to support a range of complexity:

• Start with a simple script if you just need one command.
• Add a static UI when you want structured output.
• Go full React when the extension needs richer interaction.

You aren't forced to commit to a heavy architecture up front — you can begin small and expand as the extension grows.

Community and Team Collaboration

Extensions aren't only for personal use. The Raycast Platform has two parts:

• API — for building extensions with React, Node.js, and TypeScript.
• Store — for sharing extensions with all Raycast users.

Beyond the public Store, you can also build and share extensions with teammates to speed up common workflows. The docs frame community sharing as a two-way benefit: you publish your work, and you can draw inspiration from what others have built.

Where to Find Things in the Docs

The documentation is organized into clear sections:

• Basics — step-by-step guides for building extensions.
• Teams — building and sharing extensions with teammates.
• Examples — open-source starting points you can learn from as you build.
• Information — background knowledge for understanding the platform.
• API Reference — detailed reference with code snippets.
• Utilities — helpers for common patterns and operations.

There's also a complete documentation index available at llms.txt, and pages are available in Markdown format.

Getting Started

If you're comfortable with TypeScript and React, the fastest path is to go through the Basics section, then grab an Examples project to see a working extension. From there, the API Reference and Utilities sections cover the details as you need them.