Jaspr Framework Documentation

The Jaspr API is organized into three main functional areas:

1. Components: UI building blocks including document structure, routing, styling, and specialized components like RawText or FlutterEmbedView.
2. General: Core utilities for running the application, type-safe CSS styling, event bindings, and DOM access.
3. Server / Client: Tools for managing the boundary between server-side rendering and client-side hydration, including annotations for data synchronization, state preloading, and handling HTTP headers/cookies.

Jaspr is a modern fullstack web framework for building websites in Dart. It is designed to feel similar to Flutter but renders native HTML and CSS instead of using a canvas-based approach. This makes it suitable for building all types of websites (including SEO-sensitive content) that might not be ideal for Flutter Web.

Key Capabilities:

• Rendering Modes: Supports Client-Side Rendering (CSR), Server-Side Rendering (SSR), and Static Site Generation (SSG).
• Component Model: Uses a component model similar to Flutter widgets.
• State Syncing: Automatically synchronizes component state between the server and the client.
• Performance: Performs direct DOM updates only where necessary for speed.

Jaspr is a modern fullstack web framework for building websites using the Dart programming language. It is designed to feel familiar to Flutter developers by using a component model similar to Flutter widgets, but instead of rendering to a canvas, it renders standard HTML and CSS.

Key capabilities include:

• Client-side and Server-side Rendering (SSR): Support for both rendering modes out of the box.
• Automatic State Sync: Automatically synchronizes component state between the server and the client.
• Optimized DOM Updates: Performs efficient updates to the DOM only where necessary.
• Flexible Deployment: Can run on the server, the client, or both, with options for manual or automatic setup.

The jaspr_flutter_embed package provides bindings that allow you to embed Flutter components or logic within a Jaspr application. This enables developers to leverage the Flutter ecosystem while building web applications with Jaspr.

For detailed implementation guides and advanced usage, refer to the official Jaspr documentation.

The jaspr_serverpod package enables integration between Jaspr and Serverpod, providing tools for server-side rendering and connectivity.

Key features include:

• JasprRoute: Use this in your Serverpod webserver to server-side render Jaspr components.
• context.session extension: Allows you to access the Serverpod Session directly inside a Jaspr component's build() method.
• JasprConnectivityMonitor: A monitor designed for your generated Serverpod client.

For detailed integration steps, refer to the official Setup Guide.

The Jaspr Precompiler is a tool designed to precompile assets such as smart components and generate Dart source targets. These generated targets are used to support different rendering strategies, including:

• SSG (Static Site Generation)
• SSR (Server-Side Rendering)
• CSR (Client-Side Rendering)

The precompiler is scoped to compile only the source code within the current project.

The lifecycle of a synced provider follows these steps:

1. Server-side: The provider value is read, serialized, and embedded into the rendered HTML.
2. Client-side: When the component containing ProviderScope first builds, the embedded value is read and deserialized.
3. Override: The provider is then overridden on the client using Riverpod's .overrideWith() mechanism, skipping the initial computation.

Important Note on Scoping: Overrides in Riverpod only propagate the provider chain when defined on the root ProviderScope. When using synced providers, ensure they are defined on the root client-side ProviderScope, or use the dependencies option to correctly scope them.

The standard library organizes components into functional categories. While the library is intended to grow, the primary categories include:

• Layout: Components used for arranging and positioning other components.
• Text: Components dedicated to displaying text content.
• Forms & Input: Components for handling user input and interactive elements.

Because Jaspr's component system is conceptually and implementation-wise similar to Flutter's widget system, many popular Flutter state-management packages have been ported to Jaspr.

An official port of flutter_riverpod is available as jaspr_riverpod.

By default, Jaspr uses the shelf package to create an HTTP server that handles requests and renders components. If you want to use a different Dart backend framework, you can replace the default server handling using two primary functions:

1. Handler serveApp(AppHandler handler): Bundles Jaspr's server-side logic into a custom shelf handler. This handler can then be passed to your specific backend implementation.
2. String renderComponent(Component app): Directly renders a provided component into an HTML string.

Note on Auto-reload: When using a custom backend setup, running jaspr serve will still work, but automatic server-side reloading will not function. You will need to manage the server lifecycle manually.