bank20baht-cli 0.5.0 → 0.7.0

package/templates/angular/README.md.hbs

@@ -0,0 +1,46 @@
+# {{name}}
+
+Angular microfrontends on Native Federation, scaffolded by
+[`bank20baht-cli`](https://github.com/bank20baht/bahtui) (`bahtui create --angular`).
+
+```
+apps/shell        the host (:4200): navigator from the federation manifest, a fallback page per remote
+apps/hello-web    a remote (:4201): one page calling one API route, exposed as ./Routes
+apps/server       Elysia API (:3000) under /api; exports `type App` as built declarations
+packages/kit      what the web apps share (typed ngx-eden client, error text), as @{{name}}/kit
+```
+
+## Quickstart
+
+```sh
+bun install
+bun run dev        # every apps/* dev script in parallel
+bun run check      # lint, format, typecheck, madge, boundaries, knip, dup, build, test
+```
+
+## Add a remote
+
+```sh
+bahtui g remote orders   # apps/orders-web on the next port, mounted at /orders
+bun install
+```
+
+It also adds the remote to `eslint.config.ts`, `knip.ts`, `.dependency-cruiser.mjs`, the dev
+manifest (`apps/shell/src/environments/environment.development.ts`) and the deployed one
+(`apps/shell/public/federation.manifest.json`). Each of those holds a `// bahtui:remotes` line (the
+JSON manifest is parsed instead); keep it, the generator inserts above it.
+
+## Things that are this way on purpose
+
+- `features.ignoreUnusedDeps` is off in every `federation.config.mjs`: its scan refuses sources
+  outside the app folder, and the kit lives in `packages/kit`. So every `package.json` dependency is
+  shared, and each app lists bank20baht-ui's optional peers (`marked`, `dompurify`, `flatpickr`);
+  `/^marked\/bin/` stays in `skip`.
+- `fileReplacements` sit on `esbuild:development` in `angular.json`, not on `build`.
+- The web apps see the server only as types, from `apps/server/dist/types` (`build:types` runs
+  before every web build and typecheck). Keep the server's imports extensionless: Angular's
+  compiler rejects `./x.ts` specifiers in sources it follows.
+- A remote that is down when the host boots stays unavailable until a reload, so every remote's
+  URL prefix falls back to a page that says so, and the rest keeps working.
+- In production the host reads `/federation.manifest.json` at runtime: serve each remote's build
+  under `/remotes/<app>/` and `/api` from the server on the same origin.

package/templates/angular/_dependency-cruiser.mjs

@@ -0,0 +1,51 @@
+/**
+ * Architecture boundaries, checked with `bun run deps`. `generic` gives no-circular and
+ * production-not-tests. The rules below keep the microfrontends apart: the host and the remotes
+ * meet only at runtime through the federation manifest, and share code only through packages/kit.
+ * Every rule is `error`: a violation is a decision, not a warning.
+ */
+import { makeConfig } from 'bank20baht-strict/depcruise'
+
+const HOST = 'shell'
+
+/** `bahtui g remote` adds a line. */
+const REMOTES = [
+  // bahtui:remotes
+]
+
+const WEB_APPS = [HOST, ...REMOTES]
+
+const base = makeConfig({ generic: true })
+
+const apart = WEB_APPS.map((app) => ({
+  name: `${app}-imports-no-other-app`,
+  severity: 'error',
+  comment:
+    'Web apps never import each other: a static import would bundle one app into another build.',
+  from: { path: `^apps/${app}/src/` },
+  to: { path: `^apps/(?!${app}/)(${WEB_APPS.join('|')})/` },
+}))
+
+const layers = WEB_APPS.map((app) => ({
+  name: `${app}-lower-layers-know-no-page`,
+  severity: 'error',
+  comment: 'core/, services/ and shared/ know no page; pages are reached through the router.',
+  from: { path: `^apps/${app}/src/app/(core|services|shared)/` },
+  to: { path: `^apps/${app}/src/app/modules/` },
+}))
+
+export default {
+  ...base,
+  forbidden: [
+    ...base.forbidden,
+    ...apart,
+    ...layers,
+    {
+      name: 'packages-know-no-app',
+      severity: 'error',
+      comment: 'packages/ are below the apps; the server reaches them only as built types.',
+      from: { path: '^packages/' },
+      to: { path: '^apps/', pathNot: '^apps/server/dist/types/' },
+    },
+  ],
+}

package/templates/angular/apps/server/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "server",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "types": "dist/types/index.d.ts",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --target bun --outdir dist",
+    "build:types": "tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
+  },
+  "dependencies": {
+    "@elysiajs/cors": "^1.4.3",
+    "elysia": "^1.4.31"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/angular/apps/server/src/app.ts

@@ -0,0 +1,14 @@
+import { cors } from '@elysiajs/cors'
+import { Elysia } from 'elysia'
+
+/** In dev the host and the remotes run on their own localhost ports; deployed, all share one origin. */
+const DEV_ORIGIN = /^http:\/\/localhost:\d+$/
+
+/**
+ * The API under `/api`. Keep imports extensionless (`./x`, never `./x.ts`): the web apps compile
+ * this file's declarations, and Angular's compiler rejects `.ts` specifiers.
+ */
+export const buildApp = () =>
+  new Elysia({ prefix: '/api' })
+    .use(cors({ origin: DEV_ORIGIN, credentials: true }))
+    .get('/hello', () => ({ message: 'Hello from the server' }))

package/templates/angular/apps/server/src/index.ts

@@ -0,0 +1,8 @@
+import { buildApp } from './app'
+
+const app = buildApp().listen(Number(process.env['PORT'] ?? 3000))
+
+console.log(`server on http://localhost:${String(app.server?.port)}`)
+
+/** What the web apps type their client with (through `dist/types`, `bun run build:types`). */
+export type App = typeof app

package/templates/angular/apps/server/test/app.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test'
+
+import { buildApp } from '../src/app'
+
+describe('api', () => {
+  test('says hello', async () => {
+    const response = await buildApp().handle(new Request('http://localhost/api/hello'))
+
+    expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ message: 'Hello from the server' })
+  })
+})

