@raycast/api

Raycast TypeScript API (Alpha)

Welcome to the Raycast developer program and our API Alpha!

High-level Overview

This API enables you to create a custom Raycast extension using our TypeScript API. Your extension can be installed in Raycast and its commands will appear in Raycast root search. Using our CLI dev tool, the TypeScript code is compiled into a package containing JavaScript and then loaded into Raycast at runtime. Each command runs in its own isolated environment on the Node.js runtime and can interact with Raycast and the host environment through the API. Commands can define a user interface that will be rendered with native components (no web view).

Over time, and as this API will is being further developed, more and more features will become available. Our mission is to build a rich API that will cover many use cases for your custom productivity tools, and later allow distribution, sharing, and discovery of commands through a store.

Let's get started!

Dev Environment

Raycast automatically downloads the Node runtime for you. You might still want to install npm 7.x to be able to manually install additional dependencies for your extension. (Tip: You can use a tool such as Node Version Manager to manage multiple installed versions on your machine.)

We recommend Visual Studio Code for development. You might want to install the ESLint and Prettier plugins.

Note that all starter projects include a number of dot files for configuring defaults for TypeScript, ESLint, and Prettier. These tools are also set up in the package.json file as dev dependencies. Technically, they are not required since the ray dev tool can transform TypeScript through its build and develop commands, but they make development via Visual Studio Code much more pleasant.

Extension Structure

An extension consists of an entry point file (e.g. src/index.ts) per command and a package.json manifest file that holds metadata about the extension and its commands. The format of the manifest file is very similar to that of npm packages. In addition to some of the standard properties, a commands property describes which commands an extension exposes to Raycast root search and how they are presented. Each command has a property name that maps to its main entry point file in the src folder (e.g. a command with name "create" would map to src/create).

TypeScript is the recommended language for extensions; however, plain JavaScript commands are also supported by using the js file extension for the entry point. The supported file extensions are ts, tsx, js, and jsx. Extensions using React tags should be .tsx or .jsx.

An assets folder can hold icons and images that will be packaged into the command and can be referenced at runtime, for example the icon for the command or other icons for lists and the action panel.

Manifest

The example below shows a manifest file for a simple Raycast command.

{
  "name": "raycast-example-react-helloworld",
  "title": "Raycast Examples",
  "description": "Raycast API example projects",
  "icon": "command-icon.png",
  "private": true,
  "commands": [
    {
      "name": "index",
      "title": "React Helloworld",
      "description": "Simple React Helloworld Example",
      "mode": "view"
    }
  ],
  "engines": {
    "raycast": ">=1.19.0"
  },
  "devDependencies": {},
  "dependencies": {
    "@raycast/api": "<Link to Raycast API>"
  }
}

Extension Properties

Property	Description
name	A unique name for the extension under your username handle. The name should be compatible with URLs ("slugified", lowercase with dashes) since it can appear in store deeplinks.
title	The display name of the extension, shown to the user in Raycast.
description	The full description of the extension shown in the Raycast store.
icon	A reference to an icon file in the assets folder. We recommend the png format and a size of at least 128x128 pixels.
keywords	An optional array of keywords for which the extension can be searched in Raycast.
private	This is a standard property with a fix value of "true" so that npm installs do not generate license-related warnings. (Officially this property means that packages are not published to the npm registry.)
commands	An array of commands exposed by the extension, see Command Properties.
engines	Expresses version compatibility with the Raycast API. For now, you do not need to modify this property or just match it to the current Raycast version.
preferences	Extensions can contribute preferences that are shown in Raycast Preferences > Extensions when selecting the command. You can use preferences for configuration values and passwords or personal access tokens, see Preference Properties.
devDependencies	Standard npm property for declaring dependencies that are relevant for development only.
dependencies	Standard npm property for declaring dependencies that are bundled into the final compiled JavaScript entry point file for a command. In general, you can use all npm dependencies that run on Node.js and are compatible with standard JavaScript bundlers. Note that we currently do not support binary dependencies.
external	Optional array of package or file names that should be excluded from the build. The package will not be bundled but the import is preserved and will be evaluated at runtime.

Command Properties

Property	Description
name	A unique name for the command. The name directly maps to the entry point file for the command. So a command named "index" would map to index.ts (or any other supported TypeScript or JavaScript file extension such as .tsx, .js, .jsx).
title	The display name of the command, shown to the user in Raycast.
description	The full description of the extension shown in the Raycast store.
icon	A optional reference to an icon file in the assets folder. We recommend the png format and a size of at least 128x128 pixels. If no icon is specified, the extension icon will be used.
mode	A value of view indicates that the command will show a main view when performed. no-view means that the command does not push a view to the main navigation stack in Raycast (e.g., use it for directly opening a URL or other API functionality that does not require a user interface.)
keywords	An optional array of keywords for which the command can be searched in Raycast.
preferences	Commands can optionally contribute preferences that are shown in Raycast Preferences > Extensions when selecting the command. You can use preferences for configuration values and passwords or personal access tokens, see Preference Properties. Commands automatically "inherit" extension preferences and can also override entries with the same name.

Preference Properties

