Prepare an Extension for Store
Learn how to get through review process quickly
Here you will find requirements and guidelines that you'll need to follow in order to get through the review before your extension becomes available in the Store. Please read it carefully because it will save time for you and for us. This document is constantly evolving so please do visit it from time to time.
- Things to double-check in your
package.json
- Ensure you use your Raycast account username in the
author
field - Ensure you use
MIT
in thelicense
field - Ensure you are using the latest Raycast API version
- Please use
npm
for installing dependencies and includepackage-lock.json
in your pull request. We usenpm
on our Continuous Integration (CI) environment when building and publishing extensions so, by providing apackage-lock.json
file, we ensure that the dependencies on the server match the same versions as your local dependencies. - Please check the terms of service of third-party services that your extension uses. If your extension doesn't comply with their terms, include a warning in your extension's README. The warning should be similar to:Warning: This extension is not compliant with the Terms of Service of [service name]. Use at your own risk.
- Make sure to run a distribution build with
npm run build
locally before submitting the extension for review. This will perform additional type checking and create an optimized build. Open the extension in Raycast to check whether everything works as expected with the distribution build. In addition, you can perform linting and code style checks by runningnpm run lint
. (Those checks will later also run via automated GitHub checks.)
- ✅
Google Workplace
,Doppler Share Secrets
,Search in Database
- ❌
Hacker news
,my issues
- 🤔 It's okay to use lower case for names and trademarks that are canonically written with lower case letters. E.g.
iOS
,macOS
,npm
.
- Extension title
- It will be used only in the Store and in the preferences
- Make it easy for people to understand what it does when they see it in the Store
- ✅
Emoji Search
,Airport - Discover Testflight Apps
,Hacker News
- ❌
Converter
,Images
,Code Review
,Utils
- 🤔 In some cases, you can add additional information to the title similar to the Airport example above. Only do so if it adds context.
- 💡 You can use more creative titles to differentiate your extension from other extensions with similar names.
- Aim to use nouns rather than verbs
Emoji Search
is better thanSearch Emoji
- Avoid generic names for an extension when your extension doesn't provide a lot of commands
- E.g. if your extension can only search pages in Notion, name it
Notion Search
instead of justNotion
. This will help users to form the right expectations about your extension. If your extension covers a lot of functionality, it's okay to use a generic name likeNotion
. Example: GitLab. - Rule of thumb: If your extension has only one command, you probably need to name the extension close to what this command does. Example: Visual Studio Code Recent Projects instead of just
Visual Studio Code
.
- Extension description
- In one sentence, what does your extension do? This will be shown in the list of extensions in the Store. Keep it short and descriptive. See how other approved extensions in the Store do it for inspiration.
- Command title
- Usually it's
<verb> <noun>
structure or just<noun>
- The best approach is to see how other commands are named in Raycast to get inspiration
- ✅
Search Recent Projects
,Translate
,Open Issues
,Create Task
- ❌
Recent Projects Search
,Translation
,New Task
- Avoid articles
- ✅
Search Emoji
,Create Issue
- ❌
Search an Emoji
,Create an Issue
- Avoid just giving it a service name, be more specific about what the command does
- ✅
Search Packages
- ❌
NPM
- Command subtitle
- Use subtitles to add context to your command. Usually, it's an app or service name that you integrate with. It makes command names more lightweight and removes the need to specify a service name in the command title.
- The subtitle is indexed so you can still search using subtitle and title:
xcode recent projects
would returnSearch Recent Projects
in the example above. - Don't use subtitles as descriptions for your command
- ❌
Quickly open Xcode recent projects
- Don't use a subtitle if it doesn't add context. Usually, this is the case with single command extensions.
- There is no need for a subtitle for the
Search Emoji
command since it's self-explanatory - Rule of thumb: If your subtitle is almost a duplication of your command title, you probably don't need it

