jaspr build

The jaspr build command compiles your Jaspr project for production deployment, generating optimized assets and executables.

Basic Usage

jaspr build

The build output is located in build/jaspr/ and varies based on your project’s rendering mode.

$ jaspr build

[CLI] Building jaspr for server rendering mode.
[CLI] Building web assets...
[CLIENT] Compiling with dart2js...
[CLIENT] Compiled main.dart.js (12.3s)
[CLI] Completed building web assets.
[CLI] Building server app...
[SERVER] Compiling to executable...
[CLI] Completed building project to /build/jaspr.

Output Structure

The build output varies by rendering mode:

Server Mode
Static Mode
Client Mode

build/jaspr/
├── app.exe              # Server executable (or app.aot, app on Linux/macOS)
└── web/                 # Client assets
    ├── index.html
    ├── main.dart.js     # Compiled JavaScript
    ├── styles.css
    └── assets/

Deployment:

Copy entire build/jaspr/ directory to your server
Run the executable: ./app (or app.exe on Windows)
Set PORT environment variable as needed

build/jaspr/
├── index.html           # Pre-rendered pages
├── about/
│   └── index.html
├── contact/
│   └── index.html
├── main.dart.js         # Client JavaScript
├── styles.css
├── sitemap.xml          # Generated sitemap (if configured)
└── assets/

Deployment:

Serve the entire build/jaspr/ directory as static files
Compatible with any static hosting (Netlify, Vercel, GitHub Pages, etc.)

build/jaspr/
├── index.html
├── main.dart.js         # Compiled application
├── styles.css
└── assets/

Deployment:

Serve as static files
Configure server to route all requests to index.html for client-side routing

Server Build Options

These options apply when building in server mode:

--input

string

Specify the server entry point file. Must end in .server.dart.

jaspr build --input lib/custom.server.dart

Defaults to:

lib/main.server.dart
First *.server.dart file in bin/
First *.server.dart file in lib/

--target

option

default:"exe"

Specify the compilation target for the server executable.Options:

exe - Self-contained executable
aot-snapshot - AOT snapshot (requires Dart runtime)
jit-snapshot - JIT snapshot (requires Dart runtime)

jaspr build --target aot-snapshot

Executable (exe)
AOT Snapshot
JIT Snapshot

Compiles to a standalone executable.

jaspr build --target exe

Pros:

No Dart runtime required
Single file deployment
Fastest startup time

Output: build/jaspr/app.exe (Windows) or build/jaspr/app (Linux/macOS)

Compiles to an ahead-of-time compiled snapshot.

jaspr build --target aot-snapshot

Pros:

Smaller file size
Fast execution

Cons:

Requires Dart runtime on target system

Run: dart run build/jaspr/app.aot

Compiles to a just-in-time snapshot.

jaspr build --target jit-snapshot

Pros:

Very small file size
Fastest compilation

Cons:

Requires Dart runtime
Slower startup than AOT

Run: dart run build/jaspr/app.jit

Cross-Compilation

--target-os

option

Compile for a specific operating system.Options: linux, macos, windows

jaspr build --target-os linux

Only available with --target exe or --target aot-snapshot.

--target-arch

option

Compile for a specific CPU architecture.Options: arm, arm64, riscv64, x64

jaspr build --target-arch arm64

# Build for Linux ARM64 from any platform
jaspr build \
  --target exe \
  --target-os linux \
  --target-arch arm64

Web Compilation Options

--optimize

option

default:"2"

Set the dart2js/dart2wasm optimization level.Options:

0 - No optimizations (debugging only)
1 - Basic optimizations and inlining
2 - Production optimizations (recommended)
3 - Potentially unsafe optimizations
4 - Aggressive unsafe optimizations

jaspr build --optimize 3

Level 0
Level 1
Level 2 (Default)
Level 3
Level 4

No optimizations - for compiler debugging only.

jaspr build -O0

Use: Only when debugging the Dart compiler itself

Basic whole-program analysis and inlining.

jaspr build -O1

Use: Development builds with some optimization

Safe production optimizations including minification.

jaspr build -O2

Use: Recommended for production

Aggressive optimizations that may change behavior.

jaspr build -O3

Use: When you need maximum performance and have tested thoroughly

Maximum optimization with potential breaking changes.

jaspr build -O4

Use: Experimental - test carefully

--experimental-wasm

flag

default:"false"

Compile to WebAssembly instead of JavaScript.

jaspr build --experimental-wasm

Output: main.dart.wasm instead of main.dart.js

WebAssembly support is experimental. Ensure browser compatibility.

--include-source-maps

flag

default:"false"

Include source maps and Dart source files in the build output.

jaspr build --include-source-maps

Useful for debugging production issues, but increases bundle size.

Static Site Generation

These options apply when building in static mode:

--sitemap-domain

string

Generate a sitemap.xml file with the specified domain.

jaspr build --sitemap-domain example.com

Output includes:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2026-03-03T10:30:00Z</lastmod>
    <priority>0.5</priority>
  </url>
  ...
</urlset>

--sitemap-exclude

string

Regex pattern of routes to exclude from the sitemap.

jaspr build \
  --sitemap-domain example.com \
  --sitemap-exclude "^/admin|^/api"

Excludes routes matching the pattern from sitemap.xml.

Sitemap Configuration

