# Aurelia Foundation

> 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.

- Skill: `expert-vision-software/aurelia-foundation` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add expert-vision-software/aurelia-foundation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/expert-vision-software/aurelia-foundation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: Expert-Vision-Software (https://skillmd.com/u/expert-vision-software)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/expert-vision-software/aurelia-foundation

---


# 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](reference/philosophy.md) |
| "Scaffold a new project", "hello world", "first `main.ts`", "make aurelia my-app" | [reference/quickstart.md](reference/quickstart.md) |
| "`npx makes` feature flags", "silent select `-s`", "scaffold with Tailwind/Vitest/Playwright/Storybook" | [reference/cli.md](reference/cli.md) |
| "Create a custom element", "kebab-case name", "bindable", "dependencies array" | [reference/components.md](reference/components.md) |
| "`binding` / `attached` / `unbinding`", "lifecycle order", "dispose subscriptions" | [reference/lifecycle.md](reference/lifecycle.md) |
| "Use an AI to scaffold this", "DHB prompts", "NotebookLM ground truth" | [reference/ai-tooling.md](reference/ai-tooling.md) |

If 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.

## 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](reference/components.md); naming → [components](reference/components.md); state → [lifecycle](reference/lifecycle.md)).

## 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.