Example of a good subtitle
We made a new icon generator tool to ease the process of creating icons for your extensions. You can find it here.
- The published extension in the Store should have a 512x512px icon in
png
format - The icon should look good in both light and dark themes (you can switch the theme in Raycast Preferences → Appearance)
- If you have separate light and dark icons, refer to the
package.json
manifest documentation on how to configure them - Extensions that use the default Raycast icon will be rejected
- Make sure to remove unused assets and icons
- 💡 If you feel like designing icons is not up to your alley, ask community for help (#extensions channel)
- If your extension requires additional setup, such as getting an API access token, enabling some preferences in other applications, or has non-trivial use cases, please provide a README file at the root folder of your extension. When a README is provided, users will see the "About This Extension" button on the preferences onboarding screen.
- Supporting README media: Put all linked media files in a top-level
media
folder inside your extension directory. (This is different from assets that are required at runtime in your extension: they go inside the assets folder and will be bundled into your extension.)

Onboarding button linking to the README file

Categories shown on an extension details screen
- All extensions should be published with at least one category
- Add categories in the
package.json
manifest file or select the categories when you create a new extension using the Create Extension command
Category | Example |
---|---|
Applications | |
Communication | |
Data | |
Documentation | |
Design Tools | |
Developer Tools | |
Finance | |
Fun | |
Media | Unsplash – Search images or collections on Unsplash, download, copy or set them as wallpaper without leaving Raycast. |
News | |
Productivity | |
Security | |
System | |
Web | |
Other | To be used if you think your extension doesn’t fit in any of the above categories. |

An example of an extension with screenshot metadata
- Screenshots are displayed in the metadata of an extension details screen, where users can click and browse through them to understand what your extension does in greater detail, before installing
- You can add a maximum of six screenshots. We recommend adding at least three, so your extensions detail screen looks beautiful.
In Raycast 1.37.0+ we made it easy for you to take beautiful pixel perfect screenshots of your extension with an ease.
- 1.Set up Window Capture in Advanced Preferences (Hotkey e.g.:
⌘⇧⌥+M
) - 2.Open the command
- 3.Press the hotkey, remember to tick
Save to Metadata
This tool will use your current background. Choose a background image with a good contrast that makes it clear and easy to see the app and extension you’ve made.
Screenshot size | Aspect ratio | Format | Dark mode support |
---|---|---|---|
2000 x 1250 pixels (landscape) | 16:10 | PNG | No |
- ✅ Choose a background with good contrast, that makes it clear and easy to see the app and extension you’ve made
- ✅ Select the most informative commands to showcase what your extension does – focus on giving the user as much detail as possible
- ❌ Do not use multiple backgrounds for different screenshots – be consistent and use the same across all screenshots
- ❌ Do not share sensitive data in your screenshots – these will be visible in the Store, as well as the Extension repository on GitHub
- ❌ Avoid using screenshots in different themes (light and dark), unless it is to demonstrate what your extension does

A CHANGELOG.md file displayed in the app
- Make it easier for users to see exactly what notable changes have been made between each release of your extension with a
CHANGELOG.md
file in your extension metadata- To add Version History to your extension, add a
CHANGELOG.md
file to the root folder of your extension
- With each change, provide clear and descriptive information around the latest update, providing a title as a h2 header followed by a date timestamp YYYY-MM-DD
- Make sure your change title is within square brackets
- Separate your title and date with a hyphen
-
and spaces either side of the hyphen
- Below is an example of a changelog that follows the correct format
# Brew Changelog
## [Added a bunch of new feedback] - 2022-01-17
- Improve reliability of `outdated` command
- Add action to copy formula/cask name
- Add cask name & tap to cask details
- Add Toast action to cancel current action
- Add Toast action to copy error log after failure
## [New Additions] - 2022-12-13
- Add greedy upgrade preference
- Add `upgrade` command
## [Fixes & Bits] - 2021-11-19
- Improve discovery of brew prefix
- Update Cask.installed correctly after installation
- Fix installed state after uninstalling search result
- Fix cache check after installing/uninstalling cask
- Add uninstall action to outdated action panel
## [New Commands] - 2021-11-04
Add support for searching and managing casks