package/templates/angular/apps/server/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": ["src", "test"]
+}

package/templates/angular/apps/server/tsconfig.types.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": false,
+    "outDir": "dist/types",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/templates/angular/apps/shell/_editorconfig

@@ -0,0 +1,17 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+ij_typescript_use_double_quotes = false
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/templates/angular/apps/shell/angular.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "bun"
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "shell": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-architects/native-federation:build",
+          "options": {
+            "cacheExternalArtifacts": true,
+            "tsConfig": "tsconfig.federation.json"
+          },
+          "configurations": {
+            "production": {
+              "target": "shell:esbuild:production"
+            },
+            "development": {
+              "target": "shell:esbuild:development",
+              "dev": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-architects/native-federation:build",
+          "options": {
+            "target": "shell:serve-original:development",
+            "tsConfig": "tsconfig.federation.json",
+            "rebuildDelay": 500,
+            "cacheExternalArtifacts": true,
+            "dev": true,
+            "devServer": true,
+            "port": 0
+          }
+        },
+        "test": {
+          "builder": "@angular/build:unit-test",
+          "options": {
+            "buildTarget": "shell:esbuild:development",
+            "coverageReporters": ["text", "lcov"],
+            "coverageExclude": ["src/main.ts", "src/bootstrap.ts", "src/environments/**"]
+          }
+        },
+        "esbuild": {
+          "builder": "@angular/build:application",
+          "options": {
+            "browser": "src/main.ts",
+            "tsConfig": "tsconfig.app.json",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "public"
+              }
+            ],
+            "styles": ["node_modules/bank20baht-ui/dist/tokens.css", "src/styles.css"],
+            "polyfills": ["es-module-shims"]
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1MB"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "4kB",
+                  "maximumError": "8kB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true,
+              "fileReplacements": [
+                {
+                  "replace": "src/environments/environment.ts",
+                  "with": "src/environments/environment.development.ts"
+                }
+              ]
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve-original": {
+          "builder": "@angular/build:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "shell:esbuild:production"
+            },
+            "development": {
+              "buildTarget": "shell:esbuild:development"
+            }
+          },
+          "defaultConfiguration": "development",
+          "options": {
+            "port": 4210
+          }
+        }
+      }
+    }
+  }
+}

