Building fullstack applications in Flutter has become more streamlined with Serverpod. This guide will walk you through setting up both the full version of Serverpod, which integrates with a PostgreSQL database, and Serverpod Mini, a lightweight version without database dependencies.
🧱 What Is Serverpod?
Serverpod is a Dart-based backend framework tailored for Flutter developers. It offers:
- Shared Models: Seamlessly share data models between client and server.
- Auto-Generated APIs: Simplifies endpoint creation with automatic API generation.
- Built-in Features: Includes authentication, file storage, and logging.
- Database Support: Native integration with PostgreSQL.
- Real-Time Communication: Supports WebSockets for live data updates.
🆚 Serverpod vs. Serverpod Mini
Before diving in, it’s essential to choose the right version for your project:
- Serverpod: Full-featured with PostgreSQL integration. Ideal for production applications requiring database support.
- Serverpod Mini: Lightweight, without database dependencies. Perfect for small projects or prototyping.
Note: Starting with Mini allows for an easy upgrade to the full version later. Learn more about the differences.
🛠 Setting Up Serverpod
Prerequisites
Ensure you have the following installed:
- Flutter
- Serverpod CLI
- Docker Desktop (for full Serverpod)
⚙️ Step 1: Install Serverpod CLI
Install the Serverpod Command Line Interface (CLI) globally:
dart pub global activate serverpod_cli
Add the Serverpod binary path to your system’s PATH:
export PATH="$PATH":"$HOME/.pub-cache/bin"
Verify the installation:
serverpod --version
📦 Step 2: Create a New Serverpod Project
Navigate to your desired directory and run:
serverpod create my_project
This command generates a my_project directory containing:
my_project_server: Server-side code.my_project_client: Auto-generated client code.my_project_flutter: Pre-configured Flutter app.
Note: On Windows, ensure Developer Mode is enabled, as Serverpod executes flutter create during project setup. More details.
🔁 Step 3: Start the Server
Navigate to the server directory:
cd my_project/my_project_server
Start the necessary Docker containers:
docker compose up --build --detach
Then, run the server with:
dart bin/main.dart --apply-migrations
If successful, you’ll see output indicating the server is running on ports 8080 (default), 8081 (Insights), and 8082 (Webserver).
Note: Ensure Docker Desktop is running before executing these commands. Starting the server.
📱 Step 4: Run the Flutter Client
Open a new terminal, navigate to the Flutter app directory:
cd my_project/my_project_flutter
Run the app:
flutter run -d chrome
This launches the default demo app connected to your local server.
Note: For iOS simulators, adjust the client initialization in main.dart to use your machine’s IP address instead of localhost. Running the demo app.
🛠 Setting Up Serverpod Mini
For projects without the need for a database, Serverpod Mini offers a streamlined setup.
⚙️ Step 1: Create a Mini Project
Navigate to your desired directory and run:
serverpod create my_mini_project --mini
This creates a my_mini_project directory with:
my_mini_project_server: Server-side code.my_mini_project_client: Auto-generated client code.my_mini_project_flutter: Flutter app.
Note: Serverpod Mini doesn’t require Docker or PostgreSQL. Get started with Mini.
🔁 Step 2: Start the Mini Server
Navigate to the server directory:
cd my_mini_project/my_mini_project_server
Run the server:
dart bin/main.dart
📱 Step 3: Run the Mini Flutter Client
In a new terminal, navigate to the Flutter app directory:
cd my_mini_project/my_mini_project_flutter
Run the app:
flutter run -d chrome
This launches the sample Flutter app connected to the Mini server.
Tip: If using VS Code, consider installing the Serverpod extension for enhanced development support.
🔄 Upgrading from Mini to Full Serverpod
If you started with Serverpod Mini and wish to upgrade to the full version:
- Navigate to the server directory:
cd my_mini_project/my_mini_project_server - Run the upgrade command:
serverpod create .
This adds the necessary configuration files for the full version. Upgrade from Mini to full.
✅ Final Thoughts
Serverpod empowers Flutter developers to build fullstack applications efficiently, whether using the full version with database support or the lightweight Mini version. By following this guide, you’ve set up a foundational project ready for further development.
Note: For advanced features like authentication, file uploads, and real-time communication, refer to the Serverpod documentation.
