rosvik
commented
8 months ago Metadata and Configuration
Things to double-check in your package.json
- [x] Ensure you use your Raycast account username in the author field
- [x] Ensure you use MIT in the license field
- [x] Ensure you are using the latest Raycast API version
- [x] Please use npm for installing dependencies and include package-lock.json in your pull request. We use npm on our Continuous Integration (CI) environment when building and publishing extensions so, by providing a package-lock.json file, we ensure that the dependencies on the server match the same versions as your local dependencies.
- [x] Please check the terms of service of third-party services that your extension uses.
- [x] Read the Extension guidelines and make sure that your Extension comply with it.
- [x] 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 running npm run lint. (Those checks will later also run via automated GitHub checks.)
Extensions and Commands Naming
- [x] Extension and command titles should follow convention
- ✅ 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.
- [x] 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 than Search 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 just Notion. 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 like Notion. Example:
- Rule of thumb: If your extension has only one command, you probably need to name the extension close to what this command does. Example: instead of just Visual Studio Code.
- [x] 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.
- [x] Command title
- Usually it's
structure or just - 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
- Usually it's
- [x] 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 return Search 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
Extension Icon
We made a new icon generator tool to ease the process of creating icons for your extensions. You can find it here.
- [x] The published extension in the Store should have a 512x512px icon in png format
- [x] The icon should look good in both light and dark themes (you can switch the theme in Raycast Preferences → Appearance)
- [x] If you have separate light and dark icons, refer to the package.json documentation on how to configure them
- [x] Extensions that use the default Raycast icon will be rejected
- [x] This Icon Template can help you with making and exporting a proper icon Make sure to remove unused assets and icons
Provide README if Additional Configuration Required
NOT APPLICABLE
Categories
Categories shown on an extension details screen
- [x] All extensions should be published with at least one category
- [x] Categories are case-sensitive and should follow the convention
- [x] Add categories in the package.json manifest file or select the categories when you create a new extension using the Create Extension command
All Categories: https://developers.raycast.com/basics/prepare-an-extension-for-store#all-categories
Screenshots
- [x] 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
- [x] You can add a maximum of six screenshots. We recommend adding at least three, so your extensions detail screen looks beautiful.
Adding Screenshots
- In Raycast 1.37.0+ we made it easy for you to take beautiful pixel perfect screenshots of your extension with an ease.
- https://developers.raycast.com/basics/prepare-an-extension-for-store#adding-screenshots
Do's & Dont's
- [x] ✅ Choose a background with good contrast, that makes it clear and easy to see the app and extension you’ve made
- [x] ✅ Select the most informative commands to showcase what your extension does – focus on giving the user as much detail as possible
- [x] ❌ Do not use multiple backgrounds for different screenshots – be consistent and use the same across all screenshots
- [x] ❌ Do not share sensitive data in your screenshots – these will be visible in the Store, as well as the Extension repository on GitHub
- [x] ❌ Avoid using screenshots in different themes (light and dark), unless it is to demonstrate what your extension does
Version History
- [x] 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
- See an extension files structure with
- 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
You can use https://keepachangelog.com/en/1.0.0/ to help you format your changelog correctly
Contributing to Existing Extensions vs Creating a New One
NOT APPLICABLE
Binary Dependencies and Additional Configuration
NOT APPLICABLE
UI/UX Guidelines
Preferences
- [x] Required preferences will be shown when opening the command
- [x] Use the preferences API to let your users configure your extension or for providing credentials like API tokens
- When using required: true, Raycast will ask the user to set preferences before continuing with an extension. See the example here.
- [x] You should not build separate commands for configuring your extension. If you miss some API to achieve the preferences setup you want, please file a GitHub issue with a feature request.
Action Panel
- [x] Actions in the action panel should also follow the Title Case naming convention
- ✅ Open in Browser, Copy to Clipboard
- ❌ Copy url, set project, Set priority
- [x] Provide icons for actions if there are other actions with icons in the list
- Avoid having a list of actions where some have icons and some don't
- [x] Add ellipses … for actions that will have a submenu. Don't repeat the parent action name in the submenu
- [x] ✅ Set Priority… and submenu would have Low, Medium, High
- [x] ❌ Set Priority and submenu would have Set Priority Low, Set Priority Medium, etc
Navigation
- [x] Use the Navigation API for pushing new screens. This will ensure that a user can navigate within your extension the same way as in the rest of the application.
- [x] Avoid introducing your own navigation stack. Extensions that just replace the view's content when it's expected to push a new screen will be rejected.
Empty States
-
[x] When you update lists with an empty array of elements, the "No results" view will be shown. Avoid introducing your own UI to achieve a similar effect (e.g. showing list item).
- [x] Known issue: Sometimes, there is nothing you can show when the search query is empty, and an extension shows "No results" when you open it (often in search commands). We have plans to provide an API that would improve that experience. In the meantime, you might want to consider introducing some sections that could be helpful in an empty state – e.g. suggestions or recently visited items.
-
[x] Common mistake – "flickering empty state view" on start
- [x] If you try rendering an empty list before real data arrives (e.g. from the network or disk), you might see a flickering "No results" view when opening the extension. To prevent this, make sure not to return an empty list of items before you get the data you want to display. In the meantime, you can show the loading indicator. See this example.
Navigation Title
- [x] Don't change the navigationTitle in the root command - it will be automatically set to the command name. Use navigationTitle only in nested screens to provide additional context. See Slack status extension as an example of correct usage of the navigationTitle property.
- [x] Avoid long titles. If you can't predict how long the navigation title string will be, consider using something else. E.g. in the Jira extension, we use the issue key instead of the issue title to keep it short.
- [x] Avoid updating the navigation title multiple times on one screen depending on some state. If you find yourself doing it, there is a high chance you are misusing it.
Placeholders in Text Fields
- [x] For a better visual experience, add placeholders in text field and text area components. This includes preferences.
- [x] Don't leave the search bar without a placeholder
Analytics
- [x] It’s not allowed to include external analytics in extensions. Later on, we will add support to give developers more insights into how their extension is being used.
Localization / Language
- [x] At the moment, Raycast doesn't support localization and only supports US English. Therefore, please avoid introducing your custom way to localize your extension. If the locale might affect functionality (e.g. using the correct unit of measurement), please use the preferences API.
- [x] Use US English spelling (not British)
TODO