If you use a tool like Shelf to build your API, you assemble everything yourself. You choose your packages, write your own middleware, manage your own database connection, and wire every piece together manually. That's the Shelf way, and it teaches you exactly how server-side Dart works under the hood.

Serverpod is a different philosophy entirely.

Where Shelf gives you primitives, Serverpod gives you a complete system. You define your models in YAML, run a generator, and get fully typed database classes, serialization, and client-side code produced automatically.

For Flutter engineers, this feels immediately familiar. It's the same kind of productivity you get from the Flutter toolchain itself, applied to the backend.

In this article, we're going to build a User and Profile Management REST API from scratch using Serverpod. You'll learn how Serverpod's code generation, built-in ORM, and endpoint system work, and you'll have a fully deployed backend by the end.

Table of Contents

• Prerequisites

• How Serverpod Differs from Shelf

• Installing Serverpod

• Creating the Project

• Understanding the Project Structure

• Serverpod Core Concepts

  • Endpoints and the Session Object

  • Model Files and Code Generation

  • The Built-in ORM

  • Migrations

• Starting the Development Server

• Defining the Models

  • The User Model

  • The Profile Model

  • Running Code Generation

  • Creating and Applying Migrations

• Building the API

  • The Auth Endpoint

  • The User Endpoint

  • The Profile Endpoint

• Authentication

  • Password Hashing and JWT

  • Protecting Endpoints

• Error Handling in Serverpod

• Testing the API

• Deployment

  • Deploying with Docker and Fly.io

  • Deploying with Serverpod Cloud

• Conclusion

Prerequisites

Before starting, you should have:

• Familiarity with Dart and Flutter development

• Understanding of REST API concepts, endpoints, HTTP methods, status codes

• Docker Desktop installed and running

• Flutter SDK installed (Serverpod requires it even for server-only projects)

• A Fly.io account or a Serverpod Cloud account for deployment

How Serverpod Differs from Shelf

Before writing a single line of code, it's worth understanding the fundamental difference in philosophy between Shelf and Serverpod. This will make every design decision in the framework feel deliberate rather than arbitrary.

With Shelf, you write everything. Request parsing, response formatting, database queries, migrations, auth, and logging. Every piece is explicit code that you understand because you wrote it.

With Serverpod, you define things and the framework writes code for you. You define a model in YAML, run serverpod generate, and get a full Dart class with database bindings, serialization, and client-side access automatically. You define an endpoint method, and the framework handles routing, parameter extraction, and response formatting.

This is the same trade-off Flutter makes compared to building with raw platform APIs. Flutter writes the layout engine, the rendering pipeline, and the gesture system for you. You focus on your product logic. Serverpod makes the same bet on the backend.

The cost of that productivity is flexibility. Serverpod has strong opinions about how things should be structured. If your use case fits those opinions, development is extremely fast. If it doesn't, you're working against the framework.

For the User and Profile Management API we're building here, Serverpod is a very good fit.

Installing Serverpod

Serverpod requires Flutter to be installed, even for server-only work. This is because its toolchain builds client packages alongside the server package during project creation.

Install the Serverpod CLI globally:

dart pub global activate serverpod_cli

Verify the installation:

serverpod
# Should print the Serverpod CLI help

Make sure Docker Desktop is running before proceeding. Serverpod uses Docker to manage PostgreSQL and Redis for local development.

Creating the Project

serverpod create user_profile_api
cd user_profile_api

This single command creates three Dart packages:

user_profile_api/
  user_profile_api_server/    ← your server code
  user_profile_api_client/    ← auto-generated client (do not edit)
  user_profile_api_flutter/   ← Flutter app pre-configured to connect

For this article, everything we write lives in user_profile_api_server. The client and Flutter packages are generated automatically and used when you want a Flutter frontend talking to your Serverpod backend.

Understanding the Project Structure

Inside user_profile_api_server:

user_profile_api_server/
  bin/
    main.dart                  ← entry point
  lib/
    src/
      endpoints/               ← your endpoint classes live here
      generated/               ← auto-generated code (never edit manually)
    user_profile_api_server.dart
  config/
    development.yaml           ← database and server config
    staging.yaml
    production.yaml
    passwords.yaml             ← database passwords
  migrations/                  ← auto-generated migration files
  web/                         ← optional web server files
  Dockerfile
  docker-compose.yaml
  pubspec.yaml

