Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/01-get-started/01-creating-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,13 +103,13 @@ $ cd magic_recipe_server
$ serverpod generate
```

`serverpod generate` will create bindings for the endpoint and register them in the server's `generated/protocol.dart` file. It will also generate the required client code so that you can call your new `generateRecipe` method from your app.
`serverpod generate` will create bindings for the endpoint and register them in the server's `generated/protocol.dart` file. It will also generate the required Flutter app code so that you can call your new `generateRecipe` method from your app.

:::note
When writing server-side code, in most cases, you want it to be _stateless_. This means you avoid using global or static variables. Instead, think of each endpoint method as a function that does stuff in a sub-second timeframe and returns data or a status messages to your client. If you want to run more complex computations, you can return a `Stream` to yield progress updates as your task progresses.
When writing server-side code, in most cases, you want it to be _stateless_. This means you avoid using global or static variables. Instead, think of each endpoint method as a function that does stuff in a sub-second timeframe and returns data or a status messages to your Flutter app. If you want to run more complex computations, you can return a `Stream` to yield progress updates as your task progresses.
:::

## Call the endpoint from the client
## Call the endpoint from the Flutter app

Now that you have created the endpoint, you can call it from the Flutter app. Do this in the `magic_recipe_flutter/lib/main.dart` file. Rename the `_callHello` method to `_callGenerateRecipe` and modify it to do the following (feel free to just copy and paste):

Expand Down Expand Up @@ -231,4 +231,4 @@ Try out the app by clicking the button to get a new recipe. The app will call th

## Next steps

For now, you are just returning a `String` to the client. In the next section, you will create a custom data model to return structured data. Serverpod makes it easy by handling all the serialization and deserialization for you.
For now, you are just returning a `String` to the app. In the next section, you will create a custom data model to return structured data. Serverpod makes it easy by handling all the serialization and deserialization for you.
2 changes: 1 addition & 1 deletion docs/01-get-started/03-working-with-the-database.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ $ cd magic_recipe_server
$ serverpod generate
```

## Call the endpoint from the app
## Call the endpoint from the Flutter app

Now that we have updated the endpoint, we can call it from the app. We do this in the `magic_recipe_flutter/lib/main.dart` file. We will call the `getRecipes` method when the app starts and store the result in a list of `Recipe` objects. We will also update the UI to show the list of recipes.

Expand Down
2 changes: 1 addition & 1 deletion docs/01-get-started/04-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ For non-Docker deployments, you'll need to [compile the Dart code](https://dart.

By default Serverpod is active on three ports:

- **8080**: The main port for the server - this is where the generated client will connect to.
- **8080**: The main port for the server - this is where the generated Flutter app will connect to.
- **8081**: The port for connecting with the [Serverpod Insights](../09-tools/01-insights.md) tooling. You may want to restrict which IP addresses can connect to this port.
- **8082**: The built in webserver is running on this port.

Expand Down
10 changes: 5 additions & 5 deletions docs/02-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar_label: 🧭 Overview

# Overview

Serverpod is an open-source backend framework for Flutter applications written in Dart. It aims to minimize boilerplate and integrate many common backend tasks out of the box. With Serverpod, Flutter developers can build secure, scalable server applications using the same language and tools as their client apps, benefiting from seamless code generation and a rich set of built-in capabilities.
Serverpod is an open-source backend framework for Flutter applications written in Dart. It aims to minimize boilerplate and integrate many common backend tasks out of the box. With Serverpod, Flutter developers can build secure, scalable server applications using the same language and tools as their Flutter apps, benefiting from seamless code generation and a rich set of built-in capabilities.

## Key capabilities

Expand All @@ -22,7 +22,7 @@ Serverpod is an open-source backend framework for Flutter applications written i

## Defining Endpoints

