Chapter 5 - JavaScript Framework

Introduction

Chapter 5 covers the JavaScript framework powering the NETWRIX website 🚀. This custom architecture, built by Terra, combines modern tools like SWUP, GSAP, and Boostify to deliver seamless page transitions, optimized performance, and modular code organization.

Think of the JavaScript framework as the nervous system of the website - coordinating smooth animations, managing component lifecycles, and ensuring optimal performance across all user interactions.

Key Benefit

This framework enables SPA-like navigation without sacrificing SEO, delivers 60fps animations, and maintains clean memory management through coordinated lifecycle events.

---

What is the JavaScript Framework?

The NETWRIX JavaScript framework is a performance-focused architecture built on three core pillars:

1. Modular Structure - Components, handlers, and utilities organized for reusability
2. Performance Optimization - Strategic code splitting and lazy loading
3. Smooth Transitions - SWUP-powered page transitions with coordinated animations

Key Characteristics:

• 🎯 SWUP Integration: SPA-like navigation with SEO-friendly server-rendered HTML
• 📐 Handler System: Consistent lifecycle management for all components
• 🔄 Manager Registry: Centralized instance and library management
• 🎨 GSAP Animations: High-performance, timeline-based motion design
• 💪 Lazy Loading: Boostify-powered on-demand component loading

Location in Code: src/scripts/

Structure:

src/scripts/
├── Project.js          # Entry point & initialization
├── Core.js             # SWUP controller
├── Main.js             # Application controller
├── handler/            # Component lifecycle managers
├── module/             # Component classes
├── motion/             # Animations (heroes, reveals, transitions)
├── preload/            # Asset management & loading strategy
└── utilities/          # Helper functions

---

Framework Topics

Explore each framework topic in detail:

📚 Framework Overview

Learn about the three core files (Project.js, Core.js, Main.js), SWUP integration, and how the framework orchestrates page transitions and component initialization.

🎯 Classes Structure

Understand Terra’s strict class conventions, the four pillars of component architecture (constructor, init, events, destroy), and how to build SWUP-compatible components.

🔄 Handlers System

Master the Handler pattern for managing component lifecycle, learn about the Manager registry, and discover how handlers coordinate with SWUP transitions.

🎬 Animations with GSAP

Explore GSAP integration, page transition animations, hero reveals, scroll-triggered effects, and the coordinated animation system.

📦 Libraries & Tools

Discover the complete catalog of internal Terra libraries and external packages used in NETWRIX, including their purpose and usage patterns.

---

Quick Start Guide

For New Developers

If you’re new to the NETWRIX JavaScript framework, follow this learning path:

1. Start with Overview → Understand the three core files and SWUP lifecycle
2. Learn Classes → Master the component structure conventions
3. Practice Handlers → Build lifecycle-aware components
4. Explore Animations → Implement GSAP-based motion design
5. Review Libraries → Familiarize yourself with available tools

Common Questions

Q: What’s the difference between Project.js, Core.js, and Main.js?

• Project.js: Entry point, loads libraries, runs preloader
• Core.js: SWUP controller, manages page transitions
• Main.js: Application controller, initializes all handlers

Q: How do I create a new component?

1. Create the component class following Terra’s structure
2. Add it to extraAssets.js for lazy loading
3. Create a Handler to manage its lifecycle
4. Register the Handler in Main.js
5. Allocate instance pool in Project.js

Q: Why use Handlers instead of direct instantiation?

• Handlers ensure components are properly destroyed on page transitions
• They integrate with Boostify for performance optimization
• They provide consistent patterns across the codebase
• They prevent memory leaks in SWUP navigation

Q: How do I debug the framework?

• Add ?debug to any URL to enable debug mode
• Check console for library loading logs
• Inspect Manager.instances to view active components
• Use SWUP debug plugin to trace lifecycle events

---

Framework Architecture

The Three Core Files

┌─────────────┐
│ Project.js  │ ← Entry point, loads libraries, preloader
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Core.js   │ ← SWUP controller, page transitions
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Main.js   │ ← Application controller, handlers
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│  Handlers (30+ instances)       │
│  - SliderHandler                │
│  - ModalHandler                 │
│  - AlgoliaHandler               │
│  - etc.                         │
└─────────────────────────────────┘

Component Lifecycle Flow

1. Initial Page Load
   Project.js → loads GSAP, Boostify
   ↓
   Main.js → initializes handlers
   ↓
   Handlers → create component instances
   ↓
   Components → rendered and functional

2. User Clicks Link
   SWUP intercepts navigation
   ↓
   MitterWillReplaceContent event
   ↓
   Handlers → destroy instances
   ↓
   Out animation plays
   ↓
   SWUP fetches new page
   ↓
   Content replaced
   ↓
   In animation plays
   ↓
   MitterContentReplaced event
   ↓
   Handlers → create new instances

---

Key Concepts

SWUP Integration

SWUP enables SPA-like navigation while maintaining SEO benefits:

• No full page reloads - Content swaps via AJAX
• Server-rendered HTML - SEO-friendly, no client routing
• Lifecycle hooks - Control over content replacement
• Animation coordination - Smooth transitions between pages
• Script execution - Re-run page-specific scripts

