> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoforge.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins overview

> What an editor plugin is, where it lives and how the editor loads it

Almost everything in the NanoForge editor is a plugin: the file manager, the code editor, the Game and Scene screens, the ECS panels, the console, Git. Your own plugins use the same API as these.

A plugin is a folder with:

* `nanoforge.manifest.json`: its name, what it adds to the editor, and when to load it;
* a **client entry** (`index.js`): code that runs in the editor's page;
* optionally a **worker entry** (code analysis and code generation) and a **server entry** (code that runs in the editor's server);
* its styles and assets.

## Where plugins live

The editor looks in four places. When the same plugin is in several, the later one in this table is used.

| Source | Folder | Loaded |
| - | - | - |
| Built in | shipped with the editor | always |
| Installed | `~/.nanoforge/editor/plugins/@scope/name` | in every project |
| Project | `<project>/.nanoforge/plugins/@scope/name` | while that project is open |
| Dev | the folders listed in `DEV_PLUGINS` (their `dist`) | always, and reloaded when rebuilt |

*Settings › Plugins* lists every plugin with its source and state, lets you turn one off, and installs plugins from the marketplace.

> [!NOTE]
>
> A project plugin's server entry only runs in a local editor, never in a hosted one.

The editor's page has a Content Security Policy: in a hosted editor, the page (plugins included) connects to the editor's own origin only; in a local editor, the page, plugins and games, may connect anywhere (`http:`, `https:`, `ws:`, `wss:`).

## How a plugin is loaded

1. The editor reads every manifest. Everything a manifest declares in `contributes` (commands, menus, panels, settings, shortcuts) is in place **before any plugin code runs**.
2. A plugin's code is fetched and `activate` is called when one of its **activation events** happens: a panel of the plugin is shown, one of its commands runs, or at startup.
3. When the plugin is turned off or replaced, everything it added through `context.subscriptions` is removed.

So a plugin that only shows a panel costs nothing until the panel is opened.

## What a plugin can import

Only the SDK:

* `@nanoforge-dev/editor-sdk`: services, commands, settings, history, code, runtime;
* `@nanoforge-dev/editor-sdk/ui`: panels, menus, the status bar, and the editor's own components;
* `@nanoforge-dev/editor-sdk/worker`: types for worker entries.

The editor provides these modules, and Svelte, at run time: they are not bundled into your plugin, so your panels use the editor's own components and theme. Plugins are written in **Svelte 5 with runes**.

## Next

> [card] [Create your first plugin](https://docs.nanoforge.eu/docs/editor/plugins/create-your-first-plugin.md)
>
> `nf create plugin`, run it in the editor, change it.

> [card] [Manifest reference](https://docs.nanoforge.eu/docs/editor/plugins/manifest.md)
>
> Every field of `nanoforge.manifest.json`.

> [card] [SDK](https://docs.nanoforge.eu/docs/editor/plugins/sdk.md)
>
> The activation context and the editor's services.

> [card] [Extension points](https://docs.nanoforge.eu/docs/editor/plugins/extension-points.md)
>
> Every place a plugin can add something.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.