Rendering Modes

Jaspr is a full-stack web framework, meaning it can run both on the server and the client. Depending on what you want to build you can choose how your app should be built and executed using Jaspr.

Therefore, Jaspr supports the following three rendering modes:

• static (also known as static-site-generation)
• server (also known as server-side-rendering)
• client

Each mode is explained in detail below. The following table gives a quick overview:

Static Mode

With this mode, Jaspr will generate a fully static site when building your project that you can host at any common website hosting service. You can write server-side code to pre-render components and pages at built time, outputting clean html and css to deploy anywhere. Additionally, you can set up hydration on the client in order to make your site interactive.

Generating Pages

Static-Site Generation (SSG) describes the process of generating all your website routes at build time. Different to SSR, this doesn't require a running server that generates your website on each request. Instead, jaspr build will generate all the routes for your website and outputs only static files (.html, etc.) that can be deployed to any static hosting provider.

Say you have a project in static mode with the routes /, /about and /contact. Then running jaspr build will output a index.html, about/index.html and contact/index.html file.

To make sure all pages are generated for your site, you need to tell Jaspr about the routes of your website.

Using jaspr_router

It is recommended you use jaspr_router together with static mode, since it automatically renders all routes that you define.

The following shows a router that would render the above three routes:

Router(
  routes: [
    Route(path: '/', builder: (_, __) => HomePage()),
    Route(path: '/about', builder: (_, __) => AboutPage()),
    Route(path: '/contact', builder: (_, __) => ContactPage()),
  ]
);

Generating dynamic routes

You may want to generate dynamic routes based on some data for your application.

Take for example a typical blog site, where each blog post has its own route, e.g. /posts/{postId}, and you want to render these as separate pages when running jaspr build. Normally you could use routes with path parameters for this, however for static-site generation, path parameters are not supported, since all routes need to be resolvable when initializing the router.

Instead, you need to add a route for each page you want generated:

Router(
  routes: [
    for (var post in posts)
      Route(path: '/posts/${post.id}', /* ... */),
  ],
);

Here, the posts list may be loaded from a database before the component builds.

Manual usage

If you want to set this up manually, you need to call ServerApp.requestRouteGeneration('/my_route'); for any of your routes you want to generate.

Since ServerApp is only available through the package:jaspr/server.dart import, you need to make sure this is only part of your server code and not the client.

The method should be called during the initial build of your app, so putting it into initState() of your root component is a good choice.

Server Mode

In this mode Jaspr runs and builds a server application that pre-renders your components for each incoming request. You can use either Jasprs inbuilt webserver or choose to integrate it into your favorite Dart backend framework. Additionally, you can set up hydration on the client in order to make your site interactive.

To deploy your site, you either need a service that supports Dart deployments or otherwise bundle your application with e.g. Docker. See the Deploying guide for more information.

Client Mode

If you want, you can skip the server and pre-rendering part of Jaspr completely and use it as a client-side only framework. Similar to static mode, you can deploy your built site to any common website hosting service without needing an extra server.