🤖 Angular SSR for bots, prebuilt CSR shell for humans v2026.4.108

🌌 Bugs are evident™ - MATRIX️
🚧 This project is under active development!
📢 We welcome your feedback and contributions.

NodeJS LTS is supported

🛠️ Built on NodeJs version

v24.15.0

📝 Description

Faster page loads for users, fully prerendered HTML for Googlebot, Bingbot, Yandex, ClaudeBot, GPTBot and link unfurlers (Slack, Twitter, Facebook, WhatsApp). Powered by isbot.

Why

Angular SSR is great for crawlers and great in the readme — but in production, every real user pays for it: SSR HTML arrives, hydrates, and re-renders. Users see a flash, click handlers don't fire until hydration completes, and Time to Interactive is worse than a CSR-only build for sites with any meaningful JS.

Meanwhile, the bots that actually need server-rendered HTML — Googlebot, Bingbot, Yandex, Facebook/Twitter unfurlers, ClaudeBot, GPTBot, PerplexityBot — execute little or no JavaScript. Shipping them the CSR shell means empty meta tags, empty link previews, and weak indexing.

ngx-bot-ssr switches the response based on the User-Agent:

• Real browsers → static index.csr.html shell, Angular bootstraps client-side, no hydration flicker
• Bots / crawlers / unfurlers / missing UA → Angular SSR via AngularNodeAppEngine.handle(), fully prerendered HTML

Sets Vary: User-Agent so any upstream cache (CDN, Varnish, Cloudflare) keeps the two responses separate.

The Angular community has been asking for this for years:

• angular/angular#52360 — "skip Client App Initialization for Google/Bing Crawlers/Bots"
• angular/universal-starter#536 — "Is it possible to use SSR only for bots/crawlers?"

Install

yarn add ngx-bot-ssr
# or
npm install ngx-bot-ssr

express is a peer dependency. You almost certainly already have it via @angular/ssr.

Usage — Angular SSR (the easy way)

In your Angular SSR project's src/server.ts, replace the catch-all app.use((req, res, next) => angularApp.handle(req)...) block with angularBotSsr(...). Three lines, no glue code:

import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  isMainModule,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';
import { join } from 'node:path';
import { angularBotSsr } from 'ngx-bot-ssr';

const browserDistFolder = join(import.meta.dirname, '../browser');

const app = express();
const angularApp = new AngularNodeAppEngine();

// Static assets first (CSR JS, images, fonts)
app.use(express.static(browserDistFolder, {
  maxAge: '1y',
  index: false,
  redirect: false,
}));

// Bots → SSR, humans → CSR shell. That's it.
app.use(angularBotSsr({
  browserDistFolder,
  angularApp,
  writeResponseToNodeResponse,
}));

if (isMainModule(import.meta.url) || process.env['pm_id']) {
  const port = process.env['PORT'] || 4000;
  app.listen(port, () => console.log(`listening on http://localhost:${port}`));
}

export const reqHandler = createNodeRequestHandler(app);

Build with ng build (which already produces index.csr.html), run the SSR server, and:

• curl -H 'User-Agent: Googlebot/2.1' http://localhost:4000/ → fully prerendered Angular HTML
• curl -H 'User-Agent: Mozilla/5.0 (...) Chrome/...' http://localhost:4000/ → CSR shell, ~1 KB

Why pass writeResponseToNodeResponse and angularApp in? @angular/ssr/node is ESM-only, so the package can't require() it from a CJS module. Passing them in keeps ngx-bot-ssr framework-agnostic at the core (Hono, raw Web fetch handlers, etc. all work) while still giving the Angular case a one-call API.

API — angularBotSsr(options)

const { angularBotSsr } = require('ngx-bot-ssr');
// or: import { angularBotSsr } from 'ngx-bot-ssr';

app.use(angularBotSsr(options));

| Option | Required | Description | | --- | --- | --- | | browserDistFolder | ✅ | Absolute path to your Angular dist/.../browser/ folder. The CSR shell is read from ${browserDistFolder}/index.csr.html unless shell is set. | | angularApp | ✅ | An AngularNodeAppEngine instance from @angular/ssr/node. | | writeResponseToNodeResponse | ✅ | Imported from @angular/ssr/node. | | shell | – | Override the shell path if your CSR file lives elsewhere. | | isBot | – | (userAgent: string \| undefined) => boolean. Override the default detection. | | shellCacheControl | – | Cache-Control header for the CSR shell. Defaults to 'no-cache'. |

API — botSsr(options) (low-level, framework-agnostic)

Use this if you're not on Angular — Hono, plain fetch-style handlers, anything that returns a Web Response works.

const { botSsr } = require('ngx-bot-ssr');

