#Using webview in Lynxtron

<webview> is the Lynx element for embedding Web content. Its attributes, events, and methods are defined by the Lynx element API. This page only explains how to introduce this capability in Lynxtron through the officially maintained npm package.

Because CEF and WebView artifacts can significantly increase package size, Lynxtron does not bundle <webview> into the runtime by default. Instead, it is provided as an officially maintained Lynx native library. Other official Lynx elements remain built in and can be used normally.

The officially maintained @lynx-js/cef-webview package provides a native view capability based on the Chromium Embedded Framework (CEF). You can consume it like other Lynx native libraries: install the package, load its Lynxtron package entry in the host process, initialize CEF in the main process, and then use the <webview> Lynx element.

The native <webview> element is registered by the package C++ library through LYNX_REGISTER_ELEMENT(...). Application code only needs to make sure the library is loaded and call initialize(); it should not call lower-level Lynx registration APIs.

#Install the npm Package

npm install @lynx-js/cef-webview

yarn add @lynx-js/cef-webview

pnpm add @lynx-js/cef-webview

bun add @lynx-js/cef-webview

deno add npm:@lynx-js/cef-webview

#Enable AutoLink

AutoLink automatically discovers and loads native libraries from project dependencies. Lynxtron's build plugin, pluginLynxtron(), includes AutoLink by default and is already configured by create-lynxtron.

For a manually configured project, use the following Rspack example. In Rsbuild, place the plugin in the desktop environment's tools.rspack.plugins:

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

#Initialize CEF in the Main Process

Initialize CEF before using webview: call cefWebview.initialize() after app.whenReady() and before creating a LynxWindow or loading a Lynx bundle.

CEF selects its storage directory based on the host application's identity. Multiple instances sharing the same identity may encounter storage conflicts. initialize() throws on failure; do not ignore the error and continue creating WebViews. See initialization details.

import { app, LynxWindow } from '@lynx-js/lynxtron';
import cefWebview from '@lynx-js/cef-webview/lynxtron';

app.whenReady().then(() => {
  cefWebview.initialize();

  const win = new LynxWindow({
    width: 1200,
    height: 800,
  });

  win.show();
  // Keep the scaffold's dev loadURL / production loadFile logic here.
});

Merge this initialization into src/main/desktop/main.ts; retain the scaffold's bundle paths and environment-dependent loading code rather than replacing them with a hard-coded path.

#Use the Lynx Element

After the native library is loaded and CEF is initialized in the main process, you can use the <webview> Lynx element.

export function App() {
  return (
    <view style={{ width: '100%', height: '100%' }}>
      <webview
        src="https://www.example.com"
        style={{ width: '100%', height: '100%' }}
      />
    </view>
  );
}

For the attributes, events, and methods supported by <webview>, see the <webview> API.

#Packaging Notes

Keep pluginLynxtron() enabled for the packaged host build and point electron-builder's directories.app at the host build's output.path. With the project's standard build and packaging commands, lynxtron-builder keeps native packages outside ASAR, places the macOS CEF Framework and Helper apps in Contents/Frameworks, and preserves the package-relative layout of the Windows addon, DLLs, and resources. No CEF-specific copy script or per-library packaging rules are needed in the app.