Raycast API: 커스텀 확장 프로그램 만드는 방법 (개발자 가이드 2026)

Q: Raycast 확장 프로그램 심사 프로세스는 어떤가요?

raycast/extensions GitHub 저장소에 풀 리퀘스트를 통해 확장 프로그램을 제출하면 Raycast 팀이 품질, 보안, 가이드라인 준수 여부를 검토합니다. 심사는 일반적으로 3~7 영업일이 소요됩니다. 팀에서 승인 전에 변경을 요청할 수 있습니다. 승인되면 확장 프로그램이 Raycast 스토어에 게시됩니다.

Q: Raycast API는 무료로 사용할 수 있나요?

네, Raycast API와 모든 개발 도구는 완전 무료입니다. 비용 없이 확장 프로그램을 만들고 테스트하고 게시할 수 있습니다. API 자체는 오픈되어 있고 잘 문서화되어 있습니다. 확장 프로그램을 개발하기 위해 Raycast Pro도 필요 없습니다 — 무료 플랜에는 전체 확장 프로그램 개발 기능이 포함되어 있습니다.

Raycast를 Spotlight나 Alfred 같은 다른 macOS 런처와 구별짓는 요소 중 하나는 확장 프로그램 생태계입니다. Raycast 스토어에 1,000개 이상의 커뮤니티 제작 확장 프로그램이 있어 거의 모든 것을 위한 도구가 있습니다. 하지만 맞춤형이 필요하다면? Raycast API를 사용하면 대부분의 개발자가 이미 알고 있는 스택인 React와 TypeScript로 자신만의 확장 프로그램을 만들 수 있습니다.

이 가이드에서는 2026년에 Raycast 확장 프로그램을 만들고 테스트하고 게시하는 데 필요한 모든 것을 다룹니다. 팀을 위한 내부 도구를 만들고 싶든, 반복적인 워크플로우를 자동화하고 싶든, 오픈소스 스토어에 기여하고 싶든 이것이 시작점입니다. 그리고 커스텀 확장 프로그램과 잘 어울리는 AI 기능을 잠금 해제하려면 현재 Raycast Pro 딜을 확인하세요.

Raycast API로 만들 수 있는 것

Raycast API는 전체 런처 UI와 시스템 통합 레이어에 대한 접근을 제공합니다. 확장 프로그램은 다음을 할 수 있습니다:

목록과 그리드 표시 — 검색 가능하고 필터링 가능한 항목 목록 (저장소, 작업, 북마크, 모든 것)
상세 뷰 표시 — 메타데이터 사이드바가 있는 풍부한 마크다운 렌더링 콘텐츠
폼 렌더링 — 데이터 입력을 위한 입력 필드, 드롭다운, 날짜 선택기, 파일 선택기
액션 실행 — URL 열기, 텍스트 복사, 셸 명령 실행, API 호출 트리거
메뉴 바와 통합 — 영구적인 상태 표시기와 빠른 접근 메뉴
설정 및 데이터 저장 — 설정, 캐시, 사용자 데이터를 위한 로컬 스토리지
시스템 API 접근 — 클립보드, 알림, 선택된 Finder 파일, 최전면 애플리케이션

API로 만든 인기 확장 프로그램으로는 GitHub 확장, Jira 통합, Notion 빠른 캡처, Spotify 컨트롤, 수백 가지 더 있습니다. 최고의 Raycast 확장 프로그램 목록에서 모두 살펴볼 수 있습니다.

기술 스택: React + TypeScript

React 웹 앱을 만들어본 적이 있다면 Raycast 개발 경험이 즉시 친숙하게 느껴질 것입니다. 확장 프로그램은 TypeScript(또는 JavaScript이지만 TypeScript가 강력히 권장됨)로 작성되며 @raycast/api 패키지가 제공하는 React 컴포넌트를 사용합니다.

웹 React와의 주요 차이점: DOM에 렌더링하지 않습니다. Raycast는 자체 UI 컴포넌트 — List, Detail, Form, Grid, ActionPanel — 를 제공하며 Raycast 창 내에서 네이티브로 렌더링됩니다. 즉, CSS 없이 일관된 스타일링, 키보드 네비게이션, 부드러운 성능을 얻을 수 있습니다.

목록을 표시하는 최소한의 확장 프로그램입니다:

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

