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
78 changes: 70 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,72 @@
# angular-boilerplate

[Vercel's Angular Boilerplate](https://github.com/vercel/examples/tree/main/framework-boilerplates/angular) on
**Cloudflare Workers**, deployed by [Orun](https://github.com/sourceplane/orun) to stage
and prod on every merge, and then packaged as an Orun baseline.

This commit is the repository's frame: `intent.yaml` (with the placeholder
workspace `ws_CHANGE_ME`, so CI plans nothing until it is linked), the Orun
CI workflow, the shared TypeScript and ESLint configuration, and the spec
index. The work is tracked as an epic under [`specs/epics`](specs/epics/README.md).
Vercel's [Angular Boilerplate](https://github.com/vercel/examples/tree/main/framework-boilerplates/angular)
template — the Angular CLI's welcome page, with its resources, its Next Steps
terminal and its router, and the template's specs — moved from Angular 15 to
Angular 22, running on **Cloudflare Workers + Static Assets**, deployed by
[Orun](https://github.com/sourceplane/orun) to stage and prod on every merge.
Packaging it as an Orun baseline is the next milestone (NG2).

Angular builds fully static: `ng build` (Angular's esbuild application
builder) writes the app's shell, its hashed JavaScript and CSS bundles and
the favicon to `dist/browser`. That folder is uploaded as Workers Static
Assets with one small Worker in front, and the app is served as a
single-page app: every page address is answered with the app, whose router
shows the page, and a missing file is a 404. The welcome page, its styles and
its specs do not change; the app's name moves into one module, the app is
standalone (Angular 22's own shape — its test builder cannot compile the
template's NgModule), and the specs run on Angular's own Vitest builder. See [`specs/epics/angular-boilerplate`](specs/epics/angular-boilerplate/README.md)
for the design, the milestones and the as-built status.

## What is here (the app)

| Surface | Where |
|---|---|
| The app's name, which the welcome banner reads | `apps/web/src/app/site.ts` |
| The welcome page (the template's, byte for byte), its component and its styles | `apps/web/src/app/app.component.{html,css,ts}`, `apps/web/src/styles.css` |
| The app's configuration, its routes (none yet) and its bootstrap | `apps/web/src/app/app.config.ts`, `apps/web/src/app/app.routes.ts`, `apps/web/src/main.ts` |
| The shell and the favicon | `apps/web/src/index.html`, `apps/web/src/favicon.ico` |
| The Angular workspace: build, serve and test targets | `apps/web/angular.json` |
| The template's specs, and one for the Next Steps terminal | `apps/web/src/app/*.spec.ts` (Angular's Vitest builder) |
| The Worker in front of the assets, its config, deploy contract | `apps/web/worker/index.ts`, `apps/web/wrangler.jsonc`, `apps/web/component.yaml` |
| Tests (the name seam, the build config, the Worker's routing, the template's page) | `tests/web` (vitest) |

## Getting started

```bash
pnpm install
pnpm typecheck # tsc: the app, its specs and the Worker
pnpm lint # eslint
pnpm test # ng test (the app's specs) and vitest (tests/web)
pnpm build # ng build → apps/web/dist/browser
```

```bash
pnpm --filter @app/web dev # ng serve on http://localhost:3000
pnpm --filter @app/web preview # wrangler dev over the built app and its Worker
```

## How it maps to Vercel

| Vercel | Here |
|---|---|
| Static output on Vercel's CDN, from its Angular framework preset | Workers Static Assets: `dist/browser` uploaded with the Worker `<repo>-web-<env>` (`apps/web/wrangler.jsonc`) |
| The template's build (`ng build`, Angular 15's webpack browser builder) | `ng build` on Angular 22's esbuild application builder (`@angular/build:application`), through turbo — Angular 15 cannot build on Node 22, the runners' Node |
| `ng test` on Karma and Chrome | `ng test` on Angular's Vitest builder (`@angular/build:unit-test`, jsdom): the template's three specs, run without a browser |
| A page address other than `/` answered by the host (the template sets no rewrite) | Every page address is the app's: a browser's navigation that matches no file gets `index.html` (`not_found_handling: single-page-application`), and the Worker hands any other page request back to the assets, so the router owns every route the app adds |
| The host's 404 for a missing file | The Worker answers 404 when the path names a file (`/missing.js`), so a stale script reference fails as a 404, not as HTML parsed as JavaScript |
| Deploy on push | Orun deploys `<repo>-web-{stage,prod}` on merge to `main` (`apps/web/component.yaml`) |
| "Deploy with Vercel" (clone the template) | `orun new --blueprint repo-blueprint.yaml` — a new repository, branded, deployed |

## CI

| Workflow | What it runs | Ships to an app |
|---|---|---|
| `ci.yml` | the Orun pipeline, and the only workflow an app carries: `orun plan --changed`, then one job per lane. A pull request runs the verify lanes (the app built and dry-deployed per environment; the tests' `quick-check` lane installs and checks the package, it does not run them), except the bootstrap's own landings (`orun/BASE-*`), where `plan` alone is the check; a merge deploys stage → prod. It plans nothing while `intent.yaml` names the placeholder workspace `ws_CHANGE_ME`, as this repository does. A manual run (Orunbase's Deploy button, or Run workflow on `main`) plans the environment and components it names under the push-to-main trigger, so they deploy as a merge deploys them | yes |

## Credits

The app is Vercel's Angular example
([vercel/examples](https://github.com/vercel/examples),
`framework-boilerplates/angular`, © 2023 Vercel, MIT — `apps/web/LICENSE.md`),
itself the Angular CLI's generated welcome app, at vercel/examples `de86723`.
21 changes: 21 additions & 0 deletions apps/web/LICENSE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
The MIT License (MIT)

Copyright (c) 2023 Vercel, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
34 changes: 34 additions & 0 deletions apps/web/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# apps/web — the Angular app

An Angular app on [Angular](https://angular.dev) 22 — the Angular CLI's
welcome page, as Vercel's Angular example (MIT, `LICENSE.md`) ships it —
built fully static by Angular's esbuild application builder and served as
Cloudflare Workers + Static Assets, as a single-page app:

- the welcome page in `src/app/app.component.html` — its toolbar, the
"<name> app is running!" banner, the Resources cards and the Next Steps
terminal whose command switches with the card you click
- a standalone `AppComponent`, its configuration (`src/app/app.config.ts`:
zone change detection and the router) and its routes (`src/app/app.routes.ts`,
none yet), bootstrapped by `src/main.ts`
- the template's specs and one for the Next Steps terminal
(`src/app/*.spec.ts`), run by `ng test` on Angular's Vitest builder

The app's name is in `src/app/site.ts`; `AppComponent` reads it as its
`title`, which the banner shows.

`worker/index.ts` sits in front of the static build: the assets answer every
file and every browser navigation (`not_found_handling:
"single-page-application"` in `wrangler.jsonc`), and the Worker answers what
is left — a 404 for a path that names a missing file, the app for any other
page.

```bash
pnpm dev # ng serve on http://localhost:3000
pnpm build # ng build → dist/browser
pnpm test # ng test: the specs, once, in jsdom
pnpm preview # wrangler dev over the built app, behind worker/index.ts
```

How it is deployed — per environment, on merge to `main` — is the
repository's README and `component.yaml` beside this file.
88 changes: 88 additions & 0 deletions apps/web/angular.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
{
"$schema": "./node_modules/@angular/cli/lib/config/schema.json",
"version": 1,
"cli": {
"packageManager": "pnpm",
"analytics": false
},
"newProjectRoot": "projects",
"projects": {
"web": {
"projectType": "application",
"root": "",
"sourceRoot": "src",
"prefix": "app",
"architect": {
"build": {
"builder": "@angular/build:application",
"options": {
"outputPath": "dist",
"index": "src/index.html",
"browser": "src/main.ts",
"polyfills": [
"zone.js"
],
"tsConfig": "tsconfig.app.json",
"assets": [
"src/favicon.ico",
"src/assets"
],
"styles": [
"src/styles.css"
],
"scripts": []
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "500kB",
"maximumError": "1MB"
},
{
"type": "anyComponentStyle",
"maximumWarning": "2kB",
"maximumError": "4kB"
}
],
"outputHashing": "all"
},
"development": {
"optimization": false,
"extractLicenses": false,
"sourceMap": true,
"namedChunks": true
}
},
"defaultConfiguration": "production"
},
"serve": {
"builder": "@angular/build:dev-server",
"configurations": {
"production": {
"buildTarget": "web:build:production"
},
"development": {
"buildTarget": "web:build:development"
}
},
"defaultConfiguration": "development"
},
"extract-i18n": {
"builder": "@angular/build:extract-i18n",
"options": {
"buildTarget": "web:build"
}
},
"test": {
"builder": "@angular/build:unit-test",
"options": {
"tsConfig": "tsconfig.spec.json",
"watch": false
}
}
}
}
}
}
89 changes: 89 additions & 0 deletions apps/web/component.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
apiVersion: sourceplane.io/v1
kind: Component
metadata:
name: web
description: The Angular app (Angular 22, built fully static and served as Cloudflare Workers + Static Assets behind one Worker with single-page-app routing, per environment)
spec:
type: cloudflare-workers-assets-turbo
lifecycle: production
owner: platform
# Its pages, attached to it in the workspace's catalog: what the Docs
# library shows for it, and what the catalog's docs and runbook checks read.
# Generated from what this manifest and its sources declare.
docs:
overview: docs/overview.md
pages:
- { path: docs/architecture.md, role: architecture, title: Architecture }
- { path: docs/runbook.md, role: runbook, title: Runbook }
# `app`, not `web`: a domain and a component share one name space in the
# catalog, and a domain called `web` hid this component from it.
domain: app
path: apps/web
# Its own lane per environment: the app's build is the longest job in the
# plan, and a shared lane would wait on it.
lane: isolated
subscribe:
environments:
- name: dev
profile: verify
- name: stage
profile: verify
profileRules:
- profile: deploy
when:
triggerRef: github-push-main
- name: prod
profile: verify
profileRules:
- profile: deploy
when:
triggerRef: github-push-main
parameters:
nodeVersion: "22"
pnpmVersion: "10.12.1"

workspaceDir: ../..
appDir: .

turboFilter: "@app/web"
# The config the dry run and the deploy hand to wrangler: the Worker
# (worker/index.ts) and the static build in dist/browser as its assets,
# with single-page-app routing. The app builds fully static, so there is
# no adapter and no generated config — this committed file is the one
# wrangler deploys.
wranglerConfig: wrangler.jsonc

# `ng build` (Angular's esbuild application builder) writes index.html,
# the hashed JavaScript and CSS bundles and the favicon to dist/browser.
# The Worker is a source file wrangler bundles at deploy; the lane checks
# it exists after the build like any entry.
workerEntrypoint: worker/index.ts
assetsDir: dist/browser

# Per-env worker name: angular-boilerplate-web-{dev,stage,prod}.
workerName: angular-boilerplate-web
environmentAwareWorkerName: true

# The account's workers.dev subdomain; exported to the smoke step as
# ${WORKERS_DEV_SUBDOMAIN} and used to build ${DEPLOYED_URL}.
workersDevSubdomain: your-workers-subdomain

installCommand: pnpm install --frozen-lockfile
# The app writes no absolute URL (it renders in the browser, from the
# origin it was loaded from), so the build takes no origin and is the same
# for every environment.
buildCommand: pnpm exec turbo run build --filter=@app/web

# Smoke: the home page is the app's shell (index.html with its
# <app-root>), the main bundle it loads is served and carries the
# template's welcome ("app is running!" — not the site's name, which is
# the owner's to change), a deep link answers with the same shell (the
# app routes in the browser), and a missing file is a 404 rather than the
# app's page (the Worker's rule). Each response is buffered before grep so
# an early match cannot SIGPIPE curl.
smokeCommand: "html=$(curl -sfL \"${DEPLOYED_URL}/\") && echo \"${html}\" | grep -q '<app-root></app-root>' && main=$(echo \"${html}\" | grep -oE 'main-[A-Z0-9]+[.]js' | head -n 1) && test -n \"${main}\" && js=$(curl -sfL \"${DEPLOYED_URL}/${main}\") && echo \"${js}\" | grep -q 'app is running!' && deep=$(curl -sfL \"${DEPLOYED_URL}/some/deep/link\") && echo \"${deep}\" | grep -q '<app-root></app-root>' && test \"$(curl -s -o /dev/null -w '%{http_code}' \"${DEPLOYED_URL}/no-such-file.js\")\" = 404"
labels:
team: platform
layer: delivery
surface: web
runtime: cloudflare
16 changes: 16 additions & 0 deletions apps/web/docs/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# web — architecture

Built by the turbo pipeline from `apps/web` and deployed with wrangler.

| | |
| ------------------- | ----------------------------------------------- |
| Worker config | `apps/web/wrangler.jsonc` |
| Entry | `./worker/index.ts` |
| Compatibility date | `2026-10-01` |
| Compatibility flags | `nodejs_compat`, `global_fetch_strictly_public` |

## Bindings

| Binding | Kind | Source |
| -------- | ------------- | ---------------- |
| `ASSETS` | Static assets | `./dist/browser` |
20 changes: 20 additions & 0 deletions apps/web/docs/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# web

The Angular app (Angular 22, built fully static and served as Cloudflare Workers + Static Assets behind one Worker with single-page-app routing, per environment)

A Cloudflare Worker with Static Assets (server rendering plus static files), deployed per environment by its CI lane.

| | |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Type | `cloudflare-workers-assets-turbo` |
| Source | `apps/web` |
| Package | `@app/web` |
| Environments | `dev`: `verify` · `stage`: `verify`, `deploy` on a push to `main` · `prod`: `verify`, `deploy` on a push to `main` |

## Depends on

- (none)

## Depended on by

- (none)
38 changes: 38 additions & 0 deletions apps/web/docs/runbook.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# web — runbook

## How it runs

Pull requests verify it; a merge to `main` deploys it to `stage`, `prod`.
CI plans what changed (`orun plan --changed`) and runs each lane with `orun run`;
the plan orders a component after everything it depends on.

## Local commands

```bash
pnpm --filter @app/web dev
pnpm --filter @app/web build
pnpm --filter @app/web test
pnpm --filter @app/web typecheck
pnpm --filter @app/web lint
pnpm --filter @app/web preview
```

## Verify

After a deploy the lane runs this smoke against the environment it
deployed (`ORUN_ENVIRONMENT`); `DEPLOYED_URL` overrides the URL:

```bash
html=$(curl -sfL "${DEPLOYED_URL}/") && echo "${html}" | grep -q '<app-root></app-root>' && main=$(echo "${html}" | grep -oE 'main-[A-Z0-9]+[.]js' | head -n 1) && test -n "${main}" && js=$(curl -sfL "${DEPLOYED_URL}/${main}") && echo "${js}" | grep -q 'app is running!' && deep=$(curl -sfL "${DEPLOYED_URL}/some/deep/link") && echo "${deep}" | grep -q '<app-root></app-root>' && test "$(curl -s -o /dev/null -w '%{http_code}' "${DEPLOYED_URL}/no-such-file.js")" = 404
```

## Rollback

Revert the commit on `main`. The next convergence applies the previous desired
state; nothing was changed out of band, so there is nothing else to undo.

## Common failures

- **The smoke fails right after a first deploy**: a new workers.dev route can
answer 4xx for a few seconds and the lane retries. A failure that persists
is a regression in the deployed code.
Loading
Loading