npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

isr-engine

v4.4.0

Published

ISR/SSG/Fallback rendering orchestration on Vite + React 19 RSC.

Readme

isr-engine

基于 Vite 与 React Server Components 的页面渲染编排层,提供按路由配置的 ISR、SSG、SSR、缓存失效和渲染失败恢复。Flight 编译与传输由 @vitejs/plugin-rsc 处理。

运行要求与安装

  • Node.js 24.15.0;仓库使用 pnpm 9.15.9。
  • TypeScript 6.0.3;paths 相对声明它的配置文件解析,不再设置 baseUrl。
  • Vite 8.3.8;引擎内置 @vitejs/plugin-rsc 0.5.39 及其 Flight 运行时。
  • React 与 React DOM 使用正式版 19.3.1。引擎管理 HTML 流传输依赖。

在应用目录安装引擎和应用直接使用的 React、Vite:

npm install --save-exact isr-engine [email protected] [email protected]
npm install --save-dev --save-exact [email protected] [email protected] \
  @types/[email protected] @types/[email protected] @types/[email protected]

应用 package.json 设置 "type": "module",并保留锁文件以复现依赖组合。

最小应用

vite.config.ts:

import { defineConfig } from 'vite';
import { createIsrPlugin } from 'isr-engine';

export default defineConfig({ plugins: [...createIsrPlugin()] });

src/app.tsx 是应用根 Server Component,必须命名导出 App。交互组件单独使用 'use client':

import { cacheTag } from 'isr-engine/rsc';

export function App({ url }: { url: URL }) {
  cacheTag('site-content');
  return (
    <html lang="zh-CN">
      <head><meta charSet="utf-8" /><title>My site</title></head>
      <body><main><h1>{url.pathname}</h1></main></body>
    </html>
  );
}

项目根目录的 ssr.config.ts 声明渲染策略与部署配置:

import { defineIsrConfig } from 'isr-engine/config';

export default defineIsrConfig({
  renderMode: 'isr',
  revalidate: 60,
  routes: {
    '/': { mode: 'isr', ttl: 60, staleWhileRevalidate: 300 },
    '/about': 'ssg',
    '/account/*': 'ssr',
  },
  runtime: {
    site: process.env.SITE_URL ?? 'http://localhost:3000',
    services: { api: undefined, telemetry: undefined },
    redis: process.env.REDIS_URL ? {
      url: process.env.REDIS_URL,
      host: undefined, port: undefined, password: undefined,
      keyPrefix: 'my-site:', invalidationChannel: 'my-site:invalidate',
    } : undefined,
    experiments: {},
    i18n: undefined, seo: undefined, telemetry: false,
  },
  server: {
    port: Number(process.env.PORT ?? 3000),
    host: process.env.HOST,
    strictPort: process.env.NODE_ENV === 'production',
    ops: {
      authToken: process.env.ISR_OPS_TOKEN,
      tokenHeader: 'x-isr-admin-token',
      health: { enabled: true, public: true },
      metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
      inventory: { enabled: true, public: false },
    },
  },
  ssg: {
    routes: ['/about'], concurrent: 3,
    requestTimeoutMs: 30_000, maxRetries: 3,
    retryBaseDelayMs: 200, failBuildThreshold: 0.05,
  },
});

package.json 脚本:

{
  "scripts": {
    "dev": "isr-engine dev",
    "build": "vite build",
    "start": "isr-engine start"
  }
}
npm run dev                          # 默认 http://localhost:3000
npm run build                        # 构建 RSC/SSR/client,并预渲染 SSG 路由
NODE_ENV=production npm run start    # 从应用根目录启动生产服务

dev、start 接受 --port <port> 和 --host <host>,显式参数覆盖配置。dev --no-open 关闭自动打开浏览器。构建和启动生产进程时通过运行环境设置 NODE_ENV,避免 .env* 中的 NODE_ENV=development 影响生产构建。

渲染与生产缓存