In Serverpod, endpoints are the entry points that clients call to execute server-side logic. An endpoint is defined by creating a class that extends the Endpoint class and adding asynchronous methods to it. Each endpoint method must return a `Future<Type>` and take a `Session` object as its first parameter. The `Session` provides context about the call and gives access to server resources like the database or cache.
In Serverpod, endpoints are the entry points that Flutter app call to execute server-side logic. An endpoint is defined by creating a class that extends the Endpoint class and adding asynchronous methods to it. Each endpoint method must return a `Future<Type>` and take a `Session` object as its first parameter. The `Session` provides context about the call and gives access to server resources like the database or cache.

For example, here's a simple endpoint definition with a single method:

Expand All @@ -36,9 +36,9 @@ class GreetingEndpoint extends Endpoint {
}
```

You can place your endpoints anywhere in your server package. After adding or modifying endpoints, you run the Serverpod code generator (`serverpod generate`) to update the client interface. The generator produces a Dart client library that mirrors your server API.
You can place your endpoints anywhere in your server package. After adding or modifying endpoints, you run the Serverpod code generator (`serverpod generate`) to update the Flutter interface. The generator produces a Dart client library that mirrors your server API.

On the Flutter client side, calling the endpoint is as straightforward as calling a local function. For instance, using the generated client, you can invoke the above hello method like this:
On the Flutter side, calling the endpoint is as straightforward as calling a local function. For instance, using the generated client, you can invoke the above hello method like this:

```dart
final result = await client.greeting.hello('World');
Expand All @@ -59,7 +59,7 @@ fields:
foundedDate: DateTime?
```

This defines a `Company` class with two fields. When you run `serverpod generate`, Serverpod creates a Dart class named `Company` (with a `name` and `foundedDate` property) that can be used in your endpoint methods and in the client code.
This defines a `Company` class with two fields. When you run `serverpod generate`, Serverpod creates a Dart class named `Company` (with a `name` and `foundedDate` property) that can be used in your endpoint methods and in the Flutter app code.

By default, model classes are plain data holders that can be sent over the network. Serverpod supports most basic types, including `bool`, `int`, `double`, `String`, `Duration`, `DateTime`, `ByteData`, `UuidValue`, `Uri`, and `BigInt`. You can also use `List`, `Map`, `Set`, and other custom serializable objects. Null safety is supported, and the models can be nested with each other as needed.

Expand Down
4 changes: 2 additions & 2 deletions docs/05-tutorials/02-tutorials/02-real-time-communication.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ We begin by creating a new project with the `serverpod create` command. Since we
serverpod create pixorama --mini
```

Now, let's open the project in VS Code and explore the structure. The server code resides in the `pixorama_server` package. We'll start by creating models - classes that we can serialize and pass between the client and server. Our models will be placed in the `lib/src/models` directory.
Now, let's open the project in VS Code and explore the structure. The server code resides in the `pixorama_server` package. We'll start by creating models - classes that we can serialize and pass between the Flutter app and server. Our models will be placed in the `lib/src/models` directory.

## Creating models

Expand Down Expand Up @@ -72,7 +72,7 @@ serverpod generate

## Building the server

Next, we'll build the server. We need to create a new endpoint. An endpoint is a connection point for the client to interact with the server. In Serverpod, you create endpoints by extending the `Endpoint` class and placing it in the `lib/src/endpoints` directory. The endpoint will manage our pixel data and handle client updates.
Next, we'll build the server. We need to create a new endpoint. An endpoint is a connection point for the Flutter app to interact with the server. In Serverpod, you create endpoints by extending the `Endpoint` class and placing it in the `lib/src/endpoints` directory. The endpoint will manage our pixel data and handle client updates.

We will start by creating a `PixoramaEndpoint` class, which we place in a file called `pixorama_endpoint.dart` in the `lib/src/endpoints` directory.

Expand Down
8 changes: 4 additions & 4 deletions docs/06-concepts/01-working-with-endpoints.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Working with endpoints

