DoneJS Server-Side Rendering Middleware

3.0.1 verified Thu Apr 23 auth: no javascript

done-ssr-middleware is an Express/Connect middleware designed to integrate server-side rendering capabilities into DoneJS applications. The current stable version is 3.0.1, which aligns with the DoneJS 3.0 ecosystem. It provides a straightforward way to add SSR to an existing Node.js server, allowing DoneJS applications to be pre-rendered for faster initial page loads and improved SEO. Key features include configurable SSR options inherited from `done-ssr`, and a live-reload utility to automatically refresh the SSR cache during development. It differentiates itself by tightly integrating with the DoneJS framework's module loading and rendering pipeline, leveraging `done-ssr` for the core rendering logic.

Common errors

error Error: Cannot find module 'main' for package 'my-donejs-app' ↓

cause The `packageName` was not explicitly included or correctly resolved in the `system` configuration object passed to `done-ssr-middleware`, causing the underlying `done-ssr` engine to fail at identifying the main application module.

fix

Ensure the packageName property is explicitly defined in the first argument (the systemOptions object) of the ssrMiddleware factory. Example: ssrMiddleware({ config: ..., packageName: 'your-app-name' }, options);

error TypeError: next is not a function (in error handling middleware) ↓

cause An Express error handling middleware function was defined with an incorrect signature, missing the `next` argument. Express expects error handlers to have exactly four arguments: `(err, req, res, next)`.

fix

Ensure your error handling middleware function includes all four arguments, even if next is not directly used: app.use((err, req, res, next) => { /* handle error */ });

Warnings

breaking Major breaking changes introduced in `done-ssr-middleware` v3.0.0 are inherited directly from `done-ssr` v3.0.0. These changes primarily relate to the core rendering pipeline, configuration, and expected behaviors of DoneJS applications. Users upgrading from v1.x will need to adapt their DoneJS application code and middleware configurations. ↓

fix Consult the `done-ssr` v3.0.0 release notes (linked from the `done-ssr-middleware` v3.0.0 announcement) for a comprehensive list of breaking changes and migration steps, and update your DoneJS application and middleware options accordingly.

gotcha The `done-ssr-middleware` must be placed strategically in your Express/Connect middleware chain. It should typically be positioned *after* static file servers and other route handlers that should take precedence for non-SSR routes, but crucially *before* any general error handling middleware. Incorrect placement can lead to routes not being server-rendered or rendering-specific errors not being properly caught. ↓

fix Ensure `app.use(ssrMiddleware(systemOptions, middlewareOptions))` is called after `app.use(express.static(...))` or specific `app.get(...)` routes, but always before `app.use((err, req, res, next) => { ... })`.

gotcha To enable incremental rendering for performance optimization, the `strategy: 'incremental'` option must be explicitly provided in the `middlewareOptions` object when instantiating the `done-ssr-middleware` factory. By default, the middleware uses a full rendering strategy. ↓

fix Pass `{ strategy: 'incremental' }` as a property within the *second* argument (the `middlewareOptions` object) to the `ssrMiddleware()` factory function, for example: `app.use(ssrMiddleware({ config: '...' }, { strategy: 'incremental' }));`

Install

npm install done-ssr-middleware

yarn add done-ssr-middleware

pnpm add done-ssr-middleware

Imports

ssrMiddlewareFactory
wrong
```
import ssrMiddleware from 'done-ssr-middleware';
```
correct
```
const ssrMiddleware = require('done-ssr-middleware');
```
This package exports a single factory function using CommonJS syntax. Direct ES module default imports are not supported.
ssrMiddlewareFactory
wrong
```
import { ssrMiddleware } from 'done-ssr-middleware';
```
correct
```
const ssrMiddleware = require('done-ssr-middleware');
```
The module exports a single default function for CommonJS environments. Named ES module imports will result in `undefined` or a module loading error.
MiddlewareFunction
wrong
```
app.use(require('done-ssr-middleware')(systemOptions, middlewareOptions));
```
correct
```
app.use(ssrMiddleware(systemOptions, middlewareOptions));
```
While technically functional, assigning the factory to a variable first (e.g., `const ssrMiddleware`) is the recommended and clearer practice for readability and reusability.

Quickstart

This quickstart demonstrates how to integrate `done-ssr-middleware` into an Express application, configuring it to serve a DoneJS application with server-side rendering and enabling live-reload for development environments. It correctly places the middleware relative to static asset serving and includes basic error handling.

const express = require('express');
const ssrMiddleware = require('done-ssr-middleware');
const path = require('path');

const app = express();
const PORT = process.env.PORT || 3000;

// Resolve the path to your DoneJS application's package.json
// This usually resides in a 'public' or 'src' directory relative to your server.
const doneJsConfigPath = path.join(__dirname, 'public', 'package.json!npm');

// Integrate the server-side rendering middleware
// The first object contains 'system' options (for done-ssr),
// the second contains 'middleware' options (for done-ssr-middleware itself).
app.use('/', ssrMiddleware(
  // System options for done-ssr
  {
    config: doneJsConfigPath
  },
  // Middleware options for done-ssr-middleware
  {
    // Enable live-reload in development to automatically clear SSR cache
    liveReload: process.env.NODE_ENV !== 'production',
    // Example: Enable incremental rendering strategy
    // strategy: 'incremental'
  }
));

// Serve static assets. Ensure this is *after* the SSR middleware
// so that SSR has a chance to handle routes first.
app.use(express.static(path.join(__dirname, 'public')));

// Catch-all for 404s - must be after all other routes and middleware
app.use((req, res, next) => {
  res.status(404).send('Page Not Found');
});

// Express error handling middleware (must have 4 arguments)
app.use((err, req, res, next) => {
  console.error('SSR or application error:', err.stack);
  res.status(500).send('An internal server error occurred.');
});

app.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
});