DEV Community: Serverpod

Type-safe everything - Eliminate manual API glue code

Jamiu Okanlawon — Thu, 01 Oct 2026 09:28:14 +0000

Every Flutter app that talks to a backend needs some code you never really wanted to write. That includes an endpoint path, an HTTP request, JSON parsing, and a client model that must match the data defined on the server. None of it is the feature, but all of it has to stay correct.

When you maintain the code that connects to the server by hand, it has to change with the API. Add three fields to a response, and you'll need to update the client model and parsing code before Flutter can use them. Each edit is small, but the server response, client model, and parser all have to stay in sync.

Serverpod, an open-source backend written in Dart for Flutter, takes a different approach. You define each model once, and Serverpod generates the model classes and serialization code for both your server and Flutter app. It also generates type-safe client methods from your endpoints. Those generated types let the Dart analyzer catch type errors before you run the app.

In this article, we'll build a ride fare estimator, call it from Flutter, and then modify its API. We'll see which parts of that change we need to write, which parts Serverpod generates, and how the analyzer catches a mismatch.

How Serverpod connects the server and Flutter

For our fare estimator, the app sends a pickup location and a destination. The server calculates the price and returns it with a currency code for Flutter to display.

A model describes the data your app sends or receives. An endpoint contains the Dart methods that your app can call on the server.

The serialization code turns Dart objects into a format that can be sent between the app and server. It turns received data back into Dart objects. Flutter calls the endpoint through a generated client method.

Before we start

If you haven't installed Serverpod yet, follow the installation guide. Then create a project:

serverpod create tripquote

Keep the recommended defaults during setup.

The project contains three packages. Here are the parts we'll use, including the fare files we'll add next:

tripquote/
├── tripquote_server/lib/src/fare/   # Models and endpoint we'll add
│   ├── location.spy.yaml
│   ├── fare_estimate.spy.yaml
│   └── fare_endpoint.dart
├── tripquote_client/               # Generated client code
└── tripquote_flutter/lib/main.dart # Flutter code

Open the tripquote directory, then start the project:

cd tripquote
serverpod start

Keep it running while you follow the tutorial. Serverpod watches your models and endpoints and regenerates the connecting code when they change.

Build the fare estimator

The fare estimator needs a pickup location and a destination. Start by defining a Location model for both.

Model definitions go in .spy.yaml files. Create tripquote_server/lib/src/fare/location.spy.yaml with:

### A geographic point.
class: Location
fields:
  ### Degrees north of the equator.
  latitude: double
  ### Degrees east of the prime meridian.
  longitude: double

Next, define the estimate that the server will return. Create tripquote_server/lib/src/fare/fare_estimate.spy.yaml with:

### What a ride is expected to cost.
class: FareEstimate
fields:
  ### The estimated fare.
  fare: double
  ### ISO currency code, such as USD.
  currency: String

With these models in place, let’s create an endpoint to calculate the estimate. We'll use a base fare of USD 2.50 plus USD 1.20 per kilometer.

Create tripquote_server/lib/src/fare/fare_endpoint.dart with the following code. The helper functions calculate the distance and round the fare to two decimal places:

import 'dart:math';
import 'package:serverpod/serverpod.dart';
import '../generated/protocol.dart';

/// Estimates what a ride will cost.
class FareEndpoint extends Endpoint {
  /// Returns an estimate for a ride from [pickup] to [destination].
  Future<FareEstimate> estimateFare(
    Session session,
    Location pickup,
    Location destination,
  ) async {
    const baseFare = 2.50;
    const pricePerKm = 1.20;

    final distanceKm = _distanceKm(pickup, destination);
    final fare = baseFare + distanceKm * pricePerKm;

    return FareEstimate(fare: _round(fare), currency: 'USD');
  }
}

/// The great-circle distance between two points, in kilometers.
double _distanceKm(Location start, Location end) {
  const earthRadiusKm = 6371.0;
  final latitudeDelta = _toRadians(end.latitude - start.latitude);
  final longitudeDelta = _toRadians(end.longitude - start.longitude);
  final a =
      pow(sin(latitudeDelta / 2), 2) +
      cos(_toRadians(start.latitude)) *
          cos(_toRadians(end.latitude)) *
          pow(sin(longitudeDelta / 2), 2);
  return 2 * earthRadiusKm * asin(sqrt(a));
}

double _toRadians(double degrees) => degrees * pi / 180;
double _round(double value) => (value * 100).round() / 100;

