> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# Native Libraries and Autolink

A Lynx native library is an npm package that ships any combination of Elements, Native Modules, and Services for a host Lynx app to consume. Before this, those capabilities had to be wired up once per host app, with a separate pass for Android, iOS, and HarmonyOS. Autolink is the companion integration mechanism that lets the host app discover libraries installed under `node_modules` and connect their native capabilities without wiring each Element, Native Module, or Service by hand.

Autolink provides app-wide registration on Android and iOS. HarmonyOS integration is documented below but is not yet available in a released Lynx SDK. Autolink also covers the package metadata and host loading used by Lynxtron native libraries, but does not generate per-`LynxView` library registration or Web integration code.

This page has two halves: to use an existing library in your app, start from [Consuming a Library](#consuming-a-library); to publish your own native capability as a library, start from [Authoring a Library](#authoring-a-library). If you would rather understand the machinery first, read [How Autolink Works](#how-autolink-works).

:::info Prerequisites

✅ Completed [Integrate with Existing Apps](/next/guide/start/integrate-with-existing-apps.md)

✅ Familiar with [Native Modules](/next/guide/use-native-modules.md) and [Custom Native Element](/next/guide/custom-native-component.md)

:::

:::note Tooling Availability

Use Autolink tooling from the same Lynx release channel as your app. The package and plugin names are:

- npm: `create-lynx-library` and `@lynx-js/autolink-codegen` (`lynx-autolink-codegen` binary)
- Android: Gradle plugins `org.lynxsdk.lynx.library-settings` and `org.lynxsdk.lynx.library-build`
- iOS: Ruby gem `cocoapods-lynx-library`
- HarmonyOS: Hvigor plugin `@lynx-js/lynx-library-plugin`
- Lynxtron: `create-lynx-library` can generate shared native library packages, and `@lynx-js/lynxtron-dev-plugins` provides host-side loading through `pluginLynxtron()`.

If one of these packages cannot be resolved from your configured registries, your current Lynx SDK release does not include Native Autolink in that registry yet. Keep using the existing manual native registration flow until the matching release is available.

:::

## Platform Compatibility

The following table shows Autolink support for the platforms represented in Lynx Compatibility Data. Lynxtron's host-side integration is documented in [Set Up Autolink](#set-up-autolink), but Lynxtron is not represented in this table.


**Compatibility Table**
**Query:** `features.autolink`

**Platform Support**

| Platform | Version Added | Notes |
|----------|---------------|-------|
| Android | 4.0 | - |
| iOS | 4.0 | - |
| HarmonyOS | ❌ No | - |
| Web | ❌ No | - |

**Description:** Autolink


## What Is a Lynx Native Library

A library is an npm package that may ship any combination of:

- **Elements**: custom native UI elements rendered by Lynx, such as `<x-button>`.
- **Native Modules**: typed JavaScript-to-native APIs callable from Lynx app code.
- **Services**: app-wide native singletons that other library capabilities can depend on.

Every library declares its native entry points in a `lynx.lib.json` manifest at the package root. The three capability types are independent: a library may expose only Elements, only Native Modules, only Services, or any combination of them.

App teams install a library like any other npm dependency. The Android Gradle plugins, iOS CocoaPods plugin, and HarmonyOS Hvigor plugin read `lynx.lib.json` and link the native code into the host app, so the host never needs to know which specific capabilities any given library exposes. Lynxtron reads the same manifest from installed packages, stages matched package files into the host output, and prepends generated host-bundle code that requires each staged package's `./lynxtron` entry.

## Consuming a Library

This section is for app teams integrating one or more libraries into a host Lynx app.

### Host App Project Structure

Before enabling Autolink, make sure the host app has a project root that can install npm packages and expose the native app build entry points. A typical host app looks like this:

```text
lynx-app/
├── package.json
├── android/
│   ├── settings.gradle
│   └── app/
│       └── build.gradle
├── ios/
│   └── Podfile
├── harmony/
│   ├── hvigorconfig.ts
│   └── entry/
│       └── hvigorfile.ts
├── shared/
│   ├── CMakeLists.txt
│   └── ...
├── dist/
└── src/
```

- `package.json` is required so the app can declare Autolink library packages as dependencies.
- For Android, the project needs a Gradle settings file, such as `settings.gradle` or `settings.gradle.kts`, and an Android application build file, such as `app/build.gradle` or `app/build.gradle.kts`.
- For iOS, the project needs a CocoaPods entry point, usually `Podfile`. The Podfile must declare the [`lynx-family` Specs repository](https://github.com/lynx-family/Specs) as a source. If your team manages Ruby dependencies with Bundler, keep the `cocoapods-lynx-library` gem in `Gemfile`.
- For HarmonyOS, the project needs a root `hvigorconfig.ts` and an entry or feature HAP module that depends on `@lynx/lynx`.
- `shared/` is used when the host app owns cross-platform native source code and CMake build entry points; build these sources yourself.
- For Lynxtron, the app needs a host-side Rspack build that can install npm packages and load native libraries through `pluginLynxtron()`; it generally consumes the compiled `dist/` artifacts.

After you install dependencies, Autolink scans the installed npm packages for `lynx.lib.json` files at package roots. A lockfile such as `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock` is recommended for reproducible installs, but it is not required by Autolink.

### Set Up Autolink

Set up Autolink once in the host app. After that, installed library packages can be discovered from `node_modules` and registered through the generated registry during Lynx initialization.


iOSAndroidHarmonyOSLynxtron

Enable the settings plugin in `settings.gradle` so library Android projects can be discovered from `lynx.lib.json` and included:
```groovy
plugins {
  id 'org.lynxsdk.lynx.library-settings' version '4.0.1'
}
```
Enable the build plugin in the Android application project so the generated registry is added to the app and library projects are wired as dependencies:
```groovy
plugins {
  id 'com.android.application'
  id 'org.lynxsdk.lynx.library-build' version '4.0.1'
}
```
After Gradle sync/build, Autolink generates a fixed Android registry entry and adds it to the app sources. When the app initializes `LynxEnv`, that entry is loaded automatically, and Elements, Native Modules, and Services from installed libraries are registered app-wide. App code does not need any additional native initialization.

Install the `cocoapods-lynx-library` gem in your iOS build environment. Then add the pod sources and the CocoaPods plugin to the app's Podfile and call `use_lynx_library!` so podspecs from installed libraries and the generated registry pod are added during `pod install`:
```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/lynx-family/Specs.git'

plugin 'cocoapods-lynx-library'

target 'LynxApp' do
  use_lynx_library!
end
```
After `pod install`, Autolink generates the registry pod and hooks it into the Lynx initialization flow. When the app creates `LynxConfig` or initializes `LynxEnv`, Elements, Native Modules, and Services from installed libraries are registered automatically. App code does not need to import generated files or add extra native initialization.

Add the plugin dependency to `hvigor/hvigor-config.json5` in the HarmonyOS project root:
```json5
{
  modelVersion: '5.0.0',
  dependencies: {
    '@lynx-js/lynx-library-plugin': '^0.1.0',
  },
}
```
Create `hvigorconfig.ts` in the HarmonyOS project root and enable the plugin once:
```ts
import * as hvigorApi from '@ohos/hvigor';
import { enableHarmonyLynxAutolink } from '@lynx-js/lynx-library-plugin';

enableHarmonyLynxAutolink(hvigorApi, {
  moduleName: 'entry',
});
```
You can omit `moduleName` when the project has exactly one entry or feature HAP that depends on `@lynx/lynx`. Projects with multiple Lynx HAP modules must select the target explicitly.
Before Hvigor creates module nodes, the plugin scans visible `node_modules` directories, parses HarmonyOS JSON5 metadata with Hvigor's public `parseJsonFile()` API, generates a Registry HAR in the project's ignored `.hvigor/lynx-autolink/<moduleName>` cache directory, and adds the library and Registry HAR modules to the build graph through `hvigorConfig.includeNode()`. After the target HAP is evaluated, it uses HAP model APIs to inject the Registry dependency and generated resource directory and set `module.appStartup`. The AppStartup sources stay under the HAP module's `build/generated/lynx-autolink` directory; a generated Hvigor task restores them after `clean` and before the active target's `PreBuild`. The plugin does not edit the app's `src` tree or checked-in `build-profile.json5` files.
The generated AppStartup task runs on the main thread before app code creates a Lynx runtime and calls only the Registry HAR's idempotent `setupGlobal()` function. If the HAP already has an AppStartup profile, the plugin preserves its tasks and `configEntry` and appends the Lynx task. No command such as `lynx-harmony-autolink` and no manual `setupGlobal()` call is required.

:::note Lynxtron Tooling Version
The `targets` manifest and automatic native artifact packaging are available in the published `0.0.22` releases of `@lynx-js/create-lynxtron`, `@lynx-js/lynxtron`, `@lynx-js/lynxtron-dev-plugins`, and `@lynx-js/lynxtron-builder`. Library creation has been verified with `create-lynx-library@0.6.1` and `@lynx-js/autolink-codegen@0.6.0`. Use these compatible versions together and retain the lockfile when reproducing this guide.
:::
Lynxtron enables Autolink for Desktop native libraries. Not every Lynx-embedded Desktop host supports Autolink out of the box; this is a Lynxtron-provided integration.
In the Lynxtron host's Rspack config, add `pluginLynxtron()`. The plugin includes Lynxtron Autolink by default: it scans installed dependencies for `lynx.lib.json`, selects the matching `platforms.lynxtron.targets` record, copies each matching native library package into the host output, and injects code that imports the copied package's `./lynxtron` entry. Direct imports of `<package>/lynxtron` are also aliased to a generated proxy that resolves the copied package at runtime, but they are not needed for native registration. The `./lynxtron` entry loads the current host's `.node` artifact.
```ts
import { pluginLynxtron } from '@lynx-js/lynxtron-dev-plugins/rspack';

export default {
  target: 'electron-main',
  plugins: [
    pluginLynxtron({
      isDev: process.env.NODE_ENV === 'development',
      entry: './dist/desktop',
    }),
  ],
};
```
The `entry` field is the Lynxtron host's own bundle entry. `pluginLynxtron()` stages native library packages under the configured Rspack `output.path`, and electron-builder's `directories.app` must point to that same application output directory. When packaging the application, `lynxtron-builder` keeps these packages outside ASAR. It copies macOS Framework and nested app bundle payloads from the selected target into `Contents/Frameworks`; on Windows, the unpacked package keeps the `.node` addon, DLLs, resource packs, and locales together. See the `@lynx-js/lynxtron-dev-plugins` package for the full option shape.
After Lynxtron loads a native library, its Lynx static registrations become available in the Lynx runtime. The library author does not need a Lynxtron-specific registration macro.

### Install a Library

After the app has set up Autolink, install the library package in your Lynx app:

```bash
npm install @example/lynx-button
```

Each library package exposes a `lynx.lib.json` manifest at the package root. Autolink scans installed npm packages for this file.

```json
{
  "platforms": {
    "android": {
      "packageName": "com.example.button",
      "sourceDir": "android"
    },
    "ios": {
      "sourceDir": "ios",
      "podspecPath": "ios/build.podspec"
    },
    "harmony": {
      "packageDir": "harmony"
    },
    "lynxtron": {
      "targets": [
        {
          "os": "darwin",
          "arch": "arm64",
          "files": ["dist/darwin/arm64/lynx-button.node"],
          "frameworks": ["dist/darwin/arm64/Button.framework"],
          "appBundles": ["dist/darwin/arm64/Button Helper.app"]
        },
        {
          "os": "win32",
          "arch": "x64",
          "files": ["dist/win32/x64/lynx-button.node"]
        }
      ]
    },
    "macos": {
      "sourceDir": "shared"
    },
    "windows": {
      "sourceDir": "shared"
    }
  }
}
```

For Android, `platforms.android.packageName` is required, and `sourceDir` defaults to `android`. For iOS, `sourceDir` defaults to `ios`, and `podspecPath` defaults to the first `.podspec` found under the iOS source directory. For HarmonyOS, `packageDir` defaults to `harmony`; that directory must contain a complete source HAR with `hvigorfile.ts`, `oh-package.json5`, `build-profile.json5`, `src/main/module.json5`, and the package entry declared by `main` or `Index.ets`.

`platforms.macos.sourceDir` and `platforms.windows.sourceDir` point to the source-exposed `shared/` directory, which is the cross-platform native source layout and may be reused by more platforms later.

For Lynxtron, use `targets` to group runtime payloads by host. Each target declares `os`, `arch`, and at least one string array named `files`, `frameworks`, or `appBundles`; every path is relative to the package root. Autolink selects the matching target, verifies its paths, stages the package, and loads its `./lynxtron` export. That entry reads the same manifest and loads the selected `.node` from `files`. `files` lists every payload that remains at its package-relative location, including native addons, dynamic libraries, executables, resource packs, and directories. On macOS, `frameworks` lists `.framework` bundles and `appBundles` lists nested `.app` bundles. Lynxtron places both categories in `Contents/Frameworks` and includes the nested applications in the host's signing flow.

`npm pack` does not preserve symbolic-link entries inside package contents. If a Framework or app bundle relies on links, provide an idempotent installation step that reconstructs them from shipped targets, then verify the installed package. Lynxtron preserves those restored links when it stages and packages the bundle.

These paths identify source artifacts inside the npm package. Lynxtron's development plugin and builder automatically choose their final locations in development output and packaged applications. App teams do not copy these artifacts or add per-library packaging rules. The Lynxtron manifest does not provide opaque package roots or legacy aliases: use `targets`, `files`, `frameworks`, `appBundles`, and the `arch` selector exactly as shown.

After installing or updating a library package, sync/build the Android or HarmonyOS app and run `pod install` for iOS so the generated registry and native dependencies are refreshed. For Lynxtron, use the app's standard build and package commands; `pluginLynxtron()` and `lynxtron-builder` handle the selected target automatically. You do not need to import a library's `./lynxtron` entry, copy its native files, or add per-library registration or packaging code in the app.

## Authoring a Library

This section is for library authors building a reusable native package for other Lynx apps to install.

### Library Package Structure

A typical library package looks like this. `shared/` is for cross-platform native implementations, and packages that also ship Lynxtron native artifacts may contain a Lynxtron loading entry and per-host outputs:

```text
lynx-button/
├── package.json
├── lynx.lib.json
├── types/
│   ├── index.d.ts
│   ├── platform-native-module.d.ts
│   └── napi-native-module.d.ts
├── src/
│   └── index.ts
├── generated/
│   ├── ButtonModule.ts
│   └── ButtonModuleNapi.ts
├── android/
│   └── src/main/java/com/example/button/
│       ├── ButtonElement.java
│       ├── ButtonModule.java
│       ├── ButtonService.java
│       └── generated/ButtonModuleSpec.java
├── ios/
│   ├── build.podspec
│   └── src/
│       ├── ButtonElement.m
│       ├── ButtonModule.m
│       ├── ButtonService.m
│       └── generated/
│           ├── ButtonModuleSpec.h
│           └── ButtonModuleSpec.m
├── harmony/
│   ├── Index.ets
│   ├── hvigorfile.ts
│   ├── oh-package.json5
│   ├── build-profile.json5
│   └── src/main/
│       ├── module.json5
│       └── ets/
│           ├── LynxLibraryProviderImpl.ets
│           ├── ButtonElement.ets
│           ├── ButtonModule.ets
│           ├── ButtonService.ets
│           └── generated/ButtonModuleSpec.ets
├── shared/
│   ├── CMakeLists.txt
│   ├── nativeModule/
│   └── elements/
├── lynxtron/
│   ├── CMakeLists.txt
│   ├── index.cjs
│   └── library_entry.cc
├── dist/
│   ├── darwin/
│   │   └── arm64/
│   │       └── lynx-button.node
│   └── win32/
│       └── x64/
│           └── lynx-button.node
└── example/
```

- `package.json` makes the package installable from npm and usually provides the `codegen` script.
- `lynx.lib.json` is the Autolink contract. It declares each platform-selected file or Framework source artifact.
- `types/index.d.ts` re-exports typed Native Module declarations. Platform Native Module declarations live in `types/platform-native-module.d.ts`, and N-API Native Module declarations live in `types/napi-native-module.d.ts` when those features are selected.
- `src/index.ts` exports the JavaScript API that app code imports.
- `android/`, `ios/`, and `harmony/` contain native implementations and generated native specs. The HarmonyOS directory is a complete source HAR, including its module-level `hvigorfile.ts`.
- `shared/` contains cross-platform native code, such as self-render element implementations and C++ N-API callback stubs under `shared/nativeModule/`.
- `lynxtron/` and `dist/` contain the Lynxtron loading entry and per-host outputs.
- `example/` is a local app used by the library author to verify the package.

### Create a Library

Create a new library package interactively:

```bash
npm create lynx-library
```

For scripts and tests, the same scaffold can run without prompts:

```bash
npm create lynx-library -- \
  --dir ./lynx-button \
  --features native-module,napi-native-module,element,service \
  --platforms android,ios,harmony,lynxtron \
  --package-name @example/lynx-button \
  --android-package com.example.button \
  --module-name ButtonModule \
  --element-name x-button \
  --service-name ButtonService
```

The generated package includes:

- `package.json` with `"codegen": "lynx-autolink-codegen"`
- `lynx.lib.json` for Android, iOS, HarmonyOS, and Lynxtron Autolink metadata
- `types/index.d.ts`, `types/platform-native-module.d.ts`, and `types/napi-native-module.d.ts` for typed Native Module declarations, depending on the selected module features
- `src/index.ts` for the JavaScript facade
- `android/` and `ios/` native source folders plus a complete `harmony/` source HAR
- `shared/` native sources when cross-platform implementations are generated
- `lynxtron/` loading entry when Lynxtron artifacts are generated
- `example/`, `tsconfig.json`, and `README.md`

Run codegen from the library root:

```bash
npm run codegen
```

`lynx-autolink-codegen` reads `lynx.lib.json`. For Native Modules, it scans the Native Module declaration files under `types/` for `@lynxmodule` declarations:

```ts
/** @lynxmodule */
export declare class ButtonModule {
  getLabel(id: string): string;
  setEnabled(id: string, enabled: boolean): void;
}
```

It generates:

- `generated/<ModuleName>.ts` for the JavaScript facade
- Android `<ModuleName>Spec.java` for Android platform native modules
- iOS `<ModuleName>Spec.h` and `<ModuleName>Spec.m` for iOS platform native modules
- HarmonyOS `<ModuleName>Spec.ets` under `<packageDir>/src/main/ets/generated`
- shared C++ N-API callback stubs under `shared/nativeModule/` for N-API native modules

The HarmonyOS spec currently supports `void`, `string`, `number`, `boolean`, and nullable unions with `null`. Other generated targets retain their existing support for arrays, objects/maps/sets, promises, and N-API wrapped value types such as `ArrayBuffer`, typed arrays, `BigInt`, `Date`, `Function`, `Symbol`, `Buffer`, and `Value`.

### Write Native APIs

Use platform-specific Lynx annotations or registration APIs in native source files so Autolink can discover each library's capabilities. On Android and iOS, Native Modules usually extend the spec generated by `lynx-autolink-codegen`, and Elements and Services are discovered from their native markers. HarmonyOS libraries export one provider that registers all capabilities.


iOSAndroidHarmonyOSLynxtron

Native Module example:
```java
package com.example.button;

import com.example.button.generated.ButtonModuleSpec;
import com.lynx.jsbridge.LynxNativeModule;
import com.lynx.jsbridge.LynxMethod;
import com.lynx.tasm.behavior.LynxContext;
import java.util.HashMap;
import java.util.Map;

@LynxNativeModule(name = "ButtonModule")
public final class ButtonModule extends ButtonModuleSpec {
  private final Map<String, Boolean> enabledState = new HashMap<>();

  public ButtonModule(LynxContext context) {
    super(context);
  }

  @Override
  @LynxMethod
  public String getLabel(String id) {
    return "Button " + id;
  }

  @Override
  @LynxMethod
  public void setEnabled(String id, boolean enabled) {
    enabledState.put(id, enabled);
  }
}
```
Element example:
```java
package com.example.button;

import android.content.Context;
import android.view.Gravity;
import android.widget.TextView;
import com.lynx.tasm.behavior.LynxElement;
import com.lynx.tasm.behavior.LynxContext;
import com.lynx.tasm.behavior.LynxProp;
import com.lynx.tasm.behavior.ui.LynxUI;

@LynxElement(name = "x-button")
public final class ButtonElement extends LynxUI<TextView> {
  public ButtonElement(LynxContext context) {
    super(context);
  }

  @Override
  protected TextView createView(Context context) {
    TextView view = new TextView(context);
    view.setGravity(Gravity.CENTER);
    view.setText("x-button");
    return view;
  }

  @LynxProp(name = "text")
  public void setText(String text) {
    mView.setText(text == null ? "" : text);
  }
}
```
Service example:
```java
package com.example.button;

import android.content.Context;
import com.lynx.tasm.service.IServiceProvider;
import com.lynx.tasm.service.LynxService;

@LynxService
public final class ButtonService implements IServiceProvider {
  private Context appContext;

  @Override
  public Class<? extends IServiceProvider> getServiceClass() {
    return ButtonService.class;
  }

  @Override
  public void onInitialize(Context context) {
    appContext = context.getApplicationContext();
  }

  public void recordClick(String id) {
    // Send analytics or call platform capabilities here.
  }
}
```

Native Module example:
```objc
// ButtonModule.h
#import <Foundation/Foundation.h>
#import <Lynx/LynxModule.h>
#import "generated/ButtonModuleSpec.h"

NS_ASSUME_NONNULL_BEGIN

@LynxNativeModule("ButtonModule")
@interface ButtonModule : NSObject <ButtonModuleSpec>

@end

NS_ASSUME_NONNULL_END

// ButtonModule.m
#import "ButtonModule.h"

@implementation ButtonModule {
  NSMutableDictionary<NSString *, NSNumber *> *_enabledState;
}

- (instancetype)init {
  self = [super init];
  if (self) {
    _enabledState = [NSMutableDictionary dictionary];
  }
  return self;
}

- (NSString *)getLabel:(NSString *)buttonId {
  return [NSString stringWithFormat:@"Button %@", buttonId];
}

- (void)setEnabled:(NSString *)buttonId enabled:(BOOL)enabled {
  _enabledState[buttonId] = @(enabled);
}

@end
```
Element example:
```objc
// ButtonElement.h
#import <UIKit/UIKit.h>
#import <Lynx/LynxUI.h>

NS_ASSUME_NONNULL_BEGIN

@interface ButtonElement : LynxUI<UILabel *>

@end

NS_ASSUME_NONNULL_END

// ButtonElement.m
#import "ButtonElement.h"
#import <Lynx/LynxPropsProcessor.h>

@LynxElement("x-button")
@implementation ButtonElement

LYNX_PROP_SETTER("text", setText, NSString *) {
  self.view.text = value ?: @"";
}

- (UILabel *)createView {
  UILabel *label = [[UILabel alloc] init];
  label.textAlignment = NSTextAlignmentCenter;
  label.text = @"x-button";
  return label;
}

@end
```
Service example:
```objc
// ButtonService.h
#import <Foundation/Foundation.h>
#import <LynxServiceAPI/ServiceAPI.h>

NS_ASSUME_NONNULL_BEGIN

@protocol ButtonServiceProtocol <LynxServiceProtocol>

- (void)recordClick:(NSString *)buttonId;

@end

@interface ButtonService : NSObject <ButtonServiceProtocol>

@end

NS_ASSUME_NONNULL_END

// ButtonService.m
#import "ButtonService.h"

@LynxService(ButtonService, ButtonServiceProtocol)
@implementation ButtonService

+ (instancetype)sharedInstance {
  static ButtonService *service;
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
    service = [[ButtonService alloc] init];
  });
  return service;
}

- (void)recordClick:(NSString *)buttonId {
  // Send analytics or call platform capabilities here.
}

@end
```
On iOS, Autolink scans `@LynxNativeModule(...)`, `@LynxElement(...)`, and `@LynxService(...)` declarations from library sources and adds the discovered capabilities to the generated registry. The legacy iOS Service API still provides `@LynxServiceRegister(...)` for existing code. New library code should use `@LynxService(...)`.

HarmonyOS libraries register all capabilities from one provider. `Index.ets` must export a class named `LynxLibraryProviderImpl`:
```ts
// harmony/Index.ets
export { LynxLibraryProviderImpl } from './src/main/ets/LynxLibraryProviderImpl';
export { ButtonElement } from './src/main/ets/ButtonElement';
export { ButtonModule } from './src/main/ets/ButtonModule';
export { ButtonService } from './src/main/ets/ButtonService';
```
Implement a Native Module by extending the generated ArkTS spec:
```ts
import { ButtonModuleSpec } from './generated/ButtonModuleSpec';

export class ButtonModule extends ButtonModuleSpec {
  getLabel(id: string): string {
    return `Button ${id}`;
  }

  setEnabled(_id: string, _enabled: boolean): void {}
}
```
Implement an Element with the existing HarmonyOS `UIBase` API:
```ts
import { UIBase } from '@lynx/lynx';

export class ButtonElement extends UIBase {
  layout(
    _x: number,
    _y: number,
    _width: number,
    _height: number,
    _paddingLeft: number,
    _paddingTop: number,
    _paddingRight: number,
    _paddingBottom: number,
    _marginLeft: number,
    _marginTop: number,
    _marginRight: number,
    _marginBottom: number,
    _sticky?: number[],
  ): void {}
}
```
Services use the existing Lynx service interfaces. This example supplies the global Extension service:
```ts
import { ILynxExtensionService, LynxContext } from '@lynx/lynx';

export class ButtonService implements ILynxExtensionService {
  static readonly instance: ButtonService = new ButtonService();

  onLynxViewSetup(
    _context: LynxContext,
    _uiDelegate: number[],
    _isHostRenderer: boolean,
  ): void {}

  onLynxViewDestroy(_context: LynxContext): void {}
}
```
The provider connects those implementations to Lynx:
```ts
import {
  Behavior,
  LynxLibraryProvider,
  LynxLibraryRegistry,
  LynxServiceType,
} from '@lynx/lynx';
import { ButtonElement } from './ButtonElement';
import { ButtonModule } from './ButtonModule';
import { ButtonService } from './ButtonService';

export class LynxLibraryProviderImpl implements LynxLibraryProvider {
  register(registry: LynxLibraryRegistry): void {
    registry.registerBehavior('x-button', new Behavior(ButtonElement));
    registry.registerModule('ButtonModule', { moduleClass: ButtonModule });
    registry.registerService(LynxServiceType.Extension, ButtonService.instance);
  }
}
```
Use `registerInitializer(() => packageInit())` for package-level native initialization such as a native XElement registration API. Keep native XElements on their existing C++ registration path; do not wrap them in a `UIBase` implementation just for Autolink.
The Registry rejects duplicate global Element tags, Native Module names, and Service types with package-aware diagnostics. Global Native Modules are installed before a `LynxView` or `LynxBackgroundRuntime`'s explicit module map, so an explicitly supplied local module keeps its existing override behavior.

Lynxtron native libraries use the shared Lynx C/C++ extension APIs and static registration macros. This page only covers how Autolink discovers and loads packages. For implementation details, use the Desktop (Node-API) tab for Native Modules and the Desktop tab for Custom Native Elements:
- [Native Modules for Desktop (Node-API)](/next/guide/use-native-modules.md?platform=node-api)
- [Custom Native Elements for Desktop](/next/guide/custom-native-component.md?platform=desktops)

### Distribute a Library

Publish the library like any other npm package: pick a name, often scoped as `@example/lynx-button`, and set a version in `package.json`. If the package declares Lynxtron targets, generate its sources and build every declared OS/architecture on the matching host before packing it:

```bash
npm run codegen
npm run build:lynxtron
npm pack
```

`npm pack` and `npm publish` do not compile native artifacts. Collect every target's output under `dist/`, make sure `package.json#files` includes `dist`, `lynxtron`, and `lynx.lib.json`, and verify that the resulting tgz contains every path listed in `targets` before running `npm publish`.

App teams only add the published package to their dependencies and run the application's standard build/package commands. Lynxtron Autolink loads the matching target and packages its runtime payload without per-library application configuration. Pin a compatible Lynx SDK version range in the library's `peerDependencies` so app teams get a clear signal when the library and the host SDK drift apart.

## How Autolink Works

Autolink runs at build time. It scans every npm package under `node_modules` for a `lynx.lib.json` manifest, then generates or feeds host integration data for the current platform. Generation works differently per platform:

- **Android**: registry generation runs through the Gradle settings and build plugins.
- **iOS**: registry generation runs through the CocoaPods plugin and emits a registry pod.
- **HarmonyOS**: registry generation runs during Hvigor configuration and emits a source Registry HAR plus an AppStartup task.
- **Lynxtron**: Autolink runs in the host Rspack build, staging matching native packages, injecting a loader into the host bundle, and letting the loaded library's Lynx static registrations provide its native modules and elements.

Android, iOS, and HarmonyOS load their generated registry once during initialization, so no per-library wiring code lives in the host.