export default function Command() {
  return (
    <List>
      <List.Item title="Hello World" subtitle="첫 번째 확장 프로그램" />
      <List.Item title="다른 항목" subtitle="아이콘과 함께" icon="star.png" />
    </List>
  );
}

이것이 전부입니다. webpack 설정 없음, CSS 없음, 빌드 도구 설정 없음. Raycast가 렌더링, 키보드 네비게이션, 검색 필터링을 자동으로 처리합니다.

시작하기: 첫 번째 확장 프로그램

사전 요구사항

Mac에 Raycast 설치 (개발에는 무료 플랜으로 충분)
Node.js 버전 16 이상
코드 편집기 (VS Code 권장 — Raycast에는 개발을 위한 공식 VS Code 확장 프로그램이 있음)

1단계: 확장 프로그램 만들기

Raycast를 열고 "Create Extension" 명령을 실행하세요. 이렇게 하면 대화형 마법사가 시작되어 다음을 선택합니다:

확장 프로그램 이름 및 설명
템플릿 (List, Detail, Form, 또는 빈 것)
프로젝트가 생성될 디렉토리

또는 CLI를 사용하세요:

npx create-raycast-extension my-extension

이렇게 하면 TypeScript 설정, package.json, 샘플 명령이 포함된 완전한 프로젝트가 스캐폴드됩니다.

2단계: 프로젝트 구조 이해하기

Raycast 확장 프로그램 프로젝트는 다음과 같이 생겼습니다:

my-extension/
  src/
    index.tsx          # 메인 명령
    other-command.tsx   # 추가 명령
  assets/              # 아이콘 및 이미지
  package.json         # 의존성 및 Raycast 메타데이터
  tsconfig.json        # TypeScript 설정

package.json에는 raycast 키 아래에 Raycast 전용 메타데이터가 포함되어 있습니다: 확장 프로그램 이름, 설명, 명령, 기본 설정, 필요한 권한.

3단계: 핫 리로드로 개발하기

개발 서버를 실행하세요:

npm run dev

파일 변경 시 재컴파일하는 감시자가 시작됩니다. Raycast에서 개발 확장 프로그램이 자동으로 나타납니다. 파일을 저장할 때마다 확장 프로그램이 Raycast에서 다시 로드됩니다 — 웹 개발의 핫 모듈 교체와 유사하게 거의 즉각적인 피드백을 받을 수 있습니다.

4단계: 빌드 및 테스트

개발 환경이 테스트 환경이기도 합니다. 빌드하면서 Raycast에서 직접 확장 프로그램과 상호작용하세요. 별도의 시뮬레이터나 에뮬레이터가 없습니다 — 실제 환경에서 테스트합니다.

디버깅을 위해 Raycast 개발자 콘솔("Toggle Developer Tools" 명령으로 접근 가능)에 표시되는 console.log() 문을 사용하거나, Raycast의 디버그 설정으로 VS Code 디버거를 사용하세요.

주요 API 컴포넌트

List

가장 일반적인 컴포넌트. 제목, 부제목, 아이콘, 액세서리가 있는 항목의 검색 가능한 목록을 표시합니다. 섹션, 필터링, 페이지네이션을 지원합니다. 대부분의 Raycast 확장 프로그램은 List 기반입니다.

Detail

마크다운에서 렌더링된 풍부한 콘텐츠를 표시합니다. README 파일, API 응답, 문서, 또는 상세한 정보를 표시하는 데 적합합니다. 구조화된 데이터를 위한 메타데이터 사이드바를 지원합니다.

Form

텍스트 필드, 텍스트 영역, 드롭다운, 체크박스, 날짜 선택기, 파일 선택기가 있는 입력 폼. 확장 프로그램이 사용자로부터 정보를 수집해야 할 때 사용합니다 — 이슈 만들기, 메시지 작성, 설정 구성 등.

Grid

이미지가 많은 콘텐츠를 위한 시각적 그리드 레이아웃. Unsplash, 아이콘 선택기, 색상 팔레트 도구 같은 확장 프로그램에서 사용됩니다. 각 그리드 항목은 제목과 부제목이 있는 이미지를 표시할 수 있습니다.

ActionPanel

