Page And Route

Page and Route Skill

This skill helps create and configure pages and routes in the OneKey app-monorepo.

⚠️ WARNING: Page Deletion Policy

DO NOT DELETE PAGES unless you have confirmed there are NO external links to the page.

External links include:

• Deep links / Universal links
• QR code handlers
• Banner click handlers
• Web URLs shared externally
• Third-party integrations
• Marketing materials / Documentation

If you need to remove a page's functionality:

Instead of deleting the route, keep the route registered and modify the page component:

import { Page } from '@onekeyhq/components';

/**
 * @deprecated This page has been deprecated since v5.0.0
 *
 * New location: packages/kit/src/views/NewFeature/pages/NewPage.tsx
 * New route: EModalRoutes.NewFeatureModal -> ENewFeatureRoutes.NewPage
 *
 * This page is kept for backward compatibility with external deep links.
 * DO NOT DELETE - external links may still reference this route.
 */
function DeprecatedPage() {
  return (
    <Page
      shouldRedirect={() => true}  // Always redirect
      => {
        // Navigate to replacement page or home
        navigation.switchTab(ETabRoutes.Home);
        // Or show a toast explaining the change
        Toast.info({ title: 'This feature has been moved' });
      }}
    >
      {null}  // Render nothing
    </Page>
  );
}

export default DeprecatedPage;

This approach ensures:

• Users accessing via old deep links are gracefully redirected
• No broken links or blank screens
• Analytics can track deprecated route access
• Backward compatibility is maintained

Page Types

The page types are defined in packages/components/src/hocs/PageType/pageType.ts:

Creating Routes

1. Modal Route

Modal routes are configured in packages/kit/src/routes/Modal/router.tsx.

Example: Creating a NotificationsModal route

Step 1: Define Route Enum and Param Types

Create route file packages/shared/src/routes/notifications.ts:

export enum EModalNotificationsRoutes {
  NotificationList = 'NotificationList',
  NotificationIntroduction = 'NotificationIntroduction',
}

export type IModalNotificationsParamList = {
  [EModalNotificationsRoutes.NotificationList]: undefined;
  [EModalNotificationsRoutes.NotificationIntroduction]: undefined;
};

Step 2: Add to EModalRoutes Enum

In packages/shared/src/routes/modal.ts:

export enum EModalRoutes {
  // ... existing routes
  NotificationsModal = 'NotificationsModal',
}

export type IModalParamList = {
  // ... existing types
  [EModalRoutes.NotificationsModal]: IModalNotificationsParamList;
};

Step 3: Create Router Configuration

Create packages/kit/src/views/Notifications/router/index.ts:

import type { IModalFlowNavigatorConfig } from '@onekeyhq/components';
import { LazyLoadPage } from '@onekeyhq/kit/src/components/LazyLoadPage';
import type { IModalNotificationsParamList } from '@onekeyhq/shared/src/routes/notifications';
import { EModalNotificationsRoutes } from '@onekeyhq/shared/src/routes/notifications';

const NotificationList = LazyLoadPage(
  () => import('@onekeyhq/kit/src/views/Notifications/pages/NotificationList'),
);

const NotificationIntroduction = LazyLoadPage(
  () => import('@onekeyhq/kit/src/views/Notifications/pages/NotificationIntroduction'),
);

export const ModalNotificationsRouter: IModalFlowNavigatorConfig<
  EModalNotificationsRoutes,
  IModalNotificationsParamList
>[] = [
  {
    name: EModalNotificationsRoutes.NotificationList,
    component: NotificationList,
  },
  {
    name: EModalNotificationsRoutes.NotificationIntroduction,
    component: NotificationIntroduction,
  },
];

Step 4: Register in Modal Router

In packages/kit/src/routes/Modal/router.tsx:

import { ModalNotificationsRouter } from '../../views/Notifications/router';

const router: IModalRootNavigatorConfig<EModalRoutes>[] = [
  // ... existing routes
  {
    name: EModalRoutes.NotificationsModal,
    children: ModalNotificationsRouter,
  },
];

Step 5: Create Page Component

Create packages/kit/src/views/Notifications/pages/NotificationList.tsx:

import { Page } from '@onekeyhq/components';

