TypeScript @ Lynx

This Skill summarizes common TypeScript issues and their solutions in Lynx development, mainly covering environment configuration, type extending, event handling, components, and ReactLynx advanced usages.

1. Configuration (Environment Configuration)

1.1 tsconfig.json Configuration

Rspeedy reads the tsconfig.json in the root directory by default. Since Rspeedy uses SWC for transpilation, it is recommended to enable the isolatedModules option to avoid cross-file type reference errors.

```json title="tsconfig.json" { "compilerOptions": { "isolatedModules": true, "paths": { "@/": ["./src/"] } } }

### 1.2 Type Packages Installation

Ensure the correct type packages are installed. **@lynx-js/types** is the core type package for Lynx.

- **ReactLynx**: Install `@lynx-js/types` and `@lynx-js/react`.

### 1.3 Type Declaration File `rspeedy-env.d.ts`

To allow TypeScript to recognize Rspeedy's built-in features (such as CSS Modules, static resource imports), you need to create a `src/rspeedy-env.d.ts` file in the project:

```typescript title="src/rspeedy-env.d.ts"
/// <reference types="@rspeedy/core/client" />

(Note: The actual package might depend on your Rspeedy setup, typically @rspeedy/core or similar for open source)

1.4 ReactLynx JSX Configuration

For ReactLynx projects, you need to configure jsxImportSource as @lynx-js/react in tsconfig.json to ensure JSX is compiled correctly and gets type support.

```json title="tsconfig.json" { "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@lynx-js/react" } }

## 2. Extending Lynx Types

Lynx provides default type definitions, but you usually need to extend them to suit business needs.

### 2.1 GlobalProps

Extend the type of `lynx.__globalProps`:

```typescript title="src/global-props.d.ts"
declare module '@lynx-js/types' {
  interface GlobalProps {
    appTheme: string;
    title: string;
    // Add other custom global properties
  }
}
export {};

This way, there will be type hints when using lynx.__globalProps.appTheme.

2.2 InitData

Extend the return value type of the ReactLynx Hook useInitData():

```typescript title="src/init-data.d.ts" declare module '@lynx-js/react' { interface InitData { userInfo: { name: string; id: number; }; // Add other initialization data properties } } export {};

This way, there will be type hints when using `useInitData().userInfo`.

### 2.3 IntrinsicElements (Custom Native Components)

If custom native components are used, you need to extend `IntrinsicElements` to get JSX type checking:

```typescript title="src/intrinsic-element.d.ts"
import type * as Lynx from '@lynx-js/types';
import type { CSSProperties } from '@lynx-js/types';

declare module '@lynx-js/types' {
  interface IntrinsicElements extends Lynx.IntrinsicElements {
    'custom-input': {
      'bindcustom-event'?: (e: { type: 'custom-event'; detail: { value: string } }) => void;
      value?: string;
      class?: string;
      className?: string;
      style?: string | CSSProperties;
    };
  }
}

2.4 NativeModules

Extend the NativeModules type to support custom Native Module calls:

```typescript title="src/native-modules.d.ts" declare module '@lynx-js/types' { interface NativeModules { NativeLocalStorageModule: { getStorageItem(key: string): string | null; setStorageItem(key: string, value: string): void; }; } } export {};

### 2.5 Lynx Global Object

Extend the type of the `lynx` global object (e.g., adding a custom method `lynx.myMethod`):

```typescript title="src/lynx-global.d.ts"
declare module '@lynx-js/types' {
  interface Lynx {
    myMethod(param: string): void;
    customProperty: number;
  }
}
export {};

This way, there will be type hints when using lynx.myMethod('test').

3. Event Handling

When handling events, you should avoid using the any type. Lynx provides standard event types.

3.1 Basic Events and Touch Events

For touch events (like bindtap, bindtouchstart), the event object contains properties like detail, touches, changedTouches.

// Example: Handling a tap event
const handleTap = (event: any) => { // Using any is not recommended
  console.log(event);
};

// Recommended approach: Define event interfaces or use inferred types
import type { TouchEvent } from '@lynx-js/types';

// Usage example
const handleButtonTap = (e: TouchEvent) => {
  const { dataset } = e.currentTarget;
  console.log('Tapped!', dataset);
};

4. ReactLynx & LynxUI Types

4.1 LynxUI Component Types

LynxUI components usually export the type definitions for their Props and Ref. When using components from @lynx-js/lynx-ui (or its sub-packages like @lynx-js/lynx-ui-button, @lynx-js/lynx-ui-scroll-view, etc.), you should use these exported types.

Best Practices:

1. Explicitly import Props and Ref types.
2. Specify the Ref type when using useRef.

import { ScrollView } from '@lynx-js/lynx-ui-scroll-view';
import type { ScrollViewRef, ScrollViewProps } from '@lynx-js/lynx-ui-scroll-view';
import { useRef } from '@lynx-js/react';

function App() {
  // Explicitly specify the Ref type
  const scrollViewRef = useRef<ScrollViewRef>(null);

  const handleScroll: ScrollViewProps['onScroll'] = (e) => {
    console.log('Scrolled:', e.detail);
  };

  return (
    <ScrollView
      ref={scrollViewRef}
      onScroll={handleScroll}
      // ...
    />
  );
}

4.2 MainThreadRef and Multi-threading APIs

ReactLynx provides dedicated APIs for handling main thread state.

import { useMainThreadRef, runOnMainThread } from '@lynx-js/react';

function AnimationComponent() {
  // Define the data type stored in MainThreadRef
  const widthRef = useMainThreadRef<number>(0);

  const handleTap = () => {
    // Call main thread logic from the background thread
    runOnMainThread(widthRef, (ref) => {
      // This callback executes on the main thread
      ref.current += 10;
      console.log('New width:', ref.current);
    });
  };

  return <view bindtap={handleTap} />;
}

4.3 Lynx Global Object

The lynx global object provides methods like querySelector.

// Select element
const element = lynx.querySelector('#my-id');
// The type of element is Element | null

// Register data processors (functional)
lynx.registerDataProcessors({
  defaultDataProcessor: (data) => {
    return data;
  }
});

5. Common Error Fix Guide

• Error: Property '...' does not exist on type 'GlobalProps'

-> Refer to [2.1 GlobalProps](#21-globalprops) for type extension.

• Error: Property '...' does not exist on type 'InitData'

-> Refer to [2.2 InitData](#22-initdata) for type extension.

• Error: Property '...' does not exist on type 'JSX.IntrinsicElements'

-> Refer to [2.3 IntrinsicElements (Custom Native Components)](#23-intrinsicelements-custom-native-components) for type extension. -> Also check if conflicting type packages are installed.

• Error: Property 'cancelAnimationFrame' does not exist on type 'UnsafeLynx' or CSSProperties not assignable

-> Cause: Usually caused by installing multiple conflicting Lynx type packages. -> Solution: Check package.json, remove unnecessary type packages, ensuring only @lynx-js/types along with @lynx-js/react are kept.

• Error: Cannot find module '...' or its corresponding type declarations

-> Check if paths is configured (refer to [1.1](#11-tsconfigjson-configuration)) or if d.ts definitions are missing.

• Error: 'lynx' is not defined

-> Ensure the project contains the reference import {} from "@lynx-js/react".

• When using declare module '@lynx-js/types' in a d.ts file, make sure to export an empty object export {} to avoid global pollution.