Build System & Workspace
Relevant source files
The following files were used as context for generating this wiki page:
The Build System and Workspace for the RoundingWell frontend project is a modern JavaScript environment built around Vite and npm workspaces. It handles the compilation of legacy and modern assets, including Backbone/Marionette modules, Handlebars templates, and SCSS, into a highly optimized production bundle.
The workspace is structured to support modularity through local packages (found in packages/) while maintaining a core application in src/. The build process includes sophisticated asset transformation, environment-specific configurations (Dev, Test, Production), and a robust deployment pipeline that targets AWS infrastructure.
Workspace Architecture
The project utilizes npm workspaces to manage internal libraries and shared dependencies. These packages are treated as local modules that can be imported across the application.
Local Packages (Workspaces)
The following internal packages are defined within the workspace:
packages/care-ops-authpackages/care-ops-configpackages/care-ops-datadogpackages/care-ops-five9packages/care-ops-fontawesomepackages/care-ops-ringcentral
Sources: package.json:13-20
Directory Structure & Aliases
Vite is configured to handle specific path aliases and module resolutions, allowing for cleaner imports without relative paths. For instance, marionette is aliased to backbone.marionette, and the build system looks into node_modules, src, and test (during tests) for module resolution.
Sources: vite.config.js:28-32, vite.config.js:100-103
Build Process & Configuration
The build system is powered by Vite, utilizing a series of plugins to handle the project's specific templating and styling needs.
Asset Transformation
The build pipeline includes custom plugins for non-standard file types:
- Handlebars: Templates are precompiled via
vite-plugin-handlebars-loader. - Inline Handlebars: Support for ``hbs```` template literals via
vite-plugin-inline-handlebars. - Sass: Global variables are automatically injected from
src/scss/provider-variables.scssinto every SCSS file. - YAML: Configuration files are processed via a YAML plugin.
Sources: vite.config.js:20-23, vite.config.js:77-83, src/js/views/README.md:27-46
Build Lifecycle
The project defines a multi-stage build process to ensure shared runtimes and application assets are properly prepared.
The diagram above shows the sequential dependencies required to produce a final distribution.
Sources: package.json:28-35, scripts/deploy.js:199-201
Build Configurations
| Mode | Purpose | Port | Key Features |
|---|---|---|---|
development | Local iteration | 8081 | HMR, Proxy to VITE_DEV_API_URL |
test | Unit/E2E testing | 8090 | Istanbul instrumentation, no HMR |
production | Deployment | N/A | PWA manifest injection, code splitting, minification |
Sources: vite.config.js:123-145, vite.config.js:154-165
Release Management
Releases are managed via a tag-based system. The scripts/release.js utility ensures that releases are only created from authorized branches (develop or release/*) and that the local environment is synchronized with the remote.
Tagging Strategy
The system generates immutable tags in the format vYYMMDD.N.
- YYMMDD: Current UTC date.
- N: Daily sequence number (starts at 1).
Sources: README.md:38-43, scripts/release.js:192-205
Release Flow
This diagram illustrates the safety checks performed by the release script before pushing a new immutable version tag.
Sources: scripts/release.js:235-272
Deployment Pipeline
The deployment system is an AWS-centric flow that identifies target environments via CloudFormation tags and uploads assets to S3.
Infrastructure Mapping
The scripts/deploy.js script queries AWS for stacks that match specific stage and organization tags to find the correct WebsiteBucket.
Sources: scripts/deploy.js:63-78
Deployment Logic
- AppConfig Generation: Before upload,
scripts/generate-appconfig.jsfetches organization-specific secrets from AWS Secrets Manager to create a localappconfig.json. - Asset Upload: Files are uploaded to S3 with appropriate Content-Types. Root files like
index.htmlandsw.jsare uploaded last to ensure an atomic-like cutover. - Cache Control: Shared runtime assets are assigned
no-cacheheaders, while hashed assets rely on long-term caching. - CloudFront Invalidation: After S3 upload, the system triggers an invalidation for the distribution ID found in the organization's secrets.
Sources: scripts/deploy.js:158-165, scripts/deploy.js:189-195, scripts/generate-appconfig.js:127-142
Summary
The Build System and Workspace provide a tightly integrated environment that bridges the gap between RoundingWell's legacy Backbone/Marionette architecture and modern frontend tooling. By leveraging Vite for rapid development and custom Node.js scripts for AWS-integrated deployment, the system ensures consistent delivery of localized, branded organization environments across multiple deployment stages.