function NotificationList() {
  return (
    <Page safeAreaEnabled={false}>
      <Page.Body>
        {/* Page content */}
      </Page.Body>
    </Page>
  );
}

export default NotificationList;

2. Onboarding Route

Onboarding routes are configured in packages/kit/src/views/Onboardingv2/router/index.tsx.

Example: Creating AddExistingWallet page

Step 1: Define Route Enum

In packages/shared/src/routes/onboarding.ts:

export enum EOnboardingPagesV2 {
  GetStarted = 'GetStarted',
  AddExistingWallet = 'AddExistingWallet',
  // ... more pages
}

Step 2: Add to Router

In packages/kit/src/views/Onboardingv2/router/index.tsx:

const AddExistingWallet = LazyLoadPage(
  () => import('../pages/AddExistingWallet'),
  undefined,
  false,
  <OnboardingLayoutFallback />,
);

export const OnboardingRouterV2: IModalFlowNavigatorConfig<
  EOnboardingPagesV2,
  IOnboardingParamListV2
>[] = [
  // ... other routes
  {
    name: EOnboardingPagesV2.AddExistingWallet,
    component: AddExistingWallet,
    options: hiddenHeaderOptions,
  },
];

3. Tab Route

Tab routes are configured in packages/kit/src/routes/Tab/router.ts.

Example: Creating Market tab with sub-pages

Step 1: Define Route Enum and Params

In packages/shared/src/routes/tabMarket.ts:

export enum ETabMarketRoutes {
  TabMarket = 'TabMarket',
  MarketDetail = 'MarketDetail',
  MarketDetailV2 = 'MarketDetailV2',
  MarketNativeDetail = 'MarketNativeDetail',
  MarketBannerDetail = 'MarketBannerDetail',
}

export type ITabMarketParamList = {
  [ETabMarketRoutes.TabMarket]: { from?: EEnterWay } | undefined;
  [ETabMarketRoutes.MarketDetail]: { token: string };
  [ETabMarketRoutes.MarketDetailV2]: {
    tokenAddress: string;
    network: string;
    isNative?: boolean;
  };
  // ... more params
};

Step 2: Create Sub-Router

Create packages/kit/src/routes/Tab/Marktet/router.ts:

import type { ITabSubNavigatorConfig } from '@onekeyhq/components';
import { ETabMarketRoutes } from '@onekeyhq/shared/src/routes';
import { LazyLoadRootTabPage, LazyLoadPage } from '../../../components/LazyLoadPage';

const MarketHome = LazyLoadRootTabPage(() => import('../../../views/Market/MarketHome'));
const MarketDetail = LazyLoadPage(() => import('../../../views/Market/MarketDetail'));

export const marketRouters: ITabSubNavigatorConfig<any, any>[] = [
  {
    rewrite: '/',
    name: ETabMarketRoutes.TabMarket,
    headerShown: !platformEnv.isNative,
    component: MarketHome,
  },
  {
    name: ETabMarketRoutes.MarketDetail,
    component: MarketDetail,
    rewrite: '/tokens/:token',
  },
];

Step 3: Register in Tab Router

In packages/kit/src/routes/Tab/router.ts:

import { marketRouters } from './Marktet/router';

export const useTabRouterConfig = () => {
  return useMemo(() => {
    const tabs = [
      {
        name: ETabRoutes.Market,
        tabBarIcon: (focused?: boolean) =>
          focused ? 'ChartTrendingUp2Solid' : 'ChartTrendingUp2Outline',
        translationId: ETranslations.global_market,
        rewrite: '/market',
        exact: true,
        children: marketRouters,
        // Control visibility per platform
        hiddenIcon: platformEnv.isNative, // Hide on mobile
      },
      // ... other tabs
    ];
    return tabs;
  }, []);
};

Tab Configuration Options:

• hiddenIcon: Hide tab icon on certain platforms
• hideOnTabBar: Hide from tab bar but keep route accessible
• inMoreAction: Show in "More" menu instead of main tab bar
• freezeOnBlur: Keep tab state when switching tabs

Configuring Page Paths

⚠️ WARNING: Route Paths Must Be Unique

Route paths MUST NOT be duplicated. Each route path must be unique across the entire application.

If duplicate paths are detected, the application will throw an error at startup:

