Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions specs/epics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@ folder is the adoption; the merge creates the epic in the workspace.

| Epic | Cluster | Status | What it is |
|------|---------|--------|------------|
| [`angular-boilerplate/`](./angular-boilerplate/) | **NG** | In progress (NG0) | Vercel's Angular Boilerplate — the Angular CLI's welcome app, moved to Angular 22 — built static and served as Cloudflare Workers Static Assets behind one Worker as a single-page app, and an Orun baseline that instantiates it (NG2) |

As-built ≠ intent: what shipped lives in each epic's `IMPLEMENTATION-STATUS.md`.
11 changes: 11 additions & 0 deletions specs/epics/angular-boilerplate/IMPLEMENTATION-STATUS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# angular-boilerplate — implementation status

| Milestone | State | Landed |
|---|---|---|
| NG0 — the spec | ✅ | the repository's first commit and NG-1 |
| NG1 — the app on Workers | planned | NG-2 |
| NG2 — a baseline | planned | NG-3 |

## Departures from the upstream template

Recorded as they land, from NG1 on.
38 changes: 38 additions & 0 deletions specs/epics/angular-boilerplate/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# angular-boilerplate — Vercel's Angular Boilerplate on Cloudflare Workers

**Angular builds fully static, so the port is two things: the template moved
from Angular 15 to Angular 22 — the only Angular that builds and tests on
the runners' Node 22, standalone because Angular 22's test builder cannot
compile the template's NgModule — and where it is served — `dist/browser` as
Cloudflare Workers Static Assets behind one small Worker, every page address
answered by the app, deployed by Orun to stage and prod on every merge — and
then the baseline that makes a copy of it somebody else's app in one
landing.**

