← Back to DevBytes
Developer Tutorial August 05, 2026 6 min read

Server-Side Rendering with Koa: SSR, SSG, ISR

Introduction to Rendering Strategies with Koa

Modern web development relies heavily on how and where HTML is generated. While Client-Side Rendering (CSR) dominated the early days of Single Page Applications (SPAs), the pendulum has swung back toward the server to improve performance, SEO, and user experience. Koa, a minimalist Node.js web framework created by the team behind Express, provides an excellent foundation for implementing various server-side rendering strategies.

In this tutorial, we will explore three primary rendering strategies using Koa: Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR). Understanding when and how to use each will allow you to build highly optimized web applications.

Why Rendering Strategies Matter

Setting Up the Koa Environment

To get started, we need a basic Koa application and a templating engine. We will use ejs for templating because it is simple and widely understood. Initialize a new Node.js project and install the required dependencies:

npm init -y
npm install koa koa-router koa-ejs ejs

Create a directory for your views and a public directory for static files:

mkdir views public

Inside the views directory, create a file named post.ejs. This will be our base template for all three rendering strategies:

<!DOCTYPE html>
<html>
<head>
  <title><%= post.title %></title>
</head>
<body>
  <h1><%= post.title %></h1>
  <div><%= post.content %></div>
</body>
</html>

Server-Side Rendering (SSR) with Koa

SSR is the process of rendering web pages on the server on every request. The server fetches the necessary data, compiles the HTML, and sends it to the client. This is ideal for highly dynamic, user-specific content that changes frequently and cannot be cached easily.

How to Implement SSR

We will configure Koa to use koa-ejs and set up a route that fetches data and renders the template on every request.

const Koa = require('koa');
const Router = require('koa-router');
const render = require('koa-ejs');
const path = require('path');

const app = new Koa();
const router = new Router();

render(app, {
  root: path.join(__dirname, 'views'),
  layout: false,
  viewExt: 'ejs',
  cache: false
});

// Simulate a database fetch
async function fetchPost(id) {
  return {
    id: id,
    title: `Dynamic Post ${id}`,
    content: `This content was generated on the server at ${new Date().toISOString()}`
  };
}

router.get('/ssr/:id', async (ctx) => {
  const postId = ctx.params.id;
  const post = await fetchPost(postId);
  await ctx.render('post', { post });
});

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000, () => {
  console.log('SSR Server running on http://localhost:3000');
});

When a user visits /ssr/1, Koa fetches the post data, passes it to the EJS template, renders the HTML string, and sends it back. The timestamp will update on every refresh, proving the page is dynamically rendered.

Static Site Generation (SSG) with Koa

SSG involves generating all HTML pages at build time, before the application is deployed. This results in incredibly fast page loads because the server only needs to serve static files. SSG is perfect for blogs, documentation sites, and marketing pages where content does not change frequently.

How to Implement SSG

Instead of running a server that listens to requests, we write a build script that fetches all possible data, renders the templates, and writes the output to the public directory as .html files.

const fs = require('fs');
const path = require('path');
const ejs = require('ejs');

// Simulate fetching all posts from a CMS or Database
async function getAllPosts() {
  return [
    { id: 1, title: 'Static Post 1', content: 'Content for post 1' },
    { id: 2, title: 'Static Post 2', content: 'Content for post 2' }
  ];
}

async function generateStaticSite() {
  const posts = await getAllPosts();
  const templatePath = path.join(__dirname, 'views', 'post.ejs');

  for (const post of posts) {
    const html = await ejs.renderFile(templatePath, { post });
    const outputPath = path.join(__dirname, 'public', `post-${post.id}.html`);
    
    fs.writeFileSync(outputPath, html);
    console.log(`Generated: ${outputPath}`);
  }
  console.log('SSG Build Complete!');
}

generateStaticSite();

Run this script during your CI/CD pipeline (e.g., node build.js). You can then serve the public directory using Koa's static middleware, a CDN, or Nginx. The content is frozen at build time, ensuring maximum speed.

Incremental Static Regeneration (ISR) with Koa

ISR bridges the gap between SSR and SSG. It allows you to serve static pages for maximum speed, but revalidates and regenerates those pages in the background when the data becomes stale. This is highly effective for e-commerce sites or news feeds where data updates periodically but doesn't need to be real-time.

How to Implement ISR

To implement ISR in Koa, we serve the static HTML file if it exists. We check the file's last modified time. If it is older than our revalidation window, we serve the stale file immediately (for speed) but trigger an asynchronous background rebuild.

const Koa = require('koa');
const Router = require('koa-router');
const fs = require('fs');
const path = require('path');
const ejs = require('ejs');

const app = new Koa();
const router = new Router();
const REVALIDATE_SECONDS = 60; // Revalidate every 60 seconds

async function fetchPost(id) {
  return {
    id: id,
    title: `ISR Post ${id}`,
    content: `Updated content at ${new Date().toISOString()}`
  };
}

async function regeneratePost(id) {
  const post = await fetchPost(id);
  const templatePath = path.join(__dirname, 'views', 'post.ejs');
  const html = await ejs.renderFile(templatePath, { post });
  const outputPath = path.join(__dirname, 'public', `post-${id}.html`);
  fs.writeFileSync(outputPath, html);
}

router.get('/isr/:id', async (ctx) => {
  const postId = ctx.params.id;
  const filePath = path.join(__dirname, 'public', `post-${postId}.html`);

  if (fs.existsSync(filePath)) {
    const stats = fs.statSync(filePath);
    const ageInSeconds = (Date.now() - stats.mtimeMs) / 1000;
    const isStale = ageInSeconds > REVALIDATE_SECONDS;

    if (isStale) {
      // Trigger background regeneration without awaiting it
      regeneratePost(postId).catch(err => console.error('Regeneration failed:', err));
    }

    // Serve the existing (potentially stale) static file immediately
    ctx.type = 'html';
    ctx.body = fs.createReadStream(filePath);
  } else {
    // First request ever: generate and serve synchronously
    await regeneratePost(postId);
    ctx.type = 'html';
    ctx.body = fs.createReadStream(filePath);
  }
});

app.use(router.routes());
app.listen(3000, () => {
  console.log('ISR Server running on http://localhost:3000');
});

In this example, the first request to /isr/1 generates the file. Subsequent requests within 60 seconds serve the static file instantly. If a request comes in after 60 seconds, the user still gets the fast, static response, but Koa silently fetches new data and overwrites the HTML file for the next user.

Best Practices for Koa Rendering

Conclusion

Koa's unopinionated and middleware-driven architecture makes it a fantastic choice for implementing custom rendering pipelines. By understanding and applying SSR, SSG, and ISR, you can tailor your application's performance and SEO to exact specifications. SSR provides dynamic flexibility, SSG offers unmatched speed, and ISR gives you the best of both worlds by keeping static content fresh without sacrificing load times. Evaluate your application's data freshness requirements and choose the strategy that best fits your needs.

— Ad —

Google AdSense will appear here after approval

← Back to all articles