Lynx Native Libraries

A Lynx native library is a native library that registers capabilities with the Lynx runtime. It can be linked into an embedder directly, or distributed with an application package. In Lynxtron apps, it is often delivered through npm so the host build can install, stage, and load the platform artifact.

native-module: native APIs exposed to Lynx JS through NativeModules.<ModuleName>.
custom element: custom native elements exposed as Lynx elements. The concrete tag name is declared by the library and then used like a normal Lynx element.

This page focuses on how Lynxtron consumes these packages. For authoring and package layout details, see:

Loading Model

The basic model is static registration plus host-side native library loading:

The library's C/C++ code registers Lynx capabilities with static registration macros such as LYNX_REGISTER_NATIVE_MODULE(...) and LYNX_REGISTER_ELEMENT(...).
The host integration layer loads the native binary for the current platform. In Lynxtron this can be generated by AutoLink from package metadata, or implemented by application code.
If the Lynxtron artifact is a .node file, the host can load it through normal Node.js require(). Loading the binary activates the static Lynx registrations in the Lynx runtime, so app code can use NativeModules.<ModuleName> and custom elements.

The .node file can also expose a normal Node-API addon surface when the library needs host-side entry points. If the library only needs to make Lynx capabilities available, the Node-API addon surface can be empty; the load side effect is enough to activate static registration.

Runtime Boundaries

Lynxtron has both a Node.js host and a Lynx JS runtime. A native library must keep these two environments separate.

Environment	Purpose	Typical API
Lynxtron Node.js host	Loads the host integration entry or native artifact; calls host-side APIs	`require(...)`, package-specific exports
Lynx JS runtime	Runs Lynx app code and calls capabilities registered into Lynx	`NativeModules.<ModuleName>`, `<custom-element />`
Lynx native library	Registers native modules and elements when the binary is loaded or linked	`LYNX_REGISTER_NATIVE_MODULE`, `LYNX_REGISTER_ELEMENT`

Do not make capabilities available in the Lynx runtime by calling low-level registration APIs from application code. The library registers them in native code; the application only needs to load the library.

Create and Use a Lynx Library in Lynxtron with AutoLink

The steps below show the minimal Lynxtron path.

Create an AutoLink Library for Lynxtron

Create a Lynx library with Lynxtron metadata and a minimal native module or element scaffold. For the full package format, see AutoLink.

npm

yarn

pnpm

bun

deno

npm create lynx-library -- --dir ./hello-lynx-library --features native-module,napi-native-module,element --platforms lynxtron --package-name hello-lynx-library --module-name HelloModule --element-name hello-element

yarn create lynx-library -- --dir ./hello-lynx-library --features native-module,napi-native-module,element --platforms lynxtron --package-name hello-lynx-library --module-name HelloModule --element-name hello-element

pnpm create lynx-library -- --dir ./hello-lynx-library --features native-module,napi-native-module,element --platforms lynxtron --package-name hello-lynx-library --module-name HelloModule --element-name hello-element

bun create lynx-library -- --dir ./hello-lynx-library --features native-module,napi-native-module,element --platforms lynxtron --package-name hello-lynx-library --module-name HelloModule --element-name hello-element

deno init --npm lynx-library -- --dir ./hello-lynx-library --features native-module,napi-native-module,element --platforms lynxtron --package-name hello-lynx-library --module-name HelloModule --element-name hello-element

Implement Native Module or Element

The generated AutoLink library keeps the cross-platform native implementation under shared/ and the Lynxtron loading entry under lynxtron/:

hello-lynx-library/
|-- shared/
|   |-- nativeModule/  # NAPI native module implementation
|   `-- elements/      # element implementation and static registration
`-- lynxtron/
    |-- index.cjs        # CommonJS entry loaded by the Lynxtron host
    `-- library_entry.cc # Node-API entry used to build the .node artifact

Keep the generated implementation for a quick smoke test, or edit shared/nativeModule/ for a native module and shared/elements/ for an element. To learn how to implement each capability, see Native Modules and Custom Element.

Build and Publish

Build the current OS/architecture artifact and pack it as the package that a Lynxtron app can install:

cd hello-lynx-library
npm install
npm run codegen
npm run build:lynxtron
npm pack

Use npm publish instead of npm pack when publishing to a real registry.

Consume the Lynx Library in Lynxtron

Install the packed library into an existing Lynxtron app. If you need a base app first, follow Getting Started. This AutoLink flow depends on pluginLynxtron() in the host Rspack config; the plugin provides Lynxtron-side AutoLink loading:

cd <your-lynxtron-app>
npm install ../hello-lynx-library/hello-lynx-library-0.0.1.tgz
npm run start

After the host build loads the library through AutoLink, the capabilities are available in the Lynx runtime: app code can call the native module or render the custom element.

#Lynx Native Libraries

#Loading Model

#Runtime Boundaries

#Create and Use a Lynx Library in Lynxtron with AutoLink

#Create an AutoLink Library for Lynxtron

#Implement Native Module or Element

#Build and Publish

#Consume the Lynx Library in Lynxtron