schultek/jasprLight logoJaspr
PR #153

Project Configuration

The configuration options for a Jaspr project.

Each Jaspr project is a normal Dart project including a pubspec.yaml file and lib/ directory.

The project-wide Jaspr configuration is specified in pubspec.yaml under the jaspr option:

name: my_project
...

jaspr:
  mode: server
  port: 8080
  flutter: plugins

There are currently the following configuration options available:

modeEnumrequired

Sets the Rendering Mode for your project. Either static, server or client.

portintoptional

Only applicable in "static" or "server" mode.

Specifies the target port to use when serving your project. This is optional and defaults to "8080" if not set. Can be overridden by the --port flag with jaspr serve.

flutterEnumoptional

Specifies the Flutter support for your project.

  • embedded: Enables Flutter embedding support, allowing you to use Flutter widgets inside Jaspr components.
  • plugins: Enables Flutter plugin support, allowing you to use Flutter plugins that provide web support inside your project.
  • none or omitted: No Flutter support.

Using either embedded or plugins requires the Flutter SDK to be installed and available in your system PATH, as well as a dependency on build_web_compilers with a minimum version constraint of 4.4.6 or higher.

Project Structure

The following is the recommended project structure for any Jaspr website. The concrete files vary slightly depending on your chosen Rendering Mode.

├── lib/
│   ├── components/      // Shared components
│   │   ├── counter.dart
│   │   └── ...
│   ├── pages/           // The pages of your website
│   │   ├── home.dart
│   │   └── ...
│   ├── app.dart         // The main app component, usually containing the Router
│   ├── ...
│   ├── main.client.dart // The client entrypoint, for all modes, optional
│   ├── main.client.options.dart // Auto-generated by Jaspr
│   ├── main.server.dart // The server entrypoint, only for server or static mode
│   └── main.server.optionsdart // Auto-generated by Jaspr
├── web/.                // Static assets
│   ├── images/
│   │   └── ...
│   ├── styles.css       // Usually only for client mode
│   └── index.html       // The index file, only for client mode
├── pubspec.lock
└── pubspec.yaml

  • The lib directory contains all your usual dart code, including components, pages, routes etc. depending on your architecture.

  • The lib/main.server.dart file is the entry point for your server application. It calls runApp() and provides your root document component. Only needed for static or server mode.

    You can also have other *.server.dart files and choose one with --input flag when running your project.

  • The lib/main.client.dart file is the entrypoint for your client environment. It calls runApp() and either provides your root component (in client mode), or the ClientApp() component (in static or server mode) which hydrates all @client components.

    You can also have other *.client.dart files. Any *.client.dart file inside lib/ is automatically compiled to JavaScript. In static and server mode, any file that has a peer <filename>.server.dart file is automatically loaded as a script tag. In client mode, or for using non-peer *.client.dart files you need to manually include a script tag pointing to <filename>.client.dart.js in your page.

  • The *.<server|client>.options.dart files are auto-generated by Jaspr's tooling. It exposes a top-level defaultServerOptions or defaultClientOptions that you should provide to the Jaspr.initializeApp(options: ...) call inside *.<server|client>.dart.

  • The web directory contains any static assets you want to access from your website, like images or fonts. Files inside this directory are later accessible through their relative url, e.g. <domain>/images/logo.png.

  • The web/index.html file (along with other html and css files) is only needed in client mode and contains the static markup and styling for your website.

Edit this page on GitHub
🕹 Jaspr CLI
🧹 Linting