Build and Layout investigation

[dlabaj]

Description

As a developer we would like to know how the Svelte code is generated to HTML, and if it will fit our documentation needs.

To Do

• Show how the output of the Svelte code looks in HTML. Does the build process give us minified code? Is there a way to get non minified code from vite and Svelte?
• Decide how we can use the output in our documentation framework. Are we going to generate all HTML and consume that? Is it going to be generated into markdown?
• Document pros and cons of moving to Svelte so the team can have a way to evaluate it compared to alternative solutions.
• Flush out the infrastructure and how a developer would add a component in core using Svelte.

Resources

Svelte Documentation
Vite Documentation

[mattnolting]

Flush out the infrastructure and how a developer would add a component in core using Svelte.

2024.stateofjs.com

Libraries Experience & Sentiment

Changes Over Time

Template System Migration Guide: From Handlebars to SvelteKit

Top-level Summary

Think of this like replacing a monolithic templating engine with microservices - while the system is still running. We're migrating from Handlebars to SvelteKit, but instead of a risky big-bang migration, we're taking the strangler fig pattern approach. The old system keeps running while we gradually wrap new functionality around it.

Core Strategy

• Keep the template manager as our abstraction layer
• Migrate components individually, like deploying microservices
• No downtime, no breaking changes
• Incremental improvements, testable at each step

The Migration Pattern

Our migration uses three key mechanisms to manage the transition from Handlebars to Svelte:

1. Routes - maintains the same URL structure while the underlying implementation changes

   /components/alert  →  Choose Implementation
   /modules/alert    →  Choose Implementation
   

2. Aliases - provides flexibility to point to either implementation

   $component/alert  →  Svelte Component
                    →  Handlebars Template
   

3. Feature Toggles - controls which implementation is active

   Component Request → Toggle → Implementation Choice
                           ├─→ Svelte 
                           └─→ Handlebars
   

This enables:

• Maintaining existing routes while changing implementations
• Switching between implementations using aliases
• Controlling which version is live
• Rolling back instantly if needed

Similar to how Git allows us to maintain multiple branches while developing new features, our migration maintains dual implementations during transition:

main (production) ----*----*----*----> (Handlebars)
                      \    \    \
feature branches       *----*----* --> (SvelteKit)

Architecture Evolution

Current: Handlebars System

templates/
└── base templates
    └── partial templates
        └── component templates

Target: SvelteKit Architecture

src/
├── lib/modules/
│   ├── components/      # Component library
│   ├── hbs/            # Legacy support
│   └── layouts/        # Layout system
└── routes/             # Page routing

Migration Path

Phase 1: Foundation

.svelte-kit/
└── src/
    └── lib/
        ├── modules/
        │   ├── components/    # New component system
        │   ├── hbs/          # Legacy template support
        │   ├── layouts/      # Layout architecture
        │   └── utilities/    # Shared utilities
        └── templates/        # Base templates

Phase 2: Component Migration

// Before: Handlebars Template
{{!-- alert-template.hbs --}}
<div class="alert {{modifier}}">
  {{content}}
</div>

// After: Svelte Component
<!-- Alert.svelte -->
<script>
  export let modifier = '';
  export let content = '';
</script>

<div class="alert {modifier}">
  {content}
</div>

Implementation Strategy

Template Manager Abstraction

class ModernTemplateManager {
  constructor() {
    this.templates = new Map();
    this.validators = new Map();
  }

  // Supports both systems during migration
  async render(name, context) {
    const template = this.templates.get(name);
    if (template.type === 'hbs') {
      return this.renderHandlebars(template, context);
    }
    return this.renderSvelte(template, context);
  }
}

Migration Workflow

1. Package Structure

   src/lib/modules/components/
   ├── Alert/
   │   ├── Alert.svelte    # New implementation
   │   └── alert.hbs      # Legacy support
   

2. Route Structure

   src/routes/
   ├── docs/
   │   └── components/
   │       └── alert/
   │           ├── +layout.svelte
   │           └── +page.svelte
   

3. Documentation Integration

   <!-- +page.svelte -->
   <script>
     import { Alert } from '$lib/modules/components';
   </script>
   
   # Alert Component
   <Alert type="success">
     Migration successful!
   </Alert>

Success Metrics

• Zero downtime during migration
• Component-by-component transition
• Maintained documentation coverage
• Improved developer experience

Rollback Strategy

Components maintain dual implementations until fully migrated:

render(name, context) {
  return this.useNewSystem
    ? this.renderSvelte(name, context)
    : this.renderHandlebars(name, context);
}

Developer Guide

1. Setup New Component

   └── src/
       └── lib/
           └── modules/
               └── YOUR_COMPONENT/
                   ├── index.ts
                   ├── Component.svelte
                   └── legacy.hbs

2. Migration Steps

   // 1. Create Svelte version
   // 2. Test in isolation
   // 3. Update documentation
   // 4. Remove legacy template

[mattnolting]

Migration Analysis & Strategy

Overview

The migration from Handlebars to Svelte focuses on automated conversion with zero downtime. Our approach leverages parallel systems and feature toggles, allowing gradual migration with minimal risk. The strategy prioritizes business continuity while modernizing our template system.

Compatibility Pattern

A visual representation of how much of our current system can be automatically migrated to each framework option.

