OneKey Coding Patterns and Best Practices

General Development

• Develop functions with a test-driven development mindset, ensuring each low-level function or method intended for reuse performs a single, atomic task, but avoid adding unnecessary abstraction layers

Promise Handling - MANDATORY COMPLIANCE

• ALWAYS await Promises; use void prefix ONLY if intentionally not awaiting
• ZERO TOLERANCE for floating promises - they cause unhandled rejections
• FOLLOW the @typescript-eslint/no-floating-promises rule strictly
• BEFORE ANY ASYNC OPERATION: Consider error scenarios and add appropriate try/catch blocks
• VERIFY: All Promise chains have proper error handling

React Components

• Avoid default React import; use named imports only
• Prefer functional components over class components
• Use pure functions to create components; avoid importing import type { FC } from 'react'
• Follow React hooks rules (dependencies array, call only at top level)
• Use the usePromiseResult and useAsyncCall hooks with proper dependency arrays

Restricted Patterns - STRICTLY FORBIDDEN

ABSOLUTELY FORBIDDEN PATTERNS:

• ❌ NEVER use toLocaleLowerCase() or toLocaleUpperCase() → Use toLowerCase() and toUpperCase() instead
• ❌ NEVER directly import from '@onekeyfe/hd-core' → ALWAYS use const {} = await CoreSDKLoader() pattern
• ❌ NEVER import localDbInstance directly → ALWAYS use localDb instead
• ❌ NEVER modify auto-generated files (translations.ts, locale JSON files)
• ❌ NEVER bypass TypeScript types with any or @ts-ignore without documented justification
• ❌ NEVER commit code that fails linting or TypeScript compilation

VIOLATION CONSEQUENCES:

• Build failures and broken development environment
• Security vulnerabilities and data corruption
• Breaking multi-platform compatibility
• Circular dependency hell

Error Handling

• Use try/catch blocks for async operations that might fail
• Provide appropriate error messages and fallbacks
• Consider using the useAsyncCall hook for operations that need loading/error states

Linting and Code Quality

• ESLint warnings should be fixed before PRs
• Run yarn run lint to check for and fix ESLint issues

Comments and Documentation

• All comments must be written in English
• Use clear and concise English for inline comments, function documentation, and code explanations
• Avoid using non-English languages in comments to maintain consistency and accessibility for all developers
• Do not use Chinese comments; always use English comments only

Code Examples

Correct Promise Handling

// GOOD: Properly awaited
async function fetchData() {
  try {
    const result = await apiCall();
    return result;
  } catch (error) {
    console.error('Failed to fetch:', error);
    throw error;
  }
}

// GOOD: Intentionally not awaited (with void)
void backgroundTask();

// BAD: Floating promise
function badExample() {
  apiCall(); // ❌ Will trigger lint error
}

Correct React Component Pattern

// GOOD: Named imports, functional component
import { useState, useEffect, useCallback } from 'react';
import { Stack, Button } from '@onekeyhq/components';

function MyComponent({ data }: { data: MyData }) {
  const [state, setState] = useState(null);

  const handlePress = useCallback(() => {
    // handler logic
  }, []);

  return (
    <Stack>
      <Button onPress={handlePress}>Action</Button>
    </Stack>
  );
}

// BAD: Default import, FC type
import React, { FC } from 'react'; // ❌
const MyComponent: FC<Props> = () => {}; // ❌

Correct HD Core Usage

// GOOD: Use CoreSDKLoader
async function useHardware() {
  const { HardwareSDK } = await CoreSDKLoader();
  // use HardwareSDK
}

// BAD: Direct import
import { HardwareSDK } from '@onekeyfe/hd-core'; // ❌