jaspr_cli

The following packages have been updated:
jaspr_test : 0.23.3 -> 0.23.4
jaspr : 0.23.3 -> 0.23.4
jaspr_builder : 0.23.3 -> 0.23.4
jaspr_cli : 0.23.3 -> 0.23.4

• Server rendering now fails with a 500 HTTP response instead of hanging indefinitely when an error occurs during the initial build, outside of a component's build method.
• Worked around a Dart VM bug that caused server rendering to crash on linux_x64 due to a NoSuchMethodError inside TaskChain.then.

The following packages have been updated:
jaspr_test : 0.23.2 -> 0.23.3
jaspr : 0.23.2 -> 0.23.3
jaspr_builder : 0.23.2 -> 0.23.3
jaspr_router : 0.8.3 -> 0.9.0
jaspr_cli : 0.23.2 -> 0.23.3
jaspr_content : 0.5.3+1 -> 0.5.4
dart_quotes : 0.1.12 -> 0.1.13 (No Changelog)
dart_quotes_server : 0.1.12 -> 0.1.13 (No Changelog)
fluttercon : 0.0.13 -> 0.0.14 (No Changelog)
website : 0.1.8 -> 0.1.9 (No Changelog)

• Added detachRootComponent() to ComponentsBinding to cleanly unmount the root component.
• Updated testClient in jaspr_test to automatically unmount the root component and clean up document.body between test cases.
• Fixed asynchronous errors escaping the development proxy when falling back to the app root.
• Fixed repeated copying of nested build assets.
• The sitemap priority tag is now omitted when a route has no priority set, instead of always defaulting to 0.5.
• Fixed a misconfiguration of server hotreload that caused jaspr serve consuming excessive CPU.
• Require build_daemon ^4.1.4 to fix build error due to version mismatch.

• Added basePath property to AppBinding to support hosting applications under a sub-path.
• Exposed basePath parameter in testComponents and handlerPath in ServerTester.request to support testing under custom base paths.
• Support analyzer ^12.1.0.
• Added a --port option to jaspr build for configuring the server port used during static generation.

• Fixed expression compilation when debugging a client-side application with an AOT installed CLI.
• No longer generates empty css files in standalone mode when no @css declarations are used.
• Jaspr now uses OS-specific directories for its settings and cache, better respecting platform conventions.
  • The old directory at '~/.jaspr/' is automatically migrated to the new locations on first run.
  • The new directory location is:
    • when DART_DATA_HOME environment variable is set: $DART_DATA_HOME/jaspr
    • on Windows: %LOCALAPPDATA%\Dart\jaspr
    • on Mac OS: $HOME/Library/Application Support/Dart/jaspr
    • on Linux: $XDG_STATE_HOME/Dart/jaspr if $XDG_STATE_HOME is defined, and $HOME/.local/state/Dart/jaspr otherwise.
• The cli completion files are no longer auto-installed when the JASPR_NO_COMPLETION environment variable is set.

title: Version 0.23.0 description: Release notes and breaking changes.

Agent Skills for Jaspr

Jaspr now ships with a set of agent skills to improve the experience of using Jaspr with AI code generation tools.

These skills can be installed by running jaspr install-skills in your project directory. The install location depends on the AI tool you are using and can be configured via the --agent flag.

For example to install the skills for Antigravity, use jaspr install-skills --agent=antigravity.

Use jaspr install-skills -h to get the list of all available agents.

When updating Jaspr you also should update the installed skills by running jaspr install-skills again. The cli will automatically detect if the installed skills are outdated, or when new skills are available.

The following skills are available:

CLI Improvements

The Jaspr CLI is now installable with dart install jaspr_cli.

This will install the CLI as an AOT executable and is faster than the previous version installed via dart pub global activate.

<Info> When installing the CLI with dart install jaspr_cli, make sure to remove any previous global activation of jaspr_cli. You can do this by running dart pub global deactivate jaspr_cli. </Info>

Added a new jaspr convert-html command to automatically convert raw HTML to clean and idiomatic Jaspr code.

This is used by the new jaspr-convert-html agent skill, but can also be used manually by providing a file path or URL to the command.

• From a local file: jaspr convert-html --file some/path/to/file.html
• From a URL: jaspr convert-html --url https://example.com

If you only need a portion of the HTML, you can use the --query option with a CSS selector to target specific elements rather than converting the whole file and deleting pieces manually.

jaspr convert-html --file some/path/to/file.html --query "#my-id"

This will only convert and output the element with the id my-id.

Standalone CSS Generation

Jaspr now supports generating a standalone .css file for your styles declared with @css.

To enable this feature, add the following option to your pubspec.yaml:

jaspr:
  styles: standalone

By default, all styles declared with @css are inlined in the pre-rendered HTML. When standalone mode is enabled, all styles are extracted to a separate .css file and linked in the pre-rendered HTML. This can improve the initial load time of your website, since the browser can more efficiently cache the css file.