The Session parameter gives the endpoint access to server features such as logging and the database. It stays on the server, so Flutter only needs to send the two locations.

Call the endpoint from Flutter

When you save the endpoint from the previous section, Serverpod generates client.fare.estimateFare. It accepts two Location objects and returns a Future<FareEstimate>.

The template already sets up client in tripquote_flutter/lib/client.dart. Keep that file unchanged.

Create tripquote_flutter/lib/screens/fare_screen.dart with:

import 'package:flutter/material.dart';
import 'package:tripquote_client/tripquote_client.dart';

import '../client.dart';

class FareScreen extends StatefulWidget {
  const FareScreen({super.key});

  @override
  State<FareScreen> createState() => _FareScreenState();
}

class _FareScreenState extends State<FareScreen> {
  late final Future<FareEstimate> _estimate;

  @override
  void initState() {
    super.initState();

    _estimate = client.fare.estimateFare(
      Location(latitude: 6.5244, longitude: 3.3792),
      Location(latitude: 6.4281, longitude: 3.4219),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Center(
      child: FutureBuilder<FareEstimate>(
        future: _estimate,
        builder: (context, snapshot) {
          if (snapshot.hasError) {
            return const Text('Could not load the fare.');
          }

          final estimate = snapshot.data;
          if (estimate == null) {
            return const CircularProgressIndicator();
          }

          return Text(fareLabel(estimate));
        },
      ),
    );
  }
}

String fareLabel(FareEstimate estimate) {
  return '${estimate.currency} ${estimate.fare}';
}

In tripquote_flutter/lib/main.dart, replace the greeting-screen import with:

import 'screens/fare_screen.dart';

In MyHomePage, replace body: const GreetingsScreen(), with:

body: const FareScreen(),

In MyApp, change the home-page title:

home: const MyHomePage(title: 'Fare estimate'),

Keep the rest of main.dart, including await initializeClient(), unchanged.

The call to client.fare.estimateFare sends the pickup and destination to the server. The returned FareEstimate has typed fields, so our fareLabel function can read currency and fare directly.

Keep the server running and hot restart the Flutter app by pressing R in the serverpod start terminal. A successful request for these locations displays:

USD 16.54

You don't write an HTTP request, specify an endpoint path, or maintain a matching model in Flutter. Serverpod generates the code needed to transfer the data between the app and server.

The endpoint's documentation also appears in the generated client. Hover over estimateFare in your editor to read the description from the server code.

Add more data to the response

Suppose the app now needs to show a price range and tell the rider when surge pricing applies. It should still show a single fare when surge pricing does not apply.

Try replacing the fare

A first approach is to replace fare with two range fields. Replace the contents of tripquote_server/lib/src/fare/fare_estimate.spy.yaml with:

### What a ride is expected to cost.
class: FareEstimate
fields:
  fareLow: double
  fareHigh: double
  currency: String

Save the model, leaving the endpoint and Flutter code unchanged. Wait for serverpod start to process the change.

The Dart analyzer now reports errors in the server endpoint and the Flutter app:

Now update the endpoint to match the model. For this example, set the low price 10% below the estimate and the high price 15% above it. In tripquote_server/lib/src/fare/fare_endpoint.dart, keep the distance and fare calculations inside estimateFare. Replace only its return statement with:

