Skip to main content

​
Quickstart

Get up and running with Jaspr in just a few minutes. This guide will walk you through installation, creating your first project, and running the development server.

​
Installation

1

Install Dart

Jaspr requires Dart SDK 3.8.0 or higher. If you don’t have Dart installed, get it from dart.dev.Verify your installation:
dart --version
Expected output:
Dart SDK version: 3.8.0 (stable)
2

Activate Jaspr CLI

Install the Jaspr command line tool globally:
dart pub global activate jaspr_cli
Expected output:
Resolving dependencies...
+ jaspr_cli 0.22.3
Activated jaspr_cli 0.22.3
Make sure your PATH includes the Dart global bin directory. If jaspr command is not found, add ~/.pub-cache/bin (or %APPDATA%\Pub\Cache\bin on Windows) to your PATH.
3

Verify Installation

Check that the CLI is properly installed:
jaspr --version
You should see the version number printed.

​
Create Your First Project

1

Create a new project

Use the jaspr create command to scaffold a new project:
jaspr create my_website
The CLI will prompt you for:
  • Project name: Confirm or change the project name
  • Setup options: Choose between different project templates (basic, with routing, etc.)
The default template includes a basic setup with server-side rendering configured.
2

Navigate to your project

cd my_website
3

Explore the project structure

Your new Jaspr project contains:
my_website/
├── lib/
│   ├── components/
│   │   └── app.dart          # Main app component
│   ├── main.client.dart       # Client entry point
│   └── main.server.dart       # Server entry point
├── web/
│   └── index.html            # HTML template
├── pubspec.yaml              # Dependencies
└── build.yaml                # Build configuration

​
Run the Development Server

1

Start the server

Run the development server with hot-reload:
jaspr serve
Expected output:
[INFO] Building...
[INFO] Succeeded after 2.3s
[INFO] Serving at http://localhost:8080
2

Open in browser

Navigate to http://localhost:8080 in your web browser. You should see your app running!
3

Try hot-reload

Open lib/components/app.dart and change the “Hello World” text to something else. Save the file and watch your browser automatically refresh with the changes.
Hot-reload preserves your app state during development, making iteration fast and smooth.

​
Build Your First Component

Let’s create a simple interactive component to understand Jaspr’s component model.
1

Create a counter component

Create a new file lib/components/counter.dart:
import 'package:jaspr/jaspr.dart';

@client
class Counter extends StatefulComponent {
  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int count = 0;

  void increment() {
    setState(() {
      count++;
    });
  }

  @override
  Component build(BuildContext context) {
    return div([
      h2([text('Counter Example')]),
      p([text('Count: $count')]),
      button(
        onClick: increment,
        [text('Increment')],
      ),
    ]);
  }
}
The @client annotation tells Jaspr to make this component interactive by running it on the client side.
2

Use the component

Update lib/components/app.dart to include your counter:
import 'package:jaspr/jaspr.dart';
import 'counter.dart';

class App extends StatelessComponent {
  @override
  Component build(BuildContext context) {
    return div([
      h1([text('Welcome to Jaspr')]),
      Counter(),
    ]);
  }
}
3

See it in action

Save both files and your browser will automatically refresh. Click the “Increment” button to see the counter in action!

​
Understanding Components

Jaspr has three main types of components, similar to Flutter widgets:

StatelessComponent

A basic component with a single build() method. Use for UI that doesn’t change.

StatefulComponent

A component that holds state and can trigger rebuilds with setState(). Use for interactive UI.

InheritedComponent

A component that provides data to its descendants. Use for sharing state down the tree.

​
HTML Elements as Components

Jaspr provides all HTML elements as components: 
div([
  h1([text('Welcome to Jaspr')]),
  p([text('This is a paragraph')]),
  a(
    href: 'https://jaspr.site',
    [text('Visit Jaspr')],
  ),
])

​
CLI Commands Reference

Here are the essential Jaspr CLI commands:

​
jaspr create

Creates a new Jaspr project with interactive prompts for configuration. 
jaspr create my_website

​
jaspr serve

Serves your website with hot-reload for development. 
jaspr serve
Options:
  • --port or -p: Specify the port (default: 8080)
  • --host: Specify the host (default: localhost)

​
jaspr build

Builds your website for production, creating static assets and the optional server executable. 
jaspr build
The output is generated in the build/jaspr directory:
  • Compiled JavaScript files
  • HTML files
  • CSS and other assets
  • Server executable (if using SSR)
After building, you can deploy the contents of build/jaspr to any static hosting provider or run the server executable for SSR.

​
Next Steps

Now that you have a running Jaspr application, here’s what to explore next:

Components

Learn about component lifecycle, state management, and composition

Styling

Discover how to style your components with CSS and inline styles

Routing

Add navigation to your app with jaspr_router

Server-Side Rendering

Deep dive into SSR and client-server state synchronization
Remember to run jaspr build before deploying to production. The development server is not optimized for production use.

​
Troubleshooting

​
Hot-reload not working

If hot-reload isn’t working:
  1. Make sure you’re running jaspr serve (not jaspr build)
  2. Check the terminal for any error messages
  3. Try stopping the server (Ctrl+C) and starting again

​
Build errors

If you encounter build errors:
  1. Run dart pub get to ensure dependencies are installed
  2. Check that your Dart SDK version meets the minimum requirement (3.8.0+)
  3. Clear the build cache: rm -rf .dart_tool/build

​
Component not rendering

If a component isn’t rendering:
  1. Check that you’re importing the component correctly
  2. For interactive components, ensure you’ve added the @client annotation
  3. Check the browser console for JavaScript errors

Build docs developers (and LLMs) love

Get started for freeTalk to us