;
}
```
### Event Subscription
`OrderlyPluginProvider` does not currently consume a cleanup function returned by `setup`, and it may execute `setup` again when the resolved plugin list changes. Use `setup` only for idempotent non-UI work. For event subscriptions, prefer a wrapper component with `useEffect` cleanup and use `TrackerEventName` enum members.
```typescript
import { useEffect } from "react";
import { TrackerEventName } from "@orderly.network/types";
component: (Original, props, api) => {
const Wrapper = () => {
useEffect(() => {
const handleOrderPlaced = (data: unknown) => {
console.log("Order placed", data);
};
api.events.on(TrackerEventName.placeOrderSuccess, handleOrderPlaced);
return () => {
api.events.off(TrackerEventName.placeOrderSuccess, handleOrderPlaced);
};
}, [api]);
return ;
};
return ;
}
```
## Props Typing
### Approach A: `createInterceptor` (Recommended)
```typescript
import { createInterceptor } from "@orderly.network/plugin-core";
import "@orderly.network/ui"; // Loads Deposit.DepositForm props augmentation
interceptors: [
createInterceptor("Deposit.DepositForm", (Original, props, api) => {
// props automatically typed
return
Custom Form
;
}),
]
```
### Approach B: Manual Generic Type
```typescript
import type { PluginInterceptor, DepositFormProps } from "@orderly.network/ui";
const interceptor: PluginInterceptor = {
target: "Deposit.DepositForm",
component: (Original, props, api) => { /* props typed */ },
};
```
### Approach C: Inline Annotation
```typescript
component: (Original, props: DepositFormProps, api) => { ... }
```
## Error Hooks and Lifecycle Status
| Hook | Timing | Use Cases |
|------|--------|-----------|
| `setup` | When the provider resolves the plugin | Idempotent non-UI setup only |
| `onError` | When interceptor throws | Custom error logging |
| `onFallback` | When fallback UI needed | Graceful degradation |
`onInitialize` and `onInstall` are present in the current TypeScript descriptor for forward compatibility, but `OrderlyPluginProvider` does not invoke them yet. Do not rely on them for initialization, compatibility checks, or side effects; use `setup` or host-level checks instead.
```typescript
onError: (error: Error) => {
console.error("Plugin error:", error);
},
onFallback: () =>
Plugin unavailable
,
```
## Best Practices
### Error Isolation
- Each interceptor wraps in `PluginErrorBoundary`
- If an interceptor crashes, only that slot shows blank/fallback — not the entire page
### Performance
- Interceptors use memoization — no cascade redraws
- Avoid expensive computations in `component` functions
- Memoize wrapper components if they receive frequently-changing props:
```typescript
const MyWrapper = React.memo(({ data, Original, props }) => {
return ;
});
component: (Original, props, api) => (
)
```
### Plugin ID format (single rule)
Must match the **Marketplace API** wherever the plugin id appears (manifest `pluginId`, `registerPlugin({ id })`, CLI `--id`):
| Rule | Regex | Examples |
|------|--------|---------|
| Letter first; then letters, digits, hyphens only | `/^[a-zA-Z][a-zA-Z0-9-]*$/` | `my-plugin`, `orderly-onramp`, `pnlWidget` |
Do **not** treat `registerPlugin({ id })` as a separate camelCase-only rule — hyphenated ids are valid if they match the regex above.
## Registration Example
```typescript
export default function registerMyPlugin(options?: { theme?: string }) {
return (SDK: OrderlySDK, state?: { orderlyVersion?: string }) =>
SDK.registerPlugin({
id: "my-plugin",
name: "My Plugin",
version: "1.0.0",
onError: (error: Error) => {
console.error("Plugin error:", error);
// Send to error tracking service
},
onFallback: () =>
Plugin unavailable
,
interceptors: [
/* ... */
],
setup: (api) => {
/* ... */
},
});
}
```
**Note**: `onInitialize`, `onInstall`, `onMount`, `onUnmount`, and `onDispose` are not currently invoked by `plugin-core`.
## Testing
- **Interceptor Props Validation**: Use TypeScript strict mode to catch prop mismatches early.
- **Error Scenarios**: Test error boundaries by intentionally throwing errors in interceptor components.
- **Performance**: Use browser DevTools Profiler to verify interceptor rendering doesn't trigger unnecessary redraws.
## Reference
[reference.md](reference.md) — shared interceptor targets list (keep in sync with CLI constants)