API de Raycast: Cómo Crear Extensiones Personalizadas (Guía para Desarrolladores 2026)

Una de las características que diferencia a Raycast de otros lanzadores de aplicaciones para macOS, como Spotlight o Alfred, es su ecosistema de extensiones. Con más de 1.000 extensiones creadas por la comunidad en la Raycast Store, existe una herramienta para casi todo. Pero, ¿qué pasa si necesitas algo personalizado? La API de Raycast te permite crear tus propias extensiones usando React y TypeScript — una combinación que la mayoría de los desarrolladores ya conoce.

En esta guía, te explico todo lo que necesitas para crear, probar y publicar una extensión de Raycast en 2026. Ya sea que quieras crear una herramienta interna para tu equipo, automatizar un flujo de trabajo repetitivo o contribuir a la Store de código abierto, aquí es donde empiezas. Y si todavía estás explorando lo que Raycast puede hacer, consulta la oferta actual de Raycast Pro para desbloquear las funciones de IA que se combinan perfectamente con las extensiones personalizadas.

Qué Puedes Crear con la API de Raycast

La API de Raycast te da acceso a toda la interfaz del lanzador y a la capa de integración del sistema. Las extensiones pueden:

• Mostrar listas y cuadrículas — listas de elementos con búsqueda y filtros (repositorios, tareas, marcadores, lo que sea)
• Mostrar vistas de detalle — contenido enriquecido renderizado en Markdown con barras laterales de metadatos
• Renderizar formularios — campos de texto, menús desplegables, selectores de fecha y de archivos para la entrada de datos
• Ejecutar acciones — abrir URLs, copiar texto, ejecutar comandos de shell, llamar a APIs
• Integrarse con la barra de menús — indicadores de estado persistentes y menús de acceso rápido
• Almacenar preferencias y datos — almacenamiento local para configuraciones, caché y datos de usuario
• Acceder a las APIs del sistema — portapapeles, notificaciones, archivos seleccionados en Finder, aplicación en primer plano

Entre las extensiones populares creadas con la API se encuentran la extensión de GitHub, la integración con Jira, la captura rápida de Notion, los controles de Spotify y cientos más. Puedes explorarlas todas en el resumen de las mejores extensiones de Raycast.

El Stack Tecnológico: React + TypeScript

Si has creado aplicaciones web con React, la experiencia de desarrollo en Raycast te resultará inmediatamente familiar. Las extensiones se escriben en TypeScript (o JavaScript, aunque TypeScript es ampliamente recomendado) y usan componentes React proporcionados por el paquete @raycast/api.

La diferencia clave con respecto al React web es que no se renderiza en el DOM. Raycast proporciona sus propios componentes de interfaz — List, Detail, Form, Grid, ActionPanel — que se renderizan de forma nativa dentro de la ventana de Raycast. Esto significa que obtienes estilos consistentes, navegación por teclado y un rendimiento fluido sin escribir nada de CSS.

Aquí tienes una extensión mínima que muestra una lista:

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

export default function Command() {
  return (
    <List>
      <List.Item title="Hola Mundo" subtitle="Mi primera extensión" />
      <List.Item title="Otro Elemento" subtitle="Con un icono" icon="star.png" />
    </List>
  );
}

Eso es todo. Sin configuración de webpack, sin CSS, sin herramientas de compilación que configurar. Raycast se encarga del renderizado, la navegación por teclado y el filtrado de búsqueda de forma automática.

Primeros Pasos: Tu Primera Extensión

Requisitos previos

• Raycast instalado en tu Mac (el plan gratuito es suficiente para el desarrollo)
• Node.js versión 16 o posterior
• Un editor de código (se recomienda VS Code — Raycast tiene una extensión oficial para desarrollo)

Paso 1: Crear la Extensión

Abre Raycast y ejecuta el comando "Create Extension". Se abre un asistente interactivo donde eliges:

• Nombre y descripción de la extensión
• Plantilla (List, Detail, Form o vacía)
• Directorio donde se creará el proyecto

También puedes usar la CLI:

npx create-raycast-extension mi-extension

Esto crea un proyecto completo con configuración de TypeScript, package.json y un comando de ejemplo.

Paso 2: Entender la Estructura del Proyecto

Un proyecto de extensión de Raycast tiene esta estructura:

mi-extension/
  src/
    index.tsx          # Tu comando principal
    otro-comando.tsx   # Comandos adicionales
  assets/              # Iconos e imágenes
  package.json         # Dependencias y metadatos de Raycast
  tsconfig.json        # Configuración de TypeScript

El archivo package.json contiene metadatos específicos de Raycast bajo la clave raycast: nombre de la extensión, descripción, comandos, preferencias y permisos requeridos.