| 模式 | 行为 | | --- | --- | | isr | 按 TTL 缓存;SWR 窗口内返回旧响应并后台重渲,窗口结束后重新生成。 | | ssg | 构建时预生成配置的路由;运行时仍受缓存新鲜度与失效策略管理。 | | ssr | 每次请求渲染,跳过共享页面缓存。 |

TTL 与 SWR 单位为秒。routes 控制渲染策略;页面路由可使用 isr-engine/runtime 的 defineRoutes 统一声明。渲染异常的 csr-shell 是自动恢复策略;origin 进程不可用时的切换需在反向代理/CDN 配置。

  • 未配置 runtime.redis.url/host 时使用进程内存缓存,重启即清空,各实例独立。
  • 显式配置 Redis 后启用远端版本校验和跨实例失效广播,需保留可选依赖 ioredis;Redis 连接只读取配置,须如示例显式接入环境变量。多实例共享相同应用的前缀与频道,不同应用/环境使用独立命名空间。
  • 登录态、权限相关或个性化页面应配置为 ssr,并在业务层验证身份。请求 hooks 与缓存标签不提供访问控制,也不会自动按用户隔离页面。
  • 授权头、普通业务 Cookie,以及 private/no-store 等响应会触发缓存保护;不要依赖这些保护代替路由策略。anon 与实验 Cookie 有专门的共享缓存规则。
  • Server Component 使用 cacheTag('site-content') 声明依赖;数据更新成功后,在受业务鉴权保护的服务端代码中 await revalidateTag('site-content') 或 await revalidatePath('/about'),从 isr-engine/rsc 导入。

发布、撤稿或索引状态更新提交后,在站点引擎进程中调用 isr-engine/rsc 的 revalidateContent()。调用缺少活动引擎时会抛错。独立后台可在 Node 生产站点启用 server.ops.contentRevalidation: true 并配置 server.ops.authToken,向 POST /__isr/content/revalidate 发送相同 JSON 参数。请求携带 Bearer 运维令牌,失效完成后返回 204。

paths 使用实际页面路径,tags 失效声明了对应标签的页面,locales 指定字典语言,sitemap: true 刷新站点地图。使用 { localizedPaths: ['/work/arcane'], locales: ['ja'] } 可按站点语言配置将业务路径展开为 /ja/work/arcane,同时保留其他语言的 ISR 页面缓存。引擎先刷新元数据,再失效页面响应。其他实例的进程内元数据通过 Redis 广播刷新,断连后可在回放或缓存到期时更新。

runtime.seo.sitemap.load({ services }) 从已提交的数据批量读取完整目录。每条包含站内绝对路径 path、status,可带 noindex 和真实内容更新时间 modifiedTime。引擎只输出已发布且可索引的条目,缺少更新时间时省略 lastmod。单份 sitemap 上限为 50,000 个 URL 和 50 MiB。

临时降级或使用过期字典及 SEO 数据的响应跳过 ISR 写入。动态 sitemap 刷新失败时,默认可在目录过期后的 5 分钟内沿用上一份有效结果,可用 runtime.seo.sitemap.staleIfErrorMs 调整。发布事件会丢弃旧目录,缺少可用目录时返回 503。

在模块初始化时创建 siteHooks = applyRuntimeToServerHooks({}, runtime),再用 siteHooks.loadLanguageCatalog?.() 读取 runtime.i18n.locales 的显示名称。可选的 runtime.i18n.catalog.endpoint 一次返回 { locale, name }[],缺少的名称按语言自身的显示名补齐。引擎合并并发加载,语言发布时刷新目录。

请求期扩展可放在可选的 src/entry.server.tsx,默认导出 defineAdminSiteHooks({ beforeRequest, onError })(从 isr-engine/site-hooks 导入)。部署配置留在 ssr.config.ts;Server Component 用 getRequestContext() 读取 hooks 注入的上下文。