The most important thing to understand about this structure is the generated/ folder. Everything in there is produced by serverpod generate and should never be edited manually. When you change a model or endpoint, you run the generator and it rewrites that folder entirely.

The config/ folder holds environment-specific configuration. The development.yaml file is preconfigured to work with the Docker containers Serverpod spins up locally.

Serverpod Core Concepts

Endpoints and the Session Object

In Serverpod, an endpoint is a class that extends Endpoint. Every public method on that class becomes an API call that clients can make. There's no routing configuration, no handler registration, and no middleware mounting. The framework discovers and registers your endpoints automatically during code generation.

import 'package:serverpod/serverpod.dart';

class UserEndpoint extends Endpoint {
  Future<String> greet(Session session, String name) async {
    return 'Hello, $name!';
  }
}

The Session object is the most important parameter in Serverpod. It's passed to every endpoint method and gives you access to:

• session.db for database operations

• session.auth for authentication information

• session.log for structured logging

• session.caches for caching

• session.messages for real-time messaging

Think of Session as Serverpod's equivalent of Flutter's BuildContext. It's the gateway to everything the framework provides, and it's always the first parameter.

Model Files and Code Generation

This is where Serverpod's approach diverges most sharply from Shelf. Instead of writing Dart model classes manually, you define your data structures in .spy.yaml files and let Serverpod generate the Dart classes.

A model file for a Company looks like this:

class: Company
table: company
fields:
  name: String
  foundedDate: DateTime?

Running serverpod generate produces a full Dart class with:

• Immutable fields with correct types

• toJson and fromJson for serialization

• Database bindings through the db static accessor

• Constructor and copyWith method

• The same class is generated in the client package so the Flutter app can use it directly

This is the core productivity gain. You define the shape once in YAML and get a consistent, typed model that works across the server, the database, and the client without duplication.

The Built-in ORM

Serverpod's ORM uses the generated model classes directly. All database operations go through the static db accessor on your model:

// Insert a row
var company = Company(name: 'Serverpod Corp', foundedDate: DateTime.now());
company = await Company.db.insertRow(session, company);

// Find by ID
var found = await Company.db.findById(session, company.id!);

// Find with condition
var result = await Company.db.findFirstRow(
  session,
  where: (t) => t.name.equals('Serverpod Corp'),
);

// Find all with ordering
var all = await Company.db.find(
  session,
  orderBy: (t) => t.name,
);

// Update
company = company.copyWith(name: 'New Name');
await Company.db.updateRow(session, company);

// Delete
await Company.db.deleteRow(session, company);

The where parameter uses a type-safe expression builder. The t parameter gives you typed access to the table's columns, so you get autocompletion and compile-time checks on your query conditions. No raw SQL, no string-based column names, no runtime surprises.

Migrations

When you change a model, Serverpod generates a migration automatically:

serverpod create-migration

This creates a SQL migration file in the migrations/ directory. Apply it when starting the server:

dart bin/main.dart --apply-migrations

Serverpod tracks which migrations have been applied and runs only the new ones. The migration system is fully integrated with the model system, so there's no drift between your Dart classes and your database schema.

Starting the Development Server

Before writing any code, get the development environment running.

Start the Docker containers (PostgreSQL and Redis):

cd user_profile_api_server
docker compose up --build --detach

Start the server with migrations applied:

dart bin/main.dart --apply-migrations

You should see:

SERVERPOD version: 2.x.x, mode: development
Insights listening on port 8081
Server default listening on port 8080
Webserver listening on port 8082

Three ports: Port 8080 is the main API server. Port 8081 is the Serverpod Insights tool for monitoring. Port 8082 is an optional web server. For this article, we'll work exclusively with port 8080.

Defining the Models

The User Model

Create lib/src/models/user.spy.yaml in the server package:

class: AppUser
table: app_users
fields:
  email: String
  passwordHash: String
  firstName: String
  lastName: String
  isActive: bool, default=true
indexes:
  app_users_email_idx:
    fields: email
    unique: true

