@blotch/angular-lynx-build 0.0.0-stage → 22.2.3

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @blotch/angular-lynx-build
 
-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.
+The Angular CLI builders for [AngularLynx](https://github.com/Blotch-Smart-Frames/AngularLynx): `ng build`, `ng serve`, `ng test` and `ng extract-i18n` for Lynx, and `ng build --platform ios|android|all` for native apps.
+
+```bash
+ng add @blotch/angular-lynx   # installs this package and sets up angular.json
+```
+
+It is the only build dependency an AngularLynx app needs, as `@angular/build` is for a web app: it brings rspeedy, the rsbuild plugin that compiles Angular, the QR code plugin and the native app builder with it.
+
+## Builders
+
+```jsonc
+// angular.json, as `ng add` writes it
+"build": {
+  "builder": "@blotch/angular-lynx-build:application",
+  "options": { "browser": "src/main.ts", "tsConfig": "tsconfig.app.json" /* ... */ },
+  "configurations": {
+    "production": { "budgets": [/* ... */], "outputHashing": "all" },
+    "development": { "optimization": false, "extractLicenses": false, "sourceMap": true }
+  },
+  "defaultConfiguration": "production"
+},
+"serve": {
+  "builder": "@blotch/angular-lynx-build:dev-server",
+  "configurations": {
+    "production": { "buildTarget": "my-app:build:production" },
+    "development": { "buildTarget": "my-app:build:development" }
+  },
+  "defaultConfiguration": "development"
+},
+"test": {
+  "builder": "@blotch/angular-lynx-build:unit-test"
+},
+"extract-i18n": {
+  "builder": "@blotch/angular-lynx-build:extract-i18n"
+}
+```
+
+| Builder        | Command                   | What it does                                                                                                 |
+| -------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `application`  | `ng build`                | Builds the Lynx bundle (and the web preview bundle) into `dist/` with [rspeedy](https://lynxjs.org/rspeedy/) |
+|                | `ng build --watch`        | Rebuilds the bundle whenever a file changes                                                                  |
+|                | `ng build --platform ios` | Then builds the iOS app (`--platform android` or `all` for the others) into `dist/<platform>/`               |
+| `dev-server`   | `ng serve`                | Runs rspeedy's dev server for Lynx Explorer and the web preview, and prints the QR code Lynx Explorer scans  |
+| `unit-test`    | `ng test`                 | Runs the unit tests with Angular's own unit-test builder (Vitest), set up for Lynx                           |
+| `extract-i18n` | `ng extract-i18n`         | Extracts the i18n messages with Angular's own extract-i18n builder, set up for Lynx                          |
+
+They behave like Angular's own builders:
+
+- **Configurations and overrides apply.** The build target's options reach the compiler as Angular CLI resolved them, so `ng build -c development` and flags like `--optimization=false` work.
+- **`optimization` decides between a production and a development build.** There is no `mode` option: as in Angular, a build that optimizes scripts is a production build, and one that doesn't is a development build with dev mode on. `ng build -c development` is a development build, and `ng serve -c production` serves a production one.
+- **`ng serve` builds its `buildTarget`**, by default the build target's `development` configuration. `--port` / `--host` override `server` in lynx.config.ts.
+- **Budgets are enforced.** The `budgets` in the build target are checked against the Lynx bundle and the component stylesheets, with Angular's messages; `ng add` sizes the `initial` budget for a Lynx bundle. See the plugin's [README](../rsbuild-plugin-angular-lynx/README.md#budgets).
+- **`--watch` rebuilds only the bundle.** It can't be combined with `--platform`: use `ng serve` while developing, and `ng build --platform` for the app.
+
+The options are in [`builders/application/schema.json`](builders/application/schema.json), [`builders/dev-server/schema.json`](builders/dev-server/schema.json), [`builders/unit-test/schema.json`](builders/unit-test/schema.json) and [`builders/extract-i18n/schema.json`](builders/extract-i18n/schema.json).
+
+## ng test
+
+The `unit-test` builder is Angular's `@angular/build:unit-test`, set up for Lynx. Its options are Angular's (`include`, `watch`, `coverage`, `setupFiles`, `providersFile`, ...): its schema is a copy of Angular's, and a test keeps the two in step. It finds `*.spec.ts` and `*.test.ts` files, and the tests compile ahead of time, like the app. On top of Angular's setup it:
+
+- defines the compile-time flags the AngularLynx runtime reads (`__DEV__`, `__MAIN_THREAD__`, ...), through a polyfill (`@blotch/angular-lynx-build/unit-test/lynx-globals`) that loads before anything else;
+- loads `@blotch/angular-lynx-testing-library`'s setup when the project has the library, so its `render()` works with no setup file or Vitest config in the app;
+- hands Angular the build target as an Angular one, with only the options both builders share, so Angular neither warns about an unknown builder nor rejects the Lynx-only options;
+- loads imported images, fonts and media as file URLs, as rspeedy does in the app.
+
+Two things work as in any Angular app, and differ from a plain Vitest setup:
+
+- **Templates are checked strictly.** A component that uses Lynx elements imports `LYNX_ELEMENTS`, as the Angular Language Service already requires (generated components do). The app build is laxer: it adds `CUSTOM_ELEMENTS_SCHEMA` to every component, which Angular's test build has no hook for.
+- **Test code is type-checked**, and test files share one module graph (Angular's runner isn't isolated by default). `vi.mock` of a relative import isn't supported, and mocking `@angular/core` would leak into other test files.
+
+## ng extract-i18n
+
+The `extract-i18n` builder is Angular's `@angular/build:extract-i18n`, set up for Lynx. Its options are Angular's (`format`, `outputPath`, `outFile`, ...), and, as for `ng test`, its schema is a copy of Angular's that a test keeps in step. Angular CLI picks an extractor by itself only for a project built with one of Angular's builders, so an AngularLynx app needs the target: `ng add` writes it, and `add-i18n` makes it write JSON to `src/locale`, which `loadTranslations()` takes.
+
+Angular's extractor compiles the app with Angular's application builder. As in `ng test`, it gets the build target as an Angular one, and imported images, fonts and media load as file URLs: without a loader for them, Angular's build stops at the first imported image. Without `@angular/localize`, it says to run `add-i18n` rather than Angular's `ng add @angular/localize`, which only sets up Angular's own builders.
+
+## lynx.config.ts
+
+An app doesn't need one. Without it, `ng build` and `ng serve` take what rspeedy needs from angular.json and the defaults an AngularLynx app wants:
+
+- `source.entry` is the build target's `browser` option;
+- the environments are `lynx` (the native bundle) and `web` (the browser preview);
+- `ng serve` adds the QR code plugin, in full screen.
+
+Add a lynx.config.ts to change any of these or set anything else rspeedy supports; each default only applies where it doesn't set its own. The builders add [`@blotch/rsbuild-plugin-angular-lynx`](../rsbuild-plugin-angular-lynx), which compiles Angular, either way. List the plugin yourself only to pass it options. Import it and `defineConfig` from this package, which depends on both:
+
+```ts
+import { defineConfig, pluginAngularLynx } from '@blotch/angular-lynx-build';
+
+export default defineConfig({
+  plugins: [pluginAngularLynx({ enableSSR: true })],
+});
+```
+
+For the types of what the bundler handles (asset and CSS module imports, `import.meta.env`), reference them from here too, as `ng add` does in `src/rspeedy-env.d.ts`:
+
+```ts
+/// <reference types="@blotch/angular-lynx-build/client" />
+```
+
+## How it's put together
+
+This package is the Angular CLI layer. The work happens in its dependencies:
+
+- **[`@blotch/rsbuild-plugin-angular-lynx`](../rsbuild-plugin-angular-lynx)** compiles Angular inside rspeedy. It also works on its own, for projects that run rspeedy directly.
+- **[`@blotch/angular-lynx-native`](../native)** turns the Lynx bundle into iOS and Android apps.
+- **[rspeedy](https://lynxjs.org/rspeedy/)** and its QR code plugin. The builders always run the versions they were released and tested with, so an app doesn't install them.
+
+`ng test` and `ng extract-i18n` run Angular's builders from the project's own `@angular/build`, which `ng new` installs: it must match the project's Angular version.

package/builders/angular-build.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asAngularBuildTargets = exports.ASSET_LOADERS = exports.ANGULAR_BUILD_OPTIONS = exports.importAngularBuild = void 0;
+const project_import_1 = require("./project-import");
+/**
+ * @angular/build comes from the project, like Angular's own builders: its
+ * version must match the project's Angular version, which `ng new` installs
+ * it for.
+ */
+const importAngularBuild = (projectRoot) => (0, project_import_1.importFromProject)('@angular/build', projectRoot, 'Run `npm install --save-dev @angular/build` (`ng new` adds it).');
+exports.importAngularBuild = importAngularBuild;
+const LYNX_APPLICATION_BUILDER = '@blotch/angular-lynx-build:application';
+const ANGULAR_APPLICATION_BUILDER = '@angular/build:application';
+/**
+ * The options of the Lynx application builder that are Angular's application
+ * builder's too, and mean the same. The rest (native app settings, rspeedy's
+ * `config` and `environment`) are Lynx-only; Angular's schema rejects them.
+ */
+exports.ANGULAR_BUILD_OPTIONS = [
+    'browser',
+    'tsConfig',
+    'polyfills',
+    'styles',
+    'assets',
+    'scripts',
+    'inlineStyleLanguage',
+    'fileReplacements',
+    'aot',
+    'optimization',
+    'sourceMap',
+    'outputHashing',
+    'i18nMissingTranslation',
+    'budgets',
+    'extractLicenses',
+    'outputPath',
+    'index',
+    'watch',
+];
+/**
+ * How Angular's build loads imported assets (`import logo from
+ * './logo.png'`): as files, so the import is the file's URL, as rspeedy
+ * makes it in the app. Angular's build has no loader for them by default and
+ * fails on the import.
+ */
+exports.ASSET_LOADERS = Object.fromEntries([
+    // Images
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'avif',
+    'bmp',
+    'ico',
+    'svg',
+    // Fonts
+    'woff',
+    'woff2',
+    'ttf',
+    'otf',
+    'eot',
+    // Audio and video
+    'mp4',
+    'webm',
+    'mov',
+    'mp3',
+    'wav',
+    'ogg',
+    'm4a',
+    'aac',
+].map((extension) => [`.${extension}`, 'file']));
+/**
+ * The builder context Angular's unit-test and extract-i18n builders get.
+ * Both compile the app with Angular's application builder, taking its
+ * options (tsconfig, polyfills, styles, file replacements) from the build
+ * target, and only know Angular's own application builder: for any other the
+ * unit-test builder warns that "unexpected behavior or build failures may
+ * occur", and both validate the options against that builder's schema. A
+ * Lynx build target therefore reaches them as an Angular one, with the
+ * options both builders share, which Angular's schema validates and
+ * completes with its defaults, the asset loaders rspeedy's defaults
+ * correspond to, and `lynxPolyfills` after the app's own polyfills.
+ */
+const asAngularBuildTargets = (context, lynxPolyfills = []) => {
+    const isLynxApplication = async (target) => (await context.getBuilderNameForTarget(target)) ===
+        LYNX_APPLICATION_BUILDER;
+    const overrides = {
+        getBuilderNameForTarget: async (target) => (await isLynxApplication(target))
+            ? ANGULAR_APPLICATION_BUILDER
+            : context.getBuilderNameForTarget(target),
+        getTargetOptions: async (target) => {
+            const options = await context.getTargetOptions(target);
+            if (!(await isLynxApplication(target))) {
+                return options;
+            }
+            const polyfills = options['polyfills'];
+            return {
+                ...Object.fromEntries(Object.entries(options).filter(([key]) => exports.ANGULAR_BUILD_OPTIONS.includes(key))),
+                loader: exports.ASSET_LOADERS,
+                polyfills: [
+                    ...(Array.isArray(polyfills)
+                        ? polyfills
+                        : typeof polyfills === 'string'
+                            ? [polyfills]
+                            : []),
+                    ...lynxPolyfills,
+                ],
+            };
+        },
+    };
+    return new Proxy(context, {
+        get: (target, property) => property in overrides
+            ? overrides[property]
+            : Reflect.get(target, property),
+    });
+};
+exports.asAngularBuildTargets = asAngularBuildTargets;

package/builders/application/index.js

@@ -0,0 +1,165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runApplication = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const rspeedy_1 = require("../rspeedy");
+const native_cache_1 = require("./native-cache");
+/**
+ * Like the rsbuild plugin, the native builder is this package's own
+ * dependency, resolved from here. Imported only for `--platform`, so a plain
+ * bundle build never loads it.
+ */
+const importNative = () => import('@blotch/angular-lynx-native');
+const defaultDeps = {
+    importRspeedy: rspeedy_1.importRspeedy,
+    importPlugin: rspeedy_1.importPlugin,
+    importNative,
+};
+const errorOutput = (error) => ({
+    success: false,
+    error: error instanceof Error ? error.message : String(error),
+});
+/**
+ * `ng build`: builds the Lynx bundle with rspeedy, as `rspeedy build` would,
+ * then, with `--platform`, the native binaries. The Angular compile happens
+ * inside rspeedy (through @blotch/rsbuild-plugin-angular-lynx, which
+ * `createRspeedy` adds when lynx.config.ts doesn't), so this builder only
+ * orchestrates.
+ *
+ * With `--watch` it reports a result after every rebuild and keeps running
+ * until Angular CLI tears it down, as Angular's own application builder does.
+ */
+const runApplication = async function* (options, context, deps = defaultDeps) {
+    const projectName = context.target?.project;
+    if (!projectName) {
+        yield { success: false, error: 'The builder needs a project target.' };
+        return;
+    }
+    const metadata = await context.getProjectMetadata(projectName);
+    const projectRoot = node_path_1.default.join(context.workspaceRoot, metadata['root'] ?? '');
+    const platforms = options.platform === 'all'
+        ? ['ios', 'android']
+        : options.platform
+            ? [options.platform]
+            : [];
+    if (options.watch && platforms.length > 0) {
+        // A native app is built once from a finished bundle; rebuilding the
+        // Xcode or Gradle project on every save would take minutes each time.
+        yield {
+            success: false,
+            error: "--watch rebuilds only the Lynx bundle and can't be combined with --platform. Use `ng serve` while developing, and `ng build --platform` for the app.",
+        };
+        return;
+    }
+    let rspeedy;
+    let native;
+    let workDir = '';
+    try {
+        // Load the native builder first, so a broken install fails before a
+        // minute of bundling rather than after it.
+        if (platforms.length > 0) {
+            native = await deps.importNative();
+            workDir = (0, native_cache_1.nativeCacheDir)({
+                metadata,
+                workspaceRoot: context.workspaceRoot,
+                projectRoot,
+                projectName,
+            });
+        }
+        rspeedy = await (0, rspeedy_1.createRspeedy)({
+            rspeedy: await deps.importRspeedy(),
+            plugin: await deps.importPlugin(),
+            projectRoot,
+            // Angular CLI already merged these: base options, the configurations
+            // chosen with -c (or the default one), then command-line overrides.
+            angularCli: {
+                workspaceRoot: context.workspaceRoot,
+                project: projectName,
+                buildOptions: options,
+            },
+            config: options.config,
+            // Native shells only load the Lynx bundle; skipping the web
+            // environment halves the bundling time.
+            environment: platforms.length > 0 ? ['lynx'] : options.environment,
+        });
+    }
+    catch (error) {
+        yield errorOutput(error);
+        return;
+    }
+    if (options.watch) {
+        yield* watchBundle(rspeedy, context);
+        return;
+    }
+    try {
+        context.reportStatus('Building the Lynx bundle');
+        const { close } = await rspeedy.build();
+        await close();
+        const bundleDir = rspeedy.context.distPath;
+        for (const platform of platforms) {
+            context.reportStatus(`Building the ${platform} app`);
+            const { artifacts } = await native.buildNativeApp({
+                platform,
+                projectRoot,
+                workDir,
+                projectName,
+                packageVersion: readPackageVersion(projectRoot),
+                bundleDir,
+                outputDir: node_path_1.default.join(bundleDir, platform),
+                app: options,
+                log: (message) => context.logger.info(message),
+            });
+            for (const artifact of artifacts) {
+                context.logger.info(`  ✓ ${node_path_1.default.relative(context.workspaceRoot, artifact)}`);
+            }
+        }
+        yield { success: true };
+    }
+    catch (error) {
+        yield errorOutput(error);
+    }
+};
+exports.runApplication = runApplication;
+/**
+ * `ng build --watch`: rspeedy's watch build, reporting each compile's result.
+ * Compile errors fail that result but keep watching, as in Angular, so the
+ * next save can fix them. Angular CLI ends the run (Ctrl+C) through the
+ * teardown, which stops the watcher.
+ */
+const watchBundle = async function* (rspeedy, context) {
+    const results = [];
+    let wake;
+    rspeedy.onAfterBuild(({ stats }) => {
+        results.push({ success: !stats?.hasErrors() });
+        wake?.();
+    });
+    try {
+        context.reportStatus('Watching the Lynx bundle');
+        const { close } = await rspeedy.build({ watch: true });
+        context.addTeardown(close);
+    }
+    catch (error) {
+        yield errorOutput(error);
+        return;
+    }
+    for (;;) {
+        while (results.length > 0) {
+            yield results.shift();
+        }
+        await new Promise((resolve) => (wake = resolve));
+    }
+};
+const readPackageVersion = (projectRoot) => {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(node_path_1.default.join(projectRoot, 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.default = (0, architect_1.createBuilder)((options, context) => (0, exports.runApplication)(options, context));

package/builders/application/native-cache.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeCacheDir = void 0;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Where `ng build --platform` keeps the generated Xcode and Gradle projects,
+ * their build state and the logs: the project's folder in Angular's build
+ * cache, `.angular/cache/<Angular version>/<project>/lynx-native` by default.
+ *
+ * Inside Angular's cache rather than a folder of our own at the project
+ * root, so a Lynx app's root looks like any Angular app's: `ng new` already
+ * git-ignores the cache, `ng cache clean` clears it, and `cli.cache.path`
+ * moves it.
+ *
+ * The version folder isn't optional. Angular's application and dev-server
+ * builders delete every folder in the cache except the current version's,
+ * so a `lynx-native` folder beside it would be deleted by the next Angular
+ * build. Under it, an Angular update clears the native projects too, which
+ * costs one regeneration.
+ *
+ * Angular shares one cache between a repository's linked checkouts, using
+ * the main checkout's. This stays in the current checkout instead: two
+ * checkouts building at once would overwrite each other's generated
+ * project. And it's used even when `cli.cache.enabled` is
+ * false, because the native build needs a working folder either way.
+ */
+const nativeCacheDir = ({ metadata, workspaceRoot, projectRoot, projectName, }) => node_path_1.default.join(node_path_1.default.resolve(workspaceRoot, cachePath(metadata)), angularBuildVersion(projectRoot), projectName, 'lynx-native');
+exports.nativeCacheDir = nativeCacheDir;
+/**
+ * angular.json's `cli.cache.path`, defaulting as Angular does.
+ */
+const cachePath = (metadata) => {
+    const cli = metadata['cli'];
+    const value = cli?.cache?.path;
+    return typeof value === 'string' ? value : '.angular/cache';
+};
+/**
+ * The version Angular names its cache folder after: @angular/build's, which
+ * this package needs as a peer dependency (`ng new` installs it).
+ */
+const angularBuildVersion = (projectRoot) => {
+    const require = (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, 'package.json'));
+    let packageJsonPath;
+    try {
+        packageJsonPath = require.resolve('@angular/build/package.json');
+    }
+    catch {
+        throw new Error('@angular/build is not installed. Run `npm install --save-dev @angular/build` (`ng new` adds it).');
+    }
+    return JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, 'utf8')).version;
+};

package/builders/application/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });