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

package/README.md

@@ -1,3 +1,101 @@
-# 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` and `ng test` 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"
+}
+```
+
+| 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                           |
+
+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) and [`builders/unit-test/schema.json`](builders/unit-test/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.
+
+## 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` runs Angular's unit-test builder from the project's own `@angular/build`, which `ng new` installs: it must match the project's Angular version.

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 });

package/builders/application/schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularLynxApplicationBuilder",
+  "title": "AngularLynx application builder",
+  "description": "Builds the Lynx bundle with rspeedy and, with --platform, the iOS and Android binaries.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "platform": {
+      "type": "string",
+      "enum": ["ios", "android", "all"],
+      "description": "Also build native binaries into dist/<platform>/. Without it, only the bundle is built, as `rspeedy build` does."
+    },
+    "watch": {
+      "type": "boolean",
+      "default": false,
+      "description": "Rebuild the bundle when files change, as Angular's `ng build --watch` does. Can't be combined with `platform`."
+    },
+    "config": {
+      "type": "string",
+      "description": "The rspeedy config file, relative to the project root. Defaults to lynx.config.ts (or .js, .mts, .mjs) when the project has one. Without one, the app builds from angular.json: `browser` is the entry, and both the lynx and web environments are built."
+    },
+    "environment": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Only build these rspeedy environments (e.g. lynx). With --platform, only the lynx environment is built."
+    },
+    "browser": {
+      "type": "string",
+      "description": "Angular: the app's entry point. Read by @blotch/rsbuild-plugin-angular-lynx and `ng test`, and rspeedy's `source.entry` unless lynx.config.ts sets one."
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "Angular: the tsconfig the app compiles with."
+    },
+    "polyfills": {
+      "type": ["array", "string"],
+      "items": {
+        "type": "string"
+      },
+      "description": "Angular: modules loaded before the app (e.g. @angular/localize/init)."
+    },
+    "styles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Angular: global stylesheets."
+    },
+    "assets": {
+      "type": "array",
+      "description": "Angular: used by `ng test` only. Lynx bundles reference assets through imports."
+    },
+    "scripts": {
+      "type": "array",
+      "description": "Angular: used by `ng test` only."
+    },
+    "inlineStyleLanguage": {
+      "type": "string",
+      "description": "Angular: the language of inline component styles."
+    },
+    "fileReplacements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "replace": {
+            "type": "string"
+          },
+          "with": {
+            "type": "string"
+          }
+        },
+        "required": ["replace", "with"]
+      },
+      "description": "Angular: files swapped at build time, e.g. environment files."
+    },
+    "aot": {
+      "type": "boolean",
+      "description": "Angular: ahead-of-time compilation. Defaults to true."
+    },
+    "optimization": {
+      "type": ["boolean", "object"],
+      "description": "Angular: script and style optimization. Also sets rspeedy's mode: production when scripts are optimized (the default), development otherwise."
+    },
+    "sourceMap": {
+      "type": ["boolean", "object"],
+      "description": "Angular: source maps."
+    },
+    "outputHashing": {
+      "type": "string",
+      "enum": ["none", "all", "media", "bundles"],
+      "description": "Angular: hashes in emitted file names."
+    },
+    "i18nMissingTranslation": {
+      "type": "string",
+      "enum": ["warning", "error", "ignore"],
+      "description": "Angular: how to report missing translations."
+    },
+    "budgets": {
+      "type": "array",
+      "description": "Angular: size budgets, checked against the Lynx bundles (each entry's bundle is its own `initial` budget) and component stylesheets."
+    },
+    "extractLicenses": {
+      "type": "boolean",
+      "description": "Angular: accepted for compatibility with `ng new`."
+    },
+    "outputPath": {
+      "type": ["string", "object"],
+      "description": "Angular: the output folder. Defaults to rspeedy's dist/."
+    },
+    "index": {
+      "type": ["boolean", "string", "object"],
+      "description": "Angular: accepted for compatibility; Lynx apps have no index.html."
+    },
+    "appName": {
+      "type": "string",
+      "description": "The app's name under its icon. Defaults to the project name."
+    },
+    "appId": {
+      "type": "string",
+      "description": "The iOS bundle ID and Android applicationId, e.g. com.example.myapp."
+    },
+    "version": {
+      "type": "string",
+      "description": "The user-facing version, e.g. 1.2.0. Defaults to package.json's version."
+    },
+    "buildNumber": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The store build number (CFBundleVersion / versionCode). Must increase with every store upload."
+    },
+    "orientation": {
+      "type": "string",
+      "enum": ["portrait", "landscape", "all"],
+      "default": "portrait",
+      "description": "The screen orientations the app supports."
+    },
+    "icon": {
+      "type": "string",
+      "description": "The app icon: a 1024×1024 PNG without transparency, relative to the project root."
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Each permission the app uses, with the reason shown to the user.",
+      "additionalProperties": false,
+      "properties": {
+        "camera": {
+          "type": "string"
+        },
+        "microphone": {
+          "type": "string"
+        },
+        "location": {
+          "type": "string"
+        },
+        "photos": {
+          "type": "string"
+        },
+        "contacts": {
+          "type": "string"
+        },
+        "notifications": {
+          "type": "string"
+        }
+      }
+    },
+    "deepLinkSchemes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Custom URL schemes that open the app, e.g. [\"myapp\"]."
+    },
+    "ios": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "teamId": {
+          "type": "string",
+          "description": "The Apple Developer team ID that signs the app."
+        },
+        "signing": {
+          "type": "object",
+          "description": "An App Store Connect API key for headless signing. Each field names the environment variable holding the value.",
+          "additionalProperties": false,
+          "properties": {
+            "keyIdEnv": {
+              "type": "string"
+            },
+            "issuerIdEnv": {
+              "type": "string"
+            },
+            "keyPathEnv": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "android": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "signing": {
+          "type": "object",
+          "description": "The Google Play upload key. The *Env fields name the environment variables holding the values.",
+          "additionalProperties": false,
+          "properties": {
+            "storeFileEnv": {
+              "type": "string"
+            },
+            "storePasswordEnv": {
+              "type": "string"
+            },
+            "keyAlias": {
+              "type": "string"
+            },
+            "keyPasswordEnv": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/builders/builders.json

@@ -0,0 +1,19 @@
+{
+  "builders": {
+    "application": {
+      "implementation": "./application/index",
+      "schema": "./application/schema.json",
+      "description": "Builds the Lynx bundle with rspeedy (--watch to rebuild on changes) and, with --platform, the iOS and Android binaries"
+    },
+    "dev-server": {
+      "implementation": "./dev-server/index",
+      "schema": "./dev-server/schema.json",
+      "description": "Runs the rspeedy dev server for Lynx Explorer and the web preview"
+    },
+    "unit-test": {
+      "implementation": "./unit-test/index",
+      "schema": "./unit-test/schema.json",
+      "description": "Runs the unit tests with Angular's unit-test builder, set up for AngularLynx"
+    }
+  }
+}

package/builders/dev-server/index.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDevServer = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const node_path_1 = __importDefault(require("node:path"));
+const rspeedy_1 = require("../rspeedy");
+/**
+ * Starts rspeedy's dev server in this process, as `rspeedy dev` would, and
+ * closes it when Angular CLI tears the builder down (Ctrl+C). rspeedy's own
+ * plugins keep working unchanged, and live reload is rspeedy's. The QR code
+ * plugin, which prints the link Lynx Explorer opens, is added unless
+ * lynx.config.ts lists it.
+ *
+ * Like Angular's own dev server, it builds what `buildTarget` describes: its
+ * options configure the compile, so `ng serve -c production` serves the
+ * production configuration.
+ */
+const startDevServer = async (options, context, deps) => {
+    const projectName = context.target?.project;
+    if (!projectName) {
+        return { success: false, error: 'The builder needs a project target.' };
+    }
+    const metadata = await context.getProjectMetadata(projectName);
+    const projectRoot = node_path_1.default.join(context.workspaceRoot, metadata['root'] ?? '');
+    try {
+        // The same default as Angular's dev server: the project's build target
+        // with its development configuration.
+        const buildTarget = (0, architect_1.targetFromTargetString)(options.buildTarget ?? '::development', projectName, 'build');
+        // Validated against the build builder's schema, which also fills in its
+        // defaults, as the build itself would see them.
+        const buildOptions = (await context.validateOptions(await context.getTargetOptions(buildTarget), await context.getBuilderNameForTarget(buildTarget)));
+        const rspeedy = await (0, rspeedy_1.createRspeedy)({
+            rspeedy: await deps.importRspeedy(),
+            plugin: await deps.importPlugin(),
+            qrCode: await deps.importQRCodePlugin(),
+            projectRoot,
+            angularCli: {
+                workspaceRoot: context.workspaceRoot,
+                project: buildTarget.project,
+                buildOptions,
+            },
+            config: buildOptions.config,
+            environment: options.environment ?? buildOptions.environment,
+            server: { port: options.port, host: options.host },
+        });
+        const { server, urls } = await rspeedy.startDevServer();
+        context.addTeardown(() => server.close());
+        return { success: true, baseUrl: urls[0] };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+/**
+ * `ng serve`. Angular CLI keeps a target running for as long as its outputs
+ * haven't ended, so this reports the server's start and then never ends,
+ * unless the server failed to start.
+ */
+const runDevServer = (options, context, deps = { importRspeedy: rspeedy_1.importRspeedy, importPlugin: rspeedy_1.importPlugin, importQRCodePlugin: rspeedy_1.importQRCodePlugin }) => ({
+    [Symbol.asyncIterator]: () => {
+        let started;
+        return {
+            next: async () => {
+                if (!started) {
+                    started = startDevServer(options, context, deps);
+                    return { value: await started, done: false };
+                }
+                return (await started).success
+                    ? new Promise(() => { })
+                    : { value: undefined, done: true };
+            },
+        };
+    },
+});
+exports.runDevServer = runDevServer;
+exports.default = (0, architect_1.createBuilder)(exports.runDevServer);

package/builders/dev-server/schema.js

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