Unify Your Web Stack with Dart and Jaspr: A Step-by-Step Migration Guide

Introduction

If you manage multiple websites built on different technologies and dream of a single, consistent stack your team already knows, you’re not alone. At Flutter, we faced this exact challenge: our three main sites—dart.dev, flutter.dev, and docs.flutter.dev—were powered by a fragmented mix of Node.js (Eleventy) and Python (Wagtail). Each site required different tooling and expertise, making contributions cumbersome and limiting code reuse. We wanted a unified solution built entirely on Dart, the language our team uses daily for Flutter apps. That solution turned out to be Jaspr, an open-source Dart web framework. In this how-to guide, we’ll walk through the steps we followed to migrate our websites, so you can apply the same approach to your own projects.

What You Need

• Dart SDK (version 2.17 or later) – for running commands and compiling.
• Familiarity with Dart and Flutter – understanding widgets and components helps.
• Jaspr CLI – install via dart pub global activate jaspr_cli.
• A static site generator (optional, but Jaspr can replace it).
• Your existing website’s content and code – to migrate.

Step-by-Step Migration Guide

Step 1: Assess Your Current Stack

Before migrating, map out all the technologies your websites rely on. In our case, the documentation sites used Eleventy (Node.js) while flutter.dev used Wagtail (Python). Identify:

• Which parts are static vs. dynamic?
• What interactive features exist (e.g., code samples, quizzes)?
• How are assets (CSS, images) managed?
• Who maintains each site and what skills do they have?

This assessment helps you plan a phased migration and understand where Jaspr’s capabilities (SSR, SSG, CSR) will be most beneficial.

Step 2: Choose Jaspr and Understand Its Model

Jaspr is a Dart web framework that supports client-side rendering (CSR), server-side rendering (SSR), and static site generation (SSG). It uses a component model similar to Flutter widgets. Review its documentation to see how its API maps to Flutter concepts. For example, a simple card component looks like this:

class FeatureCard extends StatelessComponent {
  const FeatureCard({
    required this.title,
    required this.description,
    super.key,
  });
  final String title;
  final String description;
  @override
  Component build(BuildContext context) {
    return div(classes: 'feature-card', [
      h3([.text(title)]),
      p([.text(description)]),
    ]);
  }
}

This familiarity allows Flutter developers to contribute immediately without learning a new paradigm.

Step 3: Set Up a New Jaspr Project

Initialize a new Jaspr project for one of your sites. Use the CLI:

jaspr create my_new_site
cd my_new_site

The project structure mirrors Flutter: a lib/ folder for components, a web/ folder for assets, and a pubspec.yaml for dependencies. Configure the site type (SSR, SSG, or mixed) based on your needs. For our documentation sites, we used SSG to pre-render pages.

Step 4: Migrate Content and Templates

Take the content from your old static site generator (Markdown files, HTML templates) and recreate them as Jaspr components. Since Jaspr supports HTML-in-Dart, you can directly translate templates. For example, a page layout becomes:

class DocsPage extends StatelessComponent {
  @override
  Component build(BuildContext context) => html([
    head([…]),
    body([
      nav([…]),
      main([…]),
      footer([…]),
    ])
  ]);
}

Use Dart’s string interpolation to inject dynamic data. For interactive elements like code samples, wrap them in Jaspr’s state management (similar to StatefulWidget).

Step 5: Incorporate Interactive Features

One of the biggest pain points in our old setup was adding interactivity. With Jaspr, you can add client-side behavior without resorting to imperative DOM manipulation. For example, a quiz component can use client(JaClient()) to run logic in the browser:

class Quiz extends StatefulComponent {
  @override
  State<Quiz> createState() => _QuizState();
}
class _QuizState extends State<Quiz> {
  int score = 0;
  @override
  Component build(BuildContext context) => div([
    // quiz UI with event handlers
  ]);
}

This approach keeps the codebase consistent and testable.

Step 6: Integrate Shared Components

Because all sites now use the same stack, create a shared library of components (header, footer, search bar) in a package. Reference it via pubspec.yaml dependencies. This eliminates duplication and ensures a uniform look and feel across dart.dev, flutter.dev, and docs.flutter.dev.

Step 7: Build and Test Locally

Run jaspr build to generate static files (if using SSG) or jaspr serve for a development server. Test each page for correctness, responsiveness, and interactive functionality. Use dart analyze to catch errors and the browser’s developer tools to debug client-side issues.

Step 8: Deploy

Deploy the output folder (usually dist/ for SSG) to your hosting provider. Jaspr produces plain HTML, CSS, and JavaScript, so it works with any static host (like Firebase, Netlify, or a CDN). For SSR, you’ll need a server capable of running Dart (e.g., Google Cloud Run). We chose SSG for documentation and deployed to the same infrastructure as before.

Tips for a Smooth Migration

• Start small – Migrate one site (e.g., docs) first to iron out the process.
• Leverage Flutter skills – Train your team on Jaspr’s component lifecycle (it’s almost identical to Flutter).
• Use separation of concerns – Keep content data separate from presentation (e.g., YAML or JSON files) to make future updates easier.
• Optimize assets – Use Jaspr’s asset pipeline to minify CSS/JS and lazy-load images.
• Monitor performance – After migration, run Lighthouse tests; Jaspr’s server-side rendering can improve First Contentful Paint.
• Contribute back – Jaspr is open source; report issues or contribute improvements as you learn.

By following these steps, you can unify your web stack around Dart and Jaspr, just as we did. The result is a single language and framework that your entire team can contribute to, reduced maintenance overhead, and a foundation for richer interactive features. Start your migration today and see how Jaspr turns your fragmented web presence into a cohesive, Dart-powered site.