@blotch/rsbuild-plugin-angular-lynx 0.0.0-stage → 22.2.1

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @blotch/rsbuild-plugin-angular-lynx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rsbuild plugin that compiles Angular apps for the [Lynx](https://lynxjs.org/) native runtime. Produces dual-thread bundles (main + background) for iOS, Android, and Web.
+
+## Installation
+
+```bash
+npm install @blotch/rsbuild-plugin-angular-lynx
+```
+
+> Starting a new project? `ng add @blotch/angular-lynx` sets this up automatically.
+
+## Usage
+
+Add the plugin to your `lynx.config.ts`:
+
+```typescript
+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
+- Registers `CUSTOM_ELEMENTS_SCHEMA` so Angular accepts Lynx elements (`<view>`, `<text>`, etc.)
+
+## Documentation
+
+Full docs at [angularlynx.dev](https://angularlynx.dev).

package/dist/angular-rebuild-coordinator.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Identifies one on-disk version of a file: its mtime, or `null` when the file
+ * doesn't exist (it was deleted).
+ */
+export type FileVersion = number | null;
+/**
+ * What one Angular compile reports back to the coordinator.
+ */
+export type AngularCompileResult = {
+    /**
+     * Files whose compiled output changed during this compile: re-emitted
+     * TypeScript modules whose JS differs from the cached copy, and any scoped
+     * stylesheets rewritten on disk. rspack must rebuild these even when their
+     * own source didn't change (e.g. a parent component whose template
+     * compilation depends on an edited child component).
+     */
+    changedOutputs: Iterable<string>;
+    /**
+     * Every file the compilation read: program sources plus component
+     * resources such as external templates and stylesheets. Changes to any
+     * other non-TypeScript file (global CSS, assets, the scoped-CSS cache this
+     * plugin writes itself) can't affect Angular's output, so they don't
+     * trigger a recompile.
+     */
+    inputFiles: Iterable<string>;
+};
+export type AngularRebuildCoordinator = {
+    /**
+     * Brings the shared Angular compilation up to date before one environment's
+     * rspack compile.
+     *
+     * @param environmentName - the rsbuild environment about to compile.
+     * @param changedFiles - files the environment's watcher reported as modified
+     *   or removed since its previous compile (empty for its first compile).
+     * @returns files whose compiled output changed since this environment last
+     *   compiled. The caller adds them to the rspack compiler's
+     *   `modifiedFiles` so rspack re-runs the loader for those modules.
+     */
+    prepare: (environmentName: string, changedFiles: Iterable<string>) => Promise<Set<string>>;
+};
+/**
+ * Keeps one Angular compilation in sync with rspack's watch rebuilds.
+ *
+ * Angular compiles the whole program up front and the rspack loader only
+ * serves its cached output. So on every rebuild, Angular has to recompile the
+ * changed files *before* rspack re-runs the loader. Otherwise the loader
+ * serves the previous output and the dev server ships an empty hot update.
+ *
+ * Two things make this more than "recompile on every watchRun":
+ *
+ * - **Several environments share one compilation.** `rspeedy dev` builds `web`
+ *   and `lynx` with separate rspack compilers. Each compiler's watcher reports
+ *   the same edit, and rsbuild runs their before-compile hooks concurrently.
+ *   Compiles are therefore serialized (two concurrent `initialize()` calls on
+ *   one compilation would corrupt it). A file version Angular has already seen
+ *   doesn't trigger a second compile; only versions it hasn't seen do.
+ * - **rspack only rebuilds modules whose files changed.** When an edit changes
+ *   the compiled output of another file, that file's module would keep its
+ *   stale output. So each compile reports which outputs changed, and every
+ *   environment gets back the ones it hasn't rebuilt yet.
+ */
+export declare const createAngularRebuildCoordinator: ({ compile, getFileVersion, }: {
+    /**
+     * Runs one Angular compile. `changedFiles` is `undefined` for the initial
+     * full compile and lists the changed inputs for incremental ones.
+     */
+    compile: (changedFiles: ReadonlySet<string> | undefined) => Promise<AngularCompileResult>;
+    /** Injectable for tests; defaults to the file's mtime. */
+    getFileVersion?: (file: string) => FileVersion;
+}) => AngularRebuildCoordinator;

package/dist/angular-rebuild-coordinator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/angular-webpack-plugin.d.ts

@@ -0,0 +1,127 @@
+import type { Compiler } from '@rspack/core';
+/**
+ * The options for extractStr.
+ *
+ * @public
+ */
+export type ExtractStrConfig = {
+    /**
+     * The minimum length of string literals to be extracted.
+     *
+     * @defaultValue `20`
+     *
+     * @public
+     */
+    strLength: number;
+    /**
+     * @internal
+     */
+    extractedStrArr?: string[];
+};
+/**
+ * The options for AngularWebpackPluginOptions
+ *
+ * @public
+ */
+type AngularWebpackPluginOptions = {
+    /**
+     * Whether to disable warnings about incompatible createSelectorQuery usage
+     */
+    disableCreateSelectorQueryIncompatibleWarning?: boolean | undefined;
+    /**
+     * When to sync the first screen content
+     */
+    firstScreenSyncTiming?: 'immediately' | 'jsReady';
+    /**
+     * Whether to enable server-side rendering
+     */
+    enableSSR?: boolean;
+    /**
+     * Whether this bundle targets the web runtime (`@lynx-js/web-core`) rather
+     * than native Lynx. Injected into the bundle as the `__WEB__` compile-time
+     * define so the runtime can branch on web-only behavior (e.g. forcing the
+     * first element-tree flush, which native does implicitly but web-core does
+     * not). Set from `environment.name === 'web'` in entry.ts.
+     */
+    isWeb?: boolean;
+    /**
+     * The chunk names to be considered as main thread chunks.
+     */
+    mainThreadChunks?: string[] | undefined;
+    /**
+     * Merge same string literals in JS and Lepus to reduce output bundle size.
+     * Set to `false` to disable.
+     *
+     * @defaultValue false
+     */
+    extractStr?: Partial<ExtractStrConfig> | boolean;
+    /**
+     * Whether to enable lazy bundle.
+     *
+     * @alpha
+     */
+    experimental_isLazyBundle?: boolean;
+};
+/**
+ * AngularWebpackPlugin allows using Angular with Lynx and webpack
+ *
+ * @example
+ * ```js
+ * // webpack.config.js
+ * import { AngularWebpackPlugin } from '@lynx-js/angular-webpack-plugin'
+ * export default {
+ *   plugins: [new AngularWebpackPlugin()],
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class AngularWebpackPlugin {
+    #private;
+    /**
+     * The loaders for Angular with Lynx.
+     *
+     * @remarks
+     * Note that this loader will only transform TypeScript to valid JavaScript.
+     * You should use `swc-loader` to load TypeScript files.
+     *
+     * @example
+     * ```js
+     * // webpack.config.js
+     * import { AngularWebpackPlugin, LAYERS } from '@lynx-js/angular-webpack-plugin'
+     * export default {
+     *   module: {
+     *     rules: [
+     *       {
+     *         test: /\.ts$/,
+     *         layer: LAYERS.MAIN_THREAD,
+     *         use: ['swc-loader', AngularWebpackPlugin.loaders.MAIN_THREAD]
+     *       },
+     *       {
+     *         test: /\.ts$/,
+     *         layer: LAYERS.BACKGROUND,
+     *         use: ['swc-loader', AngularWebpackPlugin.loaders.BACKGROUND]
+     *       },
+     *     ],
+     *   },
+     *   plugins: [new AngularWebpackPlugin()],
+     * }
+     * ```
+     *
+     * @public
+     */ options: AngularWebpackPluginOptions | undefined;
+    constructor(options?: AngularWebpackPluginOptions | undefined);
+    /**
+     * `defaultOptions` is the default options that the {@link AngularWebpackPlugin} uses.
+     *
+     * @public
+     */
+    static defaultOptions: Readonly<Required<AngularWebpackPluginOptions>>;
+    /**
+     * The entry point of a webpack plugin.
+     * @param compiler - the webpack compiler
+     */
+    apply(compiler: Compiler): void;
+}
+export type { AngularWebpackPluginOptions };
+export { AngularWebpackPlugin };

package/dist/angular-webpack-plugin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/angular.d.ts

@@ -0,0 +1,31 @@
+import type { RsbuildPluginAPI } from '@lynx-js/rspeedy';
+import type { PluginAngularLynxOptions } from './utils/options.js';
+/**
+ * Wires Angular's AOT/JIT compilation pipeline into the rsbuild/rspack build
+ * graph. This is the heart of the AngularLynx build — it bridges three worlds:
+ *
+ *   1. **Angular's compiler** (`@angular/build`) — runs `createAngularCompilation`
+ *      to type-check templates, transform component metadata, and emit JS+CSS.
+ *   2. **Lynx's native element model** — Angular's template type-checker has
+ *      no knowledge of `<view>`, `<text>`, `<scroll-view>`, etc., so we inject
+ *      CUSTOM_ELEMENTS_SCHEMA into every @Component-bearing source file before
+ *      Angular's compiler sees it (see build-schema-source-file-cache.ts).
+ *   3. **rspack's loader pipeline** — Angular emits transformed output into a
+ *      `typeScriptFileCache`; the `api.transform()` hook below intercepts every
+ *      `.ts`/`.js` request and serves the precompiled content instead of
+ *      letting rspack try to parse the original TypeScript.
+ *
+ * The flow runs before every environment build, including watch rebuilds:
+ *   onBeforeEnvironmentCompile → angular-rebuild-coordinator (dedupe + serialize)
+ *     → buildLynxSchemaSourceFileCache (schema inject)
+ *     → compilation.update (rebuilds only: invalidate the changed files)
+ *     → compilation.initialize (Angular AOT walk + transformStylesheet callback)
+ *     → emitAffectedFiles (refreshes typeScriptFileCache)
+ *     → diagnoseFiles (filtered to suppress Lynx-element false positives)
+ *     → rspack rebuilds the changed files plus any whose compiled output changed
+ *
+ * Then for each module request the `api.transform` hook delegates the per-module
+ * string transform (import-prepend + ɵcmp.id + worklet) to
+ * `buildTransformedCode` in transform-module.ts.
+ */
+export declare const applyAngularRules: (api: RsbuildPluginAPI, pluginOptions: Required<PluginAngularLynxOptions>) => Promise<void>;

package/dist/build-schema-source-file-cache.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reads the tsconfig to enumerate all project TypeScript files, then returns a
+ * Map<filePath, SourceFile> where every file containing an @Component decorator
+ * has had CUSTOM_ELEMENTS_SCHEMA injected. Angular's compiler host checks this
+ * cache before reading from disk, so the template type-checker never sees unknown
+ * Lynx element errors without the user having to add the schema manually.
+ *
+ * Returns Map<string, any> to avoid TypeScript instance mismatch: the plugin's
+ * local `typescript` package and `@angular/build`'s TypeScript resolve to different
+ * module instances in the monorepo, making their SourceFile types structurally
+ * incompatible at the type level even though they're identical at runtime.
+ *
+ * `shouldInclude` limits which files are read and parsed; `fileNames` still lists
+ * every project file. Watch rebuilds pass it so only changed and new files are
+ * re-parsed, instead of every component in the project on each save.
+ */
+export declare const buildLynxSchemaSourceFileCache: (tsconfig: string, shouldInclude?: (filePath: string) => boolean) => {
+    sourceFileCache: Map<string, any>;
+    fileNames: string[];
+};

package/dist/build-schema-source-file-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/component-styles-cache.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-component stylesheet bookkeeping. `imports` lists the on-disk scoped CSS
+ * paths the loader will prepend as `import` statements; `inlineStyles` mirrors
+ * Angular's inline-style handling surface; `processedFiles` deduplicates calls
+ * that Angular's AOT compiler makes multiple times for the same stylesheet.
+ */
+export type ComponentStylesEntry = {
+    imports: string[];
+    inlineStyles: string[];
+    scopeId: string;
+    processedFiles: Map<string, string>;
+};
+export type ComponentScopeInfo = {
+    className: string;
+    scopeId: string;
+};
+/**
+ * Builds the `transformStylesheet` callback that Angular's AOT compiler invokes
+ * for every component stylesheet (inline `styles: []` and external `styleUrls`).
+ *
+ * The callback is a closure over the two shared caches the loader
+ * (`api.transform` in angular.ts) later reads from:
+ *   - `componentStylesCache` — maps component source file → its scoped CSS imports
+ *   - `componentScopeIds` — maps component source file → { className, scopeId }
+ *
+ * Extracted from angular.ts so the dedup / scoped-path / write-if-changed logic
+ * can be unit-tested directly by driving the returned callback, without standing
+ * up a full Angular compilation.
+ */
+export declare const createTransformStylesheet: (params: {
+    basePath: string;
+    scopedCssCacheDir: string;
+    componentStylesCache: Map<string, ComponentStylesEntry>;
+    componentScopeIds: Map<string, ComponentScopeInfo>;
+    /**
+     * Called with the path of each scoped CSS file whose contents were
+     * (re)written. On watch rebuilds the scoped files change after rspack's
+     * watcher has already collected the edit, so angular.ts passes them to
+     * rspack as modified. Otherwise the CSS change would only ship on the
+     * following rebuild.
+     */
+    onStylesheetWritten?: (filePath: string) => void;
+}) => ((data: string, containingFile: string, stylesheetFile: string | undefined, order: number, className: string | undefined) => Promise<string>);

package/dist/component-styles-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/css.d.ts

@@ -0,0 +1,13 @@
+import type { RsbuildPluginAPI } from '@lynx-js/rspeedy';
+import type { CSSLoaderOptions } from '@rsbuild/core';
+import type { PluginAngularLynxOptions } from './utils/options.js';
+export declare const applyCSS: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+/**
+ * This is copied from https://github.com/web-infra-dev/rsbuild/blob/9f8be2d71ffeb7da969cda36fd9755db2cadaff5/packages/core/src/plugins/css.ts#L42
+ *
+ * If the target is not `web` and the modules option of css-loader is enabled,
+ * we must enable exportOnlyLocals to only exports the modules identifier mappings.
+ * Otherwise, the compiled CSS code may contain invalid code, such as `new URL`.
+ * https://github.com/webpack-contrib/css-loader#exportonlylocals
+ */
+export declare const normalizeCssLoaderOptions: (options: CSSLoaderOptions, exportOnlyLocals: boolean) => CSSLoaderOptions;

package/dist/css.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entry.d.ts

@@ -0,0 +1,11 @@
+import type { RsbuildPluginAPI, Rspack } from '@lynx-js/rspeedy';
+import type { UndefinedOnPartialDeep } from 'type-fest';
+import type { PluginAngularLynxOptions } from './utils/options.js';
+export declare const applyEntry: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+/**
+ * This is copied from https://github.com/web-infra-dev/rsbuild/blob/037da7b9d92e20c7136c8b2efa21eef539fa2f88/packages/core/src/plugins/html.ts#L168
+ */
+export declare const getChunks: (entryName: string, entryValue: (string | string[] | UndefinedOnPartialDeep<Rspack.EntryDescription>)[]) => {
+    chunks: string[];
+    imports: string[];
+};

package/dist/entry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generator.d.ts

@@ -0,0 +1,2 @@
+import type { RsbuildPluginAPI } from '@lynx-js/rspeedy';
+export declare const applyGenerator: (api: RsbuildPluginAPI) => void;

package/dist/generator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { pluginAngularLynx } from './plugin-angular-lynx';