#Compatibility

This article explains how to ensure version compatibility between Bundle and Lynx Engine, and how to handle challenges that come with Lynx Engine version evolution.

#Build from Source

A simple way to ensure compatibility is to always build the Bundle with the Host application from source.

• Bundle can fully utilize all features of the current Lynx Engine version
• Compatibility can be fully verified during development, what you see is what you get

#Multi-version Compatibility

However, in a complex project, the relationship between Bundle and Lynx Engine is not one-to-one:

• A Bundle might run in applications with different Lynx Engine versions

• An application can run multiple Bundles maintained by different teams

In this case, you need to set the engineVersion to ensure compatibility.

For example: a Bundle with engineVersion 3.3 can run on Lynx Engine 3.3 and later versions, but cannot run on 3.2.

When a Bundle needs to run on multiple Lynx Engine versions, its engineVersion must be lower than all Lynx Engine versions.

When running multiple Bundles on a single Lynx Engine version, each Bundle can set different engineVersions, but none can be greater than the Lynx Engine version.

#Version Incompatibility Handling

If you try to run a Bundle on a lower version of the Lynx Engine, a Fatal level error with code 10204 will occur, and the rendering process will stop. This mechanism prevents potential runtime issues caused by version incompatibility.

#Configuring Engine Version

The engineVersion is a string containing two version numbers, and you can specify it in your configuration file:

import { defineConfig } from '@lynx-js/rspeedy';
import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReactLynx({
      engineVersion: '3.2',
    }),
  ],
});

#Upgrading Lynx Engine

As Lynx Engine evolves, new features are added and some features may be deprecated. Their compatibility is also managed by engineVersion.

#New Features

Some new features will not affect existing Bundles, but if engineVersion is lower than the version where they were introduced, runtime detection is needed, for example:

// Detect if `lynx.newlyAddedMethod` can be called
if (lynx.newlyAddedMethod) {
  lynx.newlyAddedMethod();
}

While some new features cannot run on lower versions of the Lynx Engine at all, so they will only be enabled when engineVersion is greater than or equal to the corresponding version.

#Deprecated Features

Some features may be deprecated during iteration, and their behavior may change when a higher engineVersion is set.

• If only the Lynx Engine version is upgraded without upgrading the Bundle's engineVersion, there will be no compatibility issues
• If both Lynx Engine and Bundle's engineVersion are upgraded, you need to read the CHANGELOG to ensure there are no unexpected behavior changes

#Compatibility Table

Lynx provides compatibility tables for each API, built-in component, and CSS property. Here's an example for the gap property:

LCD tables only load in the browser