app.use(botSsr({
  shell: '/abs/path/to/index.csr.html',
  ssr: (req) => myEngine.handle(req),         // → Promise<Response | null | undefined>
  writeResponse: (response, res) => { /* serialize Web Response → Node res */ },
  // optional:
  isBot,                // (ua) => boolean
  shellCacheControl,    // string
}));

| Option | Required | Description | | --- | --- | --- | | shell | ✅ | Absolute path to the CSR shell HTML. Read lazily on the first non-bot request, then cached (so Angular's prerender route extractor doesn't trip on the not-yet-built browser/ folder). | | ssr | ✅ | (req) => Promise<Response \| null \| undefined>. Returning null/undefined calls next(). | | writeResponse | ✅ | (response, res) => void. Serializes the Web Response into the Node res. | | isBot | – | (userAgent) => boolean. Default uses isbot and treats missing UAs as bots. | | shellCacheControl | – | Default 'no-cache'. |

How it works

                  request
                     │
                     ▼
        ┌────────────────────────┐
        │ Vary: User-Agent       │
        └────────────────────────┘
                     │
            isBot(req.UA)?
              ┌──────┴──────┐
              │             │
            true           false
              │             │
              ▼             ▼
        options.ssr     send shell
              │       (lazy read,
              ▼        then cached)
       Response | null
              │
       ┌──────┴──────┐
       │             │
   Response       null/undef
       │             │
       ▼             ▼
 writeResponse    next()

Treats missing UAs as bots — safer to prerender than to ship the CSR shell to an unknown client.

Reference reading

• Adnan Ebrahimi — switch SSR/CSR by user agent
• baunov gist
• dsimmons on Medium — Frustrated with Angular Universal SSR
• Infinum handbook — robots and sitemap

Credits

• isbot by Omri Lotan — the bot detection library this package wraps. Updated continuously, covers the long tail of crawlers, AI bots, and link unfurlers.
• Pattern originally extracted from corifeus-app-web-pages.

🌐 Meet Assistant SaaS — meeting.corifeus.com

Don't want to install anything? Try the hosted version at meeting.corifeus.com — full meeting workflow built for European businesses, no setup, no API key, no command line.

What the hosted version offers:

• 21-language live translation during the meeting
• AI summaries, action items, decisions, attendees, key quotes auto-generated after every meeting
• Custom vocabulary — your client / company / industry terms corrected automatically (Pro+ tier)
• Searchable meeting library — find any decision or promise across all your past meetings
• Shareable read-only links — send a clean meeting summary to a client or teammate, no signup needed on their end
• One-click email summary after each meeting
• Premium engine on every plan — no downgraded model, ever
• EU billing — Stripe Tax + VAT-compliant + EUR-priced (Solo €19.99 / Pro €39.99 / Business €99.99 per month, no lock-in)
• GDPR-compliant by default — browser-language auto-detection, no tracking cookies, your meetings stored encrypted

Try the live demo (1 minute free, no signup) or browse the public sample meeting at meeting.corifeus.com/sample.

Corifeus Network

AI-powered network & email toolkit — free, no signup.

Web · network.corifeus.com MCP · npm i -g p3x-network-mcp

• AI Network Assistant — ask in plain language, get a full domain health report
• Network Audit — DNS, SSL, security headers, DNSBL, BGP, IPv6, geolocation in one call
• Diagnostics — DNS lookup & global propagation, WHOIS, reverse DNS, HTTP check, my-IP
• Mail Tester — live SPF/DKIM/DMARC + spam score + AI fix suggestions, results emailed (localized)
• Monitoring — TCP / HTTP / Ping with alerts and public status pages
• MCP server — 17 tools exposed to Claude Code, Codex, Cursor, any MCP client
• Install — claude mcp add p3x-network -- npx p3x-network-mcp
• Try — "audit example.com", "why do my emails land in spam? test [email protected]"
• Source — patrikx3/network · patrikx3/network-mcp
• Contact — patrikx3.com · donate

❤️ Support Our Open-Source Project

If you appreciate our work, consider ⭐ starring this repository or 💰 making a donation to support server maintenance and ongoing development. Your support means the world to us—thank you!

🌍 About My Domains

All my domains, including patrikx3.com, corifeus.eu, and corifeus.com, are developed in my spare time. While you may encounter minor errors, the sites are generally stable and fully functional.

📈 Versioning Policy

Version Structure: We follow a Major.Minor.Patch versioning scheme:

• Major: 📅 Corresponds to the current year.
• Minor: 🌓 Set as 4 for releases from January to June, and 10 for July to December.
• Patch: 🔧 Incremental, updated with each build.

🚨 Important Changes: Any breaking changes are prominently noted in the readme to keep you informed.

NGX-BOT-SSR Build v2026.4.108