Found conflicting screens with the same pattern. The pattern '/market/tokens/.'
resolves to both 'Main > Market > MarketDetail' and 'Main > Market > MarketDetailV2'.
Patterns must be unique and cannot resolve to more than one screen.

Common causes of duplicate paths:

• Two routes using the same rewrite value
• Forgetting to update path when copying route configuration
• Child routes with identical path segments

How to avoid:

• Always use unique rewrite values for each route
• When adding similar routes, differentiate paths (e.g., /token/:network vs /token/:network/:tokenAddress)
• Run the app locally to verify no path conflicts before committing

URL Path Configuration

Route paths are calculated in packages/kit/src/routes/config/index.ts via resolveScreens.

resolveScreens Function

interface IScreenRouterConfig {
  name: string;      // Route name (used as default path segment)
  rewrite?: string;  // Override path segment
  exact?: boolean;   // If true, ignores parent paths and uses only rewrite
  children?: IScreenRouterConfig[];
}

// resolveScreens transforms route config into path config
const resolveScreens = (routes: IScreenRouterConfig[]) =>
  routes.reduce((prev, route) => {
    prev[route.name] = {
      path: route.rewrite ? route.rewrite : route.name,  // Use rewrite or name as path
      exact: !!route.exact,
    };
    if (route.children) {
      prev[route.name].screens = resolveScreens(route.children);  // Recursive for children
    }
    return prev;
  }, {});

How it works:

1. Each route's name becomes its key in the config
2. The path is either rewrite value (if provided) or name
3. exact flag determines if parent paths are included
4. Children routes are processed recursively

Path Calculation Rules

Rule 1: Default path accumulation Without any configuration, paths accumulate based on route hierarchy:

Route: Main -> Market -> MarketDetail
Path:  /Main/Market/MarketDetail

Rule 2: rewrite replaces current segment only

// Tab router config
{
  name: ETabRoutes.Market,
  rewrite: '/market',     // Replaces 'Market' with 'market'
  children: marketRouters,
}

// Result: /Main/market/... (only current segment changed)

Rule 3: exact: true truncates all parent paths

{
  name: EModalRoutes.SettingModal,
  children: ModalSettingStack,
  rewrite: '/settings',
  exact: true,            // Ignores /Modal prefix
}

// Without exact: /Modal/settings/...
// With exact:    /settings/...

Rule 4: Path params with /:param syntax

// In marketRouters
{
  name: ETabMarketRoutes.MarketDetail,
  component: MarketDetail,
  rewrite: '/tokens/:token',  // :token is a path parameter
}

// Result path pattern: /market/tokens/:token
// Actual URL example:  /market/tokens/bitcoin

Complete Examples

Example 1: Tab Route with rewrite + exact

// Tab router (packages/kit/src/routes/Tab/router.ts)
{
  name: ETabRoutes.Market,
  rewrite: '/market',
  exact: true,              // Path starts from /market, not /Main/Market
  children: marketRouters,
}

// Sub-router (packages/kit/src/routes/Tab/Marktet/router.ts)
export const marketRouters = [
  {
    name: ETabMarketRoutes.TabMarket,
    rewrite: '/',           // Root of /market
    component: MarketHome,
  },
  {
    name: ETabMarketRoutes.MarketDetail,
    rewrite: '/tokens/:token',
    component: MarketDetail,
  },
];

// Resulting paths:
// TabMarket:     /market/
// MarketDetail:  /market/tokens/:token (e.g., /market/tokens/bitcoin)

Example 2: Modal Route with exact

// Modal router (packages/kit/src/routes/Modal/router.tsx)
{
  name: EModalRoutes.SettingModal,
  children: ModalSettingStack,
  rewrite: '/settings',
  exact: true,
}

// Resulting path: /settings/... (not /Modal/settings/...)

Example 3: Onboarding Route

// Onboarding router config
{
  name: EOnboardingV2Routes.OnboardingV2,
  rewrite: '/onboarding',
  exact: true,
  children: OnboardingRouterV2,
}

// Sub-routes
{
  name: EOnboardingPagesV2.GetStarted,
  rewrite: '/get-started',
  component: GetStarted,
}

// Resulting path: /onboarding/get-started

Example 4: Native token detail (no tokenAddress in path)