From Handlebars To:
--------------------
Svelte:  [==========--------] 60% automatible
JSX:     [=======------------] 70% manual conversion
Astro:   [========-----------] 80% partial reuse

Migration Path Effort

Comparison of effort required for each framework option, highlighting Svelte's advantages in automated conversion and parallel running systems.

Svelte Approach:
--------------------
1. Automated conversion     → 60% of templates
2. Parallel systems        → Zero downtime
3. Component-by-component  → Gradual rollout
4. Feature toggles         → Instant rollback

Automation Potential

Overview of how Handlebars syntax patterns can be automatically converted to Svelte, demonstrating the straightforward mapping between the two systems.

Handlebars → Svelte Script:
--------------------
{{#if condition}}     →  {#if condition}
{{content}}           →  {content}
{{/if}}               →  {/if}

Migration Script Concept

A systematic approach to automating the conversion process while identifying areas requiring manual attention.

Migration Tool:
--------------------
1. Parse Handlebars templates
2. Convert syntax patterns
3. Generate Svelte components
4. Maintain existing logic
5. Create parallel structures
6. Enable feature toggles

Remaining Manual Work:
--------------------
1. Complex logic conversion
2. State management updates
3. Event handler adjustments
4. Component optimization

Key Benefits:

• Automated conversion reduces manual effort
• Zero downtime maintains business continuity
• Component-by-component migration minimizes risk
• Feature toggles enable instant rollback
• Parallel systems allow thorough testing

[mattnolting]

# The Business Case for Migration

## Why Change is Necessary

Our current Handlebars system, while functional, is costing us significant time and money through hidden inefficiencies. Let's talk about what this means day-to-day:

### Time is Money
Developers currently spend more time wrestling with the system than building features. When a bug appears, they're forced to play detective across multiple repositories and files just to find where the issue originates. This isn't just frustrating - it's expensive. Every hour spent searching through templates and partials is an hour not spent delivering value.

### The Maintenance Nightmare
Our maintenance situation is precarious. Templates are scattered across repositories with no clear ownership. Documentation is sparse and often outdated. This creates several critical business risks:
- Knowledge is locked in the heads of a few developers
- Onboarding new team members takes weeks longer than it should
- Making system-wide changes is risky and time-consuming
- Bug fixes often introduce new problems due to unclear dependencies

### Developer Experience Matters
The current framework actively works against our developers. Simple tasks become complex operations. Modern development practices are difficult or impossible to implement. This leads to:
- Increased frustration and potential turnover
- Longer development cycles
- Higher error rates
- Resistance to making necessary changes

### Future-Proofing Our Investment
Handlebars is essentially frozen in time. While the rest of the web development world has moved forward with modern practices and tooling, we're stuck with:
- Limited extensibility
- No modern development tooling
- Poor testing capabilities
- Outdated development practices

## The Svelte Advantage

By moving to Svelte, we're not just updating our technology - we're investing in our development team's productivity and our product's future. Here's what changes:

### Immediate Benefits
- Developers can focus on building features instead of fighting the system
- Changes are isolated and testable, reducing risk
- Modern tooling enables faster development and better quality
- Clear documentation and active community support

### Long-term Gains
- Easier recruitment - developers want to work with modern technology
- Better retention - less frustration means happier developers
- Faster feature delivery - less system overhead means more time for actual development
- Reduced risks - better testing and isolation means fewer critical bugs

## The bottom line? 
This migration isn't just a technical upgrade - it's a business investment that will pay dividends in faster development, better quality, and improved team satisfaction.

[mattnolting]

Vite + Svelte: Development Experience

Hot Module Replacement (HMR)

Current Process

When a developer makes a change:

Change file → Full page reload → Lose application state → Navigate back to spot
                  ↓
        Developer breaks focus
                  ↓
     Loses minutes per code change

With Vite + Svelte

When a developer makes a change:

Change file → Instant update → State preserved → Continue working
                  ↓
      Developer stays focused
                  ↓
    Continuous flow maintained

Build Performance

Development Build Times

Traditional Build:
Initial Build:    45-120 seconds
Rebuild:          10-30 seconds
State:            Lost on every change

Vite:
Initial Start:    < 1 second
Updates:          < 50ms
State:            Preserved

Production Build Times

Traditional Build:
Full Build:       3-5 minutes
Code Splitting:   Manual configuration
Cache Handling:   Complex setup

Vite:
Full Build:       30-60 seconds
Code Splitting:   Automatic
Cache Handling:   Built-in optimization

The impact? A developer making 50 changes per day saves:

• 25+ minutes in build waiting time
• 30+ minutes in lost context switching
• Hours in reduced frustration and maintained focus

This isn't just about faster builds - it's about maintaining developer flow state and eliminating the micro-frustrations that kill productivity.

[srambach]

I'm curious about automatically converting templates, both how that works and how you figured out the number that can be converted automatically.

Another thing I was wondering about was our handlebars helper functions - are there equivalents or is that something we'd also transition over, or code around?

[dlabaj]

@mattnolting Thanks for putting this together there's a lot of good details here. Do you mind putting up a PR with a svelte-handlebars-spike.md file containing the documentation you have above? I added a documentation folder called docs/spikes to this project where I thought we could put our spike results documentation? This way we all can leave feedback, have a discussion, and reviews around spikes. Thanks again.