A few things to note here. The class is named AppUser rather than User to avoid conflicts with Serverpod's internal User class from the auth module. The table key defines the PostgreSQL table name. The indexes block creates a unique index on the email column, enforcing uniqueness at the database level.

Serverpod automatically adds an id field of type int? to every model with a table key. You don't declare it yourself.

The Profile Model

Create lib/src/models/profile.spy.yaml:

class: Profile
table: profiles
fields:
  userId: int
  bio: String?
  avatarUrl: String?
  phone: String?
  location: String?
  website: String?
indexes:
  profiles_user_id_idx:
    fields: userId
    unique: true

userId is an int referencing the id of an AppUser. Serverpod's model system doesn't yet have a foreign key declaration syntax in the YAML, so referential integrity is handled at the application layer in the endpoint logic.

Running Code Generation

With both model files in place, run the generator:

serverpod generate

This produces Dart classes in lib/src/generated/. For AppUser, you get:

// This is auto-generated, never edit directly
class AppUser extends SerializableEntity {
  AppUser({
    this.id,
    required this.email,
    required this.passwordHash,
    required this.firstName,
    required this.lastName,
    this.isActive = true,
  });

  int? id;
  String email;
  String passwordHash;
  String firstName;
  String lastName;
  bool isActive;

  // db accessor for ORM operations
  static final db = AppUserRepository._();

  // Serialization methods
  factory AppUser.fromJson(Map<String, dynamic> jsonSerialization, ...) { ... }
  Map<String, dynamic> toJson() { ... }
}

The generated code is what your endpoints interact with. You never write this by hand.

Creating and Applying Migrations

With the models generated, create the migration:

serverpod create-migration

This creates timestamped SQL files in migrations/. Apply them:

dart bin/main.dart --apply-migrations

Your app_users and profiles tables now exist in PostgreSQL with the correct columns and indexes.

Building the API

The Auth Endpoint

Create lib/src/endpoints/auth_endpoint.dart:

import 'package:serverpod/serverpod.dart';
import 'package:bcrypt/bcrypt.dart';
import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
import '../generated/protocol.dart';

class AuthEndpoint extends Endpoint {
  Future<Map<String, dynamic>> register(
    Session session,
    String email,
    String password,
    String firstName,
    String lastName,
  ) async {
    if (email.isEmpty || password.isEmpty || firstName.isEmpty || lastName.isEmpty) {
      throw Exception('All fields are required');
    }

    if (password.length < 8) {
      throw Exception('Password must be at least 8 characters');
    }

    // Check for existing user
    final existing = await AppUser.db.findFirstRow(
      session,
      where: (t) => t.email.equals(email),
    );

    if (existing != null) {
      throw Exception('An account with this email already exists');
    }

    final passwordHash = BCrypt.hashpw(password, BCrypt.gensalt());

    var user = AppUser(
      email: email,
      passwordHash: passwordHash,
      firstName: firstName,
      lastName: lastName,
    );

    user = await AppUser.db.insertRow(session, user);

    final token = _generateToken(user);

    return {
      'user': _sanitizeUser(user),
      'token': token,
    };
  }

  Future<Map<String, dynamic>> login(
    Session session,
    String email,
    String password,
  ) async {
    if (email.isEmpty || password.isEmpty) {
      throw Exception('Email and password are required');
    }

    final user = await AppUser.db.findFirstRow(
      session,
      where: (t) => t.email.equals(email),
    );

    if (user == null || !BCrypt.checkpw(password, user.passwordHash)) {
      throw Exception('Invalid email or password');
    }

    if (!user.isActive) {
      throw Exception('This account has been deactivated');
    }

    final token = _generateToken(user);

    return {
      'user': _sanitizeUser(user),
      'token': token,
    };
  }

  String _generateToken(AppUser user) {
    final jwt = JWT({'sub': user.id, 'email': user.email});
    return jwt.sign(SecretKey(_jwtSecret), expiresIn: const Duration(hours: 24));
  }

  // Never return the password hash to the client
  Map<String, dynamic> _sanitizeUser(AppUser user) => {
        'id': user.id,
        'email': user.email,
        'firstName': user.firstName,
        'lastName': user.lastName,
        'isActive': user.isActive,
      };