Property	Description
name	A unique name for the preference.
type	The preference type. Currently we support type textfield and password (for secure entry), checkbox, and dropdown.
required	Indicates whether the value is required and must be entered by the user before the extension is usable.
title	The display name of the preference, shown to the user in Raycast preferences.
description	The full description of the preference. This value may be shown in to the user in future Raycast versions.
placeholder	An optional placeholder text shown in preference textfield types.
link	An optional additional link to an external website. This value may be shown to the user in future Raycast versions.
default	The optional default value for the field. For textfields, this is a string value; for checkboxes a boolean; for dropdowns the value of the selected item.
data	Optional, dropdowns only: An array of objects with title and value properties, e.g.: [{"title": "Item 1", value: "1"}]
label	Optional, checkboxes only: The label of the checkbox. If you want to group multiple checkboxes into a section, set the title of the first checkbox and leave the title of the other checkboxes empty but specify their label.

Development Workflow

There are two main ways how you can create your own extension: either you clone one of our example projects and import it into Raycast (built-in command "Import Extension") or you use the scaffolding commands to create a new extension from a template (built-in command "Create Extension"). In your project folder, you then start ray develop through the CLI to monitor source changes and automatically deploy the built output into Raycast. When opening your command, you can reload the changes through the action panel or the default shortcut cmd + r.

Notes

• A development version of the extension can live side by side with published extension from the extension store.
• When you change the package manifest file, you should reinstall the extension through the built-in development panel.

Using Libraries

Every command runs on a recent version of Node.js (16.3) in its own isolated environment. You can install standard npm packages that are compatible with Node.js and common JavaScript bundlers. Packages relying on binary dependencies are not yet supported and should be avoided.

API Overview

The following sections are short summaries of the main functional areas of the API. You can find more detailed information in the index and individual documentation entries.

Imports

Note that there are currently no further namespaces in the API, so you just import the needed types and functions from "@raycast/api". TypeScript supports different ways of importing, so either of the following approaches works:

import * as ray from "@raycast/api";

ray.showToast(ray.ToastStyle.Success, "Hello World");

You selectively import the needed types and functions, for instance:

import { showToast, ToastStyle } from "@raycast/api";

showToast(ToastStyle.Success, "Hello World");

Lifecycle

When a command is opened in Raycast, the command code is executed right away. If the extension exports a default function, this function will automatically be called. You can then {@link render} a user interface or just perform logic and use other API methods. For commands with their mode property set to default (instead of view) in the package manifest, no user interface will be rendered when the command is performed in Raycast.

You can inspect the {@link Environment} for extension information and paths or access Preference Properties for user-entered values that are passed to the command.

When the command is unloaded (typically by popping back to root search), Raycast unloads the entire command from memory. Note that there are memory limits for a command and if those limits are exceeded the command gets terminated.

Once we enable public distribution of commands in later releases, there will be additional integrity checks that ensure the installed package sources have not been modified before running the command.

Debugging

You can log output to a OS log stream and view the stream either when starting ray develop or via the OS console app, if you prefer a separate window. You can use standard console.log or console.error calls for logging information and errors. Unhandled exceptions and unhandled promise rejections are automatically logged and shown in the user interface. If you wish to show your own errors in the UI, you can use the {@link showToast} method.

Debugging via ray develop: Just run ray develop and view the log stream in the output.

Debugging via OS console: Open /Applications/Utilities/Console.app and in the top right corner, select Subsystem and enter com.raycast.extensions. In the Action menu, check Include Info Messages and Include Debug Messages. Click the Start button (Big Sur) to see the output of log calls from your command.

User Interface

Raycast uses React for its user interface declaration and renders the supported elements to native Raycast UI. State is managed through React's built-in hooks and effects. When state is updated, Raycast automatically re-renders the user interface.

The API comes with a set of UI components that are currently enable you to set up {@link List} and {@link Detail}-style user interfaces and provide interaction via an {@link ActionPanel}. Each action can be associated with a {@link KeyboardShortcut} so that users can interact with the command without using the mouse.

You can gather user input through {@link Form} elements and show input fields such as {@link Form.TextField textfields} or {@link Form.Checkbox checkboxes}.

The UI API also includes imperative-style methods such as {@link showToast}, {@link closeMainWindow}, or {@link popToRoot}. They trigger temporary UI changes and are typically used from actions or to show error states.

Clipboard

You can write contents to the clipboard through {@link writeTextToClipboard} and clear it through {@link clearClipboard}. We also provide convenience actions such as {@link CopyToClipboardAction} or {@link OpenInBrowserAction} for standard {@link ActionPanel} operations.

Storage

Similar to the LocalStorage browser API, this group of functions can be used to store non-sensitive small data that is persisted across command launches. All commands in an extension have shared access to the stored data. Values can be managed through functions such as {@link getLocalStorageItem}, {@link setLocalStorageItem}, or {@link removeLocalStorageItem}. A typical use cases is storing user preferences. Note that this API is not meant to store large amounts of data and the data is not encrypted, i.e. could easily be inspected by anybody. We are going to provide more storage options for larger and sensitive data in the future.

You can also use Node's built-in APIs to write files, e.g. to the extension's own supportPath, accessible through {@link Environment}.