@blotch/rsbuild-plugin-angular-lynx

Rsbuild plugin that compiles Angular apps for the Lynx native runtime. Produces dual-thread bundles (main + background) for iOS, Android, and Web.

Installation

Using the Angular CLI? You don't need this package directly. ng add @blotch/angular-lynx installs @blotch/angular-lynx-build, whose ng build and ng serve builders depend on this plugin and add it to rspeedy's config. To pass it options, import it from there: import { pluginAngularLynx } from '@blotch/angular-lynx-build'.

To run rspeedy directly:

npm install @blotch/rsbuild-plugin-angular-lynx

Usage

Add the plugin to your lynx.config.ts:

import { pluginAngularLynx } from '@blotch/rsbuild-plugin-angular-lynx';
import { defineConfig } from '@lynx-js/rspeedy';

export default defineConfig({
  source: {
    entry: './src/main.ts',
  },
  plugins: [pluginAngularLynx()],
});

What It Does

• Runs Angular's AOT compiler within Rsbuild/webpack
• Splits each entry into main-thread and background-thread bundles for Lynx's dual-thread model
• Bundles component stylesheets and processes CSS
• Runs Tailwind CSS 3 from a tailwind.config.*, and rewrites the CSS Tailwind CSS 4 writes (layers, @property, nesting, oklch() and color-mix(), logical properties, translate/rotate/scale) into CSS Lynx reads, for the device and the web preview alike. See Tailwind CSS
• Registers CUSTOM_ELEMENTS_SCHEMA so Angular accepts Lynx elements (<view>, <text>, etc.)
• Enforces the build target's budgets with ng build's units and messages: a warning is printed, an error fails the build
• Applies the build target's fileReplacements, as Angular's builders do: both threads' bundles are built from each with file instead of its replace file, and a watch build rebuilds when it changes
• Adds the Intl APIs the intl option lists, which Lynx lacks, to the Lynx bundle (see Intl)

Budgets

Budgets in angular.json are checked against the lynx environment, the bundles devices load. The web preview isn't checked. A Lynx app ships .bundle files rather than separate scripts and stylesheets, so each budget type measures:

Media and fonts aren't counted. Under plain rspeedy dev budgets are skipped: the plugin then reads angular.json's default configuration, usually production, whose budgets don't fit a development build. ng serve checks them when the configuration it serves has them, as Angular's dev server does.

Intl

Lynx has no Intl on the main thread, where Angular runs, nor on the background thread except where it runs on JavaScriptCore. The intl build option in angular.json, or pluginAngularLynx({ intl }) when the build target isn't AngularLynx's, adds the APIs it lists to the Lynx bundle, on both threads, before the app's code:

"intl": ["DisplayNames", "NumberFormat", "Collator"]

• DateTimeFormat, DisplayNames, ListFormat, NumberFormat, PluralRules and RelativeTimeFormat are FormatJS's polyfills, which the app installs (@formatjs/intl-*, with @formatjs/intl-getcanonicallocales and @formatjs/intl-locale; the build names the missing ones). They're optional peer dependencies here, because each package holds every locale's data.
• The build adds the data of angular.json's i18n.sourceLocale and i18n.locales, and the APIs each one calls (NumberFormat needs PluralRules; DateTimeFormat and RelativeTimeFormat need NumberFormat).
• Collator is the plugin's own, with localeCompare(): FormatJS has none. The build takes each locale's order of letters from Node's ICU (src/intl/collation-data.ts).
• With no locale, they use the phone's language (appLocale) when the app has its data, and dates are in the phone's time zone, named by appTimeZone.
• The web bundle gets none of it: the browser has Intl.

See Internationalization for what's approximate and what it adds to the bundle.

Documentation

Full docs at angularlynx.js.org.