How ionic-team/docs-demo works
Project Type and Purpose
• This is a front-end “kitchen sink” demo application built with Stencil (used by Ionic) showcasing a library of Web Components.
• There is no backend or database—everything is compiled to static assets and served as a static site.
Key Architectural Components
a. Developer Environment
• Source code in GitHub repo (includes package.json, stencil.config.ts, CI workflow).
• Local dev server (npm start) powered by Stencil’s watcher and build pipeline.
b. Continuous Integration & Build
• GitHub Actions (/.github/workflows/CI.yml) runs lint, tests, and npm run build.
• Build artifacts produced by Stencil (configured in stencil.config.ts).
c. Deployment
• Static host (e.g., Netlify, Surge, Firebase; static.json hints at hosting config).
• Deployed bundle includes index.html, compiled JS/CSS assets, manifest.json, service worker if any.
d. Runtime (Browser)
• index.html bootstraps the Stencil loader script.
• Components registry initializes—each UI component (in src/components/*) loads on demand.
• Demo pages (app-root, app-home) mount and render various component examples.
Relationships & Data Flow
• Developer pushes code → CI builds & tests → Artifacts deployed to Static Host → Browser fetches index.html & assets → Stencil loader registers Web Components → User interacts with components → events and property bindings drive UI demos.
• Within the browser:
→ index.html
→ Stencil runtime
→ component registry
→ individual components (each with .tsx and .css)
→ global utils (src/utils/component-utils.ts) support shared logic.
→ assets served from /src/assets.
Architectural Patterns & Principles
• Component-based architecture: encapsulated UI elements (accordion, button, modal, etc.).
• Build-time code generation and lazy loading via Stencil compiler.
• Separation of concerns:
• src/components for UI
• src/global for common styles and bootstrap code (app.ts)
• src/utils for shared helper functions
• scripts/mkcomponent.sh to scaffold new components.
a. Nodes into layers:
1. Source & CI layer (GitHub repo, CI workflow)
2. Build layer (Node.js/NPM → Stencil compiler → bundle artifacts)
3. Deployment layer (Static hosting service with static.json config)
4. Runtime layer (Browser with Stencil loader and Web Components)
• Code push → CI trigger
• CI → build artifacts
• Artifacts → deployment
• Browser requests → host → serves assets
• Loader → component registry → individual components
c. Technologies:
• GitHub Actions, Node.js, npm, Stencil.js, Hosting service (e.g., Netlify/Firebase), Web Components API
d. Patterns:
• Lazy loading of components
• Component encapsulation (shadow DOM)
• Build-time optimizations (tree shaking)