File Structure

Understand the file structure of an extension.

An extension consists of at least an entry point file (e.g. src/index.ts) and a package.json manifest file. We add a few more support files when scaffolding an extension to streamline development with modern JavaScript tooling.

The typical directory structure of a newly-created extension looks like this:

extension
├── .eslintrc.json
├── .prettierrc
├── assets
│   └── icon.png
├── node_modules
├── package-lock.json
├── package.json
├── src
│   └── index.tsx
└── tsconfig.json

The directory contains all source files, assets, and a few support files. Let's go over each of them:

Sources

Put all your source files into the src folder. We recommend using TypeScript as a programming language. Our API is fully typed, which helps you catch errors at compile time rather than runtime. ts, tsx, js and jsx are supported as file extensions. As a rule of thumb, use tsx or jsx for commands with a UI.

An extension consists of an entry point file (e.g. src/index.ts) per command and a package.json manifest file holding 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. For example, a command with the name create in the package.json file, maps to the file src/create{.ts,.tsx,.js,.jsx}.

Assets

The optional assets folder can contain icons that will be packaged into the extension archive. All bundled assets can be referenced at runtime. Additionally, icons can be used in the package.json as extension or command icons.

Support files

The directory contains a few more files that setup common JavaScript tooling:

• .eslintrc.json describes rules for ESLint, which you can run with npm run lint. It has recommendations for code style and best practices. Usually, you don't have to edit this file.

• .prettierrc contains default rules for Prettier to format your code. We recommend to setup the VS Code extension to keep your code pretty.

• node_modules contains all installed dependencies. You shouldn't make any manual changes to this folder.

• package-lock.json is a file generated by npm to install your dependencies. You shouldn't make any manual changes to this file.

• package.json is the manifest file containing metadata about your extension such as its title, the commands, and its dependencies.

• tsconfig.json configures your project to use TypeScript. Most likely, you don't have to edit this file.