  // Read from Serverpod's config system
  String get _jwtSecret =>
      Session.serverpod.getPassword('jwtSecret') ?? 'fallback_dev_secret';
}

Serverpod endpoints return typed values. When you return a Map<String, dynamic>, Serverpod serializes it automatically. When you throw an Exception, Serverpod catches it and returns a structured error response to the client. No manual response formatting, no status code management for common cases.

The User Endpoint

Create lib/src/endpoints/user_endpoint.dart:

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

class UserEndpoint extends Endpoint {
  @override
  bool get requireLogin => true;

  Future<List<Map<String, dynamic>>> getAll(Session session) async {
    final users = await AppUser.db.find(
      session,
      where: (t) => t.isActive.equals(true),
      orderBy: (t) => t.id,
    );

    return users.map(_sanitizeUser).toList();
  }

  Future<Map<String, dynamic>> getById(Session session, int userId) async {
    final user = await AppUser.db.findById(session, userId);

    if (user == null || !user.isActive) {
      throw Exception('User not found');
    }

    return _sanitizeUser(user);
  }

  Future<Map<String, dynamic>> update(
    Session session,
    int userId,
    String? firstName,
    String? lastName,
  ) async {
    final user = await AppUser.db.findById(session, userId);

    if (user == null || !user.isActive) {
      throw Exception('User not found');
    }

    final updated = user.copyWith(
      firstName: firstName ?? user.firstName,
      lastName: lastName ?? user.lastName,
    );

    await AppUser.db.updateRow(session, updated);
    return _sanitizeUser(updated);
  }

  Future<void> delete(Session session, int userId) async {
    final user = await AppUser.db.findById(session, userId);

    if (user == null || !user.isActive) {
      throw Exception('User not found');
    }

    // Soft delete
    final deactivated = user.copyWith(isActive: false);
    await AppUser.db.updateRow(session, deactivated);
  }

  Map<String, dynamic> _sanitizeUser(AppUser user) => {
        'id': user.id,
        'email': user.email,
        'firstName': user.firstName,
        'lastName': user.lastName,
        'isActive': user.isActive,
      };
}

Notice @override bool get requireLogin => true. This is Serverpod's built-in mechanism for protecting endpoints. When this getter returns true, Serverpod validates the authentication token on every request to this endpoint before the method is called. Unauthenticated requests are rejected automatically by the framework.

The Profile Endpoint

Create lib/src/endpoints/profile_endpoint.dart:

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

class ProfileEndpoint extends Endpoint {
  @override
  bool get requireLogin => true;

  Future<Map<String, dynamic>> getByUserId(
    Session session,
    int userId,
  ) async {
    final user = await AppUser.db.findById(session, userId);
    if (user == null || !user.isActive) {
      throw Exception('User not found');
    }

    final profile = await Profile.db.findFirstRow(
      session,
      where: (t) => t.userId.equals(userId),
    );

    if (profile == null) {
      throw Exception('Profile not found');
    }

    return _profileToMap(profile);
  }

  Future<Map<String, dynamic>> create(
    Session session,
    int userId,
    String? bio,
    String? avatarUrl,
    String? phone,
    String? location,
    String? website,
  ) async {
    final user = await AppUser.db.findById(session, userId);
    if (user == null || !user.isActive) {
      throw Exception('User not found');
    }

    final existing = await Profile.db.findFirstRow(
      session,
      where: (t) => t.userId.equals(userId),
    );

    if (existing != null) {
      throw Exception('Profile already exists for this user');
    }

    var profile = Profile(
      userId: userId,
      bio: bio,
      avatarUrl: avatarUrl,
      phone: phone,
      location: location,
      website: website,
    );

    profile = await Profile.db.insertRow(session, profile);
    return _profileToMap(profile);
  }

  Future<Map<String, dynamic>> update(
    Session session,
    int userId,
    String? bio,
    String? avatarUrl,
    String? phone,
    String? location,
    String? website,
  ) async {
    final profile = await Profile.db.findFirstRow(
      session,
      where: (t) => t.userId.equals(userId),
    );

    if (profile == null) {
      throw Exception('Profile not found');
    }

    final updated = profile.copyWith(
      bio: bio ?? profile.bio,
      avatarUrl: avatarUrl ?? profile.avatarUrl,
      phone: phone ?? profile.phone,
      location: location ?? profile.location,
      website: website ?? profile.website,
    );

    await Profile.db.updateRow(session, updated);
    return _profileToMap(updated);
  }

