Integrate with Existing Apps

Use Lynx as a high-performance, cross-platform UI rendering engine you can embed anywhere inside your existing application. This Brownfield approach offers the maximum flexibility, supports all platforms, lets you adopt Lynx incrementally without rewriting your app, and is commonly used for large-scale applications in production.

Integrate Lynx with Existing Apps (iOS)

Lynx for iOS

This article assumes that you are familiar with the basic concepts of native iOS application development.
You can refer to the project: integrating-lynx-demo-projects for all the code mentioned below.

1. Dependency configuration

Using Cocoapods can easily integrate Lynx into your application

Recommended Versions

Cocoapods: >= 1.11.3
Ruby: >= 2.6.10

Configuring Deps

Lynx

The core capabilities of Lynx Engine include basic capabilities such as parsing Bundle, style parsing, layout, and rendering views

Get the latest version of Lynx from Cocoapods. Then add Lynx to your Podfile:

Podfile

source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '4.0.0', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '4.0.0', :subspecs => ['quickjs', 'napi']
end

Lynx Service

Lynx Service includes LynxImageService, LynxLogService, etc. It aims to provide the ability to strongly correlate some host App features, allowing the App to inject custom Services at runtime, or use the default implementation provided by the official. For example, LynxImageService is implemented using the SDWebImage image library by default. Apps that do not integrate SDWebImage components can rely on other image libraries to implement Image Service. Lynx provides standard native Image, Log, and Http service capabilities, which can be quickly accessed and used by the access party;

Get the latest version of Lynx Service from Cocoapods. Then add Lynx Service to your Podfile:

Podfile

source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '4.0.0', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '4.0.0', :subspecs => ['quickjs', 'napi']

  # integrate image-service, log-service, and http-service
  pod 'LynxService', '4.0.0', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService dependencies:
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'
end

More Elements

XElement is an extend native elements library maintained by the Lynx team. It provides richer component capabilities, enabling faster adoption of Lynx in production environments and enhancing the vibrancy of the Lynx ecosystem.

Podfile

source 'https://cdn.cocoapods.org/'

platform :ios, '10.0'

target 'YourTarget' do
  pod 'Lynx', '4.0.0', :subspecs => [
    'Framework',
  ]

  pod 'PrimJS', '4.0.0', :subspecs => ['quickjs', 'napi']

  # integrate image-service, log-service, and http-service
  pod 'LynxService', '4.0.0', :subspecs => [
      'Image',
      'Log',
      'Http',
  ]

  # ImageService
  pod 'SDWebImage','5.15.5'
  pod 'SDWebImageWebPCoder', '0.11.0'

  pod 'XElement', '4.0.0'
end

Install Dependencies

Run pod install to install dependencies, then open your Xcode project. Additionally, make sure to disable the Sandbox Scripting capability.

Note

In order to disable the Sandbox scripting, in Xcode click on your app, then on build settings. Filter for script and set the User Script Sandboxing to NO.

Tip

If you build with Xcode 26.x and the Lynx pod fails because warnings are treated as errors, add a post_install hook to your Podfile to demote the affected warnings:

Podfile

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['GCC_TREAT_WARNINGS_AS_ERRORS'] = 'NO'

      disable = ['-Wno-error', '-Wno-c99-designator',
                 '-Wno-deprecated-declarations', '-Wno-deprecated-implementations']
      ['OTHER_CPLUSPLUSFLAGS', 'OTHER_CFLAGS'].each do |key|
        flags = config.build_settings[key] || ['$(inherited)']
        flags = [flags] unless flags.is_a?(Array)
        config.build_settings[key] = flags + disable
      end
    end
  end
end

2. Lynx Environment Initialization

LynxEnv Initialization

LynxEnv provides a global initialization interface for the Lynx Engine. Please ensure that the initialization of LynxEnv occurs before any interface call of the Lynx Engine. For example, it can be initialized in AppDelegate

Objective-C

Swift

AppDelegate.m

#import <Lynx/LynxEnv.h>
#import <Lynx/LynxView.h>

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [LynxEnv sharedInstance];
  return YES;
}

AppDelegate.swift

import UIKit

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
  var window: UIWindow?

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    LynxEnv.sharedInstance()
    return true
  }
}

3. Render LynxView

LynxView is the basic rendering unit provided by Lynx Engine. LynxView is an implementation inherited from iOS native UIView. You can quickly construct a LynxView and add it to the ViewController.

Create Bundle Loader

Lynx Engine itself does not have the ability to load resources, so it is necessary to initialize LynxEnv, or when constructing LynxView to pass in the specific implementation of the LynxTemplateProvider protocol. Lynx will use the injected resource loader to obtain the Bundle content