Endpoints are the connection points to the server from the client. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the `lib` directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database.
Endpoints are the connection points to the server from the Flutter app. With Serverpod, you add methods to your endpoint, and your client code will be generated to make the method call. For the code to be generated, you need to place the endpoint file anywhere under the `lib` directory of your server. Your endpoint should extend the `Endpoint` class. For methods to be generated, they need to return a typed `Future`, and its first argument should be a `Session` object. The `Session` object holds information about the call being made and provides access to the database.

```dart
import 'package:serverpod/serverpod.dart';
Expand All @@ -14,7 +14,7 @@ class ExampleEndpoint extends Endpoint {

The above code will create an endpoint called `example` (the Endpoint suffix will be removed) with the single `hello` method. To generate the client-side code run `serverpod generate` in the home directory of the server.

On the client side, you can now call the method by calling:
On the Flutter side, you can now call the method by calling:

```dart
var result = await client.example.hello('World');
Expand Down Expand Up @@ -305,9 +305,9 @@ abstract class AdminEndpoint extends Endpoint {

Again, just have your custom endpoint extend `AdminEndpoint` and you can be sure that the user has the appropriate permissions.

## Client-side endpoint inheritance
## Flutter-side endpoint inheritance

When you use endpoint inheritance on the server, Serverpod generates matching client-side classes that mirror your inheritance hierarchy. This allows you to write type-safe client code that works with abstract endpoint types.
When you use endpoint inheritance on the server, Serverpod generates matching Flutter-side classes that mirror your inheritance hierarchy. This allows you to write type-safe client code that works with abstract endpoint types.

### Abstract endpoint client generation

Expand Down
8 changes: 4 additions & 4 deletions docs/06-concepts/04-exceptions.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Error handling and exceptions

Handling errors well is essential when you are building your server. To simplify things, Serverpod allows you to throw an exception on the server, serialize it, and catch it in your client app.
Handling errors well is essential when you are building your server. To simplify things, Serverpod allows you to throw an exception on the server, serialize it, and catch it in your Flutter app.

If you throw a normal exception that isn't caught by your code, it will be treated as an internal server error. The exception will be logged together with its stack trace, and a 500 HTTP status (internal server error) will be sent to the client. On the client side, this will throw a non-specific ServerpodException, which provides no more data than a session id number which can help identifiy the call in your logs.
If you throw a normal exception that isn't caught by your code, it will be treated as an internal server error. The exception will be logged together with its stack trace, and a 500 HTTP status (internal server error) will be sent to the client. On the Flutter side, this will throw a non-specific ServerpodException, which provides no more data than a session id number which can help identifiy the call in your logs.

:::tip

Expand All @@ -12,7 +12,7 @@ Use the Serverpod Insights app to view your logs. It will show any failed or slo

## Serializable exceptions

Serverpod allows adding data to an exception you throw on the server and extracting that data in the client. This is useful for passing error messages back to the client when a call fails. You use the same YAML-files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`.
Serverpod allows adding data to an exception you throw on the server and extracting that data in the Flutter app. This is useful for passing error messages back to the client when a call fails. You use the same YAML-files to define the serializable exceptions as you would with any serializable model (see [serialization](serialization) for details). The only difference is that you use the keyword `exception` instead of `class`.

```yaml
exception: MyException
Expand All @@ -37,7 +37,7 @@ class ExampleEndpoint extends Endpoint {
}
```

In your app, catch the exception as you would catch any exception.
In your Flutter app, catch the exception as you would catch any exception.

```dart
try {
Expand Down
6 changes: 3 additions & 3 deletions docs/06-concepts/06-database/09-pagination.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Cursor-based pagination is an alternative method to the traditional limit-offset

### How it works

In cursor-based pagination, the client provides a cursor as a reference point, and the server returns data relative to that cursor. This cursor is usually an `id`.
In cursor-based pagination, the Flutter app provides a cursor as a reference point, and the server returns data relative to that cursor. This cursor is usually an `id`.

### Implementing cursor-based pagination

Expand All @@ -82,7 +82,7 @@ In cursor-based pagination, the client provides a cursor as a reference point, a
For the subsequent requests, use the cursor (for example, the last `id` from the previous result) to fetch the next set of records:

```dart
int cursor = lastCompanyIdFromPreviousPage; // This is typically sent by the client
int cursor = lastCompanyIdFromPreviousPage; // This is typically sent by the Flutter app

var companies = await Company.db.find(
session,
Expand All @@ -93,7 +93,7 @@ In cursor-based pagination, the client provides a cursor as a reference point, a
```

3. **Returning the cursor**:
When returning data to the client, also return the cursor, so it can be used to compute the starting point for the next page.
When returning data to the Flutter app, also return the cursor, so it can be used to compute the starting point for the next page.

```dart
return {
Expand Down
4 changes: 2 additions & 2 deletions docs/06-concepts/08-caching.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Future<UserData> getUserData(Session session, int userId) async {
await session.caches.local.put(cacheKey, userData!, lifetime: Duration(minutes: 5));
}

// Return the user data to the client
// Return the user data to the Flutter app
return userData;
}
```
Expand Down Expand Up @@ -50,7 +50,7 @@ Future<UserData> getUserData(Session session, int userId) async {
),
);

// Return the user data to the client
// Return the user data to the Flutter app
return userData;
}
```
Expand Down
2 changes: 1 addition & 1 deletion docs/06-concepts/10-modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Examples of modules are the `serverpod_auth_core` and `serverpod_auth_idp` modul

### Server setup

To add a module to your project, you must include the server and client/Flutter packages in your project's `pubspec.yaml` files.
To add a module to your project, you must include the server, client and Flutter packages in your project's `pubspec.yaml` files.

For example, to add the `serverpod_auth_idp` module to your project, you need to add `serverpod_auth_idp_server` to your server's `pubspec.yaml`:

Expand Down
2 changes: 1 addition & 1 deletion docs/06-concepts/11-authentication/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ dependencies:
serverpod_auth_idp_client: 3.x.x
```