Logger.spin() 返回 Ora 10 对象。prefixText、suffixText 可为字符串或生成函数;color 接受颜色名、false 或 undefined;自定义 spinner 的 interval 必须是正安全整数。

Logger.getInstance({ logFile }) 的文件输出为 JSON Lines,每行独立保存时间、级别、请求上下文、参数与错误;采集程序应按 JSON 解析,原有纯文本文件可在升级前轮转。

运维与部署

部署保留完整 dist/、应用依赖及 ssr.config.*;配置编译需要应用根目录可写的 .isr-cache/。容器按需设置 HOST=0.0.0.0,反向代理后显式配置 server.trustProxy 的可信来源。

/health 默认公开。生产 /metrics 默认关闭;非公开 metrics/inventory 未配置 server.ops.authToken 会自动关闭。启用后通过 Authorization: Bearer <token> 或配置的 token header 访问;设为 public: true 会绕过 token 校验。

引擎运维接口、静态 HTML 文件读取和 SEO 路由分别使用进程内请求预算;超额返回 429 与 Retry-After。通过 server.requestLimits.{ops,staticHtml,seo} 配置 windowMs、单客户端 maxRequests、总量 globalMaxRequests 与容量 maxClients,均须为正整数。默认每分钟单客户端/总量分别为 120/1200、600/12000、120/1200;缓存 HIT 与应用 SSR/API 不计入这些预算。

Google 字体自托管只接受指定 Google HTTPS 来源,验证下载内容后交给 Vite 输出;outDir 相对构建输出目录,开发环境从内存提供资源。下载失败会使该优化任务失败,构建不再改写应用 public/。

curl -fsS http://localhost:3000/health
curl -fsS -H "x-isr-admin-token: $ISR_OPS_TOKEN" \
  http://localhost:3000/__isr/cache/inventory

排查页面时先看 X-Cache-Status、X-Resolved-Mode、X-Render-Strategy。本地代理验证可用 isr-engine test-fallback-local --help;生产切换由部署层完成,浏览器恢复仍依赖可用的资源与数据服务。

公共入口

| 导入路径 | 用途 | | --- | --- | | isr-engine | Vite 插件、Node 编排 API 与公共类型。 | | isr-engine/config | ssr.config.ts 使用的 defineIsrConfig、defineRuntimeConfig、withLocale、alternates。 | | isr-engine/rsc | 缓存标签、失效、服务端请求上下文。 | | isr-engine/runtime | 页面路由、边界、i18n 与浏览器 telemetry。 | | isr-engine/site-hooks | 请求 hooks 工厂与 Cookie 工具。 | | isr-engine/server-entry、isr-engine/client-entry | 高级入口工厂;由 Vite 转译其源码。 | | isr-engine/image | 图片组件。 | | isr-engine/auto-observability、isr-engine/adapters/observability | 自动观测与观测适配器。 | | isr-engine/adapters/runtime | Fetch handler 的平台适配器。 | | isr-engine/package.json | 包元数据。 |

文档与发布

语言切换可从 isr-engine/runtime 使用 <LocaleLink locale="ja" config={i18n}>日本語</LocaleLink>。 组件在引擎接管后可操作,沿用当前路径、查询参数和锚点。 使用 runtime.i18n.prefixDefault: true 的站点可选设 rememberLocale: true。LocaleLink 保存主动切换的语言,下次访问裸根路径时优先采用,带语言前缀的 URL 始终优先。语言协商跳转默认发送 Cache-Control: no-store。

配置字段与默认行为见 公共配置类型 和 默认配置。

main 的自动发布流程通过验证后由 semantic-release 计算版本,以 npm OIDC 发布到 registry.npmjs.org;配置见 发布工作流 与 release.config.mjs。npm 端需绑定对应仓库和工作流的 Trusted Publisher。

发布必须通过依赖审计和 CodeQL security-extended 扫描;任何扫描结果或缺失的扫描证据都会阻止发布,原始审计与 SARIF 结果保留为工作流产物。

许可证声明为 UNLICENSED,以 package.json 为准。