Manager System

The Manager provides centralized registry for:

• Library References - GSAP, ScrollTrigger, Boostify, etc.
• Component Instances - All active sliders, modals, etc.
• Instance Pools - Pre-allocated arrays for each type
• Memory Management - Clean destruction prevents leaks

Handler Pattern

Handlers bridge the framework and components:

• Lifecycle Management - Init and destroy across transitions
• Smart Loading - Instant or lazy via Boostify
• Instance Tracking - Register with Manager
• Event Coordination - Listen to framework events

Performance Strategy

Code splitting and lazy loading optimize performance:

• Critical libraries - Loaded immediately (GSAP, Boostify)
• Above-fold components - Loaded instantly
• Below-fold components - Loaded on scroll proximity
• Third-party scripts - Deferred after page load

---

Framework Workflow

Creating a New Component

When building a new interactive element:

1. Create Component Class

   • Follow Terra’s four-pillar structure
   • Store DOM references in this.DOM
   • Implement init(), events(), destroy()

2. Add to extraAssets.js

   • Define library name and import path
   • Specify DOM selector for auto-detection

3. Create Handler

   • Extend CoreHandler
   • Listen to MitterContentReplaced and MitterWillReplaceContent
   • Use assignInstances() for creation

4. Register Handler

   • Add to Main.js initialization
   • Allocate instance pool in Project.js

5. Test Lifecycle

   • Verify component works on initial load
   • Test navigation (creation/destruction)
   • Check for memory leaks with debug mode

---

Debug Mode

Enable framework debugging by adding ?debug to the URL:

https://netwrix.com/page?debug

Debug Features:

• ✅ SWUP lifecycle event logging
• ✅ Library loading notifications
• ✅ Instance creation/destruction tracking
• ✅ Terra debugger UI for QA feedback
• ✅ Performance timing information

Console Output Examples:

✅ library Slider was in manager
🚧 loading library Modal
⏰ Boostify - loading library VideoPlayer
❌ Destroying Slider instances

---

Best Practices

✅ Do’s

• Use the Manager for all library references

  const gsap = Manager.getLibrary("GSAP").gsap;

• Follow Handler pattern for all components

  class MyHandler extends CoreHandler { }

• Implement destroy() in every component class

  destroy() {
    this.removeEventListeners();
    this.cleanup();
  }

• Leverage Boostify for below-fold components

  boostify.scroll({ distance: 50, callback: () => {} });

• Use emitter events for lifecycle coordination

  this.emitter.on("MitterContentReplaced", () => {});

❌ Don’ts

• Don’t bypass the Handler system - it ensures consistency
• Don’t forget destroy methods - causes memory leaks
• Don’t load all libraries upfront - use code splitting
• Don’t manipulate SWUP directly - extend Core.js instead
• Don’t skip instance pool allocation - required in Project.js

---

Framework Principles

Modular Architecture

Every piece of functionality is isolated and reusable:

• Components are self-contained classes
• Handlers manage component lifecycles
• Utilities provide shared functionality
• Animations are separate, composable modules

Performance First

Optimization is built into the architecture:

• Code splitting reduces initial bundle size
• Lazy loading defers non-critical components
• Memory management prevents leaks
• GSAP provides hardware-accelerated animations

Developer Experience

The framework prioritizes maintainability:

• Consistent patterns reduce cognitive load
• Clear separation of concerns
• Centralized management simplifies debugging
• Extensive documentation aids learning

---

Next Steps

Once you’ve mastered the JavaScript framework, you’re ready to build complex interactive features.

Recommended Learning Path:

1. 📚 Read Framework Overview to understand the architecture
2. 🎯 Study Classes Structure to learn component patterns
3. 🔄 Master Handlers System for lifecycle management
4. 🎬 Explore GSAP Animations for motion design
5. 📦 Review Libraries to see available tools

Performance Impact

Understanding this framework is crucial for maintaining NETWRIX’s fast, smooth user experience. Every component you build should integrate with this system to ensure proper lifecycle management and optimal performance.

---

Framework Resources

• Source Code: src/scripts/
• Handler Template: src/scripts/handler/_handlerFolder/Handler.js
• Asset Management: src/scripts/preload/extraAssets.js
• SWUP Documentation: https://swup.js.org/
• GSAP Documentation: https://greensock.com/docs/
• Boostify Documentation: https://www.npmjs.com/package/boostify

---

Summary

The NETWRIX JavaScript framework provides:

✅ Seamless Navigation - SPA-like experience with SEO benefits
✅ Smooth Animations - GSAP-powered 60fps motion design
✅ Optimal Performance - Code splitting and lazy loading
✅ Clean Architecture - Consistent, maintainable patterns
✅ Memory Safety - Proper lifecycle management prevents leaks

By mastering this framework, you ensure that every interactive feature you build integrates seamlessly with the existing architecture, maintains high performance, and follows established best practices.

🎯 Key Takeaway: The framework handles the complexity of page transitions, component lifecycle, and performance optimization - allowing you to focus on building great user experiences.

Happy coding! 🚀