You can use various methods to obtain the contents of the Bundle. Here, we choose to embed the contents of the Bundle within the application.

First, please either generate the Bundle file from the Quick Start phase or download the file below to your local machine, and then follow these steps to embed the file:

Note

Bundle Example: https://unpkg.com/@lynx-example/hello-world/dist/main.lynx.bundle

Note

Steps to embed files:

In the target settings of the project, select the target;
Select the Build Phases tab;
In the Copy Bundle Resources section, click the add button (+) to add the file;

Impl Bundle Loader

Objective-C

Swift

DemoLynxProvider.h

#import <Foundation/Foundation.h>
#import <Lynx/LynxTemplateProvider.h>

NS_ASSUME_NONNULL_BEGIN

@interface DemoLynxProvider : NSObject <LynxTemplateProvider>

@end

NS_ASSUME_NONNULL_END

Tip

Use Bridging Header to import the required Lynx header files if you are using a Swift project, since Lynx is a project built with Objective-C.

YourTarget-Bridging-Header.h

#import <Lynx/LynxConfig.h>
#import <Lynx/LynxEnv.h>
#import <Lynx/LynxTemplateProvider.h>
#import <Lynx/LynxView.h>

Objective-C

Swift

DemoLynxProvider.m

#import <Foundation/Foundation.h>

#import "DemoLynxProvider.h"

@implementation DemoLynxProvider

- (void)loadTemplateWithUrl:(NSString*)url onComplete:(LynxTemplateLoadBlock)callback {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:url ofType:@"bundle"];
    if (filePath) {
      NSError *error;
      NSData *data = [NSData dataWithContentsOfFile:filePath options:0 error:&error];
      if (error) {
        NSLog(@"Error reading file: %@", error.localizedDescription);
        callback(nil, error);
      } else {
        callback(data, nil);
      }
    } else {
      NSError *urlError = [NSError errorWithDomain:@"com.lynx"
                                                  code:400
                                                userInfo:@{NSLocalizedDescriptionKey : @"Invalid URL."}];
      callback(nil, urlError);
    }
}

@end

DemoLynxProvider.swift

import Foundation

class DemoLynxProvider: NSObject, LynxTemplateProvider {
  func loadTemplate(withUrl url: String!, onComplete callback: LynxTemplateLoadBlock!) {
    if let filePath = Bundle.main.path(forResource: url, ofType: "bundle") {
      do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        callback(data, nil)
      } catch {
        print("Error reading file: \(error.localizedDescription)")
        callback(nil, error)
      }
    } else {
      let urlError = NSError(domain: "com.lynx", code: 400, userInfo: [NSLocalizedDescriptionKey: "Invalid URL."])
      callback(nil, urlError)
    }
  }
}

Construct Basic LynxView

you may construct a basic LynxView as follows:

Objective-C

Swift

ViewController.m

#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    LynxView *lynxView = [[LynxView alloc] initWithBuilderBlock:^(LynxViewBuilder *builder) {
      builder.config = [[LynxConfig alloc] initWithProvider:[[DemoLynxProvider alloc] init]];
      builder.screenSize = self.view.frame.size;
      builder.fontScale = 1.0;
    }];
    lynxView.preferredLayoutWidth = self.view.frame.size.width;
    lynxView.preferredLayoutHeight = self.view.frame.size.height;
    lynxView.layoutWidthMode = LynxViewSizeModeExact;
    lynxView.layoutHeightMode = LynxViewSizeModeExact;
}
@end

ViewController.swift

import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    let lynxView = LynxView { builder in
      builder.config = LynxConfig(provider: DemoLynxProvider())
      builder.screenSize = self.view.frame.size
      builder.fontScale = 1.0
    }

    lynxView.preferredLayoutWidth = self.view.frame.size.width
    lynxView.preferredLayoutHeight = self.view.frame.size.height
    lynxView.layoutWidthMode = .exact
    lynxView.layoutHeightMode = .exact
  }
}

Add LynxView To The Window:

and then, adding the LynxView to the window.

Objective-C

Swift

ViewController.m

#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [self.view addSubview:lynxView];
}

@end

Render View

After completing the above steps, all the work of initializing LynxView have been completed. Call the lynxView.loadTemplateFromURL method to render the corresponding Bundle onto the LynxView.

Objective-C

Swift

ViewController.m

#import <Lynx/LynxView.h>

#import "ViewController.h"
#import "DemoLynxProvider.h"

@implementation ViewController

- (void)viewDidLoad {
  [super viewDidLoad];

  // ...

  [lynxView loadTemplateFromURL:@"main.lynx" initData:nil];
}