## App setup
## Flutter setup

First, add dependencies to your app's `pubspec.yaml` file for the methods of signing in that you want to support.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ For more details on configuration options, such as customizing password requirem
If you are using the `config/passwords.yaml` file or environment variables, you can use the `EmailIdpConfigFromPasswords` constructor to automatically load the secret pepper. It will expect the `emailSecretHashPepper` key or the `SERVERPOD_PASSWORD_emailSecretHashPepper` environment variable to be set with the secret pepper value.
:::

## Client-side configuration
## Flutter-side configuration

If you have configured the `SignInWidget` as described in the [setup section](../../setup#present-the-authentication-ui), the Email identity provider will be automatically detected and displayed in the sign-in widget.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ final emailIdpConfig = EmailIdpConfigFromPasswords(
```

:::tip
This is useful to ensure password policies on the server-side. It is a best practice to pair it with a configuration on the client-side to provide a better UX when creating a new password. The `EmailSignInWidget` and `EmailAuthController` have a `passwordRequirements` parameter that can be used to configure the password requirements.
This is useful to ensure password policies on the server-side. It is a best practice to pair it with a configuration on the Flutter-side to provide a better UX when creating a new password. The `EmailSignInWidget` and `EmailAuthController` have a `passwordRequirements` parameter that can be used to configure the password requirements.
:::

### Custom Verification Code Generation
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ The `google_client_secret.json` contains a private key and should not be version

## Client-side configuration

For our client-side configurations, we have to first create client-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, so any documentation there should also apply to this setup.
For our Flutter-side configurations, we have to first create Flutter-side credentials and include the credentials files in our projects. The Android and iOS integrations use the [google_sign_in](https://pub.dev/packages/google_sign_in) package under the hood, so any documentation there should also apply to this setup.

### iOS

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ Finally, run `serverpod generate` to generate the client code and create a migra

For more details on configuration options, see the [configuration section](./configuration).

## Client-side configuration
## Flutter-side configuration

The `serverpod_auth_idp_flutter` package implements the sign-in logic using [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple). The documentation for this package should in most cases also apply to the Serverpod integration.

Expand Down
Loading