{
  name: ETabMarketRoutes.MarketNativeDetail,
  component: MarketDetailV2,
  rewrite: '/token/:network',        // Only network, no token address
}

// URL example: /market/token/eth

Example 5: Non-native token detail (with tokenAddress)

{
  name: ETabMarketRoutes.MarketDetailV2,
  component: MarketDetailV2,
  rewrite: '/token/:network/:tokenAddress',
}

// URL example: /market/token/eth/0x1234...

Path Calculation in buildAllowList

The pagePath template function in routeUtils.ts calculates full paths:

function pagePath(_: TemplateStringsArray, ...screenNames: string[]): string {
  const path = screenNames.reduce((prev, screenName) => {
    const screen = screenConfig[screenName];
    const paths = screen.path.split('/:');
    const rawPath = removeExtraSlash(paths[0]);
    const screenPath = paths.length > 1 ? `${rawPath}/.` : rawPath;
    // If exact, use only current path; otherwise, accumulate
    return screen.exact ? screenPath : addPath(prev, screenPath);
  }, '');
  return `/${path}`;
}

// Usage:
pagePath`${ERootRoutes.Main}${ETabRoutes.Market}${ETabMarketRoutes.MarketDetail}`
// Result: /market/tokens/. (the /. indicates path params follow)

URL Allow List (Browser Display)

By default, routes don't display in the browser URL bar. To enable URL display, configure in packages/shared/src/utils/routeUtils.ts:

export const buildAllowList = (screens, perpDisabled, perpTabShowWeb) => {
  const rules = {
    // Show URL with parameters
    [pagePath`${ERootRoutes.Main}${ETabRoutes.Market}${ETabMarketRoutes.MarketDetailV2}`]: {
      showUrl: true,      // Enable URL display
      showParams: true,   // Show query parameters
    },
    // Show URL without parameters
    [pagePath`${ERootRoutes.Main}${ETabRoutes.Swap}${ETabSwapRoutes.TabSwap}`]: {
      showUrl: true,
      showParams: false,  // Hide query parameters
    },
  };
  return rules;
};

Note: When adding new pages that need browser URL display, configure them in buildAllowList.

Platform-Specific Routing: Web vs Extension

The routing implementation differs between web/native platforms and browser extension:

Web/Native: Standard Path Routing

File: packages/kit/src/routes/config/getStateFromPath.ts

// Simply re-exports from React Navigation
export { getStateFromPath } from '@react-navigation/core';

URL format: https://app.onekey.so/market/tokens/bitcoin

Extension: Hash Routing

File: packages/kit/src/routes/config/getStateFromPath.ext.ts

The extension uses a custom implementation copied from @react-navigation/core with hash routing modifications. The file is marked with // ---CHANGED Begin---- and // ---CHANGED end---- comments to indicate customizations.

Why custom implementation is needed:

• Browser extensions load from local HTML files (e.g., ui-expand-tab.html)
• Standard path routing doesn't work with extension URL scheme
• Hash routing allows navigation without page reload

Key customizations in getStateFromPath.ext.ts:

// 1. Store initial pathname for later use (line 98-100)
// ---CHANGED Begin----: initial path from url
let initialPath: string | undefined = globalThis.location.pathname;
// ---CHANGED end----

// 2. Extract path from hash instead of pathname (line 107-109)
export function getStateFromPath<ParamList extends {}>(
  path: string,
  options?: Options<ParamList>
): ResultState | undefined {
  // ---CHANGED Begin----: support hash router
  path = globalThis.location.hash.split('#').pop() || '/';
  // ---CHANGED end----
  // ... rest of function
}

// 3. Rewrite initial path for focused route (line 731-736)
// In createNestedStateObject function:
route = findFocusedRoute(state) as ParsedRoute;
// ---CHANGED Begin----: rewrite hash path to initial path
if (initialPath) {
  route.path = initialPath;
  initialPath = undefined;
}
// ---CHANGED end----

URL format returned (in index.ts line 139):

return `${extHtmlFileUrl}#${newPath}`;
// Example: /ui-expand-tab.html#/market/tokens/bitcoin

URL format comparison:

Important notes for extension routing:

1. The # symbol separates the HTML file from the route path
2. Windows Chrome has specific requirements (line 131-137 in index.ts):

   // /ui-expand-tab.html/#/   NOT working for Windows Chrome
   // /ui-expand-tab.html#/    works fine
   

