lynx-typescript

name: lynx-typescript description: | 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.

Trigger Scenarios: - User inputs TypeScript error messages related to Lynx and seeks fix suggestions - LSP diagnoses Lynx-related TypeScript errors, proactively invoke query to get fix solutions - User asks about TypeScript best practices or common errors related to Lynx, proactively invoke query to provide guidance - User requests to configure the TypeScript environment of the current project to support Lynx development, proactively invoke query to provide configuration steps

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.

{
  "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:

/// <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.

{
  "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:

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():

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:

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:

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):

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:

Explicitly import Props and Ref types.
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 for type extension.
Error: Property '...' does not exist on type 'InitData' -> Refer to 2.2 InitData for type extension.
Error: Property '...' does not exist on type 'JSX.IntrinsicElements' -> Refer to 2.3 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) 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.