Version 0.22.0

TLDR / Overview

Version 0.22.0 ships separate entrypoints for server and client environments to decrease magic in the framework and make it more transparent what is happening under the hood. It also splits all DOM related APIs into a separate library for better modularity and reimplements all HTML components as classes instead of functions.

TL;DR

• Separate Entrypoints: Each project can now contain a main.server.dart (in server and static mode) and main.client.dart (in all modes) file. Related APIs are updated to reflect this.
• Improved @client initialization: Any @client component is now initialized by using the new ClientApp component in main.client.dart, which can be wrapped with other components for sharing state, running custom initialization logic and more.
• New package:jaspr/dom.dart library: All DOM related APIs (HTML components, Styles, css, etc.) have been moved into a separate library for better modularity.
• Reimplemented HTML Components as Classes: All HTML components have been reimplemented as classes instead of functions, allowing const usage.
• Allow binary responses: The AppContext.setStatusCode method now accepts binary data for overriding the response body.
• Various Styling Improvements: New CSS properties like animation and quotes, improved properties like Transition, better support for dot-shorthands and more.

Project Entrypoints

The project can now contain separate entrypoints for server and client environments:

• <file>.server.dart (in server and static mode)
• <file>.client.dart (in all modes)

The generated global options file (previously jaspr_options.dart) is now generated as <file>.server.options.dart alongside the entrypoint, and an additional <file>.client.options.dart is generated for client-side code.

Client Initialization

The default main.client.dart file should look like this:

// Previously 'browser.dart', now renamed.
import 'package:jaspr/client.dart';

// Generated options file.
import 'main.client.options.dart';

void main() {
  Jaspr.initializeApp(
    options: defaultClientOptions,
  );

  runApp(
    // New component to initialize @client components.
    const ClientApp(),
  );
}

This surfaces previously hidden functionality of the framework related to the initialization of @client components on the client and thereby makes it easier to debug and understand what is happening.

Futher, the new ClientApp component may be wrapped with other (Inherited) components to share state across multiple @client components, or to run custom initialization logic before calling runApp.

Flutter Plugin Support

Jaspr supports using Flutter web plugins through the jaspr_web_compilers package. Part of the required setup logic related to plugins has now moved into the .client.options.dart file. To continue using plugins, make sure to use the latest version of jaspr_web_compilers together with the new entrypoint system.

Changed browser library to client

The package:jaspr/browser.dart library has been renamed to package:jaspr/client.dart to better reflect its purpose. The migration can be performed automatically using the jaspr migrate command.

Migration

In case you need or want to migrate your code manually, rename lib/main.dart to lib/main.server.dart and create a new lib/main.client.dart file with the content shown above. Additionally, rename all package:jaspr/browser.dart imports to package:jaspr/client.dart.

Reason for the Change

The goal of this change is to reduce the "magic" in the framework and make it more transparent what is happening under the hood. This comes with the added benefit of enabling custom initialization logic, and sharing state across multiple @client components, a feature that was frequently requested.

This change also allowed to move parts of the jaspr_web_compilers package (fork of build_web_compilers) into the main Jaspr framework, which will make it easier to maintain the fork in the future and starts work towards removing the need for the fork altogether in the future.

DOM APIs

All DOM related APIs (div() et al., Styles, css, Color et al., events(), RawText, and ViewTransitionMixin) have been moved into a separate package:jaspr/dom.dart library for better modularity.

HTML Class Components

All HTML components have been reimplemented as classes instead of functions. This is technically a breaking change, but it is expected to not affect most users.

Deprecated Helper Functions

Deprecated text(), fragment() and raw() functions in favor of Component.text(), Component.fragment() and RawText, respectively.

The new API is designed to work well with dot-shorthands while allowing const usage.

// Before:
text('Hello World');
fragment([ ... ]);
raw('<div>Raw HTML</div>');

// After (with dot-shorthands):
.text('Hello World');
.fragment([ ... ]);
RawText('<div>Raw HTML</div>');

Migration

In case you need or want to migrate your code manually, add new package:jaspr/dom.dart imports where needed.

In most cases, the new HTML class components should not need any migration, as they keep their lowercase names. One exception to this is when used with inferred typing (such as var child = div([]);), which may now require an explicit type annotation (such as Component child = div([]);) when assigning other values (such as child = span([]);).

Reason for the Change

The new library reduces the "pollution" of the global namespace when importing package:jaspr/jaspr.dart and allows for more fine-grained control of imported APIs.

The class components allow for using const on html component trees, which can improve performance. Also this makes the overall code more consistent and aligned with best-practices for writing components. As an exception to the general rule, the HTML components continue to use lowercase names to keep the familiar html-like syntax and differentiate them to other components.

Binary Responses

The context.setStatusCode method now allows binary data (Uint8List) for overriding the response body. Respectively, the related ResponseLike.body property (returned from renderComponent()) is now a Uint8List instead of a String.

New and Improved CSS Properties

The following css properties have been added to Styles() and css.styles():

Animation animation
Quotes quotes

Also added:

• Curve.linearFn() easing function
• Gap.row() and Gap.column() constructors.
• Flex.grow(), Flex.shrink() and Flex.basis() constructors.
• Border.all() constructor.

The duration and delay properties of Transition now accept Duration instead of double. For convenience, ms and seconds extensions to int are added for simple conversion:

transition: Transition('width', duration: 2.seconds, delay: 300.ms),