jaspr 0.16.2

Modern web framework for building websites in Dart that feels like Flutter but supports server-side rendering.

Quickstart • Documentation • Playground • Examples • Community & Support • Benchmarks

Jaspr

A modern web framework for building websites in Dart with support for both client-side and server-side rendering.

• 🔮 Why?: Jaspr was made with the premise to make a web-framework that looks and feels just like Flutter, but renders normal html/css like Vue or React.
• 👥 Who?: Jaspr is targeted mainly at Flutter developers that want to build any type of websites (especially ones that are not suitable for Flutter Web).
• 🚀 What?: Jaspr wants to push the boundaries of Dart on the web and server, by giving you a thought-through fullstack web framework written completely in Dart.

Want to contribute to Jaspr? Join our open Discord Community of developers around Jaspr and check out the Contributing Guide.

Core Features

• 💙 Familiar: Works with a similar component model to flutter widgets.
• 🏗 Powerful: Comes with server side rendering out of the box.
• ♻️ Easy: Syncs component state between server and client automatically.
• ⚡️ Fast: Performs incremental DOM updates only where needed.
• 🎛 Flexible: Runs on the server, client or both with manual or automatic setup. You decide.

If you want to say thank you, star the project on GitHub and like the package on pub.dev 🙌💙

Online Editor & Playground

Inspired by DartPad, Jaspr has it's own online editor and playground, called JasprPad.

Check it out here!

You can check out the samples, take the tutorial or try out jaspr for yourself, all live in the browser. When you want to continue coding offline, you can quickly download the current files bundled in a complete dart project, ready to start coding locally.

JasprPad is also built with Jaspr itself, so you can check out its source code to get a feel for how jaspr would be used in a larger app.

Outline

• Get Started
• CLI Tool
• Framework
• Differences to Flutter(-Web)
• Building
• Testing

🛫 Get Started

To get started simply activate the jasper_cli command line tool and run jaspr create:

dart pub global activate jaspr_cli
jaspr create my_website

Next, run the development server using the following command:

cd my_website
jaspr serve

This will spin up a server at localhost:8080. You can now start developing your web app. Also observe that the browser automatically refreshes the page when you change something in your code, like the Hello World text.

🕹 Jaspr CLI

Jaspr comes with a cli tool to create, serve and build your website.

• jaspr create will create a new jaspr project. The cli will prompt you for a project name and setup options.
• jaspr serve will serve the website in the current directory, including hot-reloading.
• jaspr build will build the website containing the static assets (compiled js, html, images, etc.) and the optional server executable.

Framework

Jaspr was developed with the premise to look and feel just like Flutter. Therefore when you know Flutter you probably already know jaspr (in large parts).

The core building block of UIs build with jaspr are Components. These are just what you know as Widgets from Flutter. jaspr comes with all three base types of Components, namely:

• StatelessComponent: A basic component that has a single build method.
• StatefulComponent: A component that holds state and can trigger rebuilds using setState().
• InheritedComponent: A component that can notify its dependents when its state changes.

In addition to these base components, there are also all html elements available as components:

div([
  h1([text('Welcome to Jaspr')]),
  p([text('This is some basic html!')])]),
]);

Check the Docs for more

Differences to Flutter(-Web)

As you might know Flutter renders Widgets by manually painting pixels to a canvas. However rendering web-pages with HTML & CSS works fundamentally different to Flutters painting approach. Also Flutter has a vast variety of widgets with different purposes and styling, whereas in html you can uniquely style each html element however you like.

Instead of trying to mirror every little thing from Flutter, jaspr tries to give a general Fluttery feeling by matching features where it makes sense without compromising on the unique properties of the web platform. Rather it embraces these differences to give the best of both worlds.

1. The build() method of a StatelessComponent or StatefulComponent returns an Iterable<Component> instead of a single component. This is because a HTML element can always have multiple child elements. The recommended way of using this is with a synchronous generator. Simply use the sync* keyword in the method definition and yield one or multiple components:

   class MyComponent extends StatelessComponent {
     @override
     Iterable<Component> build(BuildContext context) sync* {
       yield ChildA();
       yield ChildB();
     } 
   }
   

   Trade-Off: Returning a single component and having an extra multi-child component would be superficial to how html works and thereby not a good practice.

2. Jaspr does not care about the styling of components. There are (currently) no prestyled components like in Flutters material or cupertino libraries.

   Trade-Off: Providing styled components would be a lot of extra work and is currently not feasible. Also there exist a lot of different, well established CSS frameworks for web that you can already integrate and use with jaspr (e.g. Bulma.

3. Text receives only a String and nothing else. As usual for web, styling is done through a combination of CSS attributes, either in a Stylesheet or though the style attribute of the parent elements.

   Trade-Off: Giving Text a style option would be superficial and not native to web, and thereby not a good practice.

Building

You can build your application using the following command:

jaspr build

This will build the app inside the build/jaspr directory.

Testing

jaspr comes with it's own testing package jaspr_test. It is built as a layer on top of package:test and has a similar api to flutter_test.

A simple component test looks like this:

// This also exports 'package:test' so no need for an additional import.
import 'package:jaspr_test/jaspr_test.dart';

// Import the components that you want to test.
import 'my_component.dart';

void main() {
  group('simple component test', () {
    testComponents('renders my component', (tester) async {
      // We want to test the MyComponent component.
      // Assume this shows a count and a button to increase it.
      tester.pumpComponent(MyComponent());

      // Should render a [Text] component with content 'Count: 0'.
      expect(find.text('Count: 0'), findsOneComponent);

      // Searches for the <button> element and simulates a click event.
      await tester.click(find.tag('button'));

      // Should render a [Text] component with content 'Count: 1'.
      expect(find.text('Count: 1'), findsOneComponent);
    });
  });
}

For more examples on how to use the testing package, check out the documentation and the tests in the jaspr package.