From 57a4db9762c2d0a331d6127e801ad8f3f98b8244 Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:11:51 +0200
Subject: [PATCH 1/8] templating-compiler: remove archMatching: 'web' to
 compile templates for all architectures

This allows compiled Blaze templates to be available on the server, which
is required for server-side rendering use cases (SSG/SSR).

Server-side overhead is minimal (~500 bytes per template). The <template>
tag compiled output is pure JavaScript with no DOM dependencies. <body>
tag compilation is handled separately in templating-tools.
---
 packages/templating-compiler/compile-templates.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/packages/templating-compiler/compile-templates.js b/packages/templating-compiler/compile-templates.js
index bdeda1a86..66d16535f 100644
--- a/packages/templating-compiler/compile-templates.js
+++ b/packages/templating-compiler/compile-templates.js
@@ -1,7 +1,8 @@
 /* global CachingHtmlCompiler TemplatingTools */
 Plugin.registerCompiler({
   extensions: ['html'],
-  archMatching: 'web',
+  // archMatching removed — compile for all architectures (web + os/server)
+  // so that Template definitions are available server-side for SSG rendering.
   isTemplate: true,
 }, () => new CachingHtmlCompiler(
   'templating',

From c269336805c5a0accc9581e57ba98c06cb6385df Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:12:02 +0200
Subject: [PATCH 2/8] templating-tools: guard body rendering with
 Meteor.isClient
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The <body> tag compiled code calls Template.body.renderToDocument which
uses document.body — this crashes on the server. Wrap generateBodyJS()
output with 'if (Meteor.isClient)' to make body compiled code safe to
load on both architectures.

generateTemplateJS() is unchanged — the <template> tag compiled output
(Template.__checkName + Template[name] = new Template(...)) is already
server-safe.
---
 packages/templating-tools/code-generation.js | 36 ++++++++++++--------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/packages/templating-tools/code-generation.js b/packages/templating-tools/code-generation.js
index 2c516db2f..e13d04ca1 100644
--- a/packages/templating-tools/code-generation.js
+++ b/packages/templating-tools/code-generation.js
@@ -27,26 +27,32 @@ Template[${nameLiteral}] = new Template(${templateDotNameLiteral}, ${renderFuncC
 }
 
 export function generateBodyJS(renderFuncCode, useHMR) {
+  // Body rendering requires DOM (document.body) — guard with Meteor.isClient
+  // so that compiled templates can safely load on the server for SSG.
   if (useHMR) {
     return `
-(function () {
-  var renderFunc = ${renderFuncCode};
-  Template.body.addContent(renderFunc);
-  Meteor.startup(Template.body.renderToDocument);
-  if (typeof module === "object" && module.hot) {
-    module.hot.accept();
-    module.hot.dispose(function () {
-      var index = Template.body.contentRenderFuncs.indexOf(renderFunc)
-      Template.body.contentRenderFuncs.splice(index, 1);
-      Template._applyHmrChanges();
-    });
-  }
-})();
+if (Meteor.isClient) {
+  (function () {
+    var renderFunc = ${renderFuncCode};
+    Template.body.addContent(renderFunc);
+    Meteor.startup(Template.body.renderToDocument);
+    if (typeof module === "object" && module.hot) {
+      module.hot.accept();
+      module.hot.dispose(function () {
+        var index = Template.body.contentRenderFuncs.indexOf(renderFunc)
+        Template.body.contentRenderFuncs.splice(index, 1);
+        Template._applyHmrChanges();
+      });
+    }
+  })();
+}
 `
   }
 
   return `
-Template.body.addContent(${renderFuncCode});
-Meteor.startup(Template.body.renderToDocument);
+if (Meteor.isClient) {
+  Template.body.addContent(${renderFuncCode});
+  Meteor.startup(Template.body.renderToDocument);
+}
 `;
 }

From 59a079e58ac9020cb9a171ccbf57540d5171c8da Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:12:11 +0200
Subject: [PATCH 3/8] caching-html-compiler: guard body attrs setter with
 Meteor.isClient

The generated code calls document.body.setAttribute() which crashes on
the server. Wrap it in 'if (Meteor.isClient)' to make the compiled HTML
safe to load on both architectures.
---
 .../caching-html-compiler.js                    | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/packages/caching-html-compiler/caching-html-compiler.js b/packages/caching-html-compiler/caching-html-compiler.js
index b7b04c383..0282dd4fa 100644
--- a/packages/caching-html-compiler/caching-html-compiler.js
+++ b/packages/caching-html-compiler/caching-html-compiler.js
@@ -115,14 +115,17 @@ CachingHtmlCompiler = class CachingHtmlCompiler extends CachingCompiler {
         }
       });
 
-      // Add JavaScript code to set attributes on body
+      // Add JavaScript code to set attributes on body.
+      // Guarded with Meteor.isClient because document.body doesn't exist on the server.
       allJavaScript +=
-`Meteor.startup(function() {
-  var attrs = ${JSON.stringify(compileResult.bodyAttrs)};
-  for (var prop in attrs) {
-    document.body.setAttribute(prop, attrs[prop]);
-  }
-});
+`if (Meteor.isClient) {
+  Meteor.startup(function() {
+    var attrs = ${JSON.stringify(compileResult.bodyAttrs)};
+    for (var prop in attrs) {
+      document.body.setAttribute(prop, attrs[prop]);
+    }
+  });
+}
 `;
     }
 

From 1ceae5bcfde6aecebe8b0890c6dc766fa86c77a8 Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:12:23 +0200
Subject: [PATCH 4/8] templating-runtime: export Template to server, guard DOM
 code with Meteor.isClient
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Export Template globally (both client and server) so that compiled
templates can register themselves server-side. Previously Template was
client-only, which prevented any server-side rendering use case.

Template.__checkName is already server-safe (no DOM). Template.body,
Template.__pendingReplacement, Template._applyHmrChanges, and the HMR
branch of Template._migrateTemplate all require the DOM — wrapped with
'if (Meteor.isClient)'.

dynamic.html and dynamic.js remain client-only (they require DOM).
---
 packages/templating-runtime/package.js    |   8 +-
 packages/templating-runtime/templating.js | 284 ++++++++++++----------
 2 files changed, 154 insertions(+), 138 deletions(-)

diff --git a/packages/templating-runtime/package.js b/packages/templating-runtime/package.js
index 8ae37900d..50d761d96 100644
--- a/packages/templating-runtime/package.js
+++ b/packages/templating-runtime/package.js
@@ -11,9 +11,10 @@ Package.onUse(function (api) {
   // XXX would like to do the following only when the first html file
   // is encountered
 
-  api.export('Template', 'client');
+  // Export Template to both client and server — server needs it for SSG rendering.
+  api.export('Template');
 
-  api.addFiles('templating.js', 'client');
+  api.addFiles('templating.js');
 
   // html_scanner.js emits client code that calls Meteor.startup and
   // Blaze, so anybody using templating (eg apps) need to implicitly use
@@ -27,13 +28,14 @@ Package.onUse(function (api) {
     'meteor',
     'blaze@3.0.0',
     'spacebars@2.0.0'
-  ], 'client');
+  ]);
 
   // to be able to compile dynamic.html. this compiler is used
   // only inside this package and it should not be implied to not
   // conflict with other packages providing .html compilers.
   api.use('templating-compiler@2.0.0');
 
+  // dynamic template support is client-only (requires DOM)
   api.addFiles([
     'dynamic.html',
     'dynamic.js'
diff --git a/packages/templating-runtime/templating.js b/packages/templating-runtime/templating.js
index eab591599..f3b228b86 100644
--- a/packages/templating-runtime/templating.js
+++ b/packages/templating-runtime/templating.js
@@ -10,6 +10,7 @@ Template = Blaze.Template;
 const RESERVED_TEMPLATE_NAMES = "__proto__ name".split(" ");
 
 // Check for duplicate template names and illegal names that won't work.
+// This is server-safe — no DOM dependency.
 Template.__checkName = function (name) {
   // Some names can't be used for Templates. These include:
   //  - Properties Blaze sets on the Template object.
@@ -26,157 +27,170 @@ Template.__checkName = function (name) {
   }
 };
 
-let shownWarning = false;
-
-// XXX COMPAT WITH 0.8.3
-Template.__define__ = function (name, renderFunc) {
-  Template.__checkName(name);
-  Template[name] = new Template(`Template.${name}`, renderFunc);
-  // Exempt packages built pre-0.9.0 from warnings about using old
-  // helper syntax, because we can.  It's not very useful to get a
-  // warning about someone else's code (like a package on Atmosphere),
-  // and this should at least put a bit of a dent in number of warnings
-  // that come from packages that haven't been updated lately.
-  Template[name]._NOWARN_OLDSTYLE_HELPERS = true;
-
-  // Now we want to show at least one warning so that people get serious about
-  // updating away from this method.
-  if (!shownWarning) {
-    shownWarning = true;
-    console.warn("Your app is using old Template definition that is scheduled to be removed with Blaze 3.0, please check your app and packages for use of: Template.__define__");
-  }
-};
-
-// Define a template `Template.body` that renders its
-// `contentRenderFuncs`.  `<body>` tags (of which there may be
-// multiple) will have their contents added to it.
-
-/**
- * @summary The [template object](#Template-Declarations) representing your `<body>`
- * tag.
- * @locus Client
- */
-Template.body = new Template('body', function () {
-  const view = this;
-  return Template.body.contentRenderFuncs.map((func) => func.apply(view));
-});
-Template.body.contentRenderFuncs = []; // array of Blaze.Views
-Template.body.view = null;
-
-Template.body.addContent = function (renderFunc) {
-  Template.body.contentRenderFuncs.push(renderFunc);
-};
-
-// This function does not use `this` and so it may be called
-// as `Meteor.startup(Template.body.renderIntoDocument)`.
-Template.body.renderToDocument = function () {
-  // Only do it once.
-  if (Template.body.view)
-    return;
-
-  const view = Blaze.render(Template.body, document.body);
-  Template.body.view = view;
-};
-
-Template.__pendingReplacement = []
-
-let updateTimeout = null;
-
-// Simple HMR integration to re-render all of the root views
-// when a template is modified. This function can be overridden to provide
-// an alternative method of applying changes from HMR.
-Template._applyHmrChanges = function (templateName) {
-  if (updateTimeout) {
-    return;
-  }
-
-  // debounce so we only re-render once per rebuild
-  updateTimeout = setTimeout(() => {
-    updateTimeout = null;
-
-    for (let i = 0; i < Template.__pendingReplacement.length; i++) {
-      delete Template[Template.__pendingReplacement[i]];
+// Everything below this point requires DOM and is client-only.
+// On the server, Template is available as a registry for compiled templates
+// (used by Blaze.toHTML / StaticRender for SSG), but body rendering,
+// HMR, and DOM attachment are skipped.
+
+if (Meteor.isClient) {
+
+  let shownWarning = false;
+
+  // XXX COMPAT WITH 0.8.3
+  Template.__define__ = function (name, renderFunc) {
+    Template.__checkName(name);
+    Template[name] = new Template(`Template.${name}`, renderFunc);
+    // Exempt packages built pre-0.9.0 from warnings about using old
+    // helper syntax, because we can.  It's not very useful to get a
+    // warning about someone else's code (like a package on Atmosphere),
+    // and this should at least put a bit of a dent in number of warnings
+    // that come from packages that haven't been updated lately.
+    Template[name]._NOWARN_OLDSTYLE_HELPERS = true;
+
+    // Now we want to show at least one warning so that people get serious about
+    // updating away from this method.
+    if (!shownWarning) {
+      shownWarning = true;
+      console.warn("Your app is using old Template definition that is scheduled to be removed with Blaze 3.0, please check your app and packages for use of: Template.__define__");
+    }
+  };
+
+  // Define a template `Template.body` that renders its
+  // `contentRenderFuncs`.  `<body>` tags (of which there may be
+  // multiple) will have their contents added to it.
+
+  /**
+   * @summary The [template object](#Template-Declarations) representing your `<body>`
+   * tag.
+   * @locus Client
+   */
+  Template.body = new Template('body', function () {
+    const view = this;
+    return Template.body.contentRenderFuncs.map((func) => func.apply(view));
+  });
+  Template.body.contentRenderFuncs = []; // array of Blaze.Views
+  Template.body.view = null;
+
+  Template.body.addContent = function (renderFunc) {
+    Template.body.contentRenderFuncs.push(renderFunc);
+  };
+
+  // This function does not use `this` and so it may be called
+  // as `Meteor.startup(Template.body.renderIntoDocument)`.
+  Template.body.renderToDocument = function () {
+    // Only do it once.
+    if (Template.body.view)
+      return;
+
+    const view = Blaze.render(Template.body, document.body);
+    Template.body.view = view;
+  };
+
+  Template.__pendingReplacement = [];
+
+  let updateTimeout = null;
+
+  // Simple HMR integration to re-render all of the root views
+  // when a template is modified. This function can be overridden to provide
+  // an alternative method of applying changes from HMR.
+  Template._applyHmrChanges = function (templateName) {
+    if (updateTimeout) {
+      return;
     }
 
-    Template.__pendingReplacement = [];
-
-    const views = Blaze.__rootViews.slice();
-    for (let i = 0; i < views.length; i++) {
-      const view = views[i];
-      if (view.destroyed) {
-        continue;
-      }
+    // debounce so we only re-render once per rebuild
+    updateTimeout = setTimeout(() => {
+      updateTimeout = null;
 
-      const renderFunc = view._render;
-      let parentEl;
-      if (view._domrange && view._domrange.parentElement) {
-        parentEl = view._domrange.parentElement;
-      } else if (view._hmrParent) {
-        parentEl = view._hmrParent;
+      for (let i = 0; i < Template.__pendingReplacement.length; i++) {
+        delete Template[Template.__pendingReplacement[i]];
       }
 
-      let comment;
-      if (view._hmrAfter) {
-        comment = view._hmrAfter;
-      } else {
-        const first = view._domrange.firstNode();
-        comment = document.createComment('Blaze HMR PLaceholder');
-        parentEl.insertBefore(comment, first);
-      }
+      Template.__pendingReplacement = [];
 
-      view._hmrAfter = null;
-      view._hmrParent = null;
+      const views = Blaze.__rootViews.slice();
+      for (let i = 0; i < views.length; i++) {
+        const view = views[i];
+        if (view.destroyed) {
+          continue;
+        }
 
-      if (view._domrange) {
-        Blaze.remove(view);
-      }
+        const renderFunc = view._render;
+        let parentEl;
+        if (view._domrange && view._domrange.parentElement) {
+          parentEl = view._domrange.parentElement;
+        } else if (view._hmrParent) {
+          parentEl = view._hmrParent;
+        }
 
-      try {
-        if (view === Template.body.view) {
-          const newView = Blaze.render(Template.body, document.body, comment);
-          Template.body.view = newView;
-        } else if (view.dataVar) {
-          Blaze.renderWithData(renderFunc, view.dataVar.curValue?.value, parentEl, comment);
+        let comment;
+        if (view._hmrAfter) {
+          comment = view._hmrAfter;
         } else {
-          Blaze.render(renderFunc, parentEl, comment);
+          const first = view._domrange.firstNode();
+          comment = document.createComment('Blaze HMR PLaceholder');
+          parentEl.insertBefore(comment, first);
+        }
+
+        view._hmrAfter = null;
+        view._hmrParent = null;
+
+        if (view._domrange) {
+          Blaze.remove(view);
         }
 
-        parentEl.removeChild(comment);
-      } catch (e) {
-        console.log('[Blaze HMR] Error re-rending template:');
-        console.error(e);
-
-        // Record where the view should have been so we can still render it
-        // during the next update
-        const newestRoot = Blaze.__rootViews[Blaze.__rootViews.length - 1];
-        if (newestRoot && newestRoot.isCreated && !newestRoot.isRendered) {
-          newestRoot._hmrAfter = comment;
-          newestRoot._hmrParent = parentEl;
+        try {
+          if (view === Template.body.view) {
+            const newView = Blaze.render(Template.body, document.body, comment);
+            Template.body.view = newView;
+          } else if (view.dataVar) {
+            Blaze.renderWithData(renderFunc, view.dataVar.curValue?.value, parentEl, comment);
+          } else {
+            Blaze.render(renderFunc, parentEl, comment);
+          }
+
+          parentEl.removeChild(comment);
+        } catch (e) {
+          console.log('[Blaze HMR] Error re-rending template:');
+          console.error(e);
+
+          // Record where the view should have been so we can still render it
+          // during the next update
+          const newestRoot = Blaze.__rootViews[Blaze.__rootViews.length - 1];
+          if (newestRoot && newestRoot.isCreated && !newestRoot.isRendered) {
+            newestRoot._hmrAfter = comment;
+            newestRoot._hmrParent = parentEl;
+          }
         }
       }
-    }
-  });
-};
+    });
+  };
+
+} // end if (Meteor.isClient)
 
+// _migrateTemplate is called by compiled template code on both client and server.
+// On the server, it just registers the template without HMR logic.
 Template._migrateTemplate = function (templateName, newTemplate, migrate) {
-  const oldTemplate = Template[templateName];
-  migrate = Template.__pendingReplacement.includes(templateName);
-
-  if (oldTemplate && migrate) {
-    newTemplate.__helpers = oldTemplate.__helpers;
-    newTemplate.__eventMaps = oldTemplate.__eventMaps;
-    newTemplate._callbacks.created = oldTemplate._callbacks.created;
-    newTemplate._callbacks.rendered = oldTemplate._callbacks.rendered;
-    newTemplate._callbacks.destroyed = oldTemplate._callbacks.destroyed;
-    delete Template[templateName];
-    Template._applyHmrChanges(templateName);
-  }
+  if (Meteor.isClient) {
+    const oldTemplate = Template[templateName];
+    migrate = Template.__pendingReplacement.includes(templateName);
+
+    if (oldTemplate && migrate) {
+      newTemplate.__helpers = oldTemplate.__helpers;
+      newTemplate.__eventMaps = oldTemplate.__eventMaps;
+      newTemplate._callbacks.created = oldTemplate._callbacks.created;
+      newTemplate._callbacks.rendered = oldTemplate._callbacks.rendered;
+      newTemplate._callbacks.destroyed = oldTemplate._callbacks.destroyed;
+      delete Template[templateName];
+      Template._applyHmrChanges(templateName);
+    }
 
-  if (migrate) {
-    Template.__pendingReplacement.splice(
-      Template.__pendingReplacement.indexOf(templateName),
-      1
-    )
+    if (migrate) {
+      Template.__pendingReplacement.splice(
+        Template.__pendingReplacement.indexOf(templateName),
+        1
+      );
+    }
   }
 
   Template.__checkName(templateName);

From 31d2848c72734df06e222208f91a70c18313548c Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:12:31 +0200
Subject: [PATCH 5/8] templating: export Template to server
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Matches the export change in templating-runtime. The templating package
re-exports Template from templating-runtime and was also restricting it
to the client — which would override the templating-runtime change.
---
 packages/templating/package.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/templating/package.js b/packages/templating/package.js
index 6ac7828b1..ba4805c22 100644
--- a/packages/templating/package.js
+++ b/packages/templating/package.js
@@ -11,7 +11,8 @@ Package.describe({
 // registry and a default templating system, ideally per-package.
 
 Package.onUse(function (api) {
-  api.export('Template', 'client');
+  // Export Template to both client and server for SSG rendering support
+  api.export('Template');
 
   api.use('templating-runtime@2.0.0');
   api.imply('templating-runtime');

From e033637fe63e9ff867a1f2c707e3d91a35630d86 Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:28:02 +0200
Subject: [PATCH 6/8] test(templating-tools): update html scanner test
 expectation for Meteor.isClient wrap

The simpleBody helper in html-scanner-tests now expects the <body> rendering
code to be wrapped in 'if (Meteor.isClient)', matching the change in
generateBodyJS().
---
 packages/templating-tools/html-scanner-tests.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/templating-tools/html-scanner-tests.js b/packages/templating-tools/html-scanner-tests.js
index 9f3e22211..1c7086b98 100644
--- a/packages/templating-tools/html-scanner-tests.js
+++ b/packages/templating-tools/html-scanner-tests.js
@@ -32,7 +32,7 @@ Tinytest.add("templating-tools - html scanner", function (test) {
   // where content is something simple like the string "Hello"
   // (passed in as a source string including the quotes).
   var simpleBody = function (content) {
-    return "\nTemplate.body.addContent((function () { var view = this; return " + content + "; }));\nMeteor.startup(Template.body.renderToDocument);\n";
+    return "\nif (Meteor.isClient) {\n  Template.body.addContent((function () { var view = this; return " + content + "; }));\n  Meteor.startup(Template.body.renderToDocument);\n}\n";
   };
 
   // arguments are quoted strings like '"hello"'

From 4735f37a86319f061a3f04c8c5c3af83009ced8d Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:32:38 +0200
Subject: [PATCH 7/8] docs: add server rendering guide

Document the new server-side Blaze rendering capability:
- Blaze.toHTML() / Blaze.toHTMLWithData() work on the server
- How to make templates available server-side (import in server/main.js)
- Template restrictions (no Session, no this.subscribe, no Template.dynamic)
- Link to static-render package for higher-level SSG/SSR API
- Manual integration with server-render package
- Known rspack limitation
---
 site/source/guide/server-rendering.md | 94 +++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 site/source/guide/server-rendering.md

diff --git a/site/source/guide/server-rendering.md b/site/source/guide/server-rendering.md
new file mode 100644
index 000000000..22eede665
--- /dev/null
+++ b/site/source/guide/server-rendering.md
@@ -0,0 +1,94 @@
+---
+title: Server Rendering
+description: Render Blaze templates to HTML strings on the server for SEO, social previews, and pre-rendering.
+---
+
+# Server Rendering with Blaze
+
+Starting from Blaze 3.1.x, compiled templates are available both on the client and on the server. This enables rendering templates to HTML strings from Node.js — useful for SEO, social link previews, and pre-rendering static or dynamic pages.
+
+## The basics
+
+`Blaze.toHTML()` and `Blaze.toHTMLWithData()` work on the server, returning a string of HTML:
+
+```js
+// server/main.js
+import '../imports/ui/my-template.html';  // make template available server-side
+
+const html = Blaze.toHTML(Template.myTemplate);
+const html2 = Blaze.toHTMLWithData(Template.productCard, { title: 'Oak Chair', price: 149 });
+```
+
+The rendering path goes through `Blaze._expandView()`, which is DOM-free. No browser, no JSDOM required.
+
+## Making templates available on the server
+
+In modern Meteor with explicit imports, `.html` files must be imported from `server/main.js` (or a file it imports) to be included in the server bundle:
+
+```js
+// server/main.js
+import '../imports/ui/templates.html';
+```
+
+On the client, your existing imports continue to work unchanged.
+
+## Template restrictions
+
+Templates rendered on the server must avoid client-only APIs and Tracker-based reactivity:
+
+- ❌ `Session.get()`, `Session.set()`
+- ❌ `Template.instance().subscribe()`
+- ❌ `Template.dynamic` (it remains client-only)
+- ❌ ReactiveVar, ReactiveDict reads inside helpers
+- ❌ `onRendered()`, `onDestroyed()` callbacks (they don't fire server-side)
+- ✅ Pure helpers that use the data context passed to the template
+- ✅ `#each`, `#if`, `#unless`, `#with`, `#let` block helpers
+- ✅ Sub-templates with `{{> myTemplate}}`
+
+Server-rendered templates should be written as pure render functions against explicit data context.
+
+## Using server rendering for SSG/SSR
+
+The [`static-render` package](../packages/static-render) provides a higher-level API for pre-rendering routes at server startup (SSG) or at each request (SSR), integrating with `flow-router-extra` and the Meteor boilerplate pipeline.
+
+```js
+import { FlowRouter } from 'meteor/ostrio:flow-router-extra';
+
+FlowRouter.route('/about', {
+  static: 'ssg',
+  template: 'about',
+  staticData() {
+    return { title: 'About Us' };
+  },
+  staticHead() {
+    return '<title>About | MyShop</title>';
+  },
+});
+```
+
+See the [static-render package docs](../packages/static-render) for full API reference.
+
+## Manual rendering (without static-render)
+
+For custom integration, use `Blaze.toHTML()` directly with `server-render`'s `onPageLoad()`:
+
+```js
+import { onPageLoad } from 'meteor/server-render';
+
+onPageLoad((sink) => {
+  const html = Blaze.toHTMLWithData(Template.homepage, { title: 'Welcome' });
+  sink.appendToBody(html);
+  sink.appendToHead('<title>Welcome</title>');
+});
+```
+
+## What's new in 3.1.x
+
+Prior to this version, Blaze templates only compiled for the client, and the `Template` registry was not exported to the server. Server-side rendering was possible only through third-party packages (now unmaintained).
+
+The changes are backward-compatible: existing client-side Blaze apps continue to work identically. The server-side additions are opt-in — if you don't import `.html` files from your server entry point, nothing changes.
+
+## Known limitations
+
+- **Rspack**: requires a small patch to `@meteorjs/rspack` to allow `.html` imports on the server. See the [rspack integration notes](../packages/rspack.md#server-side-html-imports).
+- **Dynamic templates**: `{{> Template.dynamic template=content}}` is client-only. For server rendering, use direct template inclusion `{{> content}}`.

From f437642ef115eaf55ceb0b774d65d9e0214cd40b Mon Sep 17 00:00:00 2001
From: dupontbertrand <dupontbertrand59@gmail.com>
Date: Mon, 20 Apr 2026 12:36:30 +0200
Subject: [PATCH 8/8] docs: expand SSG vs SSR section in server-rendering guide

- Add dedicated SSG subsection with about-page example
- Add dedicated SSR subsection with product-page example
- Add SSG vs SSR comparison table for decision-making
---
 site/source/guide/server-rendering.md | 35 ++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/site/source/guide/server-rendering.md b/site/source/guide/server-rendering.md
index 22eede665..204f23828 100644
--- a/site/source/guide/server-rendering.md
+++ b/site/source/guide/server-rendering.md
@@ -51,6 +51,10 @@ Server-rendered templates should be written as pure render functions against exp
 
 The [`static-render` package](../packages/static-render) provides a higher-level API for pre-rendering routes at server startup (SSG) or at each request (SSR), integrating with `flow-router-extra` and the Meteor boilerplate pipeline.
 
+### SSG — Static Site Generation
+
+For pages whose content doesn't change without a server restart (about, contact, terms). The HTML is rendered once at startup and cached permanently in memory.
+
 ```js
 import { FlowRouter } from 'meteor/ostrio:flow-router-extra';
 
@@ -66,7 +70,36 @@ FlowRouter.route('/about', {
 });
 ```
 
-See the [static-render package docs](../packages/static-render) for full API reference.
+### SSR — Server-Side Rendering
+
+For pages whose data changes (products, articles, profiles). The HTML is rendered on each request with fresh MongoDB data.
+
+```js
+FlowRouter.route('/products/:slug', {
+  static: 'ssr',
+  template: 'productPage',
+  async staticData(params) {
+    return await Products.findOneAsync({ slug: params.slug });
+  },
+  async staticHead(params) {
+    const p = await Products.findOneAsync({ slug: params.slug });
+    return `<title>${p.title} — $${p.price} | MyShop</title>`;
+  },
+});
+```
+
+When a user edits the product description and saves it, refreshing the page shows the new data — because SSR queries MongoDB at each request.
+
+### SSG vs SSR — which to use?
+
+| | SSG | SSR |
+|---|---|---|
+| Data freshness | Frozen at startup | Fresh per request |
+| Serving cost | Instant (in-memory cache) | Query DB + render per request |
+| Use case | About, pricing, terms | Products, articles, profiles |
+| Data source | Hardcoded or DB at startup | MongoDB at request time |
+
+See the [static-render package docs](../packages/static-render) for full API reference including parameterized SSG routes (`staticPaths`), cache invalidation, and graceful error handling.
 
 ## Manual rendering (without static-render)
 