package/templates/angular/apps/shell/federation.config.mjs

@@ -0,0 +1,44 @@
+import { withNativeFederation, fromPackageJson } from '@angular-architects/native-federation/config'
+
+export default withNativeFederation({
+  name: 'shell',
+
+  shared: fromPackageJson({
+    singleton: true,
+    strictVersion: true,
+    requiredVersion: 'auto',
+    build: 'package',
+  })
+    // includeSecondaries is an opt-out of ignoreUnusedDeps, so all of
+    // @angular/core is shared to prevent mismatches.
+    .patch(['@angular/core'], { includeSecondaries: { keepAll: true } })
+    // Same for bank20baht-ui: the remotes import bank20baht-ui/overlay, the
+    // host only bank20baht-ui. Unshared, each side bundles its own copy of the
+    // elements and the second customElements.define('baht-button') throws.
+    .patch(['bank20baht-ui'], { includeSecondaries: { keepAll: true } }),
+
+  skip: [
+    'rxjs/ajax',
+    'rxjs/fetch',
+    'rxjs/testing',
+    'rxjs/webSocket',
+    // Server / React entry points of bank20baht-ui (pulled in by keepAll above).
+    'bank20baht-ui/ssr',
+    'bank20baht-ui/hydrate',
+    'bank20baht-ui/react',
+    // marked's command-line entry imports Node built-ins.
+    /^marked\/bin/,
+  ],
+
+  // The kit (a tsconfig path into packages/kit) is compiled into each app, not shared.
+  sharedMappings: [],
+
+  features: {
+    // Off: the unused-dependency scan (sheriff) refuses sources outside the app folder, and
+    // the kit lives in packages/kit. Every package.json dependency is shared instead, so each
+    // app lists bank20baht-ui's optional peers (marked, dompurify, flatpickr) itself.
+    ignoreUnusedDeps: false,
+    // Groups chunks in remoteEntry.json for a smaller metadata file.
+    denseChunking: true,
+  },
+})

package/templates/angular/apps/shell/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "shell",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "ng": "ng",
+    "dev": "ng serve",
+    "build": "ng build",
+    "test": "ng test",
+    "test:coverage": "ng test --watch=false --coverage",
+    "typecheck": "tsc -b --noEmit",
+    "pretypecheck": "bun run --filter server build:types",
+    "prebuild": "bun run --filter server build:types"
+  },
+  "dependencies": {
+    "@angular-architects/native-federation": "^22.2.1",
+    "@angular/common": "^22.2.0",
+    "@angular/compiler": "^22.2.0",
+    "@angular/core": "^22.2.0",
+    "@angular/platform-browser": "^22.2.0",
+    "@angular/router": "^22.2.0",
+    "bank20baht-ui": "0.19.0",
+    "bank20baht-ui-angular": "0.2.0",
+    "dompurify": "3.4.17",
+    "es-module-shims": "^2.8.0",
+    "flatpickr": "4.6.13",
+    "marked": "18.1.3",
+    "ngx-eden": "^0.2.0",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@angular/build": "^22.2.0",
+    "@angular/cli": "^22.2.0",
+    "@angular/compiler-cli": "^22.2.0",
+    "@softarc/native-federation-orchestrator": "^4.6.0",
+    "@vitest/coverage-v8": "^4.0.8",
+    "jsdom": "^30.0.0",
+    "typescript": "~6.0.2",
+    "vitest": "^4.0.8"
+  }
+}

package/templates/angular/apps/shell/public/federation.manifest.json

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

package/templates/angular/apps/shell/src/app/app.config.ts