Control sitemap generation from your components:

lib/pages/home.dart

import 'package:jaspr/jaspr.dart';

class HomePage extends StatelessComponent {
  @override
  Iterable<Component> build(BuildContext context) sync* {
    // Configure sitemap for this route
    yield Head(
      metaTags: [
        // Exclude from sitemap
        Meta(name: 'jaspr:sitemap', content: 'false'),
        
        // Or configure sitemap properties
        Meta(name: 'jaspr:sitemap:priority', content: '0.8'),
        Meta(name: 'jaspr:sitemap:changefreq', content: 'daily'),
      ],
    );
    
    yield Text('Home Page');
  }
}

Build Configuration

--managed-build-options

flag

default:"true"

Let Jaspr manage build_runner configuration automatically.

# Manually configure build options in build.yaml
jaspr build --no-managed-build-options

Disable to manually configure builders.

Dart Defines

Pass compile-time constants to your application:

--dart-define

string

Define environment variables for both client and server.

jaspr build --dart-define=API_URL=https://api.example.com

--dart-define-from-file

string

Load dart-define variables from a JSON file.

jaspr build --dart-define-from-file=prod-config.json

prod-config.json

{
  "API_URL": "https://api.example.com",
  "ANALYTICS_ID": "UA-123456-1",
  "FEATURE_FLAGS": "premium,analytics"
}

Access in your code:

const apiUrl = String.fromEnvironment('API_URL', 
  defaultValue: 'http://localhost:8080');

Complete Examples

# Optimized server build with environment config
jaspr build \
  --target exe \
  --optimize 2 \
  --dart-define-from-file=prod-config.json

Deployment Guides

Server Mode Deployment

Deploy the built server executable:

Build the application

jaspr build --target exe

Copy to server

scp -r build/jaspr/ user@server:/var/www/app/

Run the executable

cd /var/www/app
PORT=80 ./app

Environment variables:

PORT - Server port (default: 8080)
Any custom variables passed via --dart-define

Static Site Deployment

Deploy to static hosting:

Netlify
Vercel
GitHub Pages

netlify.toml

[build]
  command = "dart pub global activate jaspr_cli && jaspr build"
  publish = "build/jaspr"

vercel.json

{
  "buildCommand": "dart pub global activate jaspr_cli && jaspr build",
  "outputDirectory": "build/jaspr"
}

.github/workflows/deploy.yml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
      - run: dart pub global activate jaspr_cli
      - run: dart pub get
      - run: jaspr build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/jaspr

Docker Deployment

Containerize your server application:

Dockerfile

FROM dart:stable AS build

WORKDIR /app
COPY pubspec.* ./
RUN dart pub get

COPY . .
RUN dart pub global activate jaspr_cli
RUN jaspr build --target exe

FROM scratch
COPY --from=build /app/build/jaspr/ /app/

EXPOSE 8080
CMD ["/app/app"]

Build and run:

docker build -t my-jaspr-app .
docker run -p 8080:8080 my-jaspr-app

Build Performance

Optimize build times:

Use --target aot-snapshot for faster compilation than exe
Skip source maps in production: don’t use --include-source-maps
Use --optimize 2 for best balance of speed and size
Enable parallel builds with build_runner (configured by default)

Typical build times:

Client mode: 10-15 seconds
Server mode: 15-25 seconds (exe), 10-15 seconds (aot-snapshot)
Static mode: 20-40 seconds (depends on number of routes)

Troubleshooting

Build fails with errors

Clean build artifacts and rebuild:

dart run build_runner clean
jaspr build

Large bundle size

Check your optimization level:

jaspr build --optimize 2

Analyze bundle size:

ls -lh build/jaspr/web/main.dart.js

Cross-compilation fails

Ensure you’re using a compatible target:

# Only exe and aot-snapshot support cross-compilation
jaspr build --target exe --target-os linux

Static generation incomplete

Check that all routes are discovered:

Ensure routes are linked from the home page
Check server logs for errors during generation
Use --verbose for detailed output

jaspr build --verbose

Next Steps

Deployment

Learn about deploying Jaspr applications

Production Tips

Optimize for production environments

Serve Command

Learn about the development server

Docker

Containerize your application

Get Started

Core Concepts

Rendering Modes

CLI

Advanced

Basic Usage

Output Structure

Server Build Options

Cross-Compilation

Web Compilation Options

Static Site Generation

Sitemap Configuration

Build Configuration

Dart Defines

Complete Examples

Deployment Guides

Build Performance

Troubleshooting

Next Steps

Deployment

Production Tips

Serve Command

Docker

Build docs developers (and LLMs) love

Get Started

Core Concepts

Rendering Modes

CLI

Advanced

​Basic Usage

​Output Structure

​Server Build Options

​Cross-Compilation

​Web Compilation Options

​Static Site Generation

​Sitemap Configuration

​Build Configuration

​Dart Defines

​Complete Examples

​Deployment Guides

​Build Performance

​Troubleshooting

​Next Steps

Deployment

Production Tips

Serve Command

Docker

Build docs developers (and LLMs) love

Basic Usage

Output Structure

Server Build Options

Cross-Compilation

Web Compilation Options

Static Site Generation

Sitemap Configuration

Build Configuration

Dart Defines

Complete Examples

Deployment Guides

Build Performance

Troubleshooting

Next Steps