Additionally, @css is now also supported in client mode projects, where standalone mode is enabled by default.

Unsafe Imports Lint Rule

A new lint rule unsafe_imports has been added to jaspr_lints. It will detect and warn about unsafe platform-specific imports in components depending on where they are rendered (server or client).

For example, if a component imports e.g. dart:io or package:jaspr/server.dart but is rendered on the client, it will be flagged as unsafe. Similarly, if a component imports e.g. dart:js_interop or package:jaspr/client.dart but is rendered on the server, it will be flagged as unsafe.

This will help you to avoid compilation errors due to wrong imports, which before were quite hard to debug.

<Info> To further improve your experience, consider using the Jaspr VSCode Extension, which will give you in-editor hints for each component on where they are rendered (server, client, or both). </Info>

• Added Agent Skills for Jaspr, which can be installed with jaspr install-skills.

• Multiple improvements to the Jaspr CLI:

  • Jaspr can now be installed with dart install jaspr_cli instead of dart pub global activate jaspr_cli.
  • Added jaspr convert-html command to automatically convert raw HTML to Jaspr code.
  • Breaking Removed jaspr tooling-daemon command. The functionality is now provided by the jaspr_lints package.
  • Improved logging and overall stability.

• Added jaspr: styles: standalone option to pubspec.yaml.

  • When enabled, all @css declarations are rendered to a standalone .css file instead of being inlined in the pre-rendered HTML.
  • @css is now also allowed in client mode projects, where standalone mode is enabled by default.

• Allow analyzer versions 10.x.

• Added new jaspr.styles: standalone option to pubspec.yaml.

  • When enabled, all @css declarations are output to a standalone .css file instead of being inlined in the HTML.
  • This is enabled by default in client mode, which is why @css is now allowed in client mode projects.

• Added ServerApp.addMiddleware() method to add custom middleware to Jaspr's HTTP server.

• Added --web-port and --proxy-port options to jaspr serve for configuring webdev and proxy server ports.

  • Allows running multiple Jaspr projects simultaneously with different ports.

• Fixed testComponents failing with RawText components due to MarkupRenderObject cast error.

  • Added RawableRenderObject and RawableRenderText interfaces for raw HTML text rendering support.
  • MarkupRenderObject and TestRenderObject now implement RawableRenderObject.
  • MarkupRenderText and TestRenderText now implement RawableRenderText.

• Fixed encoding of lastmod property in generated sitemap to be a valid W3C date string.

• Fixed launching debug builds in Safari.

• Added --target-os and --target-arch options to the build command to cross-compile server binaries.

• Added --dart-define-from-file option to the serve and build commands.

• Respect PUB_HOSTED_URL environment variable for custom pub mirrors.

• Added an example to show on pub.dev.

• Fixed bug when using flutter: plugins or flutter: embedded on Windows.
• Fixed generation of *.client.options.dart file in client mode.
• Improved detection of Flutter plugins by reading the generated .flutter-plugins-dependencies file.
• Fixed bug preventing event handlers from being updated in rebuilds.

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:

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

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

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():

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:

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.

• Breaking Changed project entrypoint conventions:

  • Any server entrypoint file must now end in .server.dart (e.g. lib/main.server.dart).

  • The generated server-side options file is now generated alongside the server entrypoint (e.g. as lib/main.server.options.dart) containing defaultServerOptions.

  • Jaspr.initializeApp() now requires the package:jaspr/server.dart import.

  • The project can contain at least one client entrypoint file ending in .client.dart (e.g. lib/main.client.dart) for client-side rendering (also available in client mode).

  • A new client-side Jaspr options file is generated alongside the client entrypoint (e.g. as lib/main.client.options.dart) containing defaultClientOptions.

  • Added a new ClientApp component that should be used inside the client entrypoint like this:

    // This file is lib/main.client.dart
    
    import 'package:jaspr/client.dart';
    import 'main.client.options.dart';
    
    void main() {
      Jaspr.initializeApp(
        options: defaultClientOptions,
      );
    
      runApp(
        const ClientApp(),
      );
    }
    

• Breaking Renamed package:jaspr/browser.dart library to package:jaspr/client.dart, as well as:

  • Renamed BrowserAppBinding class to ClientAppBinding.
  • Renamed package:jaspr_test/browser_test.dart library to package:jaspr_test/client_test.dart.
  • Renamed testBrowser() class to testClient().

• Breaking Moved all html components, style classes and dom utilities including div() et al., Styles, css, Color et al., events(), RawText, and ViewTransitionMixin to a separate package:jaspr/dom.dart library.

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

• Breaking All html components are now implemented as classes instead of functions, and can thereby used with const.

  This is mostly a structural change, as all components keep their lowercase names to have the familiar html-like syntax and differentiate to other Components. All standard uses of these components should still work as before, with a few exceptions 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([]);).

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

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

