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.

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

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.

Tags: