home / skills / onekeyhq / app-monorepo / 1k-feature-guides

1k-feature-guides skill

safe

This skill guides you through adding new chains, WebSocket events, notifications, and pages in OneKey, accelerating secure feature implementations.

npx playbooks add skill onekeyhq/app-monorepo --skill 1k-feature-guides

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

3.5 KB

---
name: 1k-feature-guides
description: Feature development guides for OneKey. Use when adding new chains, socket events, notifications, pages, or routes. Covers blockchain integration, WebSocket subscriptions, push notifications, and navigation patterns.
---

# Feature Development Guides

Comprehensive guides for extending OneKey app functionality.

## Quick Reference

| Feature | Guide | Key Files |
|---------|-------|-----------|
| Add blockchain chain | [adding-chains.md](references/rules/adding-chains.md) | `packages/core/src/chains/` |
| Add WebSocket events | [adding-socket-events.md](references/rules/adding-socket-events.md) | `packages/shared/types/socket.ts` |
| Push notifications | [notification-system.md](references/rules/notification-system.md) | `packages/kit-bg/src/services/ServiceNotification/` |
| Pages & routes | [page-and-route.md](references/rules/page-and-route.md) | `packages/kit/src/routes/` |

## Adding New Chains

See: [references/rules/adding-chains.md](references/rules/adding-chains.md)

**Key steps:**
1. Implement chain core logic in `packages/core/src/chains/mychain/`
2. Add chain configuration in `packages/shared/src/config/chains/`
3. Update UI components for chain-specific features
4. Add comprehensive tests

**Reference implementations:**
- EVM chains: `packages/core/src/chains/evm/`
- Bitcoin: `packages/core/src/chains/btc/`
- Solana: `packages/core/src/chains/sol/`

## Adding WebSocket Events

See: [references/rules/adding-socket-events.md](references/rules/adding-socket-events.md)

**Key steps:**
1. Define event name in `EAppSocketEventNames` enum
2. Define payload type interface with `msgId: string`
3. Add event handler in `PushProviderWebSocket.initWebSocket()`
4. **Always acknowledge messages** via `ackNotificationMessage`

```typescript
this.socket.on(EAppSocketEventNames.myEvent, (payload: IMyPayload) => {
  void this.backgroundApi.serviceNotification.ackNotificationMessage({
    msgId: payload.msgId,
    action: ENotificationPushMessageAckAction.arrived,
  });
  void this.backgroundApi.someService.handleEvent(payload);
});
```

## Notification System

See: [references/rules/notification-system.md](references/rules/notification-system.md)

**Notification modes:**
| Mode | Action |
|------|--------|
| 1 (page) | Navigate to specific page |
| 2 (dialog) | Show dialog |
| 3 (openInBrowser) | Open URL in external browser |
| 4 (openInApp) | Open URL in in-app browser |
| 5 (openInDapp) | Open URL in DApp browser |

**Key files:**
- Service: `packages/kit-bg/src/services/ServiceNotification/ServiceNotification.ts`
- Utils: `packages/shared/src/utils/notificationsUtils.ts`
- Types: `packages/shared/types/notification.ts`

## Pages & Routes

See: [references/rules/page-and-route.md](references/rules/page-and-route.md)

**Page types:**
| Type | Description |
|------|-------------|
| `modal` | Modal overlay pages |
| `stack` | Tab route pages |
| `onboarding` | Full screen onboarding pages |

**Route configuration locations:**
- Modal routes: `packages/kit/src/routes/Modal/router.tsx`
- Tab routes: `packages/kit/src/routes/Tab/router.ts`
- Onboarding: `packages/kit/src/views/Onboardingv2/router/index.tsx`

**Important:**
- ⚠️ **Never delete pages** - use redirect pattern for deprecated routes
- ⚠️ **Route paths must be unique** across the entire application
- ⚠️ **Always use `pop: true`** with `navigation.navigate`

## Related Skills

- `/1k-coding-patterns` - React and TypeScript best practices
- `/1k-architecture` - Project structure and import rules
- `/1k-state-management` - Jotai atom patterns

Overview

This skill provides concrete, step-by-step feature development guides for OneKey. It covers adding new blockchains, subscribing to WebSocket events, implementing push notifications, and adding pages or routes. The guides focus on practical files, patterns, and safety checks to ship features consistently across platforms.

How this skill works

Each guide maps high-level requirements to specific code locations and example implementations in the TypeScript codebase. For chains it lists where to implement core logic and configuration. For sockets and notifications it prescribes event enums, payload shapes, acknowledgement flows, and notification modes. For pages and routes it documents route types, router files, and navigation rules to avoid regressions.

When to use it

Adding support for a new blockchain or chain-specific features
Introducing new WebSocket events or background push handlers
Implementing or changing push notification behavior or modes
Adding new UI pages, modals, or navigation routes
Migrating or deprecating routes while preserving navigation stability

Best practices

Keep chain core logic inside the designated chains folder and add matching config entries so the chain is discoverable
Define socket event names in the central enum and include msgId in payloads to always ack messages
Acknowledge incoming socket messages immediately using the notification service ack API to prevent duplicate processing
Never delete pages; deprecate with redirects to preserve route uniqueness and navigation history
Use pop: true when navigating programmatically and keep route paths globally unique

Example use cases

Add an EVM-compatible chain: implement packages/core/src/chains/mychain, add config, update UI components, and add tests
Subscribe to a new socket feed: add name to EAppSocketEventNames, define payload interface, register handler in PushProviderWebSocket.initWebSocket, and ack messages
Implement a notification action that opens a DApp: use notification mode 5 (openInDapp) and handle deep link routing
Add a modal onboarding step: register the page under modal routes and use the redirect pattern if later deprecated

FAQ

What payload fields are required for socket events?

Include msgId:string in the payload to support acknowledgement and tracking.

How should I deprecate an existing page or route?

Do not delete the page. Add a redirect or route guard to forward users to the new location and keep the original path unique to avoid collisions.