@end

ViewController.swift

import UIKit

class ViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()

    // ...

    lynxView.loadTemplate(fromURL: "main.lynx", initData: nil)
  }
}

Then you will see the following interface on the screen:

Congratulations, you have now completed all the work of integrating Lynx Engine!

4. Now what?

At this stage, you have successfully integrated Lynx into your App. Refer to our developing and debugging docs for in-depth insights on working with Lynx.

Development Tip

During development, you can use Lynx Explorer to quickly preview and iterate on your Lynx pages before integrating them into your native app. Switch to the Try with Explorer approach to set it up.

Next Steps

Integrate Lynx DevTool

Integrate Lynx DevTool to debug Lynx pages

#Integrate with Existing Apps

#Integrate Lynx with Existing Apps (iOS)

#1. Dependency configuration

#Configuring Deps

#Install Dependencies

#2. Lynx Environment Initialization

#LynxEnv Initialization

#3. Render LynxView

#Create Bundle Loader

#Construct Basic LynxView

#Add LynxView To The Window:

#Render View

#4. Now what?

#Integrate Lynx with Existing Apps (Android)

#1. Dependency configuration

#Configuring Gradle

#Configure obfuscation rules (Proguard)

#2. Environment Initialization

#Lynx Service Initialization

#LynxEnv Initialization

#3. Render LynxView

#Create Bundle Loader

#Construct LynxView

#Introduce XElement

#4 Render view

#4. Now what?

#Integrate Lynx with Existing Apps (Harmony)

#1. Dependency Configuration

#Configuring Deps

#Capability Dependencies

#2. Environment Initialization

#Lynx Service Initialization

#LynxEnv Initialization

#3. Rendering LynxView

#Create Bundle Loader

#Construct LynxView and Render the View

#4. Now what?

#Integrate Lynx with Existing Apps (Web)

#1. Development & Debugging

#Add web configuration

#Start development server

#Build & Preview

#2. Integrate with a new web project

#Create a web project

#Configure the project

#Start the project

#3. API Reference

#Integrate Lynx with Existing Apps (Windows)

#1. Dependency configuration

#Download or Build LynxSDK

#Configuring CMake

#2. Environment Initialization - Optional

#Lynx Service Initialization

#LynxEnv Initialization

#3. Render LynxView

#Create Resource Fetcher

#Construct LynxView

#Render view

#4. Now what?

#Integrate Lynx with Existing Apps (macOS)

#1. Dependency configuration

#Download or Build LynxSDK

#Configuring CMake

#2. Environment Initialization - Optional

#Lynx Service Initialization

#LynxEnv Initialization

#3. Render LynxView

#Create Resource Fetcher

#Construct LynxView

#Render view

#4. Now what?

#Next Steps

Integrate with Existing Apps

Integrate Lynx with Existing Apps (iOS)

1. Dependency configuration

Configuring Deps

Install Dependencies

2. Lynx Environment Initialization

LynxEnv Initialization

3. Render LynxView

Create Bundle Loader

Construct Basic LynxView

Add LynxView To The Window:

Render View

4. Now what?

Integrate Lynx with Existing Apps (Android)

1. Dependency configuration

Configuring Gradle

Configure obfuscation rules (Proguard)

2. Environment Initialization

Lynx Service Initialization

LynxEnv Initialization

3. Render LynxView

Create Bundle Loader

Construct LynxView

Introduce XElement

4 Render view

4. Now what?

Integrate Lynx with Existing Apps (Harmony)

1. Dependency Configuration

Configuring Deps

Capability Dependencies

2. Environment Initialization

Lynx Service Initialization

LynxEnv Initialization

3. Rendering LynxView

Create Bundle Loader

Construct LynxView and Render the View

4. Now what?

Integrate Lynx with Existing Apps (Web)

1. Development & Debugging

Add web configuration

Start development server

Build & Preview

2. Integrate with a new web project

Create a web project

Configure the project

Start the project

3. API Reference

Integrate Lynx with Existing Apps (Windows)

1. Dependency configuration

Download or Build LynxSDK

Configuring CMake

2. Environment Initialization - Optional

Lynx Service Initialization

LynxEnv Initialization

3. Render LynxView

Create Resource Fetcher

Construct LynxView

Render view

4. Now what?

Integrate Lynx with Existing Apps (macOS)

1. Dependency configuration

Download or Build LynxSDK

Configuring CMake

2. Environment Initialization - Optional

Lynx Service Initialization

LynxEnv Initialization

3. Render LynxView

Create Resource Fetcher

Construct LynxView

Render view

4. Now what?

Next Steps