Paso 3: Desarrollar con Recarga en Caliente

Ejecuta el servidor de desarrollo:

npm run dev

Esto inicia un observador que recompila los cambios en los archivos. En Raycast, tu extensión de desarrollo aparece automáticamente. Cada vez que guardas un archivo, la extensión se recarga en Raycast — obtienes retroalimentación casi instantánea, similar a la sustitución de módulos en caliente en el desarrollo web.

Paso 4: Compilar y Probar

El entorno de desarrollo también es tu entorno de pruebas. Interactúa directamente con tu extensión en Raycast mientras la construyes. No hay un simulador o emulador aparte — pruebas contra el entorno real.

Para la depuración, usa instrucciones console.log() que aparecen en la consola de desarrollador de Raycast (accesible mediante el comando "Toggle Developer Tools"), o usa el depurador de VS Code con la configuración de depuración de Raycast.

Componentes Clave de la API

List

El componente más común. Muestra una lista de elementos con búsqueda que incluye títulos, subtítulos, iconos y accesorios. Soporta secciones, filtrado y paginación. La mayoría de las extensiones de Raycast se basan en List.

Detail

Muestra contenido enriquecido renderizado desde Markdown. Perfecto para mostrar archivos README, respuestas de API, documentación o cualquier información detallada. Soporta una barra lateral de metadatos para datos estructurados.

Form

Formularios de entrada con campos de texto, áreas de texto, menús desplegables, casillas de verificación, selectores de fecha y de archivos. Úsalos cuando tu extensión necesite recopilar información del usuario — como crear un problema, redactar un mensaje o configurar ajustes.

Grid

Un diseño de cuadrícula visual para contenido con muchas imágenes. Lo usan extensiones como Unsplash, selectores de iconos y herramientas de paleta de colores. Cada elemento de la cuadrícula puede mostrar una imagen con título y subtítulo.

ActionPanel

El menú de acciones que aparece cuando el usuario presiona Enter o Cmd+K en un elemento de la lista. Las acciones pueden abrir URLs, copiar texto al portapapeles, abrir nuevas vistas, ejecutar funciones y más. Aquí es donde ocurre la mayor parte de la interacción del usuario.

Preferencias y Almacenamiento

La API proporciona un sistema de preferencias para configuraciones definidas por el usuario (claves de API, opciones predeterminadas) y una API de almacenamiento local para persistir datos entre sesiones. Las preferencias se definen en package.json y se renderizan automáticamente como un formulario de configuración en Raycast.

La Raycast Store: Publicar tu Extensión

La Raycast Store es la forma en que las extensiones llegan a los usuarios. La publicación es gratuita pero requiere un proceso de revisión. Así funciona:

1. Hacer fork del repositorio de extensiones — todas las extensiones de la Store viven en el repositorio de GitHub raycast/extensions
2. Añadir tu extensión — coloca el directorio de tu extensión en la carpeta extensions/
3. Abrir una pull request — envía tu extensión para su revisión
4. Proceso de revisión — el equipo de Raycast revisa la calidad, la seguridad y el cumplimiento de las directrices (normalmente entre 3 y 7 días laborables)
5. Publicación — una vez aprobada, tu extensión aparece en la Store para todos los usuarios de Raycast

Directrices de Revisión

Raycast tiene estándares de calidad claros para las extensiones de la Store:

• La extensión debe tener un propósito claro y funcionar de forma fiable
• La calidad del código importa — TypeScript limpio, manejo correcto de errores, estados de carga
• La interfaz debe seguir los patrones de diseño de Raycast (usa los componentes integrados, no te enfrentes al framework)
• Sin comportamiento malicioso, recolección de datos ni permisos innecesarios
• Buena descripción, capturas de pantalla y documentación en el README

El proceso de revisión es exhaustivo pero justo. Si se solicitan cambios, los revisores proporcionan comentarios claros. La mayoría de las extensiones se aprueban en una semana.

Ejemplos de Extensiones Populares Creadas con la API

Para hacerte una idea de lo que es posible, aquí tienes algunas extensiones destacadas de la Store:

• Brew — busca, instala y gestiona paquetes de Homebrew desde Raycast. Demuestra el uso de List con búsqueda, acciones y ejecución de comandos de shell.
• Notion — captura rápida en bases de datos de Notion, búsqueda de páginas y creación de nuevas páginas. Muestra el uso de Form e integración con API.
• Spotify Player — controles de música completos con información de la canción actual en la barra de menús. Demuestra la integración con la barra de menús y las actualizaciones en tiempo real.
• Clipboard History — una de las extensiones integradas de Raycast, que muestra cómo funcionan conjuntamente List con secciones, búsqueda y acciones del portapapeles.
• Color Picker — selector de color a nivel del sistema con conversión de formato. Muestra cómo las extensiones pueden acceder a las funciones del sistema macOS.

