Dartvel docs: install the CLI and run your first app

You need Flutter 3.47 or newer, which ships Dart 3.13. Pick one install method.

# pub: the CLI as a global command
dart pub global activate dartvel_cli

# Homebrew: a prebuilt binary
brew install Danroyal001/dartvel_dev/dartvel_dev

# In a project, from its dev_dependencies
dart run dartvel_cli:dartvel --help

# npm: the same prebuilt binary
npm install -g dartvel_dev

You can also download the binary from the GitHub releases page. dartvel ensure-path adds it to your PATH if your shell cannot find it.

Activate dartvel_cli, the command. dartvel_dev is the package your app depends on, and it depends on Flutter, which pub does not run as a global command.

Pub puts dartvel in ~/.pub-cache/bin. Add that to your PATH if your shell cannot find it.

The Homebrew tap is updated after each release, so it can be a version behind pub.dev.

dart run works in a project that already lists dartvel_cli in dev_dependencies, which dartvel create writes. The first run compiles the CLI, so it is slower than the binary.

The release binaries behind Homebrew and npm (v0.11.5) are Linux only, for x64 and arm64. The macOS and Windows binaries follow when the release workflow can run again.

dartvel create my_app
cd my_app

It runs flutter create, then adds pages, a backend and the Dartvel dependencies.

dartvel dev

Edit a page and Flutter hot-reloads. Edit a backend function and only the backend restarts.

dartvel dev and dartvel build write lib/dartvel_client for you. After a fresh clone, run dartvel routes once before your editor analyzes the project.

@DVPage(title: 'Home')
Widget _indexPage(BuildContext context) => DVBox.list(<Widget>[
      const DVText('Hello from Dartvel'),
      DVNavLink(to: DVRoutes.about, child: const DVText('About us')),
    ]);

The annotated function is private. Dartvel generates the public page and the DVRoutes target.

Import the generated barrel, dartvel_client.dart. It exports Dartvel and your generated code.

my_app/
  pubspec.yaml            # dependencies and the dartvel: block
  .env  .env.example      # values read at startup
  lib/
    main.dart
    pages/                # one file per route
      index.dart
      index.loading.dart  # shown while the page loads
      index.error.dart    # shown when it fails to load
    models/               # @DVModel classes
    components/           # your widgets
    styles/  services/
    backend/functions/    # one file per endpoint
      health.get.dart
      contact.dart
    dartvel_client/       # generated, ignored by git
  test/

dartvel:
  backendHost: 0.0.0.0
  backendPort: 3000
  devBackendHost: http://localhost:3000
  prodBackendHost: https://api.my-app.com
  pagesDir: lib/pages
  backendDir: lib/backend
  apiBasePath: /api
  envFiles: [.env, .env.local]

The app calls devBackendHost in development and prodBackendHost in a release build.

Each directory has a key of its own: pagesDir, modelsDir, backendDir, componentsDir, stylesDir and servicesDir. Leave one out and it keeps the path shown above.

# pubspec.yaml
dartvel: config/dartvel.dart

Point dartvel: at a Dart file instead of a map. The file must declare a public class that extends DartvelConfig.

dartvel_dev re-exports the Dartvel packages as barrels: dartvel_ui.dart, dartvel_backend.dart, dartvel_auth.dart, dartvel_database.dart, dartvel_storage.dart, dartvel_ai.dart and more. A generated app imports its own dartvel_client.dart barrel.

Directory keys take one path each. Glob patterns are not read, so pages cannot live in two directories.

The Rust bindings are DVRust and DVRustInt, one integer type. They are types you construct, so there is no DV.Rust to call.

DV.Auth.configure(DVLocalAuthProvider());
DV.Notifications.mail.useProvider(DVMemoryMailProvider());

These are the in-memory versions for development. Each topic page shows the production adapters.

You set the database in configuration and write no code for it. The generated backend opens DATABASE_URL for your data models and jobs.

# .env
DATABASE_URL=sqlite:dartvel.db

dartvel create shop
cd shop && dartvel dev
dartvel db migrate
dartvel test
dartvel build web-server
dartvel deploy
dartvel upgrade --plan

upgrade --plan lists what a new Dartvel release would change in your project, and dartvel migrate-code --apply rewrites the source for you.

dartvel upgrade updates the CLI. Applying the project changes listed by upgrade --plan is Planned; the plan is read-only.

dartvel inspect routes
dartvel inspect models
dartvel explain DV-GEN-001

inspect prints the routes, models, functions and jobs the build found, from the same project graph Studio reads.

There is no inspector yet for modules, transactions, the schema or generated files.

dartvel generate --check

The same project generates byte-identical files on any machine and in any folder, with no timestamps or absolute paths.

generate --check fails your CI when the committed files are stale, without touching the project.

Twenty-five sections are a frozen public contract with unfinished code behind them. Contract stability and implementation status are tracked separately.

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

Getting started

Install the CLI

Create an app

Run it with dartvel dev

Write your first page

Project structure

The dartvel block in pubspec.yaml

Keep the configuration in Dart

One package with every import

Choose your services at startup

Go from idea to production with one CLI

Ask the CLI what your project contains

Generated code is the same on every machine

Check what is built before you depend on it