3. When developing extension-specific routes, test on both Mac and Windows Chrome

Extension Routing Modifications Summary

The getStateFromPath.ext.ts file contains 4 key modifications from the original @react-navigation/core implementation:

Why these modifications are necessary:

• Browser extensions run from local HTML files, not a web server
• Standard path routing (/market/tokens/btc) doesn't work with chrome-extension:// URLs
• Hash routing (#/market/tokens/btc) allows client-side navigation without server requests
• The initial path storage ensures the extension knows its base HTML file location

Route Path Output by Platform

In packages/kit/src/routes/config/index.ts, the getPathFromState function handles platform differences:

getPathFromState(state, options) {
  // ... calculate path ...

  if (platformEnv.isExtension) {
    // Extension: return hash-based URL
    if (newPath === '/' && globalThis.location.href.endsWith('#/')) {
      return extHtmlFileUrl;  // e.g., /ui-expand-tab.html
    }
    return `${extHtmlFileUrl}#${newPath}`;  // e.g., /ui-expand-tab.html#/market
  }

  // Web/Desktop: return standard path
  return newPath;  // e.g., /market
}

Page Lifecycle

The Page component supports lifecycle callbacks defined in packages/components/src/layouts/Page/type.ts:

interface IPageLifeCycle {
  onMounted?: () => void;      // Called after page transition completes
  onUnmounted?: () => void;    // Called after page unmount transition completes
  onCancel?: () => void;       // Called when page closed without confirm
  onConfirm?: () => void;      // Called when page closed with confirm
  onClose?: (extra?: { flag?: string }) => void;  // Called on any close
  onRedirected?: () => void;   // Called after redirect completes
  shouldRedirect?: () => boolean;  // Return true to redirect immediately
}

Usage in Page Component:

import { Page } from '@onekeyhq/components';

function MyPage() {
  return (
    <Page
      => console.log('Page mounted')}
      => console.log('Page unmounted')}
      shouldRedirect={() => !hasPermission}
      => navigation.navigate('Login')}
    >
      <Page.Body>{/* content */}</Page.Body>
    </Page>
  );
}

Use Cases:

Redirect Pattern:

<Page
  shouldRedirect={() => {
    // Return true to immediately go back and trigger onRedirected
    return !isUserAuthenticated;
  }}
  => {
    // Called after going back, navigate to appropriate screen
    navigation.pushModal(EModalRoutes.OnboardingModal, {
      screen: EOnboardingPages.Login,
    });
  }}
>

Deep Link / Universal Link Configuration

Configure in packages/kit/src/routes/config/deeplink/index.ts:

Example: Adding invite_share deep link

Step 1: Define Deep Link Path

In packages/shared/src/consts/deeplinkConsts.tsx:

export enum EOneKeyDeepLinkPath {
  url_account = 'url_account',
  market_detail = 'market_detail',
  invite_share = 'invite_share',  // Add new path
}

export type IEOneKeyDeepLinkParams = {
  [EOneKeyDeepLinkPath.invite_share]: {
    utm_source: string;
    code: string;
  };
};

Step 2: Handle Deep Link

In packages/kit/src/routes/config/deeplink/index.ts:

async function processDeepLinkUrlAccount(params, times = 0) {
  const { parsedUrl } = params;
  const { hostname, queryParams, scheme, path } = parsedUrl;

  if (scheme === ONEKEY_APP_DEEP_LINK || scheme === ONEKEY_APP_DEEP_LINK_NAME) {
    switch (hostname ?? path?.slice(1)) {
      case EOneKeyDeepLinkPath.invite_share: {
        const { utm_source: utmSource, code } = queryParams as IEOneKeyDeepLinkParams[EOneKeyDeepLinkPath.invite_share];
        if (navigation) {
          navigation.switchTab(ETabRoutes.ReferFriends, {
            screen: ETabReferFriendsRoutes.TabReferAFriend,
            params: { utmSource, code },
          });
        }
        break;
      }
    }
  }
}

Deep Link Format:

• onekey-wallet://invite_share?utm_source=twitter&code=ABC123
• https://app.onekey.so/wc/connect/wc?uri=... (Universal Link)