Todas estas extensiones son de código abierto en el repositorio raycast/extensions, por lo que puedes leer el código fuente como referencia e inspiración.

Consejos para Crear Grandes Extensiones

Empieza Simple

Tu primera extensión no tiene por qué ser compleja. Comienza con un único comando que resuelva un problema bien. Siempre puedes añadir más comandos y funciones después. Las mejores extensiones de la Store a menudo hacen una sola cosa de manera excepcional.

Maneja la Carga y los Errores con Elegancia

Usa la prop isLoading en los componentes List y Detail para mostrar indicadores de carga. Envuelve las llamadas a la API en bloques try-catch y muestra mensajes de error significativos con showToast(). Los usuarios nunca deben ver una pantalla en blanco o un error críptico.

Usa TypeScript en Modo Estricto

Activa el modo estricto en tu tsconfig.json. La API de Raycast está completamente tipada, y TypeScript detectará la mayoría de los errores antes de que ejecutes siquiera la extensión. El autocompletado en VS Code es excelente cuando los tipos están correctamente definidos.

Aprovecha el Caché

Si tu extensión obtiene datos de una API, usa la API Cache de Raycast para almacenar las respuestas localmente. Esto hace que la extensión se sienta instantánea en los lanzamientos posteriores mientras los datos frescos se cargan en segundo plano.

Estudia las Extensiones Existentes

La mejor manera de aprender patrones es leyendo el código fuente de extensiones consolidadas. El repositorio raycast/extensions tiene más de 1.000 extensiones de las que aprender. Encuentra una similar a lo que estás construyendo y estudia su arquitectura.

Crear Extensiones con las Funciones de Raycast Pro

Si eres suscriptor de Raycast Pro, tus extensiones pueden aprovechar capacidades adicionales. Raycast AI se puede usar junto con extensiones personalizadas para autocompletado inteligente, generación de contenido y procesamiento de lenguaje natural dentro de tus herramientas. Cloud Sync garantiza que las preferencias de tu extensión sean consistentes en todos tus Macs.

Crear extensiones es gratuito en cualquier plan, pero usarlas con funciones Pro como la IA las lleva al siguiente nivel. Si aún no has probado Pro, obtén un 80% de descuento con una prueba gratuita — es la mejor oferta disponible ahora mismo.

Para saber más sobre qué es Raycast y cómo encaja en el panorama de productividad de macOS, lee nuestra guía sobre qué es Raycast.

Preguntas Frecuentes

¿Necesito saber React para crear extensiones de Raycast?

Los conocimientos básicos de React son útiles, ya que las extensiones de Raycast usan componentes React, pero no necesitas ser un experto. La API proporciona componentes de interfaz prefabricados — List, Detail, Form, ActionPanel — que se encargan de la mayor parte del diseño y la interacción. Si conoces JavaScript y entiendes la sintaxis JSX, puedes crear extensiones funcionales rápidamente. La documentación oficial incluye numerosos ejemplos para copiar y pegar que te ayudarán a empezar.

¿Cómo es el proceso de revisión de extensiones?

Tras enviar tu extensión mediante una pull request al repositorio de GitHub raycast/extensions, el equipo de Raycast la revisa para comprobar la calidad, la seguridad y el cumplimiento de sus directrices. Las revisiones suelen tardar entre 3 y 7 días laborables. El equipo puede solicitar cambios antes de aprobarla — los comentarios son constructivos y específicos. Una vez aprobada, tu extensión se publica en la Raycast Store y está disponible para todos los usuarios.

¿Puedo monetizar las extensiones de Raycast?

Actualmente, Raycast no ofrece un mecanismo de monetización directa para las extensiones de la Store. Todas las extensiones publicadas son gratuitas para que los usuarios las instalen. Sin embargo, puedes crear extensiones que se integren con tus servicios de pago o productos SaaS, usando efectivamente las extensiones como canal de distribución. Algunos desarrolladores también crean extensiones privadas y personalizadas para clientes como trabajo de consultoría remunerado.

¿Es gratuita la API de Raycast?

Sí, completamente. La API de Raycast, las herramientas de desarrollo, la creación de proyectos con la CLI y la publicación en la Store son todas gratuitas. No necesitas Raycast Pro para desarrollar o publicar extensiones — el plan gratuito incluye todas las capacidades de desarrollo de extensiones. Los únicos costes que podrías encontrar están relacionados con las APIs de terceros con las que se integra tu extensión (como OpenAI, bases de datos, etc.).