docs: Rework the Build your first app guide for 3.5 by developerjamiu · Pull Request #557 · serverpod/serverpod_docs

developerjamiu · 2026-05-27T15:37:21Z

Reworks the "Build your first app" tutorial (the magic recipe app) for Serverpod 3.5, per #545.

What changed across the four pages:

Replaces docker compose + dart bin/main.dart + manual serverpod generate with serverpod start (watch mode, hot reload, embedded Postgres). The app starts once on page 1 and hot reloads through the rest.
Matches the actual beta.9 project template (the screens/ layout and pre-wired client) instead of the stale code snippets.
Migrations are created and applied from the serverpod start TUI (the M and A keys).
Page 4 becomes "Deploy your app", defaulting to Serverpod Cloud, with the old summary folded in as "What you've built".
Adds title and description frontmatter, plus "Before you start" and continuation intros, per the tutorial template.

Note: the upstream magic_recipe example repo that feeds the SNIPSTART snippets is stale for beta.9. This PR inlines correct code; the example repo still needs a separate update.

…d, real template)

Swiftaxe

Overall, a massive improvement of this guide! I added some comments to polish some details even further.

Swiftaxe · 2026-05-28T11:50:00Z

+- Persistent storage with the database.
+- A Flutter app that talks to all of it through the generated client.
+
+We're excited to see what you'll build next. If you need help, ask in our [community on GitHub](https://github.com/serverpod/serverpod/discussions) or join the [Discord community](https://serverpod.dev/discord). To go deeper into any topic, browse the [Concepts](../06-concepts/01-working-with-endpoints/01-working-with-endpoints.md) section.


Discord is the main channel for community discussions, so rearrange this to front with Discord.

Swiftaxe · 2026-05-28T12:24:52Z

-    );
-  }
-}
+import 'package:magic_recipe_client/magic_recipe_client.dart';


While most of this code example is related to the Flutter framework, which needs no explanation, this import is a serverpod concept. We should say something about why we add it.

Swiftaxe · 2026-05-28T12:31:19Z

