Original fishing-dog mascot for jaspr_hooks jaspr_hooks

Async server hooks

Use experimental server-only hook hosts across sequential awaits with explicit lifecycle rules.

AsyncHookComponent and AsyncHookBuilder let server builds call hooks before and after await. They are experimental APIs from package:jaspr_hooks/server.dart. Keep this import in server scope; client components use the universal or web entry point.

Build a server subtree

import 'package:jaspr/server.dart';
import 'package:jaspr_hooks/server.dart';

class UserDetails extends AsyncHookComponent {
  const UserDetails({required this.userId, super.key});
  final String userId;

  @override
  Future<Component> build(BuildContext context) async {
    final requestedId = useRef(userId);
    final user = await loadUser(requestedId.value);
    final label = useMemoized(() => formatUser(user), [user]);
    return Component.text(label);
  }
}

Use AsyncHookBuilder(builder: (context) async { ... }) for a small async hook region. Both hosts integrate with Jaspr's server build owner, so the page waits for their returned futures. Their results can include synchronous hook hosts, nested async hook hosts, and @client wrappers receiving server-rendered content. The server components demo uses both APIs with a server file and nested client counters.

Ordinary AsyncStatelessComponent and AsyncBuilder do not establish a hook session. Continue returning a synchronous hook host from them, or explicitly switch to an async hook host. Do not annotate an async hook component with @client.

Keep one sequential hook call chain

Call hooks in a stable order, directly in the async build or in helpers that the build awaits sequentially. useContext continues to return the owning element after each await. Concurrent requests and sibling components have independent sessions and hook state.

Parallel I/O is fine when its branches do not call hooks:

final (user, settings) = await (loadUser(), loadSettings()).wait;
final label = useMemoized(() => format(user, settings), [user, settings]);

Do not call hooks from parallel branches, unawaited helpers, timers, stream listeners, event handlers, or detached .then callbacks. The runtime cannot infer every fork in arbitrary async code; ordered calls in one awaited chain remain a rule the caller must follow. A callback registered in a build does not gain permanent hook access: its captured session closes when that build completes or fails, and late hook calls throw StateError even if the element is still mounted.

Server hook behavior

CategoryAsync server host
Refs and memoizationLocal values available across sequential awaits
Context and inherited readsRead from the owning server element
useState, useGuardedState Read-only initial snapshots; assigning while mounted throws
Reducers and local controllersInitial values work; reactive mutations throw
Effects, timers, browser subscriptions Stay inactive under the existing SSR contract
useFuture, useStream, useOnStreamChange Sources must still be null; await server data directly
useId Use a surrounding HookIdScope; client islands need their own serialized scopes

Use local variables or refs for non-reactive server computations. This API does not add live server reactivity, browser state transfer, cross-request caching, or client-side async builds. A synchronous HookBuilder returned by an async host owns separate hook state and follows its normal synchronous rules.

Completion, failure, and unmount

A successful build closes hook-call access but retains its owned hook state until replacement or unmount. A failed build closes its session, disposes all of its hooks in reverse order, and reports the failure to Jaspr so server rendering can finish with an error response. Cleanup failures are reported without skipping the remaining disposers.

Unmount during suspension closes the session, disposes existing hooks, and invalidates the pending result. The underlying Dart future cannot be physically cancelled; its later result or error is observed and ignored. Code that resumes and tries to call another hook receives StateError. Keep resource operations cancellable at their source when needed.

Rebuild requests for the same element are serialized. If its configuration changes during a pending build, that result is discarded and the latest configuration builds with a fresh session before its subtree renders. Normal hook order and key preservation rules still apply.

HTTP response completion does not guarantee element unmount. Manage request connections and asynchronous cleanup explicitly in the caller with try/finally; useDisposable retains its element-lifetime ownership rule. See SSR and hydration and rules of hooks.