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

# 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`](/next/guide/use-native-modules.md?platform=node-api): native
  APIs exposed to Lynx JS through `NativeModules.<ModuleName>`.
- [`custom element`](/next/guide/custom-native-component.md?platform=desktops):
  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:

- [Native Modules](/next/guide/use-native-modules.md?platform=node-api)
- [Custom Element](/next/guide/custom-native-component.md?platform=desktops)
- [AutoLink](/next/guide/autolink.md?platform=lynxtron)

## Loading Model

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

1. The library's C/C++ code registers Lynx capabilities with static registration
   macros such as `LYNX_REGISTER_NATIVE_MODULE(...)` and
   `LYNX_REGISTER_ELEMENT(...)`.
2. 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.
3. 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](/next/guide/autolink.md?platform=lynxtron).

```sh [npm]
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
```

```sh [yarn]
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
```

```sh [pnpm]
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
```

```sh [bun]
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
```

```sh [deno]
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/`:
```text
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](/next/guide/use-native-modules.md?platform=node-api) and
[Custom Element](/next/guide/custom-native-component.md?platform=desktops).
### Build and Publish
Build the current OS/architecture artifact and pack it as the package that a
Lynxtron app can install:
```bash
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](/next/lynxtron/introduction.md). This AutoLink flow
depends on `pluginLynxtron()` in the host Rspack config; the plugin provides
Lynxtron-side AutoLink loading:
```bash
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.
