https://github.com/LitoMore/raycast-cross-extension-conventions
Defines the development approach for cross-extension in Raycast
https://github.com/LitoMore/raycast-cross-extension-conventions
conventions cross-extension extensions raycast
Last synced: about 1 month ago
JSON representation
Defines the development approach for cross-extension in Raycast
- Host: GitHub
- URL: https://github.com/LitoMore/raycast-cross-extension-conventions
- Owner: LitoMore
- License: cc0-1.0
- Created: 2024-05-15T00:13:45.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-20T09:33:07.000Z (over 1 year ago)
- Last Synced: 2025-02-19T21:35:56.701Z (over 1 year ago)
- Topics: conventions, cross-extension, extensions, raycast
- Language: TypeScript
- Homepage:
- Size: 49.8 KB
- Stars: 21
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Raycast Cross-Extension Conventions
Defines the development approach for cross-extension in Raycast
[![raycast-cross-extension-badge]][raycast-cross-extension-link]
## Background
Raycast has tons of extensions so far. But most of them are standalone, it’s hard to use their ability from other extensions.
## Install
```shell
npm i raycast-cross-extension
```
## Usages
### Consumer Usage
Add your target extension handle to the `crossExtensions` list of package.json.
This field allows providers to get to know who is using their extension. See [maintenance](#maintenance).
```json
{
"crossExtensions": ["target-extensions-author-name/target-extension-name"]
}
```
We recommend always using the `crossLaunchCommand()` API to launch cross-extensions even your extension doesn't use the callback launch feature.
You may need to catch exceptions from `crossLaunchCommand()` if the target command is not installed.
The [`open()`](https://developers.raycast.com/api-reference/utilities#open) redirects to the Store when `crossLaunchCommand()` errored.
#### Example
```typescript
import { LaunchType, open } from "@raycast/api";
import { crossLaunchCommand } from "raycast-cross-extension";
crossLaunchCommand({
name: "target-command-name",
type: LaunchType.UserInitiated,
extensionName: "target-extension-name",
ownerOrAuthorName: "target-extension-author-name",
context: {
foo: "foo",
bar: "bar",
},
}).catch(() => {
open(
"raycast://extensions/target-extension-author-name/target-extension-name",
);
});
```
### Provider Usage
Incoming parameters can be received from [`LaunchContext`](https://developers.raycast.com/api-reference/command#launchcontext).
The `callbackLaunchOptions` is used for running the callback `launchCommand()` to the source extension.
Please note passing parameters through [`Arguments`](https://developers.raycast.com/information/lifecycle/arguments) is not recommneded since it supports string only.
But a command with arguments is still useful if you want to reuse your existing arguments-based commands as the cross-extension entrance.
For example, the [Say](https://raycast.com/litomore/say) extension is using the `typeToSay` arguments-based command for receiving cross-extension parameters.
#### Example
```typescript
import { LaunchProps } from "@raycast/api";
import { callbackLaunchCommand, LaunchOptions } from "raycast-cross-extension";
type LaunchContext = {
foo?: string;
bar?: string;
callbackLaunchOptions?: LaunchOptions;
};
export default function Command({
launchContext = {},
}: LaunchProps<{ launchContext?: LaunchContext }>) {
const { foo, bar, callbackLaunchOptions } = launchContext;
// ...
callbackLaunchCommand(callbackLaunchOptions, {
result: "hello, world",
});
}
```
## API
### crossLaunchCommand(options, callbackOptions?)
#### options
Type: `LaunchOptions`
Options for launch the target command.
#### callbackOptions
Type: `Partial | false`
Optional. Options for launch the callback command. It will be used in the callback stage with default values below:
- `name` defaults to `environment.commandName`
- `extensionName` defaults to `environment.extensionName`
- `ownerOrAuthorName` defaults to `environment.ownerOrAuthorName` or the field in `package.json`
- `type` defaults to `LaunchType.UserInitiated`
You can set it to `false` to disable command callback.
### callbackLaunchCommand(options, payload?)
#### options
Type: `LaunchOptions`
Pass in `launchContext.callbackLaunchOptions`. This is used to load options for callback.
#### payload
Type: `LaunchOptions['context']`
Optional. Context data for sending back to consumer command.
## Maintenance
When you make breaking changes, keep an eye out for other projects using your API.
You can search for your extension handle `your-author-name/your-extension-name` from the [`raycast/extensions`](https://github.com/search?q=repo%3Araycast%2Fextensions+language%3AJSON+crossExtensions&type=code) to find that extension using your extension.
## Badges
Show the world your extension implemented Cross-Extension.
[![raycast-cross-extension-badge]][raycast-cross-extension-link]
```markdown
[](https://github.com/LitoMore/raycast-cross-extension-conventions)
```
## Who's using Cross-Extension
### Consumers
- [Badges - shields.io](https://raycast.com/litomore/badges) - Concise, consistent, and legible badges
- [Cursor Directory](https://raycast.com/escwxyz/cursor-directory) - Your cursor.directory in Raycast
- [Pomodoro](https://www.raycast.com/asubbotin/pomodoro) - Pomodoro extension with menu-bar timer
- [Steam](https://raycast.com/KevinBatdorf/steam) - Search and view any Steam games
- [United Nations](https://raycast.com/litomore/united-nations) - Peace, dignity and equality on a healthy planet
### Providers
- [Brand Icons - simpleicons.org](https://raycast.com/litomore/simple-icons) - Browse, search, and copy free SVG icons for popular brands
- [Color Picker](https://raycast.com/thomas/color-picker) - A simple system-wide color picker
- [Cursor](https://raycast.com/degouville/cursor-recent-projects) - Control Cursor, Cursor & Codium directly from Raycast
- [Do Not Disturb](https://raycast.com/yakitrak/do-not-disturb) - Disable notifications on your Apple devices
- [PM2](https://raycast.com/litomore/pm2) - Manage even run your Node.js processes through Raycast
- [ProtonDB](https://raycast.com/litomore/protondb) - Game information for Proton, Linux, Steam Deck, and SteamOS
- [Raycast Port](https://raycast.com/litomore/raycast-port) - Allows you to use Raycast features out of Raycast
- [Raycast Notification](https://raycast.com/maxnyby/raycast-notification) - Makes it easy to display notifications via a quicklink
- [Say - Text to Speech](https://raycast.com/litomore/say) - macOS built-in TTS interface
- [SteamGridDB](https://raycast.com/litomore/steamgriddb) - Browse SteamGridDB images in Raycast
### Utilities
- [raycast-hid](https://github.com/LitoMore/raycast-hid) - Access USB HID devices from Raycast
- [raycast-notifier](https://github.com/LitoMore/raycast-notifier) - Send cross platform native notifications using Raycast
- [raycast-pm2](https://github.com/LitoMore/raycast-pm2) - PM2 utilities for Raycast Extensions
## License
CC0-1.0
[raycast-cross-extension-badge]: https://shields.io/badge/Raycast-Cross--Extension-eee?labelColor=FF6363&logo=raycast&logoColor=fff&style=flat-square
[raycast-cross-extension-link]: https://github.com/LitoMore/raycast-cross-extension-conventions