jaspr-pre-rendering-and-hydration

This skill is relevant for static and server mode Jaspr projects. You can check the mode of a Jaspr project in pubspec.yaml under jaspr: mode: <mode>.

Core Rules for Pre-rendering (SSR/SSG)

Jaspr pre-renders components at request/build-time on the server. Interactive browser features require hydration.

1. Dual Entrypoints:
   • Server: lib/main.server.dart -> Calls runApp(Document(body: MyApp()))
   • Client: lib/main.client.dart -> Calls runApp(ClientApp())
2. Library Constraints:
   • Importing: You MUST NOT import dart:js_interop or package:web in any code imported by the server entrypoint.
   • Importing: You MUST NOT import dart:io or dart:ffi in any code imported by the client entrypoint.
   • Using: You can import package:universal_web in shared code, but you MUST wrap any access to its browser APIs inside an if (kIsWeb) check to prevent crashing during server-side rendering.
3. Interactivity / Hydration: Components are server-rendered by default. To add client interactivity (e.g., event listeners, state, using browser APIs), you MUST annotate a component with @client.

The @client Annotation and ClientApp

When you annotate a component with @client, Jaspr renders its initial HTML on the server and "hydrates" it in the browser.