• Added dl, dt, and dd html components to package:jaspr/dom.dart.

• Breaking Removed deprecated package:jaspr/ui.dart library.

• Breaking Removed support for jaspr.dev-command option in pubspec.yaml.

• Added support for jaspr.port option in pubspec.yaml to specify the default port used by jaspr serve. This can still be overridden using the --port flag. If neither is set, the default port stays 8080.

• Added support for jaspr.flutter option in pubspec.yaml to specify either support for Flutter embedding with 'embedded' or support for Flutter plugins with 'plugins'.

  This replaces the dependency on jaspr_web_compilers package, which is now discontinued. Instead, make sure to depend on build_web_compilers with a minimum version constraint of 4.4.6 or higher.

• Breaking: Removed jaspr analyze command, as the latest version of jaspr_lints can now be used directly with dart analyze.

• Breaking: ResponseLike.body (returned from renderComponent()) is now a Uint8List instead of String.

• Allow binary responses in AppContext.setStatusCode.

• Global @css styles from other packages will no longer be included automatically. To include them, import the file where they are defined.

• Breaking Changed events() method to accept only one optional type parameter for both onInput and onChange events.

• Added Animation, Quotes CSS properties.

• Added Curve.linearFn() easing function.

• Added Gap.row() and Gap.column() constructors.

• Added Flex.grow(), Flex.shrink() and Flex.basis() constructors.

• Added Border.all() constructor and deprecate the unnamed Border constructor.

• Breaking: Transition's duration and delay are now of type Duration instead of double.

• Added ms and seconds extensions to int for simple conversion to Duration.

• Breaking: Changed FontStyle.obliqueAngle to accept Angle instead of double.

• Added initial, inherit, revert, revertLayer and unset to Transition, TextShadow and BoxShadow.

• Allow nesting non-empty Filter.list inside each other.

• @Import now supports defining extensions and properly checks elements inside the show parameter.
• Fixed bug when using SyncStateMixin or @sync on a @client component.
• Fixed bug with checked and indeterminate attributes not rendering correctly on input elements.
• Fixed allowing children for path tag by removing it from the list of self-closing tags.
• Deprecate the package:jaspr/ui.dart library that provides legacy utility components. For accessing Jaspr APIs, import package:jaspr/jaspr.dart instead. For the utility components, build your own or use a component library.

• Added checked and indeterminate parameters to input(). These will control the state of a checkbox or radio input.
• Fixed client hydration and debugging bug on chrome when running the app under a base path.

• Fixed regression in rendering implementation.

• Added JasprBadge component that renders a "Built with Jaspr" badge.
• Add the --no-managed-build-options flag to commands launching a build daemon. Without managed build options, users are responsible for configuring build_web_compilers.
• Fixed another whitespace rendering bug.

• Fix tooling daemon crash while analyzing component scopes.

• Added html domain to tooling daemon.

• Fix rendering issue with fragments.

title: Version 0.21.0 description: Release notes and breaking changes. next: /releases/packages/jaspr-code-v0.2.2 nextTitle: VSCode Extension Release Notes

TLDR / Overview

Version 0.21.0 comes with a major overhaul of the component syntax, making it easier and even more familiar to write components. It also ships a new jaspr migrate command for automatic migrations to new versions, and adds support for five new CSS properties.

TL;DR

• Simplified Build Methods: All component build methods now return a single Component instead of an Iterable<Component>, making code more concise and Flutter-like.
• Unified Component Factories: New factory constructors on the core Component class replace DomComponent(), Text(), and Fragment() for a more consistent API.
• Automatic Migration Command: The CLI now includes a jaspr migrate command to help you automatically update your codebase for breaking changes.
• Improved Base Handling: The base parameter of the Document() component can now be set to null to suppress the <base> element.
• Expanded CSS Support: Eight new CSS properties are now available for more flexible styling: all, aspectRatio, appearance, justifyItems, justifySelf, alignContent, filter, and backdropFilter.

Additionally, a new version of the Jaspr VSCode extension was released that contains a major improvement to the developer experience. Read more in the Extension Release Notes.

Build Method Improvement

All component build methods now return a single Component instead of an Iterable<Component>. This includes:

