aurelia-foundation
Scaffold the first decision for any Aurelia v2 task: pick the right foundation reference. Aurelia's reference documentation is opinionated; the wrong pillar at the wrong time costs more than picking the right one.
Version & ground truth
- Aurelia 2.x only. v1 patterns are gone (details in each reference).
https://docs.aurelia.io is authoritative. DeepWiki deep-links follow the form aurelia/aurelia/blob/master/packages/<pkg>/docs/<file>.md.
Pick a reference
Match the request to exactly one branch. Every branch lives in reference/ and links back here.
| Request shape |
Reference |
| "What is Aurelia?", "why Aurelia over React?", "is Aurelia stable?" |
reference/philosophy.md |
"Scaffold a new project", "hello world", "first main.ts", "make aurelia my-app" |
reference/quickstart.md |
"npx makes feature flags", "silent select -s", "scaffold with Tailwind/Vitest/Playwright/Storybook" |
reference/cli.md |
| "Create a custom element", "kebab-case name", "bindable", "dependencies array" |
reference/components.md |
"binding / attached / unbinding", "lifecycle order", "dispose subscriptions" |
reference/lifecycle.md |
| "Use an AI to scaffold this", "DHB prompts", "NotebookLM ground truth" |
reference/ai-tooling.md |
If the request spans two pillars (e.g. "scaffold a custom element with lifecycle"), start with the scaffolding reference (quickstart or components) and follow its outbound links to the second.
Hard guardrails (apply to every branch)
These are non-negotiable across all seven pillars. Each is enforced by the runtime or build pipeline; ignoring any of them is a runtime error or a silent prod bug.
.trigger for all event listeners. .delegate — on custom and native DOM events alike — is removed and throws AUR0713 (template compilation error). .capture handles capture-phase listeners.- Kebab-case element names. Every custom element name must contain a hyphen (
user-profile, not userProfile).
import type / export type for interfaces. Interfaces are type-only; runtime values use regular import / export. Project enforces via verbatimModuleSyntax: true in tsconfig.json..style property binding for dynamic CSS when the value can be falsy. Inline style="width: ${value}%" is safe when the value is guaranteed non-falsy; it compiles to style="width:{};" only when the value is 0/false/'' in production builds. Prefer width.style="expr" in any component where the interpolated value may be falsy.- Singleton DI services over Event Aggregator. Prefer typed, constructor-injected services for cross-component state.
IEventAggregator exists but is a last resort; the dispose hook is the mandatory permanent cleanup site if you subscribe — detaching is only for temporary teardown and unbinding runs before potential reactivation.
- Models, not DTOs, cross the service boundary. Services return Model classes (camelCase,
*.model.ts). DTOs (PascalCase, *-dto.ts) live in src/models/ and convert via Model.fromDTO(). Components consume Models, never DTOs.
Each guardrail is expanded in the reference file closest to it (template/binding → components; naming → components; state → lifecycle).
Lead with scaffold
Use the verb scaffold to anchor each foundation action: scaffold the project, scaffold a custom element, scaffold the lifecycle, scaffold the agent prompt. The shared vocabulary keeps the agent's mental model inside Aurelia's, not React's.
1---2name: aurelia-foundation3description: Scaffold an Aurelia v2 project from zero. Picks the right foundation step — philosophy, hello-world quickstart, component naming, lifecycle hooks, or AI-assisted scaffolding. Use when starting an Aurelia 2 app, asking "what is Aurelia", creating a custom element, wiring binding/attached/unbinding, or generating the first main.ts and pair.4license: MIT5---67# aurelia-foundation89Scaffold the **first decision** for any Aurelia v2 task: pick the right foundation reference. Aurelia's reference documentation is opinionated; the wrong pillar at the wrong time costs more than picking the right one.1011## Version & ground truth1213- **Aurelia 2.x only.** v1 patterns are gone (details in each reference).14- `https://docs.aurelia.io` is authoritative. DeepWiki deep-links follow the form `aurelia/aurelia/blob/master/packages/<pkg>/docs/<file>.md`.1516## Pick a reference1718Match the request to exactly one branch. Every branch lives in `reference/` and links back here.1920| Request shape | Reference |21|---|---|22| "What is Aurelia?", "why Aurelia over React?", "is Aurelia stable?" | [reference/philosophy.md](reference/philosophy.md) |23| "Scaffold a new project", "hello world", "first `main.ts`", "make aurelia my-app" | [reference/quickstart.md](reference/quickstart.md) |24| "`npx makes` feature flags", "silent select `-s`", "scaffold with Tailwind/Vitest/Playwright/Storybook" | [reference/cli.md](reference/cli.md) |25| "Create a custom element", "kebab-case name", "bindable", "dependencies array" | [reference/components.md](reference/components.md) |26| "`binding` / `attached` / `unbinding`", "lifecycle order", "dispose subscriptions" | [reference/lifecycle.md](reference/lifecycle.md) |27| "Use an AI to scaffold this", "DHB prompts", "NotebookLM ground truth" | [reference/ai-tooling.md](reference/ai-tooling.md) |2829If the request spans two pillars (e.g. "scaffold a custom element with lifecycle"), start with the scaffolding reference ([quickstart](reference/quickstart.md) or [components](reference/components.md)) and follow its outbound links to the second.3031## Hard guardrails (apply to every branch)3233These are non-negotiable across all seven pillars. Each is enforced by the runtime or build pipeline; ignoring any of them is a runtime error or a silent prod bug.3435- **`.trigger` for all event listeners.** `.delegate` — on custom and native DOM events alike — is removed and throws `AUR0713` (template compilation error). `.capture` handles capture-phase listeners.36- **Kebab-case element names.** Every custom element name must contain a hyphen (`user-profile`, not `userProfile`).37- **`import type` / `export type` for interfaces.** Interfaces are type-only; runtime values use regular `import` / `export`. Project enforces via `verbatimModuleSyntax: true` in `tsconfig.json`.38- **`.style` property binding for dynamic CSS when the value can be falsy.** Inline `style="width: ${value}%"` is safe when the value is guaranteed non-falsy; it compiles to `style="width:{};"` only when the value is `0`/`false`/`''` in production builds. Prefer `width.style="expr"` in any component where the interpolated value may be falsy.39- **Singleton DI services over Event Aggregator.** Prefer typed, constructor-injected services for cross-component state. `IEventAggregator` exists but is a last resort; the `dispose` hook is the mandatory permanent cleanup site if you subscribe — `detaching` is only for temporary teardown and `unbinding` runs before potential reactivation.40- **Models, not DTOs, cross the service boundary.** Services return Model classes (camelCase, `*.model.ts`). DTOs (PascalCase, `*-dto.ts`) live in `src/models/` and convert via `Model.fromDTO()`. Components consume Models, never DTOs.4142Each guardrail is expanded in the reference file closest to it (template/binding → [components](reference/components.md); naming → [components](reference/components.md); state → [lifecycle](reference/lifecycle.md)).4344## Lead with `scaffold`4546Use the verb *scaffold* to anchor each foundation action: *scaffold the project*, *scaffold a custom element*, *scaffold the lifecycle*, *scaffold the agent prompt*. The shared vocabulary keeps the agent's mental model inside Aurelia's, not React's.
Expert-Vision-Software