    return FareEstimate(
      fareLow: _round(fare * 0.9),
      fareHigh: _round(fare * 1.15),
      currency: 'USD',
    );

Save both files and wait for serverpod start to finish regenerating. Leave the Flutter code unchanged.

The Dart analyzer now flags estimate.fare in fareLabel:

The getter 'fare' isn't defined for the type 'FareEstimate

The generated FareEstimate no longer has fare, but our Flutter code still reads that field. The analyzer reports the mismatch before we run the updated app.

The first attempt removed a value the app still needs for ordinary pricing. We'll keep fare and add the extra information alongside it instead.

Keep the fare and add optional details

Replace the contents of tripquote_server/lib/src/fare/fare_estimate.spy.yaml with:

### What a ride is expected to cost.
class: FareEstimate
fields:
  ### The estimated fare, adjusted when surge applies.
  fare: double
  ### ISO currency code, such as USD.
  currency: String
  ### The low end of the fare range.
  fareLow: double?
  ### The high end of the fare range.
  fareHigh: double?

The new fields have values only when surge pricing applies. The ? allows them to be null otherwise. The response always includes fare.

We'll use priceSurge to turn surge pricing on or off in this example. When it is true, the server doubles the fare before calculating the range.

In tripquote_server/lib/src/fare/fare_endpoint.dart, replace the FareEndpoint class with the code below. Include the priceSurge line above the class, and keep the imports and helper functions unchanged:

bool priceSurge = false;

/// Estimates what a ride will cost.
class FareEndpoint extends Endpoint {
  /// Returns an estimate for a ride from [pickup] to [destination].
  Future<FareEstimate> estimateFare(
    Session session,
    Location pickup,
    Location destination,
  ) async {
    const baseFare = 2.50;
    const pricePerKm = 1.20;

    final distanceKm = _distanceKm(pickup, destination);
    final fare = baseFare + distanceKm * pricePerKm;

    if (!priceSurge) {
      return FareEstimate(fare: _round(fare), currency: 'USD');
    }

    const surgeMultiplier = 2.0;
    final surgeFare = fare * surgeMultiplier;

    return FareEstimate(
      fare: _round(surgeFare),
      currency: 'USD',
      fareLow: _round(surgeFare * 0.9),
      fareHigh: _round(surgeFare * 1.15),
    );
  }
}

Save the model and endpoint files. After regeneration, estimate.fare is valid again. The two new fields are also available in Flutter.

Display the new fields in Flutter

In tripquote_flutter/lib/main.dart, replace only fareLabel. Keep the client setup, request, and widget unchanged:

String fareLabel(FareEstimate estimate) {
  final low = estimate.fareLow;
  final high = estimate.fareHigh;

  if (low != null && high != null) {
    return '${estimate.currency} $low to $high\nSurge pricing';
  }

  return '${estimate.currency} ${estimate.fare}';
}

When both range values are present, the display shows the range and indicates that surge pricing applies. Otherwise, it shows the single fare.

With priceSurge set to false, restart the server and Flutter app. The screen shows:

USD 16.54

Set priceSurge to true, then restart both again:

USD 29.77 to 38.05
Surge pricing

Restarting the server applies the changed flag. Restarting Flutter makes a new request.

The request stayed the same. We updated the model definition, pricing logic, and Flutter display. Serverpod generated the corresponding model classes and conversion code on both sides, along with the code that connects the endpoint to Flutter.

You write the contract. Serverpod generates the plumbing.

The same process works with more than the numbers and strings used in the example above. Enums, lists, maps, nested models, byte data, and UUIDs are a few of the other supported types. The model documentation covers the full set.

Conclusion

The code that connects your Flutter app to its backend has to be right. Maintaining it still takes time away from the feature you're building, even with help from a coding agent. Serverpod reduces that maintenance, while the Dart analyzer helps catch type errors before you run the app.

To apply the same approach to another feature, learn how to call Google APIs from a Serverpod backend.

Happy coding!

Accessing Google APIs server-side from a Flutter app

Jamiu Okanlawon — Thu, 13 Aug 2026 16:51:14 +0000

Your Flutter app needs data that lives in a user’s Google account. Their calendar, their contacts, their files. Google’s APIs will hand it over, but not to just anyone: the user has to consent in your app, and your backend needs an access token that lets it act on their behalf.

That second part is where most Flutter developers get stuck, because it means OAuth credentials, token verification, authenticated sessions, and a backend to hold them.

With Serverpod, that backend comes with Google sign-in built in. When a user signs in, your server gets their verified identity and receives an access token. Reading their calendar is an HTTP call away.

In this article, we’ll wire it end-to-end: Google sign-in for a Flutter app, and a backend that reads the user’s upcoming calendar events the moment they sign in. We will demonstrate it with the calendar, but the pattern is the same for any Google API that the user can grant you access to.

Understanding the flow

Before configuring anything, it’s worth understanding the whole journey.

When a user signs in, your app asks Google for two things: proof of who the user is, and permission to read their calendar. Google shows the consent screen, and what comes back reaches your Serverpod backend.

The server verifies that the identity token was issued by Google, creates an authenticated session, and receives the access token that carries the user’s consent. That token is what lets your backend call Google’s APIs for this user.

The user grants access in your app. API access occurs on your server.

Before we start

We’ll begin with a new Serverpod project created using:

serverpod create my_project

During project creation, keep the recommended defaults and make sure Authentication remains enabled when prompted.

The command gives you a Flutter app (my_project_flutter), the backend it talks to (my_project_server), and a generated client package that connects the two, so your app calls the server using plain Dart methods.

With the project in place, we’re ready to connect it to Google.

Configuring Google

Every Google integration begins in Google Cloud, regardless of which backend you’re using.

You’ll need to:

Create a Google Cloud project.
Configure the Google Auth Platform.
Enable the required APIs: the People API, which Serverpod uses for basic profile data, and the Calendar API, which is used in this article.
Under Data access, add the userinfo.email, userinfo.profile, and calendar.readonly scopes.
Create a Web OAuth client for your backend, and any platform-specific clients your app needs.

The Calendar scope is sensitive, so Google may ask you to verify your app before you publish it. While it’s in testing mode, any account you add as a test user can sign in.

The complete walkthrough, including platform-specific configuration for Android, iOS, and the web, is covered in the Serverpod documentation.

Once those credentials are ready, it’s time to connect them to Serverpod.

Connecting Google to Serverpod

The first step in connecting your backend to Google is making your Google credentials available to Serverpod.

Copy your Web OAuth credentials into config/passwords.yaml.

development:
  googleClientSecret: |
    {
      "web": {
        "client_id": "your-client-id.apps.googleusercontent.com",
        "client_secret": "your-client-secret",
        "redirect_uris": []
      }
    }

Serverpod reads these credentials at startup and uses them to verify Google identity tokens.

The credential block is a YAML block scalar, so an indentation error silently produces malformed JSON and surfaces later as an authentication failure rather than an error at startup.

The complete credential structure, along with production configuration options, is covered in the documentation.

Register the Google provider

Next, register Google as one of your application’s identity providers.

pod.initializeAuthServices(
  tokenManagerBuilders: [
    JwtConfigFromPasswords(),
  ],
  identityProviderBuilders: [
    GoogleIdpConfigFromPasswords(),
  ],
);

GoogleIdpConfigFromPasswords() reads the credentials from passwords.yaml and configures Google as an available authentication provider.

The final server-side step is exposing that provider through an endpoint.

import 'package:serverpod_auth_idp_server/providers/google.dart';

class GoogleIdpEndpoint extends GoogleIdpBaseEndpoint {}

That’s the entire endpoint.

Serverpod already provides the implementation. Your application exposes it, making the Google authentication flow available to your Flutter client.

Reading the calendar from your server

When a user signs in, Serverpod passes your code the access token via a callback in the provider config. Whatever you do with it runs on your server, with the user’s consent.

Add the http package to your server, then extend the provider registration:

dart pub add http    # from my_project_server

// my_project_server/lib/server.dart

import 'dart:convert';
import 'package:http/http.dart' as http;
pod.initializeAuthServices(
  // ... tokenManagerBuilders stay as they are ...
  identityProviderBuilders: [
    GoogleIdpConfigFromPasswords(
      getExtraGoogleInfoCallback: (
        session, {
        required accountDetails,
        required accessToken,
        required transaction,
      }) async {
        try {
          final response = await http.get(
            Uri.https('www.googleapis.com', '/calendar/v3/calendars/primary/events', {
              'maxResults': '5',
              'singleEvents': 'true',
              'orderBy': 'startTime',
              'timeMin': DateTime.now().toUtc().toIso8601String(),
            }),
            headers: {'Authorization': 'Bearer $accessToken'},
          );
          if (response.statusCode != 200) {
            session.log('Calendar request failed: ${response.statusCode}',
                level: LogLevel.warning);
            return;
          }
          final events = (jsonDecode(response.body)['items'] as List?) ?? [];
          for (final event in events) {
            session.log('Upcoming: ${event['summary'] ?? '(no title)'}');
          }
        } catch (e) {
          session.log('Calendar read skipped: $e', level: LogLevel.warning);
        }
      },
    ),
  ],
);

That’s a real Google API call, made by your backend, for the user who just signed in. This example logs their next five events. Yours might store them instead.

There are two things to know about this callback.

First, it runs as part of the sign-in flow. If the calendar request fails and the error goes uncaught, the entire sign-in fails too. Treat the calendar read as optional: log the error and let sign-in continue.

Second, the access token passed to the callback is short-lived. It works well for reading calendar data immediately during sign-in. If you need to sync calendar data later, such as in a scheduled or background job, you’ll need to store the credentials and handle token refresh separately.

The same token works against any Google API covered by the scopes the user granted. The documentation covers how to request additional scopes and use the token in your own code.

Running the application

With the backend configured, it’s time to start the project.

serverpod start

That’s the only command it takes.

Besides launching your backend, Flutter application, and development services, serverpod start automatically generates any required code before starting the project.

If your authentication setup introduces new database tables, there’s no need to stop the server. While serverpod start is running, press M to create and apply the migration. Once it has been applied, development continues without interrupting your workflow.

With the backend running, the remaining setup happens in Flutter.

Connecting Flutter

The template already initializes authentication when the app starts. Adding Google is one more call in main.dart, right after client.auth.initialize():

client.auth.initializeGoogleSignIn(
  serverClientId: '<web-client-id>.apps.googleusercontent.com',
);

The serverClientId is the Web application client ID from earlier, not one of the platform-specific ones. That’s deliberate: the sign-in happens in your app, but the tokens are for your server, and this value tells Google which server that is. On the web, the same value is used as clientId, along with a redirect URI. The documentation includes the exact call for each platform.

Then ask for the calendar scope when the user signs in. The sign-in screen that ships with the template uses SignInWidget, which accepts a customized Google button:

SignInWidget(
  client: client,
  googleSignInWidget: GoogleSignInWidget(
    client: client,
    scopes: [
      ...GoogleAuthController.defaultScopes,
      'https://www.googleapis.com/auth/calendar.readonly',
    ],
  ),
)

The scopes here are what Google puts on the consent screen and what your server’s access token is allowed to do.

Trying it out

Run the app and tap the Google button.

The consent screen now asks for calendar access alongside the usual profile permissions.

Approve it, and watch your server’s logs.

Your backend just called Google on the user’s behalf. Sign-in, verification, session, and a working API call, and the only authentication code you wrote was a callback.

A pattern you’ll reuse

The calendar was just an example. Change the scopes you request, and the endpoint you call, and the same flow reads Google Drive files, Contacts, or YouTube data. Add another identity provider, and the same four steps repeat: configure the provider, register it with Serverpod, expose its endpoint, and initialize it in Flutter.

The provider-specific configuration changes, but the authentication architecture stays the same. That consistency is one of the advantages of Serverpod’s authentication system. As your application grows, you don’t have to rethink your authentication flow. You just plug in another provider, or another API, and keep building.

Conclusion

Accessing Google APIs from a Flutter app has a reputation for being complicated, and most of that reputation stems from the requirements Google imposes, no matter what backend you use: credentials, consent, and verification. Once those are in place, Serverpod’s side is a config entry, an empty endpoint class, and a callback that receives a ready-to-use access token.

From there, Serverpod handles verifying identity tokens, creating authenticated sessions, and maintaining consistent authentication across your application. What you do with the APIs is up to you.

Happy coding!

Serverpod 4 - The first agentic coding engine that hot-reloads the full stack

Viktor Lidholt — Tue, 09 Jun 2026 14:14:47 +0000

Today, we’re thrilled to share a tech preview of Serverpod 4. The first agentic coding engine that hot-reloads the full stack and can run locally on your computer. If you are a developer, this will forever change the way you think about building apps. We are finally closing the loop between your app's output, the backend, and your AI agent.

👉 Join us on Discord to be among the first ones to try it out.

Here is what makes Serverpod 4 radically different: Sub-second stateful hot reload across the server, database, web, and app. Everything is wired up to your favorite AI agent through a tried and tested MCP server and skills. We’ve added an embedded Postgres database; there's no need for complex setup or Docker containers. Everything just works.

You can literally see your app evolving as the agent works. No recompilation. No restart. No wait.

Serverpod 4 runs locally on your computer, and with Flutter for the frontend, your app runs at native speed on any platform. And did we say that it’s all free and open source?

What's in the package?

Servepod is an open-source, scalable backend written in Dart for the Flutter community. It provides end-to-end type safety all the way from the database to the client app, catching many errors before the app is even started. You can add a method on the server and call it from your app as if it were a local method.

New in Serverpod 4 is a complete full-stack runtime for agentic coding. One of Flutter’s core strengths has always been its stateful hot reload. We are now bringing this to the server and to the database. The serverpod start command will manage your full stack, including the Flutter app. Whenever you make a change to your code, database schema, or frontend, Serverpod will pick up the changes and instantly hot-reload them.

Your AI agent can interact with the running server through a new MCP server. It can create and apply database migrations, read logs, and even drive the app, taking and reviewing screenshots. The bundled rules and skills turn the AI agent into a senior Serverpod developer, and even lower-tier models understand how to write reliable, testable code.

We are still working hard to iron out the last couple of issues, but we are getting very close to a final release. We cannot wait to see what you will build with Serverpod.