QR Code / Banner Click Navigation

Configure QR code handlers for scanning and banner clicks.

Example: MARKET_DETAIL handler

Step 1: Define Handler Type

In packages/shared/types/qrCode.ts:

export enum EQRCodeHandlerType {
  MARKET_DETAIL = 'MARKET_DETAIL',
  // ... other types
}

export enum EQRCodeHandlerNames {
  marketDetail = 'marketDetail',
  // ... other names
}

export const PARSE_HANDLER_NAMES = {
  all: [
    EQRCodeHandlerNames.marketDetail,
    // ... other handlers
  ],
};

Step 2: Create Handler

Create packages/kit-bg/src/services/ServiceScanQRCode/utils/parseQRCode/handlers/marketDetail.ts:

import { WEB_APP_URL, WEB_APP_URL_DEV, WEB_APP_URL_SHORT } from '@onekeyhq/shared/src/config/appConfig';
import { EQRCodeHandlerType } from '@onekeyhq/shared/types/qrCode';
import type { IMarketDetailValue, IQRCodeHandler } from '../type';

const marketDetail: IQRCodeHandler<IMarketDetailValue> = async (value, options) => {
  const urlValue = options?.urlResult;
  if (urlValue?.data?.urlParamList) {
    const origin = urlValue?.data?.origin;
    // Check if URL matches OneKey web app
    if (
      [WEB_APP_URL, WEB_APP_URL_DEV, WEB_APP_URL_SHORT].includes(origin) &&
      urlValue?.data?.pathname.startsWith('/market/tokens/')
    ) {
      const coinGeckoId = urlValue?.data?.pathname.split('/market/tokens/').pop();
      return {
        type: EQRCodeHandlerType.MARKET_DETAIL,
        data: { origin, coinGeckoId },
      };
    }
  }
  return null;
};

export default marketDetail;

Step 3: Register Handler

In packages/kit-bg/src/services/ServiceScanQRCode/utils/parseQRCode/handlers/index.ts:

import marketDetail from './marketDetail';

export const PARSE_HANDLERS = {
  [EQRCodeHandlerNames.marketDetail]: marketDetail,
  // ... other handlers
};

Step 4: Handle Result in UI

In packages/kit/src/views/ScanQrCode/hooks/useParseQRCode.tsx:

const parse = useCallback(async (value, params) => {
  const result = await backgroundApiProxy.serviceScanQRCode.parse(value, options);

  switch (result.type) {
    case EQRCodeHandlerType.MARKET_DETAIL: {
      const { coinGeckoId } = result.data as IMarketDetailValue;
      if (coinGeckoId) {
        await closeScanPage();
        void marketNavigation.pushDetailPageFromDeeplink(navigation, { coinGeckoId });
      }
      break;
    }
  }
}, [navigation]);

Navigation Methods

// Push modal
navigation.pushModal(EModalRoutes.NotificationsModal, {
  screen: EModalNotificationsRoutes.NotificationList,
  params: { /* page params */ },
});

// Switch tab
navigation.switchTab(ETabRoutes.Market);

// Navigate within tab
navigation.navigate(ERootRoutes.Main, {
  screen: ETabRoutes.Market,
  params: {
    screen: ETabMarketRoutes.MarketDetail,
    params: { token: 'bitcoin' },
  },
}, {
  pop: true,
});

// Go back
navigation.goBack();

⚠️ IMPORTANT: Always Use pop: true with navigation.navigate

When using navigation.navigate, ALWAYS include the pop: true option to ensure proper navigation stack management:

// ✅ Correct - with pop: true
navigation.navigate(ERootRoutes.Main, undefined, {
  pop: true,
});

navigation.navigate(ERootRoutes.Main, {
  screen: ETabRoutes.Market,
  params: {
    screen: ETabMarketRoutes.MarketDetail,
    params: { token: 'bitcoin' },
  },
}, {
  pop: true,
});

// ❌ Wrong - missing pop: true
navigation.navigate(ERootRoutes.Main, {
  screen: ETabRoutes.Market,
});

Why pop: true is required:

• Prevents navigation stack from growing indefinitely
• Ensures proper back button behavior
• Avoids memory leaks from accumulated screens
• Maintains consistent navigation state across platforms

Files Reference