Dartvel routing: file pages, links and layouts

// lib/pages/about.dart is served at /about.
import 'package:flutter/widgets.dart';

import '../dartvel_client/dartvel_client.dart';

@DVPage(title: 'About us')
Widget _aboutPage(BuildContext context) => const DVBox.list(<Widget>[
      DVText('About us'),
      DVText('We make tools for Flutter teams.'),
    ]);

A file under lib/pages is the short way. A route can also be declared in code, in lib/routes.dart, which suits a screen that is not a page of its own, a path built from something else, or a codebase that already keeps its routes in one place.

// lib/routes.dart, read by dartvel routes. Each route here gets a typed
// target on DVRoutes beside the pages' own, and the generated router mounts
// the list with them: one router, one DVRoutes, whichever way a route was
// declared.
final List<DVRouteNode> routes = <DVRouteNode>[
  DVRoute(
    path: '/settings',
    title: 'Settings',
    builder: (BuildContext context, DVRouteState state) =>
        SettingsScreen(tab: state.query['tab']),
  ),
  DVRoute(
    path: '/roasters',
    title: 'The roasters',
    builder: (BuildContext context, DVRouteState state) => const RoastersScreen(),
    routes: <DVRouteNode>[
      DVRoute(
        // Nested, so this is /roasters/:person. The name is given because
        // /roasters/:person would derive DVRoutes.roasters, which the parent
        // already is.
        path: ':person',
        name: 'roaster',
        builder: (BuildContext context, DVRouteState state) =>
            RoasterScreen(person: state.params['person']!),
      ),
    ],
  ),
];

DVShellRoute and DVStatefulShellRoute wrap children in shared chrome, and take a redirect that may be async, so a session check shows the pending view and never a blank screen.

dartvel.routes in pubspec.yaml points at another file. A route the reader cannot parse stops the build with DV-ROUTE-003. It is not skipped: a skipped route still runs, with no typed target and no page on the web.

// lib/pages/team.dart is served at /team.
@DVPage(title: 'Team')
Widget _teamPage(BuildContext context) {
  final DVSignal<bool> showAll = context.signal(false);
  final List<String> people = <String>['Ada', 'Grace', 'Linus', 'Margaret'];
  final List<String> shown = showAll.value ? people : people.take(2).toList();

  return DVBox.list(<Widget>[
    for (final String name in shown) DVText(name),
    DVText(showAll.value ? 'Show fewer' : 'Show everyone').modifier(
      DVModifier().semanticButton().onTap(() => showAll.value = !showAll.value),
    ),
  ]);
}

// lib/pages/blog/[id].dart is served at /blog/:id.
import 'package:flutter/widgets.dart';

import '../../dartvel_client/dartvel_client.dart';

@DVPage(title: 'Blog post')
Widget _blogPostPage(BuildContext context) => DVBox.list(<Widget>[
      DVText('Post ${context.dvParams['id']}'),
      DVText('Sorted by ${context.dvQuery['sort'] ?? 'date'}'),
    ]);

DVRoutes.index               // /
DVRoutes.about               // /about
DVRoutes.blog(id: '42')      // /blog/42

DVText('Open post 7').modifier(
  DVModifier().onTap(() => context.navigateToPage(DVRoutes.blog(id: '7'))),
),
DVText('Back to home').modifier(
  DVModifier().onTap(DV.Navigation.to(DVRoutes.index)),
),
// A query is still a typed route. Both halves are generated targets,
// so a page that moves is a compile error here.
DVText('Sign in and come back').modifier(
  DVModifier().onTap(DV.Navigation.to(
    DVRoutes.accountsecurity.withQuery(<String, String>{
      'from': DVRoutes.accountsettings.path,
    }),
  )),
),

target.withQuery(...) adds a query and stays a route. /sign-in?from=/account is two generated targets in one call, so either page moving is a compile error. Values are encoded.

DVNavLink(
  to: DVRoutes.about,
  child: const DVText('About us'),
),

DVNavLink(
  to: DVRoutes.blog(id: '42'),
  preload: DVLinkPreload.hover, // none, hover, visible, immediate
  preview: DVLinkPreview.none, // none, auto
  child: const DVText('Read post 42'),
),
DVNavLink.external(
  'https://pub.dev/packages/dartvel_dev',
  child: const DVText('Dartvel on pub.dev'),
),