  Map<String, dynamic> _profileToMap(Profile profile) => {
        'id': profile.id,
        'userId': profile.userId,
        'bio': profile.bio,
        'avatarUrl': profile.avatarUrl,
        'phone': profile.phone,
        'location': profile.location,
        'website': profile.website,
      };
}

After adding these endpoints, run the generator again so Serverpod registers them:

serverpod generate

Authentication

Password Hashing and JWT

Add the required packages to pubspec.yaml in the server package:

dependencies:
  serverpod: ^2.5.0
  bcrypt: ^1.1.3
  dart_jsonwebtoken: ^2.12.0

Then run dart pub get.

The _generateToken and _sanitizeUser helpers in the auth endpoint handle password hashing and JWT generation. The JWT secret is read from Serverpod's built-in password management system via Session.serverpod.getPassword('jwtSecret').

Add the secret to config/passwords.yaml:

development:
  database: 'dart_password'
  jwtSecret: 'your_development_jwt_secret_here'

This file is already in .gitignore by default in a Serverpod project. Production secrets are injected via environment variables or Serverpod Cloud's secret management.

Protecting Endpoints

Serverpod has two levels of endpoint protection:

requireLogin — rejects unauthenticated requests automatically:

@override
bool get requireLogin => true;

requiredScopes — requires specific permission scopes:

@override
Set<Scope> get requiredScopes => {Scope.admin};

For the User and Profile endpoints in this article, requireLogin is sufficient. The token from the login response is passed in the Authorization header on every subsequent request, and Serverpod validates it before the endpoint method is called.

Verifying the token inside an endpoint to get the current user's ID:

Future<void> someProtectedMethod(Session session) async {
  final authInfo = await session.authenticated;

  if (authInfo == null) {
    throw Exception('Not authenticated');
  }

  final userId = authInfo.userId;
  // proceed with userId
}

Error Handling in Serverpod

Serverpod handles exceptions thrown from endpoint methods and converts them into structured error responses automatically. When you throw:

throw Exception('User not found');

The client receives a structured error response. For more granular control, Serverpod provides typed exceptions:

throw ServerpodClientException('User not found', statusCode: 404);

For server-side logging without exposing details to the client:

session.log('Unexpected error during user creation', level: LogLevel.error);
throw Exception('An internal error occurred');

Serverpod's logging system stores logs in the database and makes them queryable through the Insights dashboard on port 8081. Every request is automatically logged with timing information, endpoint name, and outcome, no additional middleware required.

Testing the API

Serverpod exposes its endpoints over HTTP. You can test them directly with curl, though the request format follows Serverpod's RPC convention rather than a traditional REST structure.

The generated URL pattern for an endpoint method is:

POST /[endpoint]/[method]

With a JSON body containing the method parameters.

Register a user:

curl http://localhost:8080/auth/register \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "email": "seyi@example.com",
    "password": "securepassword",
    "firstName": "Seyi",
    "lastName": "Dev"
  }'

Login:

curl http://localhost:8080/auth/login \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "seyi@example.com", "password": "securepassword"}'

Get all users (authenticated):

curl http://localhost:8080/user/getAll \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..."

Get user by ID:

curl http://localhost:8080/user/getById \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"userId": 1}'

Create a profile:

curl http://localhost:8080/profile/create \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "bio": "Flutter engineer turned backend developer",
    "location": "Lagos, Nigeria",
    "website": "https://example.com"
  }'

Update a user:

curl http://localhost:8080/user/update \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"userId": 1, "firstName": "Oluwaseyi"}'

Delete a user:

curl http://localhost:8080/user/delete \
  -X POST \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"userId": 1}'

Deployment

Deploying with Docker and Fly.io

Serverpod generates a Dockerfile as part of the project creation. It's located in user_profile_api_server/Dockerfile and is ready to use.

The included docker-compose.yaml in the server package manages PostgreSQL and Redis for local development. For production deployment on Fly.io, the process follows the same Docker-based pattern covered in the deployment section below.

Step 1 — Authenticate with Fly:

