Frontend Shell & React Islands
Relevant source files
The following files were used as context for generating this wiki page:
The FusionOps frontend architecture is a hybrid system utilizing Astro v6 as the static site generator and "shell," while leveraging React v19 for interactive "islands." This approach prioritizes performance by delivering minimal JavaScript to the browser while maintaining high interactivity for complex UI components like dashboards, wizards, and interactive landing page elements.
The primary dashboard UI (internal name LP Factory) resides in apps/lander/. It serves as a control plane for building and deploying PPC and affiliate landing pages, integrating with a Cloudflare Worker-based API and multiple database backends.
Sources: CLAUDE.md:31-41, AGENTS.md:1-5
Architecture Overview
FusionOps utilizes a "Static-First" philosophy. The frontend shell provides the structural layout and routing, while interactive features are encapsulated within React islands that are hydrated only when necessary.
Shell and Component Interaction
Astro serves as the primary framework, handling routing and static generation. React is used specifically for interactive components such as TemplateManager or TrackingDashboard. Interactive React components must use Astro's client directives (e.g., client:load or client:visible) to ensure proper hydration.
The diagram shows how the Astro shell hosts both static content and hydrated React islands using specific directives.
Sources: CLAUDE.md:31-41, files/bearloannow-repo-specific.md:5-15
Framework & Technology Stack
The frontend is built on a modern stack optimized for performance and type safety.
| Technology | Version | Purpose |
|---|---|---|
| Astro | v6.0.8 | Static site generation and shell routing |
| React | v19.2.0 | Interactive UI components (Islands) |
| TailwindCSS | v4.2.0 | Utility-first styling |
| Recharts | v3.7.0 | Data visualization for tracking dashboards |
| Lucide React | Latest | Iconography |
Sources: CLAUDE.md:35-41, files/bearloannow-repo-specific.md:5-15
Template System & Runtime Preview
A core feature of the shell is the ability to analyze and preview landing page templates dynamically. This is handled by the Template Analyzer and Template Preview Runtime.
Template Analysis
The system identifies the framework of imported templates (e.g., Astro, Vite+React, Next.js, or Static HTML) by scoring file structure signals. This allows the shell to determine if a build step is required or if the template can be rendered directly in the preview iframe.
The flow demonstrates the smart parsing pipeline for template imports.
Sources: src/utils/template-analyzer.js:21-31, src/utils/template-router.js:65-70
Preview Runtime Logic
The preview runtime constructs a self-contained HTML document for use inside an <iframe>. This prevents style leakage between the landing page template and the main dashboard shell.
Key operations include:
- Astro Stripping: Removing frontmatter and inlining sub-components.
- TypeScript Conversion: Stripping TS syntax from
<script>blocks for browser compatibility. - Variable Substitution: Replacing placeholders (e.g.,
${brand},${cta}) with live wizard values. - Dependency Injection: Injecting Tailwind CDN or Lucide UMD bundles if the template requires them.
- CSS Overrides: Injecting a cascading
<style>block to apply theme colors (primary, accent) without string-replacing the original source.
Sources: src/utils/template-preview-runtime.js:1-18, src/utils/template-router.js:246-270
Deployment & Build Pipeline
The frontend shell is deployed to Cloudflare Pages. The build process integrates tracking pixels and color schemes into the landing pages before final distribution.
The sequence illustrates the CI/CD pipeline from developer push to Cloudflare Pages deployment.
Sources: CLAUDE.md:144-155, INFRASTRUCTURE_SETUP.md:145-155
Component Hydration Guidelines
To maintain performance, components are hydrated selectively. The project follows these conventions for React island hydration:
- Header/Navigation: Uses
client:loadfor immediate availability. - Hero Sections/Forms: Uses
client:loadto ensure high-priority interactivity. - Stats/Features/FAQs: Uses
client:visibleto delay execution until the user scrolls to the section. - Static Sections: Built as pure Astro components (zero JS).
Sources: files/bearloannow-repo-specific.md:280-295, CLAUDE.md:231-235
Conclusion
The Frontend Shell and React Islands architecture provides a scalable way to manage numerous landing page templates while providing a high-performance administrative interface. By isolating landing page previews in secure runtimes and leveraging Astro's static generation for the main shell, the system ensures fast load times and robust campaign management capabilities.