How googlecodelabs/codelab-elements works
Project Type and Purpose
• This is an open-source web-component library (“Codelab Custom Elements”) that provides reusable Custom Elements (analytics, index, core codelab, steps, survey) for building interactive codelabs.
• It is organized as a Bazel-based monorepo, with each element in its own package, plus a demo, third-party shims, and development tools.
File Structure Analysis
• Top-level
• BUILD.bazel, WORKSPACE – Bazel workspace definition and build rules.
• demo/ – example application showing how to use the components; contains its own BUILD.bazel, HTML, JS, tests, and images.
• google-codelab-analytics/, google-codelab-index/, google-codelab-step/, google-codelab-survey/, google-codelab/ – five independent component packages, each with a BUILD.bazel, HTML/CSS/JS sources, definitions, tests, and assets.
• third_party/ – Bazel build rules for polyfills and shims (ES6, polyfill, prettify).
• tools/ – CI scripts, Bazel config, server.go and webtest.go for local dev server and browser tests.
• Patterns
• Modular packages built via Bazel, using Google Closure Compiler for JS bundling and testing.
• Test targets in each package.
• A dev web server to serve built artifacts for manual inspection.
README Insights
• Describes standard Custom Elements usage.
• “bazel build :bundle” emits codelab-elements.js, codelab-elements.css for direct inclusion in HTML.
• Demo uses native-shim, custom-elements polyfill, prettify, then the bundled JS/CSS.
• Emphasis on no framework dependencies, only standards-based web components.
1. Monorepo Source Packages
– google-codelab (core renderer/navigator)
– google-codelab-step (step component)
– google-codelab-index (index/cards component)
– google-codelab-analytics (analytics wrapper)
– google-codelab-survey (survey component)
2. Third-Party Shims/Polyfills (ES6, Custom Elements polyfill, prettify)
3. Build System
– Bazel (WORKSPACE, BUILD.bazel rules)
– Google Closure Compiler & Library
– Bundling target (:bundle) producing JS and CSS artifacts
4. Demo Application
– HTML pages (codelab embed, hello, codelab-index)
– hello.js test driver and test suite
– bazel run tools:server (dev web server)
5. CI/Testing Tools
– tools/ci-presubmit.sh, ci-continuous.sh
– Webtest and Go server for browser-based tests
6. Runtime Environment (Browser)
– Native browser HTML/CSS/JS
– Custom Elements lifecycle
– User interactions driving codelab steps and events forwarded to analytics and survey components
• Each source package → Bazel compiler → bundle artifacts.
• third_party shims → bundled with component outputs.
• Demo HTML → includes bundle artifacts + polyfills → browser runtime.
• User clicks “Next Step” → google-codelab triggers google-codelab-step → updates DOM → optional survey popup → events → google-codelab-analytics.
• CI scripts → run bazel test on each package → report results.
c. Architectural Patterns & Principles
• Modular, packaging each component separately (Single Responsibility).
• Build pipeline orchestrated by Bazel (hermetic, reproducible).
• Standards-based Custom Elements (no framework lock-in).
• Test pyramid: unit tests per component + integration via demo + browser tests.
d. Key Technologies
• Bazel (build, test, run)
• Google Closure Compiler & Library
• JavaScript Custom Elements API
• SCSS → CSS for styling
• Go (tools/server.go for local web server)
• HTML for demos and component templates