raycast-core

name	raycast-core
description	Shared reference for the Raycast cluster: command types (view / no-view / menu-bar), the @raycast/api component & navigation model, the package.json manifest, preferences, data/storage hooks, and the build/develop/publish flow. USE WHEN building a Raycast extension and you need the cross-cutting model the spokes share. Exact API signatures: defer to developers.raycast.com.
cluster	raycast
version	1.0.0

Raycast Core

Shared model for the raycast cluster. Extensions are React + TypeScript apps rendered inside Raycast. Keep these concepts consistent across spokes. For exact, current API signatures, defer to the official docs (developers.raycast.com) — this is the mental model, not an API dump.

1. Command types (declared in the manifest)

• view — renders a React UI (List, Grid, Detail, Form).
• no-view — runs logic and returns (background/script-like; show feedback via showHUD/showToast).
• menu-bar — a menu-bar extra (MenuBarExtra) that can refresh on an interval.

Each command is an entry in the manifest with its own mode and default export.

2. The manifest (package.json)

Raycast extensions are configured in package.json, not code: extension name/title/description/icon, the commands[] array (each with name, title, mode), preferences[], tools[] (for AI extensions → raycast-ai-extensions), and categories. The file is the source of truth for what Raycast shows and runs.

3. UI & navigation (@raycast/api)

• Containers: List (searchable rows + List.Item), Grid, Detail (markdown), Form (inputs).
• Every item exposes an ActionPanel of **Action**s (the ⌘K actions) — this is how users act on results.
• Navigation: useNavigation().push()/pop() to move between views; Raycast manages the stack.

4. Preferences & environment

• Declare preferences in the manifest; read with getPreferenceValues<T>(). Per-command or extension-wide; types include password (secret) fields.
• environment exposes runtime info; LaunchProps carries arguments/launch context.

5. Data, async & storage

• Data hooks (from @raycast/utils): useFetch, useCachedPromise, useExec, usePromise — they handle loading/error/revalidation and pair with List's isLoading.
• Persistence: LocalStorage (key/value) and Cache for cross-launch state.
• Feedback: showToast (Success/Failure/Animated), showHUD, confirmAlert for destructive actions.

6. Build / develop / publish

• ray develop (or npm run dev) — live-reload into Raycast while building.
• ray build — typecheck + bundle.
• Publish = submit to the Raycast Store via PR to raycastapp/extensions → raycast-store-publishing.

7. Two different "Raycast" jobs (don't conflate)

• Building an extension that runs inside Raycast → raycast-extension (+ this core).
• Designing your own app to look like Raycast (light mode, Inter, 4px grid) → raycast-ui-skills. This is an aesthetic, not the extension API.

8. Shared guardrails

• Manifest is the source of truth — keep commands[]/preferences[]/tools[] in sync with code.
• Use the @raycast/utils data hooks for isLoading/error/revalidation instead of hand-rolled state.
• Confirm destructive actions (confirmAlert); never print secrets read from preferences.
• Defer exact/changing API signatures to developers.raycast.com rather than guessing.