#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; to publish your own native capability as a library, start from Authoring a Library. If you would rather understand the machinery first, read How Autolink Works.

#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, but Lynxtron is not represented in this table.

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

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

plugins {
  id 'org.lynxsdk.lynx.library-settings' version '4.0.1'
}

plugins {
  id 'com.android.application'
  id 'org.lynxsdk.lynx.library-build' version '4.0.1'
}

plugin 'cocoapods-lynx-library'

target 'LynxApp' do
  use_lynx_library!
end

{
  modelVersion: '5.0.0',
  dependencies: {
    '@lynx/lynx-library-plugin': '^0.1.0',
  },
}

import * as hvigorApi from '@ohos/hvigor';
import { enableHarmonyLynxAutolink } from '@lynx/lynx-library-plugin';

enableHarmonyLynxAutolink(hvigorApi, {
  moduleName: 'entry',
});

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',
    }),
  ],
};

#Install a Library

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

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.

{
  "platforms": {
    "android": {
      "packageName": "com.example.button",
      "sourceDir": "android"
    },
    "ios": {
      "sourceDir": "ios",
      "podspecPath": "ios/build.podspec"
    },
    "harmony": {
      "packageDir": "harmony"
    },
    "lynxtron": {
      "path": "dist"
    },
    "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, platforms.lynxtron.path declares the native artifact root, usually dist. pluginLynxtron() stages matching package files and verifies the artifacts; the package's ./lynxtron export loads the current host's .node, such as dist/macos/arm64/lynx-button.node or dist/windows/x64/lynx-button.node.

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. You do not need to add per-library manual registration 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:

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/
│   ├── macos/
│   │   └── arm64/
│   │       └── lynx-button.node
│   └── windows/
│       └── 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 tells the host app where each native package or artifact root lives.
• 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:

npm create lynx-library

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

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:

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:

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

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);
  }
}

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);
  }
}

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

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

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

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

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

import { ButtonModuleSpec } from './generated/ButtonModuleSpec';

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

  setEnabled(_id: string, _enabled: boolean): void {}
}

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 {}
}

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 {}
}

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);
  }
}

#Distribute a Library

Publish the library like any other npm package: pick a name, often scoped as @example/lynx-button, set a version in package.json, and run npm publish. App teams add the published version to their package.json and Autolink picks the library up the next time they install dependencies. 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.