• The build() methods of StatelessComponent and StatefulComponents State:

  @override
  Iterable<Component> build(BuildContext context) sync* { // [!code --]
    yield ... // [!code --]
  Component build(BuildContext context) { // [!code ++]
    return ... // [!code ++]
  }
  

• The builder parameter of Builder, ListenableBuilder, FutureBuilder, StreamBuilder and AsyncBuilder, e.g.:

  return Builder(
    builder: (context) sync* { // [!code --]
      yield ... // [!code --]
    builder: (context) { // [!code ++]
      return ... // [!code ++]
    }
  );
  

• The build() method of AsyncStatelessComponent:

  Stream<Component> build(BuildContext context) async* { // [!code --]
    yield ... // [!code --]
  Future<Component> build(BuildContext context) async { // [!code ++]
    return ... // [!code ++]
  }
  

Migration

<Info> After upgrading Jaspr CLI to 0.21.0, you can use the jaspr migrate command to automatically migrate your components to the new build method signature.

The automatic migration will be able to migrate most of your components (90% to 99%). </Info>

In case you need or want to manually migrate single components to the new build method, migrating is straightforward and in most cases trivial:

1. Change the method signature to Component build(BuildContext context) for normal components/builders, and Future<Component> build(BuildContext context) for async components/builders.
2. For build methods yielding a single child, simply remove the sync* modifier and return that child intead.
3. For build methods yielding multiple children, return a Fragment and provide the children as a List<Component>.

Reason for the Change

We noticed that in practice most components already only return/yield a single child component. For those components, changing to a single child build method is the natural choice.

Additionally, this change allows discontinuing the special sync*/yield syntax used before and instead aligns more closely with Flutter's widget syntax. And while this syntax is not officially deprecated, it is not really recommended by the Dart team as it lacks certain performance optimizations (especially in the js compiler) and doesn't support newer language features (e.g. no null-aware yield).

Lastly, changing to single-child components allowed for major simplifications and optimizations of the internal framework code of Jaspr, resulting in a less-complex, easier to maintain and more performant implementation.

Foundational Component Factories

New factory constructors on the core Component class have been introduced and replace the separate DomComponent(), Text() and Fragment() constructors:

return DomComponent(tag: 'div', ...); // [!code --]
return Component.element(tag: 'div', ...); // [!code ++]

return Text("..."); // [!code --]
return Component.text("..."); // [!code ++]

return Fragment(children: [...]); // [!code --]
return Component.fragment([...]); // [!code ++]

The DomComponent, Text and Fragment classes still exist in the implementation, but cannot be created directly anymore.

Additionally, a new Component.empty() convenience constructor was added to create an empty fragment.

<Info> The html utility methods (div(), button() etc.) still exist and are still recommended over using the Component.element constructor. Same goes for the text() method and the new fragment() method for consistency, both of which are now also part of the 'prefer_html_methods' lint of jaspr_lints. </Info>

Migration

<Info> After upgrading Jaspr CLI to 0.21.0, you can use the jaspr migrate command to automatically migrate your components to the new factory API.

The automatic migration will be able to migrate 99% of your components. </Info>

In case you need or want to manually migrate single components to the new factory API, migrating is straightforward and in most cases trivial:

1. Replace any DomComponent() invocation with Component.element().
2. Replace any Text() invocation with Component.text().
3. Replace any Fragment() invocation with Component.fragment() (or Component.empty() if it is an empty fragment).

Reason for the Change

This change was made to improve the API in terms of consistency and discoverability.

It is also designed to work well with the new dot shorthand syntax introduced in Dart 3.10. This allows you to omit the type name (in this case Component) when accessing a static member in a context where that type is expected (in this case e.g. a component's build method or children parameter).

It also better encapsulates the concept that Jaspr has (different to Flutter) a fixed set of foundational component types (instead of allowing to write any number of custom render objects), and thus better aligns with the internal implementation.

In real-world use we don't expect this to make much of a difference, as most Jaspr code should use the HTML utility methods anyways.

New Migrate Command

The CLI will include a new migrate command meant for helping with the migration of breaking changes in new versions. This will not only be used for the Build Method Change and Component Factories Change of this release, but also for any future change that allows for automatic migration.

Using the command is straightforward and follows the same style as the dart fix command:

• Running jaspr migrate with no options will check only show which migrations are available for the currently used Jaspr version, e.g. Build Method Migration for version 0.21.0 and newer.
• Running jaspr migrate --dry-run will compute and print all proposed migrations, but makes no changes to the code.
• Running jaspr migrate --apply will compute, print and apply all migrations.

<Image caption="Migrate options for version 0.21.0" src="/releases/assets/migrate_command.png"/>

Base Handling

The base parameter of the Document() component can now be set to null, which causes the <base> head element to not be rendered. Previously this defaulted to / even when explicitly set to null. The default when not specifying the parameter is still /.

When setting to null, the script src path of the generated client script is now corrected and does not produce an error.

There is no migration needed, as the behavior for normal usage is still the same.

New CSS Properties

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

// For resetting default styles.
All all

// For box sizing and layout.
AspectRatio aspectRatio
Appearance appearance

// For flexbox and grid layouts.
JustifyItems justifyItems
JustifySelf justifySelf
AlignContent alignContent

// For applying graphical effects like blur or color shift.
Filter filter
Filter backdropFilter

• JustifyItems, JustifySelf and AlignContent are enums with values like JustifyItems.center, JustifySelf.start or AlignItems.spaceAround.

• Filter defines several filter methods like Filter.blur(8.px), Filter.hueRotate(90.deg), Filter.opacity(0.5) or Filter.none.

Read the full Release Notes for this version.

• Breaking Changed all build() methods and builder functions to return a single Component instead of Iterable<Component>. Use jaspr migrate to migrate automatically after updating.

• Breaking Introduced new Component.element(), Component.text(), Component.fragment() and Component.wrapElement() constructors, replacing DomComponent(), Text(), Fragment() and DomComponent.wrap(), respectively. Also added Component.empty() to create an empty fragment.

• Allow setting Document(base: ) to null, and fix the path to the generated client script when no <base> element exists.

• Added justifyItems, justifySelf and alignContent styles properties.

• Added filter and backdropFilter styles properties.

• Added all, appearance and aspectRatio styles properties.

• Added --include-source-maps option to jaspr build command.

• Added jaspr tooling-daemon command and component scope analysis.

• Fixed sitemap generation bug in top-level route ('/')

• Require sdk: ^3.8.0.

• Update analyzer to ^8.0.0 and build to ^4.0.0.

• Breaking: Removed the children parameter from input and col methods as they are void elements and shouldn't be passed children.

• Breaking: Replaced the children parameter from script method with a String? content parameter, as it can only contain text content. Also made src parameter optional.

• Breaking: Removed deprecated Color.hex and Color.named constructors.

• Breaking: Removed deprecated style groups (Styles.box(), Styles.text(), Styles.background(), etc. as well as .box(), .text(), etc.).

• Breaking: Removed deprecated EdgeInsets type.

• Breaking: Removed deprecated Border.all constructor.

• Added withOpacity(), withLightness(), withHue() and withValues() methods to Color.

• Added figure and figcaption html methods.

• Added the wbr html method for creating a line-break opportunity element.

• Moved DomValidator class to foundation library.

• Added support for disabling the sitemap generation for specific pages of jaspr_content sites.

• Better error handling for async components.

• Fixed an error where building too many routes in succession caused ports to be exhausted on macOS.

• Added Color.currentColor constant.

• Added rx and ry properties for svg rect().

• Added prefersContrast: Contrast.<more|less|noPreference> to MediaQuery.

• Added MediaQuery.raw() for creating a custom media query from a String.

• Fixed rendering bug when nesting components with empty children.

• BREAKING JasprOptions.useIsolates is now false by default (was true).

  If you want to keep the old behaviour of rendering each request in a separate isolate, use Jaspr.initializeApp(..., useIsolates: true).

• Added allowedPathSuffixes option to Jaspr.initializeApp() to enable handling route paths with extensions other than html.

• Added support for generating a sitemap.xml in static mode. To enable this, pass --sitemap-domain=my.domain.com to jaspr build.

  Add sitemap params like changefreq and priority to your routes by using Route(settings: RouteSettings(priority: 0.5)) or set them through ServerApp.requestRouteGeneration().

  Exclude routes from the sitemap through the --sitemap-exclude option to jaspr build.

  Read more about Generating a Sitemap.

• Added support @client components from other packages.

  Components annotated with @client from other dependent packages are now also part of the js bundle when used during pre-rendering.

• BREAKING The Flex(basis: ...) style now accepts a Unit value directly instead of a FlexBasis.

• Allow nesting css.media and css.supports rules.

• Deprecated Color.hex() and Color.named() in favor of the default Color() constructor.

• Added onReassemble stream to ServerApp.

• Various bug fixes.

• Added jaspr daemon command to run a daemon server (used by the new VSCode extension).
• Added --launch-in-chrome option to jaspr serve command to open the browser automatically.
• Added support for running jaspr create . in an empty directory.

• Better report errors during static build.
• Fixed flutter embedding issue with version 3.29.0.
• Added onClick override to the a html tag. When used, this will override the default behaviour of the link and not visit its url when clicked.
• Added --extra-js-compiler-option and --extra-wasm-compiler-option to jaspr build command.
• Added // dart format off and // ignore_for_file: type=lint headers to all generated files.

• BREAKING Changed AppBindings Uri get currentUri to String get currentUrl.

• BREAKING Changed return type of renderComponent() from Future<String> to Future<({int statusCode, String body, Map<String, List<String>> headers})>.

  The rendered html is accessible through the body property. statusCode and headers can be used to create a response object when part of a custom http handler.

• Added context.url extension getter on both client and server.

• Added context.headers, context.headersAll and context.cookies extension getters on the server. These can be used to access the headers and cookies of the currently handled request.

• Added context.setHeader() and context.setCookie() and context.setStatusCode() extension on the server. These can be used to set headers, cookies and the status code of the response.

• Deprecated having seperate style groups (Styles.box(), Styles.text(), Styles.background(), etc. as well as .box(), .text(), etc.). All styling properties are now available under the single Styles() constructur and .styles() method.

  Before:

  css('.main')
    .box(width: 100.px, height: 100.px)
    .text(align: TextAlign.center)
    .background(color: Colors.blue);
  

  After:

  css('.main').styles(
    width: 100.px,
    height: 100.px,
    textAlign: TextAlign.center,
    backgroundColor: Colors.blue,
  );
  

• Deprecated EdgeInsets in favor of Padding and Margin types.

• BREAKING Moved zIndex property out of Position and directly into Styles.

• Added userSelect, pointerEvents and content properties to Styles.

• Added Unit.maxContent, Unit.minContent, Unit.fitContent and Unit.expression().

• Update logo and website links.

• BREAKING Removed currentState from GlobalKey, use GlobalStateKey instead.

• Added GlobalStateKey<T extends State> to access the state of a component using currentState.

  // Use any State type as the type parameter.
  final GlobalStateKey<MyComponentState> myComponentKey = GlobalStateKey();
  
  /* ... */
  
  // Access the state from the key.
  MyComponentState? state = myComponentKey.currentState;
  

• Added GlobalNodeKey<T extends Node> to access native dom nodes using currentNode.

  import 'package:universal_web/web.dart';
  
  // Use any Node type (from package:universal_web) as the type parameter.
  final GlobalNodeKey<HTMLFormElement> myFormKey = GlobalNodeKey();
  
  /* ... */
  
  // Access the dom node from the key.
  HTMLFormElement? node = myFormKey.currentNode;
  

• Migrated all web imports from package:web to package:universal_web.

• Added prefersColorScheme parameter to MediaQuery.

• Added --dart-define, --dart-define-client and --dart-define-server to serve and build commands.
• Fixed attribute validation to support attribute names including @ and :.

• Added table and related html methods.
• Added value parameter to select() method.
• Add 'standalone' option to renderComponent method.

• Fixed bug with empty text('') components.
• Fixed bug in raw() component.

• Fixed flutter embedding in new project scaffold.
• Fixed flutter embedding on mobile to always use canvaskit renderer.
• Fixed build command on windows to correctly end child process.

• BREAKING Migrated all packages to package:web, replacing dart:html.

• BREAKING Made ComponentsBinding.attachRootComponent() and ComponentTester.pumpComponent() synchronous.

• Added InheritedModel<T> similar to Flutters InheritedModel

• Added css.layer(), css.supports() and css.keyframes() rules.

• Added ViewTransitionMixin to use view transitions in a StatefulComponent.

• Improved html formatting on the server to not introduce unwanted whitespaces.

• Fixed server issue during tests where the web directory would never resolve.

• Fixed issue with unhandled parameter types of client components.

• Include and setup jaspr_lints in newly created projects.
• Added jaspr analyze command to check all custom lints.
• Added css variable support with Unit.variable(), Color.variable(), Angle.variable() and FontFamily.variable().

• Added support for using @css and @encoder/@decoder across other packages.

  1. Styles annotated with @css from other dependent packages are now also included in the pre-rendered css.
  2. Models (or extension types) that define @encoder and @decoder annotations from other dependent packages can now also be used together with @client components and @sync fields.

• BREAKING Component (or any class member) styles annotated with @css are now only included in the pre-rendered css if the file they are defined in is actually imported somewhere in the project.

  Top-level styles continue to be always included.

• Fixed issue with wrongly generated imports of @encoder/@decoder methods.

• Fixed spelling mistake from spaceRvenly to spaceEvenly

• Added default BorderStyle.solid to BorderSide constructor.

• BREAKING Calling Jaspr.initializeApp() is now required in static and server mode.

• BREAKING Removed Head component in favor of new Document.head() component. Document.head() has the same parameters as the old Head component and renders its children inside the <head> element.

• Added Document.html() and Document.body() to modify the attributes of <html> and <body>.

• BREAKING Removed syncId and syncCodec parameters from SyncStateMixin. SyncStateMixin now embeds its data locally in the pre-rendered html using standard json encoding.

• Added @sync annotation. Can be used on any field of a StatefulComponent to automatically sync its value.

  class MyComponentState extends State<MyComponent> with MyComponentStateSyncMixin {
    @sync
    String myValue;
  }
  

• BREAKING Removed MediaRuleQuery in favor of MediaQuery.

• Added css.import(), css.fontFace() and css.media() shorthands.

• Added @css annotation. Can be used on a list of style rules to automatically include them in the global styles.

  @css
  final styles = [
    css('.main').box(width: 100.px),
  ];
  

• Added Fragment component.

• Fixed missing html unescape in hydrated data.

• Added support for custom models as parameters to @client components.

  To enable this a custom model class must have two methods:

  • An instance method that encodes the model to a primitive value and is annotated with @encoder:

    @encoder
    String toJson() { ... }
    

  • A static method that decodes the model from a primitive value and is annotated with @decoder:

    @decoder
    static MyModel fromJson(String json) { ... }
    

  The method names can be freely chosen. The encoding type must be any primitive type (String, int, List, Map, etc.).

• Added ListenableBuilder and ValueListenableBuilder components.

• Added Styles.list for styling ul and ol elements.

• Added TextDecoration.none shorthand.

• Improved the performance of the building and diffing algorithm, and other performance improvements.
• Added StatelessComponent.shouldRebuild and State.shouldRebuild for possible skipping rebuilds as a performance improvement.

• Fixed namespace handling for nested svg elements.
• Fixed global key conflicts during server-side rendering by disabling them on the server.
• Change testComponents(isClient: _) default to true.

• Added Head component to render metadata inside the documents <head>.

  You can specify a title, metadata or custom children:

  Head(
    title: 'My Title',
    meta: {
      'description': 'My Page Description',
      'custom': 'my-custom-metadata',
    },
    children: [
      link(rel: "canonical" href: "https://mysite.com/example"),
    ],
  )
  

  Deeper or latter Head components will override duplicate elements:

  Parent(children: [
    Head(
      title: "My Title",
      meta: {"description": "My Page Description"}
    ),
    Child(children: [
      Head(
        title: "Nested Title"
      ),
    ]),
  ]),
  

  will render:

  <head>
    <title>Nested Title</title>
    <meta name="description" content="My Page Description" />
  </head>
  

• Added AsyncStatelessComponent and AsyncBuilder. These are special components that are only available on the server (using package:jaspr/server.dart) and have an asynchronous build function.

• Improved internal framework implementation of different element types.

  • Added BuildableElement and ProxyElement as replacement for MultiChildElement and SingleChildElement.
  • Added Element.didMount() and Element.didUpdate() lifecycle methods.

• Fixed race condition where routes were skipped during static rendering.

• Fixed infinite loading bug for async server builds.

• Fixed hydration bug with empty or nested client components.

• Added documentation comments.

• BREAKING Removed Document.file(), instead use new Document.template().

• Added Document.template() for loading template html files.

  Files that should be used with Document.template() must have the .template.html extension to differentiate between normal .html files that are served as-is. The name parameter provided to Document.template() must be the simple name of the file without extension, e.g. Document.template(name: 'index') loads the web/index.template.html file.

• Added the lang attribute to Document() constructor.

• Added <main> as main_() to the standard html components.

• Fixed bug with PreloadStateMixin and improved async server builds.

• Fixed crash with server hot-reload.

• Improved the shelf backend template for proper handling of server hot-reload.

• Fixed DomValidator to allow attributes with ..

• Fixed bug with base paths.

• BREAKING Changed jaspr configuration to require jaspr.mode in pubspec.yaml:

  The jaspr.mode option now sets the rendering mode and must be one of:

  • static: For building a statically pre-rendered site (SSG) with optional client-side hydration.
  • server: For building a server-rendered site (SSR) with optional client-side hydration.
  • client: For building a purely client-rendered site (SPA).

  This replaces the old jaspr.uses-ssr option.

• BREAKING Removed jaspr generate command in favor using the jaspr build command in combination with the new jaspr.mode = static option in pubspec.yaml.

• BREAKING Removed the runServer() method along with its support for adding middleware and listeners. Users should instead migrate to the custom backend setup using package:shelf.

• BREAKING Removed rawHtml flag from Text component and text() method, in favor of new RawText component and raw() method respectively, which fixes multiple bugs with the old implementation.

• Improved the jaspr create command by changing to a scaffolding system as replacement for templates. You will now be walked through a configuration wizard that creates a starting project based on the selected options.

• Removed jaspr.uses-flutter option. This is now auto-detected based on the dependencies.

• Styles can now be written more concise using the ability to chain style groups as well as the new css() method.

• Changes made to main.dart are now also hot-reloaded on the server.

• Document is no longer required when using server-side rendering. A basic document structure (<html><head>...<body>...) is automatically filled in.

• Improved how @client components are hydrated.

• The jaspr build command now accepts an optimization option. Minification (-O 2) enabled by default.

• Fixed DomValidator to allow special attributes with uppercase letters and colons.

• Exceptions thrown during renderHtml are now correctly passed through to the spawning isolate.

• BREAKING Restructured core libraries:

  • Removed package:jaspr/html.dart -> Use package:jaspr/jaspr.dart instead.
  • Renamed package:jaspr/components.dart to package:jaspr/ui.dart.

• BREAKING Updated @client components for a more streamlined usage.

  Annotated components no longer generate a .g.dart file and don't need to implement any generated mixin anymore. Instead, a single lib/jaspr_options.dart file is generated when using @client components.

  You must now call Jaspr.initializeApp(options: defaultJasprOptions) at the start of your app, where defaultJasprOptions is part of the newly generated jaspr_options.dart file.

  Note: Calling Jaspr.initializeApp() will be required in a future version of Jaspr, and the cli will warn you when it's not called.

• BREAKING Changed type of the classes property of html components from List<String> to String. Multiple class names can be set using a single space-delimited string, e.g. classes: 'class1 class2'.

• BREAKING Event callbacks are now typed. The events property of html components now expects a Map<String, void Function(Event)> instead of the old Map<String, void Function(dynamic)>.

  In addition to this Jaspr comes with a new events() function to provide typed event handlers for common events, like onClick, onInput and onChange. Use it like this:

  anyelement(
    // Uses the [events] method to provide typed event handlers.
    events: events(
      onClick: () {
        print("Clicked");
      },
      // [value] can be typed depending on the element, e.g. `String` for text inputs or `bool` for checkboxes.
      onInput: (String value) {
        print("Value: $value");
      },
    ),
    [...]
  )
  

  Moreover, the html components button, input, textarea and select now also come with additional shorthand properties for their supported event handlers:

  button(
    onClick: () {
      print("Clicked");
    },
    [...]
  )
  

• BREAKING Refactored components inside the package:jaspr/ui.dart library. Some component properties have changed or been discontinued. Check the separate components for details.

• BREAKING Promoted jaspr_web_compilers to non-experimental status.

  This also changes the respective cli option from jaspr create --experimental-web-compilers (old) to jaspr create --jaspr-web-compilers (new).

• Added support for rendering svg elements. Also added svg(), rect(), circle(), ellipse(), line(), path() and polygon() components.

• Refactored rendering implementation to use RenderObjects.

• Added NotificationListener component.

• Added Colors.transparent.

• Added Unit.auto, Unit.vw() and Unit.vh() for responsive styling.

• Added StyleRule.fontFace() to add external font files.

• Several bug fixes and stability improvements when running jaspr serve or jaspr build.

• Fixed melos format on Windows.
• Fixed infinite loop attempting to find root directory on Windows when running a built Jaspr executable.
• Add .exe extension to the output of jaspr build on Windows.

• Fixed cli execution on windows.

• Improved the stability and logging of the cli and added the commands:

  • clean command to clean your project directory
  • update command to automatically update the cli to the latest version
  • doctor command to print information about the environment and project

• We added lightweight anonymous usage tracking to the cli. We use mixpanel.com and only process anonymized data. The usage statistics are made public and can be viewed here (TODO: Link will be added in next release).

  To opt out of usage tracking, use jaspr --disable-analytics.

• Added Static Site Generation support.

  With the new jaspr generate command you can generate static pages from your Jaspr app. This requires a normal server-rendered Jaspr app and will output separate .html pages for each of your routes.

  To specify which routes your application should handle, either use jaspr_router or call ServerApp.requestRouteGeneration('/my/route'); for each target route.

• Fixed client template to set uses-ssr: false correctly.

• Fixed bug with rebuilding the root component.

• Added StyleRule.media({MediaRuleQuery query, List<StyleRule> styles}) to support @media css statements.

• Added support for Tailwind using the jaspr_tailwind integration.
  Simply run dart pub add jaspr_tailwind --dev and start using tailwind classes in your Jaspr components.
  For a full setup and usage guide see Tailwind Integration Docs

• Improved cli experience with better logging and progress indicators.

• Removed --ssr and --flutter cli options.

• Added support jaspr config section in pubspec.yaml.

  It is now possible to define certain configuration options for the Jaspr cli directly inside the pubspec.yaml file under the jaspr section. Initially supported options are:

  jaspr:
    uses-ssr: true # or false; Toggles server-side-rendering on or off.
    uses-flutter: true # or false; Whether the project uses flutter element embedding.
  

• Added integrated support for seamless flutter element embedding. Refer to Flutter Embedding Docs on how to setup and use this.

• Fixed bug with jaspr create.

• Added prompts when running jaspr create without any arguments. This way the developer is guided through the creation process more dynamically.

• Added support for flutter web plugins.

  Jaspr apps can now depend-on and import flutter plugins that work on web. This is achieved by using a modified compiler toolchain: jaspr_web_compilers.

  To enable support for flutter plugins simply exchange your build_web_compilers dependency for jaspr_web_compilers:

  dev_dependencies:
    jaspr_web_compilers: ^4.0.4
  

  For an example see examples/flutter_plugin_interop.

• Improved flutter element embedding.

  Flutter apps can now be directly embedded from your Jaspr codebase and integrated into the existing Jaspr component tree.

  This removes the need for any kind of interop between apps as they can directly communicate through the usual primitives of passing properties and callbacks.

  For an example see examples/flutter_embedding.

• jaspr build now outputs to /build/jaspr instead of /build.