@@ -0,0 +1,20 @@
+import type { ApplicationConfig } from '@angular/core'
+import { provideBrowserGlobalErrorListeners } from '@angular/core'
+import { provideHttpClient } from '@angular/common/http'
+import { provideRouter, withComponentInputBinding } from '@angular/router'
+import { routesFor } from './app.routes'
+import type { Manifest } from './core/federation/manifest'
+
+/**
+ * The host owns the root: router and `HttpClient`. The remotes' services are
+ * `providedIn: 'root'`, so they use this `HttpClient` too.
+ */
+export function appConfig(manifest: Manifest): ApplicationConfig {
+  return {
+    providers: [
+      provideBrowserGlobalErrorListeners(),
+      provideRouter(routesFor(manifest), withComponentInputBinding()),
+      provideHttpClient(),
+    ],
+  }
+}

package/templates/angular/apps/shell/src/app/app.css

@@ -0,0 +1,4 @@
+.shell-main {
+  display: block;
+  min-width: 0;
+}

package/templates/angular/apps/shell/src/app/app.html.hbs

@@ -0,0 +1,16 @@
+<baht-app-shell
+  brand="{{name}}"
+  brand-href="/"
+  label="{{name}}"
+  [items]="items"
+  [value]="current()"
+  (baht-nav)="navigate($event)"
+>
+  <div data-slot="actions">
+    <baht-theme-toggle default="system"></baht-theme-toggle>
+  </div>
+  <main class="shell-main">
+    <router-outlet />
+  </main>
+</baht-app-shell>
+<baht-toast></baht-toast>

package/templates/angular/apps/shell/src/app/app.routes.ts.hbs

@@ -0,0 +1,39 @@
+import type { Routes } from '@angular/router'
+import { loadRemoteRoutes } from './core/federation/load-remote'
+import type { Manifest } from './core/federation/manifest'
+
+const unavailable = () =>
+  import('./modules/unavailable/unavailable.component').then((m) => m.UnavailableComponent)
+
+/**
+ * The home page, one URL prefix per remote in the manifest, and a not-found page. A remote that
+ * cannot be loaded shows a fallback page under its prefix; the rest of the app keeps working.
+ */
+export const routesFor = (manifest: Manifest): Routes => [
+  {
+    path: '',
+    pathMatch: 'full',
+    title: '{{name}}',
+    loadComponent: () => import('./modules/home/home.component').then((m) => m.HomeComponent),
+  },
+  ...Object.entries(manifest).map(([name, remote]) => ({
+    path: remote.base,
+    title: `${remote.title} · {{name}}`,
+    loadChildren: loadRemoteRoutes(name, () => [
+      {
+        path: '**',
+        data: {
+          heading: `${remote.title} is unavailable`,
+          message: 'This part of the app could not be loaded. The rest still works.',
+        },
+        loadComponent: unavailable,
+      },
+    ]),
+  })),
+  {
+    path: '**',
+    title: 'Not found · {{name}}',
+    data: { heading: 'Page not found', message: 'Nothing lives at this address.' },
+    loadComponent: unavailable,
+  },
+]

package/templates/angular/apps/shell/src/app/app.ts

