Unifying Flutter and Dart Websites: A Migration to Jaspr
Previously, the official websites for Dart and Flutter—dart.dev, flutter.dev, and docs.flutter.dev—were built using a hodgepodge of different technologies: Eleventy (Node.js) for documentation and Wagtail (Python/Django) for the main Flutter site. This fragmentation required contributors to be skilled in multiple non-Dart ecosystems, complicating contributions and limiting code reuse. To streamline development and unlock richer interactive features, the team migrated all three sites to Jaspr, a Dart-based open-source web framework. Below are key questions and answers about this migration.
Why did the original websites need to be rebuilt?
The previous setup was fragmented across different tech stacks. The documentation sites used Eleventy (Node.js), while flutter.dev used Wagtail (Python). Anyone wanting to contribute needed expertise in Node.js, Python, or both, on top of Dart. This increased setup time and created friction for the community and internal teams. Moreover, as the sites grew, adding interactive elements like code quizzes or dynamic code samples became increasingly difficult—each new feature required custom, one-off DOM logic that was hard to maintain. A unified solution was needed to reduce complexity and make development smoother for the team.
What is Jaspr and why was it chosen?
Jaspr is a versatile Dart web framework supporting client-side rendering, server-side rendering, and static site generation. It was chosen because it is built entirely in Dart, the language the Flutter and Dart teams already use daily. Unlike other frameworks, Jaspr is designed to feel natural to Flutter developers: its component model mirrors Flutter widgets. For example, a typical Jaspr component looks like a Flutter widget but outputs HTML elements. This means developers can apply their existing Flutter skills directly to building websites, without learning a new language or toolchain. Jaspr also integrates well with existing Dart tooling, making the migration a natural step.
How did Jaspr solve the fragmentation problem?
By adopting Jaspr across all three websites, the team unified the entire stack under a single language: Dart. Now, instead of switching between Node.js for one site and Python for another, contributors only need Dart. This drastically reduces the learning curve for new contributors and allows code sharing between sites. For instance, shared components like navigation bars or interactive code snippets can be written once and reused across dart.dev, flutter.dev, and docs.flutter.dev. The unified stack also simplifies build tooling and deployment, since only Dart’s ecosystem is used. As a result, the development experience is consistent, and the team can spend more time on features rather than managing multiple toolchains.
How does Jaspr leverage Flutter developer skills?
Jaspr’s component model is explicitly designed to be familiar to Flutter developers. A component in Jaspr is declared with a class that extends StatelessComponent and implements a build method that returns a tree of HTML elements. This is analogous to Flutter’s widget tree. For example, a FeatureCard component in Jaspr looks very similar to a Flutter widget: it accepts typed parameters and constructs a UI using functions like div(), h3(), and p(). Flutter developers can immediately understand this structure and start building. Additionally, Jaspr supports state management patterns familiar from Flutter, such as using @State annotations for mutable state. This transfer of skills lowers the barrier for the large Flutter community to contribute to the websites.
What interactive features did Jaspr unlock for the sites?
With the previous fragmented stack, adding interactivity—like code quizzes, live code samples, or interactive diagrams—required complex, one-off JavaScript or DOM manipulation. Jaspr enables a more seamless approach. Because Jaspr supports both server-side rendering and client-side interactivity, the team can build interactive components using Dart that hydrate on the client. For example, a tutorial quiz that checks answers can be implemented entirely in Dart, run the same logic on the server and client, and be easy to maintain. This opens up possibilities for richer learning experiences, such as step-by-step code walkthroughs or real-time feedback, all without leaving the Dart ecosystem. The result is a more engaging website that’s simpler to author and maintain.
What impact did the migration have on contributors and the team?
The migration to Jaspr simplified the contributor experience significantly. Previously, contributing to documentation required setting up Node.js tooling, while the main site required Python and Wagtail. Now, any contributor familiar with Dart can work on any of the three sites with minimal additional setup. The team also reports a reduction in maintenance burden, as there’s no longer a need to keep up with updates in separate ecosystems. Internally, developers can share components and logic across sites, boosting productivity. For the community, this means smoother pull requests and faster improvements to the documentation and landing pages. The unified Dart stack aligns with the company’s goal of simplifying the developer journey for Flutter and Dart users.
Will the Flutter documentation style change because of Jaspr?
The migration to Jaspr changes the underlying technology but not the visual appearance or content structure of the documentation. The sites still display the same polished Flutter and Dart documentation, with the same layouts and styling. However, the team now has greater flexibility to add modern web features, such as improved search, interactive examples embedded in pages, or faster page loads. The core reading experience remains consistent, but behind the scenes, the sites are now built more efficiently. Contributors will notice that the code that generates the documentation is now written in Dart, making it easier for Flutter developers to suggest improvements or fix bugs in the site’s functionality.