Skip to main content
The jaspr serve command starts a development server with hot reload capabilities, allowing you to see changes instantly as you code.

​
Basic Usage

jaspr serve
This starts the development server with default settings:
  • Server runs on http://localhost:8080
  • Hot reload enabled for both client and server code
  • Automatic browser refresh on changes
$ jaspr serve

[CLI] Running jaspr in server rendering mode.
[CLI] Starting web compiler...
[CLI] Building web assets...
[CLIENT] Compiled main.dart
[CLI] Done building web assets.
[CLI] Starting server...
[SERVER] Server started on port 8080
[CLI] Server started.
[CLI] Serving at http://localhost:8080

​
Hot Reload

Jaspr provides intelligent hot reload for both client and server code:
Changes to client-side code trigger automatic browser updates:
  • Module reload (default) - Reloads JavaScript modules without full page refresh
  • Full refresh - Performs complete page reload including server restart
# After saving a file:
[CLIENT] Change detected: lib/app.dart
[CLIENT] Rebuilding...
[CLIENT] Compiled main.dart (234ms)
[CLI] Rebuilt web assets.

​
Server Options

​
--port
number
default:"8080"
Specify the port for the development server.
jaspr serve --port 3000
You can also set the default port in pubspec.yaml:
jaspr:
  port: 3000
​
--input
string
Specify the server entry point file. Must end in .server.dart.
jaspr serve --input lib/custom.server.dart
By default, the CLI searches for:
  1. lib/main.server.dart
  2. First *.server.dart file in bin/
  3. First *.server.dart file in lib/
​
--web-port
number
default:"5467"
Specify the port for the internal webdev server.
jaspr serve --web-port 5500
Change this if running multiple Jaspr projects simultaneously.
​
--proxy-port
number
default:"5567"
Specify the port for the internal proxy server.
jaspr serve --proxy-port 5600
Change this if running multiple Jaspr projects simultaneously.

​
Reload Modes

​
--mode
option
default:"refresh"
Sets the reload/refresh behavior when files change.Options:
  • reload - Reloads JavaScript modules without server reload (loses current state)
  • refresh - Performs full page refresh and server reload
jaspr serve --mode reload
Full page refresh including server restart on file changes.
jaspr serve --mode refresh
Pros:
  • Ensures complete state refresh
  • More reliable for complex changes
  • Restarts server with new code
Cons:
  • Loses current application state
  • Slightly slower than reload

​
Build Configuration

​
--debug
flag
default:"false"
Serve the app in debug mode with pause on start.
jaspr serve --debug
The server will pause on startup, waiting for a debugger to attach.
​
--release
flag
default:"false"
Serve the app in release mode with optimizations.
jaspr serve --release
Changes:
  • Compiles with dart2js instead of dartdevc
  • Disables server hot reload
  • Enables all optimizations
  • Removes assert statements
​
--experimental-wasm
flag
default:"false"
Compile to WebAssembly instead of JavaScript.
jaspr serve --experimental-wasm
WebAssembly support is experimental and requires a compatible browser.

​
Browser Integration

​
--launch-in-chrome
flag
default:"false"
Automatically launch the app in Chrome with debugging enabled.
jaspr serve --launch-in-chrome
This enables:
  • Automatic Chrome launch
  • Dart DevTools integration
  • VM service for debugging
$ jaspr serve --launch-in-chrome

[CLI] Running jaspr in server rendering mode.
[CLI] Starting web compiler...
[CLI] Done building web assets.
[CLI] Starting server...
[SERVER] Server started on port 8080
[CLIENT] The Dart VM service is listening on http://127.0.0.1:56789/...
[CLI] Chrome started.

​
Advanced Options

​
--skip-server
flag
default:"false"
Skip running the server, only run the client workflow.
jaspr serve --skip-server
When using this flag, you must manually start the server and set the JASPR_PROXY_PORT environment variable.
​
--managed-build-options
flag
default:"true"
Let Jaspr manage build_runner options automatically.
# Manually configure build options
jaspr serve --no-managed-build-options
Disable this to manually configure builders in build.yaml.
​
--verbose
flag
default:"false"
Enable verbose logging for detailed output.
jaspr serve --verbose

​
Dart Defines

Pass custom compile-time constants to your application:
​
--dart-define
string
Define environment variables available at compile time.
jaspr serve --dart-define=API_URL=https://api.example.com
​
--dart-define-from-file
string
Load dart-define variables from a JSON file.
jaspr serve --dart-define-from-file=config.json
config.json
{
  "API_URL": "https://api.example.com",
  "FEATURE_FLAG": "true"
}
Access these values in your code: 
const apiUrl = String.fromEnvironment('API_URL');
const featureEnabled = bool.fromEnvironment('FEATURE_FLAG');

​
Complete Examples

# Start with defaults
jaspr serve

​
Development Workflow

1

Start the server

jaspr serve
Wait for the build to complete. The first build takes longer.
2

Open in browser

Navigate to http://localhost:8080 (or your custom port).
3

Make changes

Edit your code in lib/ or web/. Changes are detected automatically.
4

See updates

The browser refreshes automatically with your changes.
[CLIENT] Change detected: lib/app.dart
[CLIENT] Rebuilding...
[CLI] Rebuilt web assets.

​
Hot Reload Behavior

Understand what triggers rebuilds and reloads:
Files in lib/ (imported by web/main.dart) or web/:
[CLIENT] Change detected: lib/components/button.dart
[CLIENT] Rebuilding...
[CLIENT] Compiled main.dart (156ms)
[CLI] Rebuilt web assets.
Result: Browser reloads (refresh mode) or hot-reloads (reload mode)
Files ending in .server.dart in lib/:
[SERVER] Change detected: lib/main.server.dart
[SERVER] Hot reloading...
[SERVER] Reloaded in 145ms
Result: Server hot-reloads, browser refreshes
Changes to files in web/ (HTML, CSS, images):
[CLIENT] Change detected: web/styles.css
[CLIENT] Rebuilding...
Result: Assets are rebuilt and browser refreshes
Changes to build.yaml or pubspec.yaml:Action required: Stop and restart jaspr serve

​
Troubleshooting

Change the port if 8080 is occupied:
jaspr serve --port 3000
Ensure your server entry point is in lib/:
# Move from bin/ to lib/
mv bin/server.dart lib/main.server.dart
jaspr serve --input lib/main.server.dart
Entry points in bin/ cannot use hot reload.
Stop the server and clean build artifacts:
# Stop jaspr serve (Ctrl+C)
dart run build_runner clean
jaspr serve
Enable verbose mode to see file watching logs:
jaspr serve --verbose
Use different ports for each project:
# Project 1
jaspr serve --port 3000 --web-port 5470 --proxy-port 5570

# Project 2  
jaspr serve --port 3001 --web-port 5471 --proxy-port 5571

​
Performance Tips

Speed up rebuilds:
  • Use --mode reload for faster updates (when server restart isn’t needed)
  • Keep server entry points in lib/ for hot reload support
  • Use conditional imports to minimize build dependencies
Memory usage:Long-running development servers may consume increasing memory. Restart periodically if you notice slowdowns.

​
Next Steps

Build Command

Build your app for production deployment

Project Structure

Learn about the Jaspr project structure

Components

Build reusable components

Debugging

Debug your Jaspr application

Build docs developers (and LLMs) love

Get started for freeTalk to us