사용자가 목록 항목에서 Enter 또는 Cmd+K를 누를 때 나타나는 액션 메뉴. 액션은 URL 열기, 텍스트를 클립보드에 복사, 새 뷰 푸시, 함수 실행 등을 할 수 있습니다. 대부분의 사용자 상호작용이 여기서 이루어집니다.

기본 설정 및 스토리지

API는 사용자 구성 가능한 설정(API 키, 기본 옵션)을 위한 기본 설정 시스템과 세션 간 데이터를 지속하기 위한 로컬 스토리지 API를 제공합니다. 기본 설정은 package.json에 정의되며 Raycast에서 설정 폼으로 자동으로 렌더링됩니다.

Raycast 스토어: 확장 프로그램 게시하기

Raycast 스토어는 확장 프로그램이 사용자에게 도달하는 방법입니다. 게시는 무료이지만 심사 프로세스가 필요합니다. 작동 방식:

확장 프로그램 저장소 포크 — 모든 스토어 확장 프로그램은 raycast/extensions GitHub 저장소에 있음
확장 프로그램 추가 — 확장 프로그램 디렉토리를 extensions/ 폴더에 배치
풀 리퀘스트 열기 — 심사를 위해 확장 프로그램 제출
심사 프로세스 — Raycast 팀이 품질, 보안, 가이드라인 준수 여부 검토 (일반적으로 3~7 영업일)
게시 — 승인 후 확장 프로그램이 모든 Raycast 사용자를 위한 스토어에 나타남

심사 가이드라인

Raycast는 스토어 확장 프로그램에 대한 명확한 품질 기준을 가지고 있습니다:

확장 프로그램은 명확한 목적을 제공하고 안정적으로 작동해야 함
코드 품질이 중요 — 깔끔한 TypeScript, 적절한 오류 처리, 로딩 상태
UI는 Raycast 디자인 패턴을 따라야 함 (내장 컴포넌트 사용, 프레임워크와 싸우지 말 것)
악의적인 동작, 데이터 수집, 불필요한 권한 없음
README에 좋은 설명, 스크린샷, 문서

심사 프로세스는 철저하지만 공정합니다. 변경이 요청되면 심사자들이 명확한 피드백을 제공합니다. 대부분의 확장 프로그램은 일주일 이내에 승인됩니다.

API로 만든 인기 확장 프로그램 예시

무엇이 가능한지 감을 잡으려면 스토어의 몇 가지 주목할 만한 확장 프로그램을 살펴보세요:

Brew — Raycast에서 Homebrew 패키지 검색, 설치, 관리. 검색과 액션, 셸 명령 실행이 있는 List 사용을 보여줌.
Notion — Notion 데이터베이스에 빠른 캡처, 페이지 검색, 새 페이지 만들기. Form 사용과 API 통합을 보여줌.
Spotify Player — 메뉴 바에 현재 재생 정보와 함께 전체 음악 컨트롤. 메뉴 바 통합과 실시간 업데이트를 보여줌.
Clipboard History — Raycast의 내장 확장 프로그램 중 하나로, 섹션이 있는 List, 검색, 클립보드 액션이 어떻게 함께 작동하는지 보여줌.
Color Picker — 형식 변환이 있는 시스템 전체 색상 선택기. 확장 프로그램이 macOS 시스템 기능에 어떻게 접근하는지 보여줌.

이 모두는 raycast/extensions 저장소에서 오픈소스이므로 참고와 영감을 위해 소스 코드를 읽을 수 있습니다.

훌륭한 확장 프로그램 만들기 팁

단순하게 시작하기

첫 번째 확장 프로그램이 복잡할 필요는 없습니다. 하나의 문제를 잘 해결하는 단일 명령으로 시작하세요. 나중에 더 많은 명령과 기능을 추가할 수 있습니다. 스토어의 최고의 확장 프로그램들은 종종 한 가지를 탁월하게 합니다.

로딩과 오류를 우아하게 처리하기

List와 Detail 컴포넌트에서 isLoading prop을 사용하여 로딩 표시기를 보여주세요. API 호출을 try-catch 블록으로 감싸고 showToast()로 의미 있는 오류 메시지를 표시하세요. 사용자는 빈 화면이나 불명확한 오류를 보아서는 안 됩니다.

TypeScript를 엄격하게 사용하기