| | |
|---|---|
| Status | In progress — NG0 on main |
| Upstream | [vercel/examples](https://github.com/vercel/examples) `framework-boilerplates/angular` (MIT), at `de86723` (2026-10-16; the folder last changed in `cb2643e`): the Angular CLI 15's welcome app |
| Reference | [docusaurus](https://github.com/sourceplane/docusaurus) — the same static build behind one Worker, its tests and its bootstrap; [astro-boilerplate](https://github.com/sourceplane/astro-boilerplate) — the same `<framework>-boilerplate` identity and rename rules |
| Key | `NG` |

## Read in this order

1. [design.md](design.md) — the template, the move to Angular 22 and to a
standalone component, how each Vercel piece maps to Cloudflare, the
single-page-app routing and the Worker's 404 rule, the repository, and
the alternative rejected.
2. [implementation-plan.md](implementation-plan.md) — the milestones and
what each one lands.
3. [risks-and-open-questions.md](risks-and-open-questions.md) — what is not
proven, and what was accepted.
4. [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md) — what shipped, and
every departure from the upstream template.

## Milestones

| Milestone | What it lands | Task |
|---|---|---|
| NG0 — the spec | the repository, its intent, CI, tooling and spec index; this doc set | NG-1 |
| NG1 — the app on Workers | the template on Angular 22 in `apps/web`, built static, served as assets behind one Worker as a single-page app, with its specs and tests | NG-2 |
| NG2 — a baseline | the console card, the build document, the context pack and the baseline's tests | NG-3 |
86 changes: 86 additions & 0 deletions specs/epics/angular-boilerplate/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# angular-boilerplate — design

## The template

Vercel's Angular example (`framework-boilerplates/angular` in
[vercel/examples](https://github.com/vercel/examples)) is the app the Angular
CLI 15 generates: an `AppModule` declaring one `AppComponent`, an
`AppRoutingModule` with no routes, and the CLI's welcome page in
`app.component.html` — a toolbar, the "`<title>` app is running!" banner,
five Resources cards, and a Next Steps terminal whose command switches with
the card you click (a hidden input's value, read by `ngSwitch`), above a
`<router-outlet>`. Its title is `angular-test`, the CLI project it was
generated as. Three Karma/Jasmine specs check that the component is created,
that its title is `angular-test`, and that the banner renders it. Vercel
builds it with its Angular framework preset and serves `dist/` statically.

## Angular 15 → 22

The runners' Node is 22. Angular CLI 15 supports Node 14, 16 and 18, and on
Node 22 it reports "Unsupported"; `ng build` then fails outright
(`lib.es5.d.ts: Duplicate identifier 'ReturnType'` — TypeScript 4.8 against
today's `@types/node`). Making it pass would mean pinning old types on a
Node the CLI refuses to support. So the template moves to the current major,
22.2: Angular's esbuild application builder (`@angular/build:application`,
output `dist/browser`), TypeScript 6.0 (whose tsconfig rejects an `outDir`
without a `rootDir`, so the template's are dropped), zone.js 0.16, and RxJS
7.8.

## Standalone

Angular 22's test builder (`@angular/build:unit-test`) cannot compile the
template of a component declared in an NgModule: the template's own spec
fails with NG8001 (`router-outlet` is not a known element) and NG8002
(`ngSwitch`), and so does the spec of a stock Angular 22.2.5 project
generated with `ng new --standalone=false`. So `AppComponent` is standalone,
the shape Angular 22 generates by default: it imports `NgSwitch`,
`NgSwitchCase`, `NgSwitchDefault` and `RouterOutlet`; `main.ts` calls
`bootstrapApplication(AppComponent, appConfig)`; `app.config.ts` provides
zone change detection (the template ran on zone.js) and the router; the
routes, still none, are `app.routes.ts`. `AppModule` and
`AppRoutingModule` go. The welcome page's HTML and CSS are byte for byte the
template's, and the three specs keep what they assert (the title they
compare against is the name seam's).

## How it maps to Cloudflare

| Vercel | Here | Why |
|---|---|---|
| Static output on Vercel's CDN | `dist/browser` as Workers Static Assets, uploaded with `<repo>-web-<env>` | The app is static; the assets are the app |
| — | One Worker, `apps/web/worker/index.ts` | The `cloudflare-workers-assets-turbo` composition deploys a Worker with its assets; it answers what the assets leave |
| A page address other than `/`: the host's (no rewrite in the template) | `not_found_handling: single-page-application`: a browser's navigation that matches no file gets `index.html` | The app routes in the browser; a route added to `app.routes.ts` must work on a deep link and a reload |
| A missing file: the host's 404 | The Worker answers 404 when the path's last segment names a file, and hands any other page request back to the assets (which answer `index.html`) | Only requests the assets did not answer reach it: a non-navigation miss. The assets binding applies the same fallback, so forwarding a `/missing.js` would answer HTML with a 200 |
| `ng build` / `ng test` on Karma and Chrome | `ng build` on the esbuild builder; `ng test` on Angular's Vitest builder in jsdom | The current Angular's defaults; no browser on a runner |

## Every page is the app's

A request reaches Workers Static Assets first. A file is served as it is
(the bundles carry content hashes). A browser's navigation that matches no
file (`Sec-Fetch-Mode: navigate`) is answered with `index.html` and a 200.
Everything else that matches no file reaches the Worker, and the Worker
decides by the path: a last segment with an extension (`/missing.js`,
`/assets/logo.png`) is a missing file and gets a plain-text 404; any other
path is a page asked for without a browser's headers (a link preview, curl)
and is handed back to the assets, which answer `index.html`. A browser that
navigates to `/missing.js` still gets the app: the assets answer navigations
before the Worker sees them. The rule is one function, `namesAFile`, tested
in `tests/web/src/worker.test.ts` and read over HTTP by the e2e tier.

## The repository

docusaurus' shape, the same static build behind one Worker: `apps/web` (the
Angular workspace, the app, the Worker, the deploy contract), `tests/web`
(vitest), the shared TypeScript and ESLint configuration, the wrangler
renderer, `ci.yml` byte for byte docusaurus' (turso-starter's but for one
comment). The rename engine is astro-boilerplate's: the same
`<framework>-boilerplate` slug, which no framework module spells, so nothing
of Angular's needs masking; the seam is `SITE_NAME` in
`apps/web/src/app/site.ts`, defaulting to the template's `angular-test`.

## The alternative rejected

**Server rendering with `@angular/ssr`** on a Worker. The template has no
server routes and no SSR; adding Angular's server build would change what
the template is and put a server bundle in front of a page that renders in
the browser. A static build behind the assets is the template as Vercel
serves it.
30 changes: 30 additions & 0 deletions specs/epics/angular-boilerplate/epic.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# The epic's declaration. metadata.name equals the directory name; metadata.key
# is the task-key prefix this epic reserves (NG → NG-1, NG-2, …). Owner, target
# date and health are the platform's — never written here.
apiVersion: orun.io/v1
kind: Epic
metadata:
name: angular-boilerplate
key: NG
spec:
title: "Vercel's Angular Boilerplate on Cloudflare Workers"
summary: "Vercel's Angular example — the Angular CLI's welcome app: a toolbar, the app-is-running banner, the Resources cards, the Next Steps terminal and the router, with the CLI's specs — moved from Angular 15 to Angular 22 (standalone, Angular's esbuild application builder, its Vitest test builder), built fully static and served as Cloudflare Workers Static Assets behind one small Worker as a single-page app, inside the Cirrus baseline's repository conventions, and becomes an Orun baseline that takes a new Angular app from nothing to live on stage and prod in one landing."
state: started
milestones:
- name: "NG0 — the spec"
exitCriteria:
- "the repository is born with its intent, CI, tooling and spec index, and this doc set and the task contracts are on main"
tasks: [NG-1]
- name: "NG1 — the app on Workers"
exitCriteria:
- "apps/web is the upstream template on Angular 22, built static by the esbuild application builder, with one Worker in front of dist/browser as Workers Static Assets"
- "`pnpm typecheck`, `pnpm lint`, `pnpm test` (the template's specs on Angular's Vitest builder, and tests/web) and `pnpm build` are green"
- "`wrangler dev` serves the shell, its bundles and the favicon, answers every page address with the app and a missing file with a 404"
- "the README says how to run, test, preview and deploy it, and how every Vercel piece maps to Cloudflare"
tasks: [NG-2]
- name: "NG2 — a baseline"
exitCriteria:
- "blueprint.yaml (the console card) and repo-blueprint.yaml (the build) take a new Angular app from nothing to live on stage and prod in one landing, then record it"
- "an app built from it carries the app only, renamed throughout to its own name, repository and Worker, with the framework's own names intact"
- "Baseline CI is green: contract tests, generated component docs, the blueprint read by the pinned orun, the leak gate, the offline bootstrap and the end-to-end tier"
tasks: [NG-3]
42 changes: 42 additions & 0 deletions specs/epics/angular-boilerplate/implementation-plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# angular-boilerplate — implementation plan

Three milestones, each one reviewed pull request (NG0 follows the
repository's first commit), each green before it merges.

## NG0 — the spec (NG-1)

The repository is born: `intent.yaml` with the placeholder workspace
`ws_CHANGE_ME`, `ci.yml` (byte for byte docusaurus', turso-starter's but for
one comment, which plans nothing until the workspace is set), the shared
TypeScript and ESLint configuration, the spec index, this doc set and the
task contracts.

## NG1 — the app on Workers (NG-2)

- The template's `src/` in `apps/web` on Angular 22.2: the welcome page,
its styles, the shell and the favicon as they are; `AppComponent`
standalone, `app.config.ts`, `app.routes.ts`, `main.ts` with
`bootstrapApplication`; `site.ts`, the name seam.
- `angular.json` (project `web`): the esbuild application builder writing
`dist/browser`, the dev server, and the Vitest test builder.
- `worker/index.ts` and `wrangler.jsonc`: the Worker in front of
`dist/browser`, single-page-app routing, the 404 rule for file paths.
- `component.yaml`: the deploy contract and its smoke over the shell, the
main bundle, a deep link and a missing file.
- Specs: the template's three, and one for the Next Steps terminal. Tests
(`tests/web`): the name seam, the build and test config, the Worker's
routing, the template's page.
- The README's "How it maps to Vercel".

## NG2 — a baseline (NG-3)

docusaurus' machinery, renamed: `blueprint.yaml`, `repo-blueprint.yaml`,
`.baseline/` (identity, product README, task contracts), `tooling/rebrand`
(astro-boilerplate's engine and rules, the seam at
`apps/web/src/app/site.ts`), `tooling/bootstrap`,
`hooks/render-deployment-docs.sh` (probing `/`, a deep link and each
`SITE_URL`), `docs/phases/`, the context pack, `testing/` (the leak and
placement gates on this tree's files, placement also failing on the
template's name left in the app or a framework module renamed; the e2e tier
building the app in the stage lane's staged tree and reading every route it
promises) and `baseline.yml` / `tag.yml`.
11 changes: 11 additions & 0 deletions specs/epics/angular-boilerplate/risks-and-open-questions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# angular-boilerplate — risks and open questions

| ID | Risk | State | Notes |
|---|---|---|---|
| NG-A | `baseline-v1` is not yet proven live | OPEN | Proven offline in Baseline CI: the offline bootstrap with the blueprint's own hooks, the stage lane's own steps in a staged job tree, the app served by `wrangler dev` and smoke-tested with the component's own command, every route read. A console bootstrap closes it |
| NG-B | Angular 22, not the template's 15 | ACCEPTED | Angular 15 does not build on Node 22 (spike: `~/orunbase/spikes/angular-boilerplate.md`). The welcome page renders the same; its links point at angular.io pages that now redirect to angular.dev, as the template's do |
| NG-C | Standalone, not NgModule | ACCEPTED | Angular 22's test builder cannot compile an NgModule-declared component's template (reproduced on a stock `ng new --standalone=false` project). A product that wants NgModules back can add one; its specs would need the same workaround |
| NG-D | The Worker's 404 rule reads the path | ACCEPTED | A page route whose last segment has a dot (`/v1.2`) asked for without a browser's navigation headers would be a 404; a browser's navigation to it is still the app. `namesAFile` is the one place to change it |
| NG-E | The template's component-style budget warns | ACCEPTED | The welcome page's inline `<style>` is 3.76 kB against the template's own 2 kB `anyComponentStyle` warning budget; `ng build` warns and succeeds, as the template's budgets say. A product replacing the page clears it |
| NG-F | stack-tectonic 0.19.0, not 0.20.0 | ACCEPTED | 0.20.0's lane-shared install links each job's `node_modules` out of its tree; the siblings pin 0.19.0 for it and the app would save nothing |
| NG-G | zone.js kept | ACCEPTED | The template ran on zone.js; Angular 22 generates zoneless apps by default. `provideZoneChangeDetection()` keeps the template's behaviour; dropping zone.js is the owner's change |
15 changes: 15 additions & 0 deletions tasks/NG-1.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: NG-1
title: "The spec"
spec:
goal: The angular-boilerplate repository is born with its intent, CI, tooling and spec index, and the angular-boilerplate epic — declaration, doc set and task contracts — is on main
affects:
- specs/epics/angular-boilerplate
- specs/epics/README.md
- tasks
doneWhen:
- epic.yaml, README, design, implementation plan, risks and status are on main
- the three task contracts exist
gates: []
18 changes: 18 additions & 0 deletions tasks/NG-2.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: NG-2
title: "The app on Workers"
spec:
goal: Vercel's Angular Boilerplate runs on Angular 22 on Cloudflare Workers + Static Assets — built static, served as assets behind one Worker as a single-page app — with its specs and tests, and its README saying how it maps to Vercel
affects:
- apps/web
- tests/web
- pnpm-lock.yaml
- pnpm-workspace.yaml
- README.md
- .gitignore
doneWhen:
- pnpm typecheck, lint, test and build are green
- wrangler dev serves the shell, its bundles and the favicon, every page address as the app, and a missing file as a 404
gates: []
28 changes: 28 additions & 0 deletions tasks/NG-3.TaskContract.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
apiVersion: orun.io/v1
kind: TaskContract
metadata:
name: NG-3
title: "angular-boilerplate becomes an Orun baseline"
spec:
goal: blueprint.yaml and repo-blueprint.yaml take a new Angular app from nothing to live on stage and prod in one landing, held by Baseline CI
affects:
- blueprint.yaml
- repo-blueprint.yaml
- BOOTSTRAP.md
- .baseline
- .github/workflows/baseline.yml
- .github/workflows/tag.yml
- ai/context
- docs/phases
- hooks
- testing
- tooling/rebrand
- tooling/bootstrap
- tooling/catalog
- apps/web/docs
- specs/epics/angular-boilerplate
- README.md
doneWhen:
- every Baseline CI tier is green
- an app placed from it carries the app only, branded, with the framework's own names intact
gates: []
Loading