fly auth login

Step 2 — Launch the app from the server directory:

cd user_profile_api_server
fly launch

Step 3 — Set production secrets:

fly secrets set JWT_SECRET="your_production_jwt_secret"

Step 4 — Update the production config:

Edit config/production.yaml with your Fly-provisioned database connection details. Fly injects the DATABASE_URL environment variable which you map to the Serverpod config format.

Step 5 — Deploy:

fly deploy

Step 6 — Apply migrations on first deploy:

fly ssh console
dart bin/main.dart --apply-migrations --mode production

Deploying with Serverpod Cloud

Serverpod Cloud is the native deployment platform built specifically for Serverpod applications. It handles database provisioning, scaling, monitoring, and deployments with minimal configuration.

Install the Serverpod Cloud CLI:

dart pub global activate serverpod_cloud_cli

Authenticate:

scloud login

Create a project in the Serverpod Cloud dashboard at cloud.serverpod.dev, then link your local project:

scloud link --project-id your-project-id

Deploy:

scloud deploy

Serverpod Cloud provisions a managed PostgreSQL database, applies your migrations, and deploys your server automatically. It also provides the Insights dashboard for monitoring requests, logs, and performance in production.

For teams already committed to the Serverpod ecosystem, Serverpod Cloud is the fastest path to a production deployment.

Conclusion

Serverpod takes a fundamentally different approach from Shelf. Where Shelf gives you control, Serverpod gives you speed. You define your models in YAML, run a generator, and get database classes, serialization, and client code produced automatically. You write an endpoint method and the framework handles routing, parameter extraction, authentication, and error formatting.

The ORM is the strongest part of the experience. Type-safe query expressions, automatic migration generation, and no SQL drift between your code and your schema make database work noticeably faster and safer than raw SQL.

The cost is rigidity. Serverpod's URL structure, serialization format, and architectural conventions aren't optional. If your API needs to conform to a specific REST structure that differs from Serverpod's RPC style, you'll be working against the framework.

For greenfield Flutter backends where the Dart client will consume the API, Serverpod is hard to beat. The code sharing between server and client, the automatic client generation, and the tight toolchain integration make it the most productive Dart backend option available.

For APIs that need to serve multiple clients, conform to external REST conventions, or integrate with existing infrastructure that doesn't expect Serverpod's format, a lower-level tool like Shelf gives you more control. If you want to see how the same User and Profile Management API is built with Shelf and compare the two approaches directly, you can find that article here.

Knowing which tool fits which job is what separates a developer who knows a framework from one who understands backend development.

Happy coding!

This approach contrasts with client-side rendering (CSR), where content is delivered as a basic HTML shell, and JavaScript fetches and displays data in the browser.

SSR offers significant SEO advantages, making it a perfect fit for Next.js, a popular React framework. Let's discuss how using SSR with Next.js can elevate your website's search engine visibility.

Table of Contents

1. What is Server-Side Rendering?
2. How to Get Started with Next.js and SSR
3. How Next.js Enables Server-side Rendering
4. Data Fetching with getStaticProps and getServerSideProps
5. Benefits of SSR for SEO with Next.js and How to Optimize
6. Conclusion

What is Server-Side Rendering?

Server-side rendering (SSR) is a technique in web development where the web server generates the complete HTML content of a web page before sending it to the user's browser.

This is unlike client-side rendering (CSR), where the browser downloads a basic HTML structure and then uses JavaScript to fetch and display the content.

How to Get Started with Next.js and SSR

Getting started with Next.js and server-side rendering (SSR) involves a few steps. Here's a step-by-step guide to help you set up a Next.js project and implement SSR.

Step 1: Install Next.js

First, you need to install Next.js. You can do this using create-next-app, which sets up a new Next.js project with a default configuration. Run the following command in your terminal:

npx create-next-app my-next-app
cd my-next-app
npm run dev

This command creates a new Next.js application in a folder called my-next-app and starts the development server.

Step 2: Understand the Project Structure

Next.js organizes the project with some default folders and files:

• pages/: This folder contains all the pages of your application. Each file represents a route in your app.
• public/: Static assets like images can be placed here.
• styles/: Contains CSS files for styling your application.

Step 3: Create a Simple Page with SSR

