How openedx/frontend-template-site works
Project type and purpose
• This is a frontend‐only “template site” for Open edX micro-frontends. It provides a static HTML/CSS/JS scaffold, build and dev configurations, and a sample SCSS entrypoint.
• Its primary use case is to be cloned as a starting point for new Open edX‐branded frontend sites, with minimal custom code.
File structure
• Top‐level config files:
• package.json / package-lock.json – npm dependencies and scripts
• tsconfig.json – TypeScript compiler settings
• eslint.config.js – lint rules
• .nvmrc – Node version (v20.x)
• catalog-info.yaml – Backstage metadata
• site.config.dev.tsx & site.config.build.tsx – development & build configuration (entrypoints for the Open edX micro-frontend build tooling)
• Public assets:
• public/index.html – static HTML template and root div for mounting JS
• Source assets:
• src/site.scss – global styles (compiled by the build tool)
• app.d.ts – TypeScript declarations
• No backend code: everything is bundled into static assets.
README for additional insights
• Emphasizes climate of use: clone, rename, update index.html title, set PORT in site.config.dev.tsx, npm run dev, npm run build.
• Mentions internationalization hook via frontend-base, but no direct i18n code here.
• CI badges indicate GitHub Actions are in place for build/checks (though workflow files aren’t in this template).
Main components & their relationships
a. Development environment
• Developer workstation with Node v20.x & nvm
• Local clone of GitHub repo
• npm scripts: “dev” → starts dev server; “build” → runs production build
• site.config.dev.tsx configures webpack‐dev‐server on port (default 8080)
• site.config.build.tsx configures production bundling (SCSS → CSS, TSX → JS)
b. Version control & CI
• GitHub repo (template) with catalog-info metadata
• GitHub Actions CI: lint, typecheck, build, test, codecov
c. Build system
• Underlying micro-frontend build tool (likely webpack under the hood)
• Input: src/site.scss, public/index.html, TypeScript config & declarations
• Output: static assets (JS bundles, CSS, assets)
d. Deployment & hosting
• Artifacts deployed to a static host/CDN (e.g., S3 + CloudFront or any static site host)
• Clients (browsers) request index.html, load JS bundles and CSS
• Optional integration with Open edX LMS via micro-frontend mounting
Architectural patterns & design principles
• Single‐Page Application (SPA) or micro-frontend shell – public/index.html provides one “shell” page
• Configuration‐driven build – site.config.{dev,build}.tsx allow per‐site customization without touching core toolchain
• Strict separation:
• config (site.config.*) vs
• source assets (SCSS, types) vs
• public assets (index.html)
• Type safety via TypeScript and declarations (app.d.ts)