How hieule-allcommerce/bc-cs-atlantisart1 works
Project type and purpose
• This repository is a BigCommerce “Stencil” theme—essentially a front-end, asset-driven storefront for an e-commerce site.
• It contains:
• A Node-based build system (Grunt + Webpack + npm scripts)
• SCSS/CSS assets
• JavaScript modules (ES6, page-scoped classes extending a PageManager)
• Handlebars templates (layout, components, pages)
• Config files (stencil.conf.js, webpack configs, package.json, schema.json)
File structure
• Top-level build dirs & files: Gruntfile.js, webpack.\*.js, package.json, stencil.conf.js
• lang/: translation files (en.json, fr.json, etc.)
• templates/: Handlebars templates organized by “components,” “layout,” “pages”
• config & schema: config.json, schema.json, schemaTranslations.json for BigCommerce theme settings
Extract architecture notes from README
• Themes are driven by BigCommerce’s Stencil engine; templates compile server‐side with Handlebars + injected context
• Client JS runs via PageManager subclasses: before(), loaded(), after() hooks
• Polyfills are feature‐detected; stencil-utils handles AJAX interactions with BigCommerce APIs
• Local dev uses “stencil” CLI to run a proxy server
• Assets are deployed as a zip to BigCommerce and served to browsers
Main components & interactions
a. Build System (Local Dev)
• Node.js + npm scripts
• Grunt task for SVG sprite generation
• Webpack: bundles assets (JS modules, SCSS → CSS, polyfills)
• ESLint for code quality
b. Theme Definition
• SCSS modules → compiled CSS
• JS modules (PageManager classes + utilities) → main bundle + route chunks
• Handlebars templates (layout, components, pages)
• Localization files
• Config & schema (theme settings)
c. Stencil CLI & BigCommerce Platform
• Stencil CLI: local preview, “stencil push” uploads theme package
• BigCommerce server: compiles templates with context, serves storefront endpoints (catalog, cart, checkout)
• stencil-utils: client AJAX calls to BigCommerce APIs (cart, products, customer data)
d. Browser (Client)
• Loads HTML (generated by Handlebars) + CSS + JS bundle
• Feature-detects and loads polyfills if needed
• PageManager modules run per page type (category, product, cart, etc.)
• Interacts with external services (payment gateways, Yotpo reviews, social widgets)
Relationships & data flows
• Developer edits SCSS/JS/templates → triggers Grunt/Webpack → outputs static assets
• stencil push → theme zip uploaded to BigCommerce
• Customer’s browser requests a page → BigCommerce renders Handlebars templates with context → HTML + CSS + JS delivered
• Browser runs polyfill loader → main bundle executes → PageManager picks correct module by route → AJAX via stencil-utils to platform APIs → UI updates
Architectural patterns & design principles
• Separation of concerns:
• Build tools vs. source code vs. runtime
• Templates (view) vs. JS modules (controller behavior) vs. SCSS (style)
• Module bundling & code-splitting: Webpack config for production/dev
• Hook pattern in PageManager: before() → loaded() → after()
• Feature-detection & progressive enhancement (polyfills only when needed)
• Theme settings schema drives dynamic template rendering
• Clear labels for each component (e.g., “Webpack Bundler,” “Handlebars Templates,” “Stencil CLI,” “Browser”)
• Related assets (assets/js, assets/scss, templates) under a “Theme Package” container
• Technologies: Node.js, Grunt, Webpack, Handlebars, stencil-utils, ES6 modules, polyfills
• Lifecycle in Browser: feature-detect → load polyfills → load main.js → PageManager.loaded()