Now, let's create a simple page that uses SSR.

Create a new file pages/index.js:

// pages/index.js
import React from 'react';

const Home = ({ data }) => {
  return (
    <div>
      <h1>Welcome to Next.js with SSR</h1>
      <p>Data fetched from the server: {data.message}</p>
    </div>
  );
};

export async function getServerSideProps() {
  // Fetch data from an API or other sources
  const res = await fetch('https://api.example.com/data');
  const data = await res.json();

  // Return the data as props to the Home component
  return {
    props: {
      data,
    },
  };
}

export default Home;

Let's discuss this code in some detail. For the home component:

• The Home component is a functional component that accepts props.
• The data prop contains the data fetched from the server.
• Inside the component, we render a welcome message and the fetched data.

The getServerSideProps function:

• This function is exported from the pages/index.js file.
• It executes on the server for each request to this page.
• Inside this function, you can perform asynchronous operations such as fetching data from an external API.
• The fetched data is returned as an object with a props key. This object will be passed to the Home component as props.

You can add error handling to the getServerSideProps function to manage any issues that might arise during data fetching. Here's an example:

export async function getServerSideProps() {
  try {
    const res = await fetch('https://api.example.com/data');
    if (!res.ok) {
      throw new Error('Failed to fetch data');
    }
    const data = await res.json();
    return {
      props: {
        data,
      },
    };
  } catch (error) {
    console.error(error);
    return {
      props: {
        data: { message: 'Error fetching data' },
      },
    };
  }
}

Step 4: Run the Application

Start your development server if it's not already running:

npm run dev

Open your browser and go to http://localhost:3000. You should see the message fetched from the API displayed on the page.

How Next.js Enables Server-Side Rendering

Next.js provides a seamless way to enable SSR and Static Site Generation (SSG). It pre-renders every page by default. Depending on the use case, you can choose between SSR and SSG:

• Server-Side Rendering (SSR): Pages are rendered on each request.
• Static Site Generation (SSG): Pages are generated at build time.

Next.js determines which rendering method to use based on the functions you implement in your page components (getStaticProps and getServerSideProps).

Next.js Page Components

Next.js uses the pages/ directory to define routes. Each file in this directory corresponds to a route in your application.

• pages/index.js → /
• pages/about.js → /about
• pages/posts/[id].js → /posts/:id

Here's a basic example of a page component:

// pages/index.js
import React from 'react';

const Home = () => {
  return (
    <div>
      <h1>Welcome to Next.js</h1>
      <p>This is the home page.</p>
    </div>
  );
};

export default Home;

Data Fetching with getStaticProps and getServerSideProps

getStaticProps is used for static generation. It runs at build time and allows you to fetch data and pass it to your page as props. Use this for data that doesn't change often.

Example:

// pages/index.js
import React from 'react';

const Home = ({ posts }) => {
  return (
    <div>
      <h1>Blog Posts</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
};

// This function runs at build time
export async function getStaticProps() {
  // Fetch data from an API
  const res = await fetch('https://jsonplaceholder.typicode.com/posts');
  const posts = await res.json();

  return {
    props: {
      posts,
    },
  };
}

export default Home;

getServerSideProps is used for server-side rendering. It runs on every request and allows you to fetch data at request time.

Example:

// pages/index.js
import React from 'react';

const Home = ({ data }) => {
  return (
    <div>
      <h1>Server-Side Rendering with Next.js</h1>
      <p>Data fetched from the server: {data.message}</p>
    </div>
  );
};

// This function runs on every request
export async function getServerSideProps() {
  // Fetch data from an external API
  const res = await fetch('https://api.example.com/data');
  const data = await res.json();

  return {
    props: {
      data,
    },
  };
}

export default Home;

Benefits of SSR for SEO with Next.js and How to Optimize

In this section, we will look at the main benefits of using SSR for SEO and give easy-to-follow tips on how to make the most of these benefits with your Next.js application.

1. Improved Indexing by Search Engines

Client-side rendering (CSR) can cause issues with search engines struggling to index content properly since it is rendered in the user's browser using JavaScript.

SSR, however, renders content on the server before sending it to the user's browser, ensuring the HTML is complete and can be easily crawled and indexed by search engines.

Use SSR for important pages: Ensure that key pages, such as landing pages, blog posts, and product pages, are rendered on the server to facilitate better indexing.

Example – Using SSR for a blog post page:

// pages/blog/[id].js
import React from 'react';
import { useRouter } from 'next/router';
import Head from 'next/head';

const BlogPost = ({ post }) => {
  const router = useRouter();
  if (router.isFallback) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <Head>
        <title>{post.title}</title>
        <meta name="description" content={post.excerpt} />
      </Head>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </div>
  );
};

