---
title: Version 0.22.0
description: Release notes and breaking changes.
---

---

## Overview

Version 0.22.0 is all about **reducing magic** in the framework and making it more **expressive and modular**.

The main features are:

- **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.

- **Discontinued `jaspr_web_compilers`**: Flutter support can now be enabled through the `jaspr.flutter` config option in `pubspec.yaml`.

- **Various Styling Improvements**: New CSS properties like `animation` and `quotes`, improved properties like `Transition`, better support for dot-shorthands and more.


<Success>
Most changes can be **automatically migrated** using the `jaspr migrate` command.

If you are on the latest Dart and want the migrations to use dot-shorthands, additionally add `--feature=dot-shorthands`.
</Success>

---

## 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:

```dart
// 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`.

### 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

<Success>
After upgrading Jaspr CLI to `0.22.0`, you can use the `jaspr migrate` command to **automatically migrate your code** to the new entrypoint system.
</Success>

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.

Also it is now possible to debug and inspect the client-side hydration process more easily, as the `ClientApp` component is now explicitly visible in the code.

## 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.

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

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

### Migration

<Success>
After upgrading Jaspr CLI to `0.22.0`, you can use the `jaspr migrate` command to **automatically migrate (most of) your code** to the new entrypoint system.
</Success>

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.

## Flutter Support

Jaspr used to support Flutter plugins and Flutter embedding through a custom `build_web_compilers` fork called `jaspr_web_compilers`. A range of changes has been landed upstream and so the fork is no longer needed and has been discontinued. Please replace all dependencies on `jaspr_web_compilers` with `build_web_compilers` and ensure a minimum version of `4.4.6`.

To continue using Flutter embedding or plugins, add the following to your `pubspec.yaml`:

```yaml
jaspr:
  flutter: embedded # or 'plugins' for plugin support
```

## New and Improved CSS Properties

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

```dart
Animation animation
Quotes quotes
```

Also 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:

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

Additionally, some APIs were improved for better ergonomics when using dot-shorthands:

- `Gap.row()` and `Gap.column()` constructors.
- `Flex.grow()`, `Flex.shrink()` and `Flex.basis()` constructors.
- `Border.all()` constructor.