{"id":17580,"library":"done-ssr-middleware","title":"DoneJS Server-Side Rendering Middleware","description":"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.","status":"active","version":"3.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/donejs/done-ssr-middleware","tags":["javascript","DoneJS","server-side","rendering"],"install":[{"cmd":"npm install done-ssr-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add done-ssr-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add done-ssr-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core server-side rendering logic for DoneJS applications","package":"done-ssr","optional":false}],"imports":[{"note":"This package exports a single factory function using CommonJS syntax. Direct ES module default imports are not supported.","wrong":"import ssrMiddleware from 'done-ssr-middleware';","symbol":"ssrMiddlewareFactory","correct":"const ssrMiddleware = require('done-ssr-middleware');"},{"note":"The module exports a single default function for CommonJS environments. Named ES module imports will result in `undefined` or a module loading error.","wrong":"import { ssrMiddleware } from 'done-ssr-middleware';","symbol":"ssrMiddlewareFactory","correct":"const ssrMiddleware = require('done-ssr-middleware');"},{"note":"While technically functional, assigning the factory to a variable first (e.g., `const ssrMiddleware`) is the recommended and clearer practice for readability and reusability.","wrong":"app.use(require('done-ssr-middleware')(systemOptions, middlewareOptions));","symbol":"MiddlewareFunction","correct":"app.use(ssrMiddleware(systemOptions, middlewareOptions));"}],"quickstart":{"code":"const express = require('express');\nconst ssrMiddleware = require('done-ssr-middleware');\nconst path = require('path');\n\nconst app = express();\nconst PORT = process.env.PORT || 3000;\n\n// Resolve the path to your DoneJS application's package.json\n// This usually resides in a 'public' or 'src' directory relative to your server.\nconst doneJsConfigPath = path.join(__dirname, 'public', 'package.json!npm');\n\n// Integrate the server-side rendering middleware\n// The first object contains 'system' options (for done-ssr),\n// the second contains 'middleware' options (for done-ssr-middleware itself).\napp.use('/', ssrMiddleware(\n  // System options for done-ssr\n  {\n    config: doneJsConfigPath\n  },\n  // Middleware options for done-ssr-middleware\n  {\n    // Enable live-reload in development to automatically clear SSR cache\n    liveReload: process.env.NODE_ENV !== 'production',\n    // Example: Enable incremental rendering strategy\n    // strategy: 'incremental'\n  }\n));\n\n// Serve static assets. Ensure this is *after* the SSR middleware\n// so that SSR has a chance to handle routes first.\napp.use(express.static(path.join(__dirname, 'public')));\n\n// Catch-all for 404s - must be after all other routes and middleware\napp.use((req, res, next) => {\n  res.status(404).send('Page Not Found');\n});\n\n// Express error handling middleware (must have 4 arguments)\napp.use((err, req, res, next) => {\n  console.error('SSR or application error:', err.stack);\n  res.status(500).send('An internal server error occurred.');\n});\n\napp.listen(PORT, () => {\n  console.log(`Server listening on http://localhost:${PORT}`);\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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) => { ... })`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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' }));`","message":"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.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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);`","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.","error":"Error: Cannot find module 'main' for package 'my-donejs-app'"},{"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 */ });`","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)`.","error":"TypeError: next is not a function (in error handling middleware)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}