export async function getServerSideProps({ params }) {
  const res = await fetch(`https://api.example.com/posts/${params.id}`);
  const post = await res.json();

  return {
    props: {
      post,
    },
  };
}

export default BlogPost

• BlogPost Component: This component displays a blog post. It uses next/head to manage meta tags, which are important for SEO.
• getServerSideProps Function: This function fetches data for the blog post from an API. It runs on the server for every request to this page, ensuring the content is ready for search engines to index when they crawl the page.

2. Faster Load Times

Search engines like Google use page load speed as a ranking factor. SSR can improve initial load time because the server sends a fully rendered page to the browser, enhancing perceived performance and user experience.

Optimize server response time: Ensure your server is optimized for quick responses. Use caching strategies to reduce server load.

Example – cache-control header for SSR:

export async function getServerSideProps({ res }) {
  res.setHeader('Cache-Control', 'public, s-maxage=10, stale-while-revalidate=59');

  const resData = await fetch('https://api.example.com/data');
  const data = await resData.json();

  return {
    props: {
      data,
    },
  };
}

• getServerSideProps Function: This function sets cache-control headers to cache the response for 10 seconds and serve stale content while revalidating for 59 seconds. This improves server response time and page load speed, contributing to better SEO.

3. Improved Social Media Sharing

When sharing links on social media, platforms like Facebook and Twitter scrape the URL content to generate previews. SSR ensures that necessary metadata is available in the initial HTML, resulting in better previews and increased click-through rates.

Manage meta tags with next/head: Use the next/head component to add meta tags for social media and SEO.

Example – Adding meta tags to a page:

import Head from 'next/head';

const Page = ({ data }) => (
  <div>
    <Head>
      <title>{data.title}</title>
      <meta name="description" content={data.description} />
      <meta property="og:title" content={data.title} />
      <meta property="og:description" content={data.description} />
      <meta property="og:image" content={data.image} />
      <meta name="twitter:card" content="summary_large_image" />
    </Head>
    <h1>{data.title}</h1>
    <p>{data.content}</p>
  </div>
);

• Page Component: This component uses next/head to add SEO meta tags, including Open Graph tags for social media previews. This ensures that when the page is shared, social media platforms can generate rich previews with the provided metadata.

4. Enhanced User Experience

A faster, more responsive website enhances the overall user experience, leading to longer visit durations and lower bounce rates. Both factors positively influence your SEO rankings.

Pre-render pages with static generation (SSG) for less dynamic content: Use SSG for pages that don’t change often to reduce server load and improve performance.

Example – Using SSG for a static page:

export async function getStaticProps() {
  const res = await fetch('https://api.example.com/static-data');
  const data = await res.json();

  return {
    props: {
      data,
    },
    revalidate: 10, // Revalidate at most once every 10 seconds
  };
}

const StaticPage = ({ data }) => (
  <div>
    <h1>{data.title}</h1>
    <p>{data.content}</p>
  </div>
);

export default StaticPage;

• StaticPage Component: This component displays static content fetched from an API.
• getStaticProps Function: This function fetches data at build time and revalidates it every 10 seconds, ensuring the content is always fresh while reducing server load.

Conclusion

Using server-side rendering and Next.js together is like giving your website an extra boost for search engines. With pre-built content for search engines and a smooth experience for visitors, your site is set up to be seen by more people naturally.

This works great for any kind of website, from online stores to blogs. Next.js with SSR makes it easy to build a website that search engines love and users enjoy.

That's all for this article! If you'd like to continue the conversation or have questions, suggestions, or feedback, feel free to reach out to connect with me on LinkedIn. And if you enjoyed this content, consider buying me a coffee to support the creation of more developer-friendly contents.