[!NOTE] In memory of Saber Rastikerdar Creator of Vazirmatn, the open typeface he gave the Persian web and asked nothing for.
Engineering decisions, not tutorials.
A long-term, community-driven, peer-reviewed knowledge base of frontend engineering
patterns, trade-offs, and production-ready practices — framework-aware, not framework-bound.
Stop re-litigating frontend decisions from scratch.
Find the trade-offs, choose deliberately, and ship the decision your future team can defend.
- Why this project exists
- What it is — and is not
- Who it's for
- Start with a decision
- Features
- Repository structure
- The knowledge map
- Learning paths
- Contributing
- Roadmap
- FAQ
- Community
- Acknowledgements
- License
Frontend engineering knowledge is scattered across blog posts, framework changelogs, conference talks, and tribal experience. Much of it goes stale, contradicts itself, or optimizes for a demo rather than a production system.
Frontend Engineering is a durable, versioned, peer-reviewed reference that captures the decisions behind good frontend systems — the problem, the options, the trade-offs, and a defensible recommendation — and stays useful for years, independent of any single framework's release cycle. The emphasis is on reasoning: why one approach is chosen over another, not step-by-step instructions.
Your next data-loading, caching, or validation choice will shape more code than the first pull request suggests. This is the place to make that choice once — with the constraints visible — instead of rediscovering it during the next incident or rewrite.
| It is | It is not |
|---|---|
|
|
Mid-level to senior frontend engineers making architectural and design decisions; tech leads and staff engineers setting standards across teams; and engineers preparing for system-design discussions who want structured reasoning rather than recipes. A working knowledge of JavaScript, the browser platform, and at least one component framework is assumed — this is not aimed at absolute beginners.
🧭 45 peer-reviewed articles are already available. Start with the decision currently slowing your team down.
| If you're deciding… | Start here | You will leave with |
|---|---|---|
| When to start a request | Fetch-on-Render vs Render-as-You-Fetch | A loading model that matches the user experience you need. |
| What makes cached data the same data | Cache Keys & Query Identity | A stable cache identity that avoids subtle duplication and invalidation bugs. |
| How to keep form input trustworthy | Schema Validation | A contract between UI, validation, and inferred types. |
| Where a piece of work should run | Process & Thread Architecture | A main-thread budget, and the rule for what to offload. |
| Which client store to reach for | Web Storage | The size and access-pattern thresholds that decide it. |
| How to stop the CSS override arms race | Specificity | A flat, layered precedence model instead of !important. |
| What actually protects a logged-in user | Same-Origin Policy | The read/write asymmetry, and the defenses each side needs. |
Browse the published collections: Data & Server State, Forms & Validation, State Management, and Performance — plus the entry-point articles now open across Foundations and Core Languages. If this would save your team a future debate, star the repository and come back when the next one begins.
|
Less recipe. More reasoning. |
A cache key is an identity, not just a URL. Read Cache Keys & Query Identity.
- 🗺️ Four-level knowledge map — Part → Domain → Topic → Article — that scales to 1000+ entries without the root ever widening.
- 🔗 Typed cross-links between every article: prerequisites, next, related, alternatives, and common mistakes.
- 🧩 Dependency graph with difficulty, reading time, and recommended order for every entry.
- 🧭 Role-based learning paths — curated journeys for beginners, React developers, architects, and specialists.
- ⚖️ Standardized template — every article contrasts a realistic bad example with a production-ready good example.
- ✅ Two-stage review — technical correctness and editorial craft are checked separately before anything ships.
- 🛡️ CI-validated — Markdown lint, link checking, spell checking, and frontmatter validation run on every change.
frontend-engineering/
├─ docs/ # The knowledge base — 9 Parts (see the map below)
├─ paths/ # Role-based learning paths across the map
├─ examples/ # Minimal, focused code illustrating one decision
├─ recipes/ # End-to-end solutions to recurring problems
├─ anti-patterns/ # Documented pitfalls and why they fail at scale
├─ templates/ # The standard article template every entry follows
├─ standards/ # The content framework every document must follow
├─ assets/ # Diagrams, images, and brand assets
├─ scripts/ # Link/graph build + validation tooling
├─ KNOWLEDGE_MAP.md # Full taxonomy and priorities
├─ ARTICLE_INVENTORY.md # Per-article backlog (title, slug, difficulty, status)
├─ GRAPH.md # Dependency graph, difficulty, reading order
├─ INTERNAL_LINKING.md # Cross-link strategy (five typed relations)
└─ .github/ # Community health, labels, CI, project specs
Documentation lives under docs/, ordered as a learning gradient from foundations to leadership. Full structure and priorities are in the Knowledge Map; the per-article backlog is in the Article Inventory; learning dependencies and reading order are in the Dependency Graph.
| Part | Focus | Priority |
|---|---|---|
| 00 · Foundations | Web platform, runtime, browser APIs, networking | Critical |
| 01 · Core Languages | HTML, CSS, JavaScript, TypeScript | Critical |
| 02 · Rendering & Frameworks | Rendering architectures, React, reactivity, routing | Critical |
| 03 · Application Architecture | Architecture, state, data, forms, API contracts | Critical |
| 04 · Interface Engineering | Components, design systems, accessibility, motion | High |
| 05 · Reliability & Quality | Performance, security, testing, observability | Critical |
| 06 · Engineering Systems | Build, packages, developer experience, delivery | High |
| 07 · Platform Reach | Internationalization, PWA, graphics & immersive | Medium |
| 08 · Craft & Leadership | Engineering practices, systems thinking, leadership | High |
Rather than reading top to bottom, follow a role-based path curated through the map:
- Frontend Beginner · React Developer · TypeScript Mastery
- Performance Engineer · Testing Specialist · Accessibility Specialist
- Senior Frontend Engineer · Frontend Architect · Staff Engineer
Contributions are welcome and encouraged. Every entry follows the standard article template and passes peer review. Good starting points are issues labeled good first issue and content corrections.
Before opening a pull request, read:
- CONTRIBUTING.md — how to contribute, standards, naming, and review criteria.
- standards/ — the content framework every document follows: philosophy, voice, quality bar, code and diagram rules, review pipeline, and health metrics.
- CODE_OF_CONDUCT.md — community standards.
- GOVERNANCE.md — roles, decision-making, and the RFC process.
Work is organized with a scalable label system, a project board, and milestones.
The published site is built from this repository with VitePress — the markdown is the source, so there is nothing to duplicate. To preview a change locally:
npm install # or pnpm install
npm run docs:dev # local server with hot reload
npm run docs:build # production build into .vitepress/distSidebar navigation is generated from each domain's graph.json, so a new article appears once its file exists — no navigation file to update.
Two notes on the toolchain: Mermaid's dayjs, cytoscape, and @braintree/sanitize-url are declared as direct devDependencies because the Mermaid plugin pre-bundles them by bare name, which needs them resolvable from the project root under any package manager. And vitepress dev prints one harmless Failed to resolve dependency: debug warning — that name is on the plugin's pre-bundle list but is not a Mermaid 11 dependency.
The project ships in versioned releases; a "release" is a citable snapshot of the content. Full goals and completion criteria are in .github/MILESTONES.md.
- v0.1 — Foundation: structure, standards, governance, and the full professional GitHub surface.
- v0.2 — Core Articles: seed the critical Parts with peer-reviewed articles.
- v0.3 — Examples: runnable code tied to the reasoning.
- v0.4 — Recipes: end-to-end solutions to recurring problems.
- v0.5 — Anti-patterns: documented pitfalls with honest caveats.
- v1.0 — Stable: coverage across all nine Parts, decision guides, and a maintenance cadence.
How is this different from MDN or the official framework docs?
MDN and framework docs explain what an API does. This repository explains which approach to choose and why, across competing options, with the trade-offs made explicit. It complements reference docs; it doesn't replace them.
Is this a tutorial or course?
No. There are no "getting started" walkthroughs. Every entry assumes working familiarity and focuses on engineering decisions. If you want to learn your first framework, start elsewhere and come back when you're making architectural choices.
Which frameworks does it cover?
It is framework-aware but not framework-bound. Concepts that transfer are prioritized; where a pattern is framework-specific (often React), it says so and names versions when behavior depends on them.
Can I contribute if I'm not a staff engineer?
Yes. Corrections, references, clearer prose, and examples are all valuable, and every contribution is reviewed against clear criteria. See CONTRIBUTING.md.
How do I cite it?
Use the metadata in CITATION.cff, and cite a specific release tag so the reference is stable.
- 💬 Discussions — ask conceptual questions and propose topics.
- 🐞 Issues — report content errors or propose articles using the templates.
- 🔒 Security — privately report unsafe example code or tooling risk.
- 🙋 Support — where to go for what.
Participation is governed by our Code of Conduct.
This project's structure and standards are inspired by the maintainers who set the bar for open-source quality — the teams behind React, TypeScript, TanStack, shadcn/ui, Next.js, Vitest, and Astro — and by the countless engineers whose blog posts, talks, and code reviews turned scattered lessons into shared craft. Thank you to every contributor who helps keep this reference accurate and durable.
Released under the MIT License. Content contributed to this repository is shared under the same terms.