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

# Tutorial 1: First plugin from the template

> Goal: Scaffold a plugin and make one visible change on a single interceptor target that exists in the SDK.

**Goal:** Scaffold a plugin and make **one** visible change on a **single** interceptor target that exists in the SDK.

**Prerequisite:** [Getting started](/build-on-omnichain/builder-marketplace/getting-started) completed (includes **`orderly-devkit skills install`** and **`mcp install`** if you use an agent).

## Using agent skills for this tutorial

Install the default plugin skills once — see [Skills-first workflow](/build-on-omnichain/builder-marketplace/skills-first). For this tutorial the relevant skills are:

| Skill                     | What it covers                                                                               | CLI / tool it leads you to                                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **orderly-plugin-create** | Scaffold from the official template; naming (`--name`, `--id`), `--interceptor`, `--target`. | **`orderly-devkit create plugin`** (interactive or `--no-interactive` + flags).                                                                           |
| **orderly-plugin-write**  | Interceptor patterns, Hooks in inner components, docs-first API lookup.                      | Editing generated code; **Orderly SDK Docs MCP** (`orderly_docs_search`, `orderly_docs_get_component`, `orderly_docs_get_hook`, `orderly_docs_get_type`). |

**MCP note:** Prefer **`orderly_docs_get_hook`** for hook APIs (params/returns/JSDoc) and **`orderly_docs_get_component`** for components such as **`OrderlyAppProvider`** (`plugins` prop). Searching alone may not surface structured metadata.

**Example prompts (agent with skills loaded):** “Scaffold an Orderly plugin named `FeeHint` with interceptor `Trading.OrderEntry.SubmitSection` under `./fee-hint`” → maps to **create**. “Add a wrapper around the submit section that shows a small label” → maps to **write** + your code changes.

You can still run **`orderly-devkit create plugin`** by hand; the skill is the structured checklist so the agent does not skip flags or mix up plugin id rules.

## 1. Pick a target path

Valid runtime targets are listed in **[Runtime injector targets](/build-on-omnichain/builder-marketplace/runtime-injector-targets)** (paths must match **exactly**, case-sensitive).

For this tutorial, use a target you know appears on your trading page—for example `Trading.OrderEntry.SubmitSection` or another row from that page.

> **Note:** `orderly-devkit create plugin --interceptor` only offers a **subset** of SDK targets. You can still register interceptors for any runtime path in [Runtime injector targets](/build-on-omnichain/builder-marketplace/runtime-injector-targets) by editing the generated plugin code.

## 2. Create the project

```bash theme={null}
orderly-devkit create plugin
```

Answer the prompts, or use `--no-interactive` with `--name`, `--id`, `--interceptor`, and `--target` as in [Getting started](/build-on-omnichain/builder-marketplace/getting-started).

## 3. Implement one small behavior

Open the generated registration file (often `plugin.tsx` or similar—follow the template). Ensure `SDK.registerPlugin` includes an interceptor whose `target` equals your chosen path.

Typical pattern (pseudo-code; align with the template’s exports):

```typescript theme={null}
const myPlugin = {
  // Inside registerPlugin({ ... })
  interceptors: [
    {
      target: "Trading.OrderEntry.SubmitSection",
      component: (Original, props, api) => {
        // Example: wrap default UI with a label
        return (
          <div className="oui-flex oui-flex-col oui-gap-2">
            <span className="oui-text-xs oui-text-base-contrast-54">Plugin tutorial</span>
            <Original {...props} />
          </div>
        );
      },
    },
  ],
};
```

**Important:** The `component` function is **not** a React component—do not call Hooks directly on it. Return JSX that uses inner components if you need Hooks (see [Interceptor strategies](/build-on-omnichain/builder-marketplace/interceptor-strategies)).

## 4. Build the package

```bash theme={null}
cd your-plugin-directory
pnpm install
pnpm run build
```

Adjust commands to match the template’s `package.json`.

**Verification:** Build exits with code 0.

## 5. Integrate in a host (smoke test)

Follow [Tutorial 2: Integrate into host](/build-on-omnichain/builder-marketplace/integrate-host) to add `plugins={[registerYourPlugin()]}` on `OrderlyAppProvider`.

**Verification:** Navigate to the trading view and confirm your UI change appears at the interceptor location.

## Failure recovery

| Issue                        | Action                                                                                                                                                                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target not found / no effect | Re-read the target against [Runtime injector targets](/build-on-omnichain/builder-marketplace/runtime-injector-targets); typos break injection.                                                                                 |
| Hooks error in interceptor   | Move Hook usage into a child component; see [How-to: Interceptor strategies](/build-on-omnichain/builder-marketplace/interceptor-strategies).                                                                                   |
| Scaffold mismatch            | Regenerate or trim generated files to the minimal **`registerPlugin`** shape; see **[Plugin types](/build-on-omnichain/builder-marketplace/plugin-types)** and **`@orderly.network/plugin-core`** on npm for full architecture. |