From b2bb5af8df1428fc2f9d37227077a62d748f8d91 Mon Sep 17 00:00:00 2001 From: Abdul Awal Date: Fri, 14 Aug 2026 11:41:35 +0600 Subject: [PATCH 1/2] addressed the doc --- .../01-models/01-working-with-models.md | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md b/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md index b4a8d304..8352c4f2 100644 --- a/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md +++ b/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md @@ -6,7 +6,7 @@ description: Serverpod model files define serializable classes, exceptions, and # Working with models -A data model is a YAML definition that becomes a typed Dart class on both the server and the client, and, with a [table](./database/tables) key, a database table as well. Models are the unit of data your endpoints pass and your database stores. +A data model is a YAML definition that becomes a typed Dart class on both the server and the client, and, with a [table](./database/tables) key, a database table as well. Models are the unit of data your endpoints pass and your database stores. You can also [define models that you only use in Flutter](#using-models-on-the-client-only). The recommended file extension is `.spy.yaml` (.spy stands for "Serverpod YAML"), with `.spy` and `.spy.yml` accepted as well. These files can be placed anywhere in your server's `lib` directory, and the extension enables syntax highlighting through the [Serverpod Extension](https://marketplace.visualstudio.com/items?itemName=serverpod.serverpod) for VS Code. Regular `.yaml` files are also supported, but only within `lib/src/models` (or the legacy `lib/src/protocol` directory). @@ -100,6 +100,30 @@ fields: Models can be saved to and read from the database. See the [Database](./database/tables) section. ::: +### Using models on the client only + +You can define models that you only use in the Flutter app, for example to hold local UI state or form data. Leave `serverOnly` unset so the class is generated for the client. There is no separate `clientOnly` flag. + +Place the `.spy.yaml` file anywhere in the server's `lib` directory, run code generation, and import the class from the client package. + +```yaml +class: CartItem +immutable: true +fields: + productId: String + quantity: int +``` + +```dart +import 'package:my_project_client/my_project_client.dart'; + +var item = CartItem(productId: 'sku-1', quantity: 2); +``` + +The class is also generated on the server. That is harmless: omit the `table` key so no database table is created, and you do not need to use the class in any endpoint. Set `immutable: true` if you want value equality for Flutter state management. See [Immutable classes](#immutable-classes). + +If you want the YAML and generated classes in a package that both the server and the app depend on, use a [shared package](./models/shared-packages). + ### JSON key aliasing By default, fields are serialized to JSON using their Dart field name as the key. The `jsonKey` property allows you to specify a different key name for JSON serialization and deserialization, which is useful when integrating with external APIs that use different naming conventions. From 45f088e025d54f3453d5964369e9ae02e3112166 Mon Sep 17 00:00:00 2001 From: Abdul Awal Date: Fri, 14 Aug 2026 19:23:26 +0600 Subject: [PATCH 2/2] docs: Address review feedback on client-only models --- .../01-models/01-working-with-models.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md b/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md index 8352c4f2..78d8ff7d 100644 --- a/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md +++ b/docs/06-concepts/03-data-and-the-database/01-models/01-working-with-models.md @@ -104,23 +104,22 @@ Models can be saved to and read from the database. See the [Database](./database You can define models that you only use in the Flutter app, for example to hold local UI state or form data. Leave `serverOnly` unset so the class is generated for the client. There is no separate `clientOnly` flag. -Place the `.spy.yaml` file anywhere in the server's `lib` directory, run code generation, and import the class from the client package. +Place the `.spy.yaml` file anywhere in the server's `lib` directory. With `serverpod start` running, saving the file regenerates the code; otherwise run `serverpod generate`. Then import the class from the client package. ```yaml class: CartItem -immutable: true fields: productId: String quantity: int ``` ```dart -import 'package:my_project_client/my_project_client.dart'; +import 'package:your_client/your_client.dart'; var item = CartItem(productId: 'sku-1', quantity: 2); ``` -The class is also generated on the server. That is harmless: omit the `table` key so no database table is created, and you do not need to use the class in any endpoint. Set `immutable: true` if you want value equality for Flutter state management. See [Immutable classes](#immutable-classes). +The class is also generated on the server, which is harmless: without a `table` key no database table is created, and nothing requires you to use the class in an endpoint. Set `immutable: true` if you want value equality for Flutter state management. See [Immutable classes](#immutable-classes). If you want the YAML and generated classes in a package that both the server and the app depend on, use a [shared package](./models/shared-packages).