@@ -0,0 +1,57 @@
+import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core'
+import { toSignal } from '@angular/core/rxjs-interop'
+import { NavigationEnd, Router, RouterOutlet } from '@angular/router'
+import type { ShellNavItem } from 'bank20baht-ui'
+import { BAHT_UI } from 'bank20baht-ui-angular'
+import { filter, map } from 'rxjs'
+import { MANIFEST } from './core/federation/remote-loader'
+
+/** The frame every page sits in: brand, a navigator built from the federation manifest, the page. */
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [RouterOutlet, BAHT_UI],
+  selector: 'app-root',
+  templateUrl: './app.html',
+  styleUrl: './app.css',
+})
+export class App {
+  private readonly router = inject(Router)
+  private readonly manifest = inject(MANIFEST)
+
+  private readonly url = toSignal(
+    this.router.events.pipe(
+      filter((event) => event instanceof NavigationEnd),
+      map((event) => event.urlAfterRedirects),
+    ),
+    { initialValue: this.router.url },
+  )
+
+  protected readonly items: ShellNavItem[] = [
+    { key: '', label: 'Home', href: '/' },
+    ...Object.values(this.manifest).flatMap((remote) =>
+      remote.nav.map((nav) => ({
+        key: nav.path,
+        label: nav.label,
+        href: `/${nav.path}`,
+        group: remote.title,
+      })),
+    ),
+  ]
+
+  /** The navigator entry whose path the URL sits under; the longest one wins. */
+  protected readonly current = computed(() => {
+    const path = (this.url().split(/[?#]/)[0] ?? '').replace(/^\//, '')
+    const keys = this.items
+      .map((item) => item.key)
+      .filter((key) => key !== '' && (path === key || path.startsWith(`${key}/`)))
+    return keys.sort((a, b) => b.length - a.length)[0] ?? ''
+  })
+
+  /** Route in place instead of letting the link reload the page. */
+  protected navigate(event: Event): void {
+    const { href } = (event as CustomEvent<{ href: string | undefined }>).detail
+    if (href === undefined) return
+    event.preventDefault()
+    void this.router.navigateByUrl(href)
+  }
+}

package/templates/angular/apps/shell/src/app/core/federation/load-remote.ts

@@ -0,0 +1,31 @@
+import { inject } from '@angular/core'
+import type { Routes } from '@angular/router'
+import { REMOTE_LOADER } from './remote-loader'
+import { withTimeout } from './timeout'
+
+/** What every remote exposes as `./Routes`. */
+type RoutesModule = { routes: Routes }
+
+/** How long a first visit waits for a remote before showing the fallback page. */
+const LOAD_TIMEOUT_MS = 10_000
+
+/**
+ * `loadChildren` for a remote's URL prefix: its `./Routes`, or `fallback()` when federation is
+ * off or the remote cannot be loaded. One remote being down never takes the others with it.
+ */
+export const loadRemoteRoutes =
+  (name: string, fallback: () => Routes): (() => Promise<Routes>) =>
+  async () => {
+    const loadRemoteModule = inject(REMOTE_LOADER)
+    if (loadRemoteModule === null) return fallback()
+    try {
+      const module = await withTimeout(
+        loadRemoteModule<RoutesModule>(name, './Routes'),
+        LOAD_TIMEOUT_MS,
+      )
+      return module.routes
+    } catch (err) {
+      console.error(`${name} ./Routes failed to load`, err)
+      return fallback()
+    }
+  }

package/templates/angular/apps/shell/src/app/core/federation/manifest.spec.ts

@@ -0,0 +1,46 @@
+import { parseManifest } from './manifest'
+import { withTimeout } from './timeout'
+
+const entry = {
+  entry: 'http://localhost:4201/remoteEntry.json',
+  title: 'Hello',
+  base: 'hello',
+  nav: [{ label: 'Hello', path: 'hello' }],
+}
+
+describe('parseManifest', () => {
+  it('accepts well-formed entries', () => {
+    expect(parseManifest({ 'hello-web': entry })).toEqual({ 'hello-web': entry })
+    expect(parseManifest({})).toEqual({})
+  })
+
+  it('rejects the whole file when one entry is wrong', () => {
+    expect(parseManifest(null)).toBeNull()
+    expect(parseManifest([entry])).toBeNull()
+    expect(parseManifest({ ok: entry, bad: { ...entry, entry: 1 } })).toBeNull()
+    expect(parseManifest({ bad: { ...entry, base: '../etc' } })).toBeNull()
+    expect(parseManifest({ bad: { ...entry, nav: [{ label: 'x' }] } })).toBeNull()
+  })
+})
+
+describe('withTimeout', () => {
+  it('passes a settled promise through', async () => {
+    await expect(withTimeout(Promise.resolve('ok'), 50)).resolves.toBe('ok')
+    await expect(withTimeout(Promise.reject(new Error('no')), 50)).rejects.toThrow('no')
+    await expect(
+      withTimeout(
+        new Promise((_resolve, reject) => {
+          // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors -- the case under test: a non-Error rejection is wrapped
+          reject('text')
+        }),
+        50,
+      ),
+    ).rejects.toThrow('text')
+  })
+
+  it('rejects when the promise is too slow', async () => {
+    await expect(withTimeout(new Promise(() => undefined), 5)).rejects.toThrow(
+      'timed out after 5 ms',
+    )
+  })
+})