name: 1k-coding-patterns
description: Coding patterns and best practices for OneKey development. Use when writing React components, handling promises, error handling, or following code conventions. Triggers on react, component, hooks, promise, async, await, error, pattern, convention, typescript.
allowed-tools: Read, Grep, Glob, Write, Edit

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'; // ❌