-  /// Holds the last result or null if no result exists yet.
+class _RecipeScreenState extends State<RecipeScreen> {
+  /// The recipe currently shown, or null if there's none yet.
  Recipe? _recipe;


This is the first time we use a type in Flutter that was generated by Serverpod. It deserves at least a sentence. See the comment above about the import.

Swiftaxe · 2026-05-28T12:47:13Z


 :::info
-On the server, you can do things you don't want to do in the app, like calling an API secured by a secret key or accessing a database. The server can also do things that are impossible in the app, like sending push notifications or emails.
+The server is the right place for work you can't or shouldn't do in the app, such as calling an API secured by a secret key, accessing a database, or sending push notifications and emails. Here, it keeps your Gemini API key off the client.


Sometimes we call the serverpod application and 'app', so let's be specific about what type of app here:

Suggested change

The server is the right place for work you can't or shouldn't do in the app, such as calling an API secured by a secret key, accessing a database, or sending push notifications and emails. Here, it keeps your Gemini API key off the client.

The server is the right place for work you can't or shouldn't do in the Flutter app, such as calling an API secured by a secret key, accessing a database, or sending push notifications and emails. Here, it keeps your Gemini API key off the client.

Swiftaxe · 2026-05-28T12:51:50Z

+## Before you start
+
+- [Serverpod installed](../04-get-started/01-installation.md). Run `serverpod version` to confirm it works.
+- A free Gemini API key. Create one on [Google AI Studio](https://aistudio.google.com/app/apikey); it's free, but you need to sign in with a Google account.


We leave the user without guidance on how to create an API key. Consider adding a screenshot and instructions, or just linking to a high-quality guide maintained by the Google AI Studio team, to explain the steps.

Swiftaxe · 2026-05-28T14:29:00Z

+You've built and deployed a full-stack app with Flutter and Serverpod:
+
+- A custom endpoint that calls an external API from the server.
+- A typed data model shared between the server and the app.


Suggested change

- A typed data model shared between the server and the app.

- A typed data model shared between the server and the Flutter app.

Swiftaxe · 2026-05-28T14:38:55Z


 :::info
-For methods to be recognized by Serverpod, they need to return a typed `Future` or `Stream`, where the type must be `void` `bool`, `int`, `double`, `String`, `UuidValue`, `Duration`, `DateTime`, `ByteData`, `Uri`, `BigInt`, or a [serializable model](../06-concepts/02-models/01-models.md). The first parameter must be a `Session` object. You can pass any serializable types as parameters, and even use `List`, `Map`, `Set` or Dart records as long as they are typed.
+Endpoint methods take a `Session` as their first parameter and return a typed `Future` or `Stream`. You can pass and return primitive types or any [serializable model](../06-concepts/02-models/01-models.md). The class name's `Endpoint` suffix is dropped on the client, so `RecipeEndpoint` is called through `client.recipe`. See [How it works](../04-get-started/03-how-it-works.md) for how that call reaches the server.


Some minor simplification of the language:

Suggested change

Endpoint methods take a `Session` as their first parameter and return a typed `Future` or `Stream`. You can pass and return primitive types or any [serializable model](../06-concepts/02-models/01-models.md). The class name's `Endpoint` suffix is dropped on the client, so `RecipeEndpoint` is called through `client.recipe`. See [How it works](../04-get-started/03-how-it-works.md) for how that call reaches the server.

Endpoint methods take a `Session` as their first parameter and return a typed `Future` or `Stream`. You can pass and return primitive types or any model defined in a .spy.yaml file. The class name's `Endpoint` suffix is dropped on the client, so `RecipeEndpoint` is called via `client.recipe`. See [How it works](../04-get-started/03-how-it-works.md) for how that call reaches the server.

Swiftaxe · 2026-05-28T14:43:25Z

 # Create data models

-Serverpod ships with a powerful data modeling system that uses easy-to-read definition files in YAML. It generates Dart classes with all the necessary code to serialize and deserialize the data and connect to the database. This allows you to define your data models for the server and the app in one place, eliminating any inconsistencies. The models give you fine-grained control over the visibility of properties and how they interact with each other.
+On the [previous page](./01-creating-endpoints.md) your endpoint returned a plain string. Here you'll define a `Recipe` model so the server returns structured, typed data instead. You define the model once in YAML, and Serverpod generates the Dart class plus all the serialization that moves it between server and client.


Suggested change

On the [previous page](./01-creating-endpoints.md) your endpoint returned a plain string. Here you'll define a `Recipe` model so the server returns structured, typed data instead. You define the model once in YAML, and Serverpod generates the Dart class plus all the serialization that moves it between server and client.

On the [previous page](./01-creating-endpoints.md) your endpoint returned a plain string. Here you'll define a `Recipe` model so the server returns structured, typed data instead. You define the model once in YAML, and Serverpod generates the Dart class plus all the serialization needed between server and client.

Swiftaxe · 2026-05-28T14:45:43Z

+Then enter some ingredients and tap **Generate Recipe**. The app calls your endpoint and displays the result:

-Try out the app by clicking the button to get a new recipe. The app will call the endpoint on the server and display the result in the app.
+![Example Flutter App](/img/getting-started/endpoint-chrome-result.png)


The button says "Send to server", while the code and guide set it to "Generate Recipe". Update the screenshot.

Swiftaxe · 2026-05-28T14:48:37Z

 # Manage the database

-In this section, we will build upon the models we created in the previous section and add a database to store the recipes that users create in the app. This will allow our application to persist data between sessions.
+Right now your recipes disappear when the app reloads. Here you'll store them in the database so they persist, and list previously generated recipes in the app. Serverpod maps your model to a table and gives you a typed API to read and write rows, without writing any SQL.


Suggested change

Right now your recipes disappear when the app reloads. Here you'll store them in the database so they persist, and list previously generated recipes in the app. Serverpod maps your model to a table and gives you a typed API to read and write rows, without writing any SQL.

Right now your recipes disappear when the Flutter app reloads. Here you'll store them in the database so they persist, and list previously generated recipes in the app. Serverpod maps your model to a table and gives you a typed API to read and write rows, without writing any SQL.

developerjamiu added 2 commits May 27, 2026 15:26

docs: Rewrite first-app pages 1-2 for 3.5 (serverpod start, hot reloa…

88065dc

…d, real template)

docs: Rewrite first-app database and deploy pages for 3.5

0a29ea5

developerjamiu requested a review from Swiftaxe May 27, 2026 15:38

developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels May 27, 2026

developerjamiu self-assigned this May 27, 2026

Swiftaxe reviewed May 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Rework the Build your first app guide for 3.5#557

docs: Rework the Build your first app guide for 3.5#557
developerjamiu wants to merge 2 commits into
mainfrom
docs/first-app-3-5-rework

developerjamiu commented May 27, 2026

Uh oh!

Swiftaxe left a comment

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Swiftaxe May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	The server is the right place for work you can't or shouldn't do in the app, such as calling an API secured by a secret key, accessing a database, or sending push notifications and emails. Here, it keeps your Gemini API key off the client.
	The server is the right place for work you can't or shouldn't do in the Flutter app, such as calling an API secured by a secret key, accessing a database, or sending push notifications and emails. Here, it keeps your Gemini API key off the client.

	- A typed data model shared between the server and the app.
	- A typed data model shared between the server and the Flutter app.

	On the [previous page](./01-creating-endpoints.md) your endpoint returned a plain string. Here you'll define a `Recipe` model so the server returns structured, typed data instead. You define the model once in YAML, and Serverpod generates the Dart class plus all the serialization that moves it between server and client.
	On the [previous page](./01-creating-endpoints.md) your endpoint returned a plain string. Here you'll define a `Recipe` model so the server returns structured, typed data instead. You define the model once in YAML, and Serverpod generates the Dart class plus all the serialization needed between server and client.

	Right now your recipes disappear when the app reloads. Here you'll store them in the database so they persist, and list previously generated recipes in the app. Serverpod maps your model to a table and gives you a typed API to read and write rows, without writing any SQL.
	Right now your recipes disappear when the Flutter app reloads. Here you'll store them in the database so they persist, and list previously generated recipes in the app. Serverpod maps your model to a table and gives you a typed API to read and write rows, without writing any SQL.

Conversation

developerjamiu commented May 27, 2026

Uh oh!

Swiftaxe left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants