> For the complete documentation index, see [llms.txt](https://developers.raycast.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.raycast.com/information/file-structure.md). # 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. An extension's directory structure can look like this, including optional files for AI features, setup help, and Store screenshots: ```bash extension ├── .prettierrc ├── ai.json ├── assets │ └── icon.png ├── eslint.config.js ├── help.md ├── metadata │ └── screenshot.png ├── node_modules ├── package-lock.json ├── package.json ├── README.md ├── src │ ├── command.tsx │ └── tools │ └── tool.ts └── tsconfig.json ``` The directory contains all source files, assets, and a few support files. Let's go over each of them: ## Manifest **package.json** is the most important file in your extension. It defines the extension's metadata, including its title, commands, tools, preferences, and dependencies. See the [manifest reference](/information/manifest.md) for all supported properties. ## 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 at least an entry point file (e.g. `src/command.ts`) per command and a `package.json` manifest file holding metadata about the extension, its commands and tools. The format of the manifest file is very similar to [that of npm packages](https://docs.npmjs.com/cli/v7/configuring-npm/package-json). In addition to some of the standard properties, there are some [additional properties](/information/manifest.md), in particular, the `commands` properties which describes the entry points exposed by the extension. 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}`. ### Tools Put tool entry points in `src/tools`. Tools expose functionality that Raycast AI can call, such as searching data or creating an item. Declare each tool in the `tools` array in `package.json`; its `name` maps to a `.ts` or `.tsx` file in this folder. For example, a tool named `search` maps to `src/tools/search.ts`. See [Create an AI Extension](/ai/create-an-ai-extension.md) for a walkthrough. ## 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. ## Help The optional **help.md** file contains Markdown instructions for configuring required preferences, such as obtaining an API key. Place it next to `package.json`. Raycast bundles it automatically and displays its contents beside the setup form when required preferences are missing. See [Help for Required Preferences](/api-reference/preferences.md#help-for-required-preferences) for an example. ## AI Configuration The optional **ai.yaml** file contains AI configuration, including additional `instructions` and `evals` to test your AI extension. Place it next to `package.json` to keep this configuration separate from the manifest. You can also use `ai.json5`, `ai.yaml`, or `ai.yml`; choose one format for your extension. See [AI File](/ai/learn-core-concepts-of-ai-extensions.md#ai-file) and [Write Evals for Your AI Extension](/ai/write-evals-for-your-ai-extension.md). ## Metadata The optional `metadata` folder contains PNG screenshots for your extension's Store listing. These are uploaded when publishing. Put images needed at runtime in `assets`, and images linked from your README in a top-level `media` folder. See [Adding Screenshots](/basics/prepare-an-extension-for-store.md#adding-screenshots) for capture instructions and image requirements. ## Support files The directory contains a few more files that setup common JavaScript tooling: * **eslint.config.js** describes rules for [ESLint](https://eslint.org), 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](https://prettier.io) to format your code. We recommend to setup the [VS Code extension](https://prettier.io/docs/en/editors.html#visual-studio-code) to keep your code pretty automatically. * **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. * **tsconfig.json** configures your project to use TypeScript. Most likely, you don't have to edit this file. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.raycast.com/information/file-structure.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.