tsconfig.json에서 strict 모드를 활성화하세요. Raycast API는 완전히 타입이 지정되어 있으며, TypeScript는 확장 프로그램을 실행하기 전에 대부분의 버그를 잡아냅니다. 타입이 제대로 정의되어 있으면 VS Code의 자동 완성이 탁월합니다.

캐싱 활용하기

확장 프로그램이 API에서 데이터를 가져온다면 Raycast의 Cache API를 사용하여 응답을 로컬에 저장하세요. 이렇게 하면 신선한 데이터가 백그라운드에서 로드되는 동안 후속 실행에서 즉시 느껴지게 합니다.

기존 확장 프로그램 연구하기

패턴을 배우는 가장 좋은 방법은 확립된 확장 프로그램의 소스를 읽는 것입니다. raycast/extensions 저장소에는 1,000개 이상의 확장 프로그램이 있습니다. 만들려는 것과 유사한 것을 찾아 아키텍처를 연구하세요.

Raycast Pro 기능으로 확장 프로그램 만들기

Raycast Pro 구독자라면 확장 프로그램이 추가 기능을 활용할 수 있습니다. Raycast AI는 커스텀 확장 프로그램과 함께 지능적인 자동 완성, 콘텐츠 생성, 도구 내의 자연어 처리에 사용할 수 있습니다. 클라우드 동기화는 모든 Mac에서 확장 프로그램 설정이 일관되게 유지되도록 합니다.

확장 프로그램 만들기는 모든 플랜에서 무료이지만, Pro 기능인 AI와 함께 사용하면 한 단계 더 나아갈 수 있습니다. 아직 Pro를 사용해보지 않으셨다면 무료 체험으로 80% 할인을 받으세요 — 현재 이용 가능한 최고의 딜입니다.

Raycast가 무엇인지, macOS 생산성 환경에서 어떻게 맞는지에 대한 자세한 내용은 Raycast란 무엇인가 가이드를 읽어보세요.

자주 묻는 질문

Raycast 확장 프로그램을 만들려면 React를 알아야 하나요?

Raycast 확장 프로그램이 React 컴포넌트를 사용하므로 기본적인 React 지식이 도움이 되지만 전문가일 필요는 없습니다. API는 레이아웃과 상호작용의 대부분을 처리하는 사전 구축된 UI 컴포넌트 — List, Detail, Form, ActionPanel — 를 제공합니다. JavaScript를 알고 JSX 문법을 이해한다면 빠르게 기능적인 확장 프로그램을 만들 수 있습니다. 공식 문서에는 시작할 수 있는 복사-붙여넣기 예시가 많이 있습니다.

확장 프로그램 심사 프로세스는 어떤가요?

raycast/extensions GitHub 저장소에 풀 리퀘스트를 통해 확장 프로그램을 제출하면 Raycast 팀이 품질, 보안, 가이드라인 준수 여부를 검토합니다. 심사는 일반적으로 3~7 영업일이 소요됩니다. 팀에서 변경을 요청할 수 있으며 피드백은 건설적이고 구체적입니다. 승인되면 확장 프로그램이 Raycast 스토어에 게시되어 모든 사용자가 이용할 수 있게 됩니다.

Raycast 확장 프로그램으로 수익을 창출할 수 있나요?

현재 Raycast는 스토어 확장 프로그램에 대한 직접적인 수익 창출 메커니즘을 제공하지 않습니다. 게시된 모든 확장 프로그램은 사용자가 무료로 설치할 수 있습니다. 하지만 유료 서비스나 SaaS 제품과 통합되는 확장 프로그램을 만들어 효과적으로 배포 채널로 확장 프로그램을 사용할 수 있습니다. 일부 개발자는 유료 컨설팅 작업으로 클라이언트를 위한 비공개 커스텀 확장 프로그램을 만들기도 합니다.

Raycast API는 무료로 사용할 수 있나요?

네, 완전히 무료입니다. Raycast API, 개발 도구, CLI 스캐폴딩, 스토어 게시는 모두 무료입니다. 확장 프로그램을 개발하거나 게시하는 데 Raycast Pro가 필요 없습니다 — 무료 플랜에는 전체 확장 프로그램 개발 기능이 포함되어 있습니다. 발생할 수 있는 유일한 비용은 확장 프로그램이 통합하는 서드파티 API(OpenAI, 데이터베이스 등)와 관련된 것입니다.