DVNavLink(
  to: DVRoutes.about,
  preview: DVLinkPreview.widget(
    const Padding(
      padding: .all(16),
      child: DVText('Meet the people building our app.'),
    ),
  ),
  child: const DVText('About us'),
),

A custom preview replaces the destination page with your widget, including its buttons and scrolling. It gets at most 340 × 240 logical pixels, reduced to fit the safe screen area and keyboard. Use normal constrained layouts inside it. It does not need a registered destination preview.

// lib/pages/_layout.dart wraps every page in lib/pages.
import 'package:flutter/widgets.dart';

import '../dartvel_client/dartvel_client.dart';

class const Layout({super.key, required super.child}) extends DartvelLayout {
  @override
  Widget build(BuildContext context) => DVBox.list(<Widget>[
        DVBox.row(<Widget>[
          DVNavLink(to: DVRoutes.index, child: const DVText('Home')),
          DVNavLink(to: DVRoutes.about, child: const DVText('About')),
        ], spacing: 16),
        Expanded(child: child),
      ]);
}

// lib/pages/blog/_layout.dart wraps the pages under /blog,
// inside the root layout.
import 'package:flutter/widgets.dart';

import '../../dartvel_client/dartvel_client.dart';

class const BlogLayout({super.key, required super.child})
    extends DartvelLayout {
  @override
  Widget build(BuildContext context) => DVBox.row(<Widget>[
        const DVText('Blog'),
        Expanded(child: child),
      ], spacing: 24);
}

// lib/pages/account/_guard.dart runs before every page under /account.
import 'dart:async';

import 'package:flutter/widgets.dart';

import '../../dartvel_client/dartvel_client.dart';

FutureOr<String?> guard(BuildContext context, GoRouterState state) {
  // Return a path to redirect there, or null to let the page open.
  if (DV.Auth.currentUser == null) return DVRoutes.index.path;
  return null;
}

// lib/pages/about.loading.dart
import 'package:flutter/widgets.dart';

import '../dartvel_client/dartvel_client.dart';

@DVFunctionalWidget()
Widget _aboutPageLoading(BuildContext context) => const DVText('Loading');

// lib/pages/about.error.dart
import 'package:flutter/widgets.dart';

import '../dartvel_client/dartvel_client.dart';

@DVFunctionalWidget()
Widget _aboutPageError(BuildContext context) =>
    const DVText('That did not load');

# pubspec.yaml
dartvel:
  notFoundRedirect: /

@DVPage(
  title: 'Pricing',
  sitemap: DVPageSitemap(
    priority: 0.8,
    changeFrequency: DVSitemapChangeFrequency.weekly,
  ),
)
Widget _pricingPage(BuildContext context) => const DVText('Plans');

dartvelRoutes(at: '/app') returns every Dartvel route under a prefix for your own GoRouter. DV.Navigation and DVNavLink place Dartvel targets under it and leave your paths alone.

Each kind of router takes your existing routes as existing:: dartvelGoRouter for go_router, dartvelAutoRoutes for auto_route, dartvelRouteFactory for Navigator 1.0, dartvelNavigator2_0Routes spread into a Navigator 2.0 route table, and dartvelRouterConfig for MaterialApp.router or CupertinoApp.router. Dartvel answers its own paths under the prefix, with its guards, and back goes through Dartvel's stack first. Every other path is handled by your router. dartvel init says which router an app uses.

List your domains under dartvel.deepLinks in pubspec.yaml. dartvel build web writes assetlinks.json and apple-app-site-association, and dartvel doctor --target android,ios checks the deployed files.

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

Routing

Add a page with a file

Or declare routes in a file, if you prefer

Write logic in a page body

Read route and query parameters

Navigate with typed DVRoutes targets

Link with DVNavLink

Choose when it preloads and previews

Show your own preview

Share chrome with _layout.dart

Nest a layout in a folder

Guard a folder with _guard.dart

Show loading and error states

Handle unknown URLs

Set the title and sitemap entry

Layouts, tabs and somebody else's router

Tabs from a folder

Mount into the router you already have

Deep links

Status