isr-engine 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +755 -0
- package/README.md +694 -2
- package/dist/RequestContext-BVQ-rOmV.js +58 -0
- package/dist/RequestContext-BVQ-rOmV.js.map +1 -0
- package/dist/RequestContext-DgGEAxcW.cjs +105 -0
- package/dist/RequestContext-DgGEAxcW.cjs.map +1 -0
- package/dist/abVariantContext-CWCdRSdG.js +549 -0
- package/dist/abVariantContext-CWCdRSdG.js.map +1 -0
- package/dist/abVariantContext-Cqp-uxtd.cjs +678 -0
- package/dist/abVariantContext-Cqp-uxtd.cjs.map +1 -0
- package/dist/adapters/observability/client/sentry.d.ts +42 -0
- package/dist/adapters/observability/client/sentry.d.ts.map +1 -0
- package/dist/adapters/observability/index.cjs +152 -0
- package/dist/adapters/observability/index.cjs.map +1 -0
- package/dist/adapters/observability/index.d.ts +17 -0
- package/dist/adapters/observability/index.d.ts.map +1 -0
- package/dist/adapters/observability/index.js +148 -0
- package/dist/adapters/observability/index.js.map +1 -0
- package/dist/adapters/observability/server/datadog.d.ts +45 -0
- package/dist/adapters/observability/server/datadog.d.ts.map +1 -0
- package/dist/adapters/observability/server/otel.d.ts +51 -0
- package/dist/adapters/observability/server/otel.d.ts.map +1 -0
- package/dist/adapters/observability/server/sentry.d.ts +67 -0
- package/dist/adapters/observability/server/sentry.d.ts.map +1 -0
- package/dist/adapters/observability/types.d.ts +39 -0
- package/dist/adapters/observability/types.d.ts.map +1 -0
- package/dist/adapters/runtime/cloudflare.d.ts +33 -0
- package/dist/adapters/runtime/cloudflare.d.ts.map +1 -0
- package/dist/adapters/runtime/errorResponse.d.ts +3 -0
- package/dist/adapters/runtime/errorResponse.d.ts.map +1 -0
- package/dist/adapters/runtime/index.cjs +100 -0
- package/dist/adapters/runtime/index.cjs.map +1 -0
- package/dist/adapters/runtime/index.d.ts +10 -0
- package/dist/adapters/runtime/index.d.ts.map +1 -0
- package/dist/adapters/runtime/index.js +97 -0
- package/dist/adapters/runtime/index.js.map +1 -0
- package/dist/adapters/runtime/types.d.ts +24 -0
- package/dist/adapters/runtime/types.d.ts.map +1 -0
- package/dist/adapters/runtime/vercel-edge.d.ts +59 -0
- package/dist/adapters/runtime/vercel-edge.d.ts.map +1 -0
- package/dist/app/createISRApp.d.ts +19 -0
- package/dist/app/createISRApp.d.ts.map +1 -0
- package/dist/cache/CacheManager.d.ts +81 -0
- package/dist/cache/CacheManager.d.ts.map +1 -0
- package/dist/cache/ICacheAdapter.d.ts +84 -0
- package/dist/cache/ICacheAdapter.d.ts.map +1 -0
- package/dist/cache/MemoryCacheAdapter.d.ts +50 -0
- package/dist/cache/MemoryCacheAdapter.d.ts.map +1 -0
- package/dist/cache/RedisCacheAdapter.d.ts +111 -0
- package/dist/cache/RedisCacheAdapter.d.ts.map +1 -0
- package/dist/cache/RedisInvalidationBus.d.ts +59 -0
- package/dist/cache/RedisInvalidationBus.d.ts.map +1 -0
- package/dist/cache/RedisResponseCacheBackend.d.ts +30 -0
- package/dist/cache/RedisResponseCacheBackend.d.ts.map +1 -0
- package/dist/cache/ResponseCacheBackend.d.ts +28 -0
- package/dist/cache/ResponseCacheBackend.d.ts.map +1 -0
- package/dist/cache/createAutoCacheStore.d.ts +26 -0
- package/dist/cache/createAutoCacheStore.d.ts.map +1 -0
- package/dist/cache/index.d.ts +18 -0
- package/dist/cache/index.d.ts.map +1 -0
- package/dist/cli/cli.cjs +372 -0
- package/dist/cli/cli.cjs.map +1 -0
- package/dist/cli/cli.d.ts +8 -0
- package/dist/cli/cli.d.ts.map +1 -0
- package/dist/cli/cli.js +370 -0
- package/dist/cli/cli.js.map +1 -0
- package/dist/cli/dev.d.ts +11 -0
- package/dist/cli/dev.d.ts.map +1 -0
- package/dist/cli/fallback.d.ts +42 -0
- package/dist/cli/fallback.d.ts.map +1 -0
- package/dist/cli/serverOptions.d.ts +7 -0
- package/dist/cli/serverOptions.d.ts.map +1 -0
- package/dist/cli/start.d.ts +7 -0
- package/dist/cli/start.d.ts.map +1 -0
- package/dist/config/defaults.d.ts +11 -0
- package/dist/config/defaults.d.ts.map +1 -0
- package/dist/config/defineConfig.cjs +26 -0
- package/dist/config/defineConfig.cjs.map +1 -0
- package/dist/config/defineConfig.d.ts +44 -0
- package/dist/config/defineConfig.d.ts.map +1 -0
- package/dist/config/defineConfig.js +24 -0
- package/dist/config/defineConfig.js.map +1 -0
- package/dist/config/getEnv.d.ts +9 -0
- package/dist/config/getEnv.d.ts.map +1 -0
- package/dist/config/getStatus.d.ts +3 -0
- package/dist/config/getStatus.d.ts.map +1 -0
- package/dist/config/loadConfig.d.ts +18 -0
- package/dist/config/loadConfig.d.ts.map +1 -0
- package/dist/config/normalizeEngineConfig.d.ts +10 -0
- package/dist/config/normalizeEngineConfig.d.ts.map +1 -0
- package/dist/config/resolveImageOptions.d.ts +5 -0
- package/dist/config/resolveImageOptions.d.ts.map +1 -0
- package/dist/config/resolveRuntimeRedis.d.ts +11 -0
- package/dist/config/resolveRuntimeRedis.d.ts.map +1 -0
- package/dist/context/RequestContext.d.ts +28 -0
- package/dist/context/RequestContext.d.ts.map +1 -0
- package/dist/context/createServerRequestContext.d.ts +42 -0
- package/dist/context/createServerRequestContext.d.ts.map +1 -0
- package/dist/createCacheInspectorMiddleware-B32Suct_.js +105 -0
- package/dist/createCacheInspectorMiddleware-B32Suct_.js.map +1 -0
- package/dist/createCacheInspectorMiddleware-CAzxgGNh.cjs +105 -0
- package/dist/createCacheInspectorMiddleware-CAzxgGNh.cjs.map +1 -0
- package/dist/createISRApp-Bvs5_63N.cjs +7663 -0
- package/dist/createISRApp-Bvs5_63N.cjs.map +1 -0
- package/dist/createISRApp-CfGFTcw-.js +7322 -0
- package/dist/createISRApp-CfGFTcw-.js.map +1 -0
- package/dist/createImagePlugin-BHVUkFBd.js +416 -0
- package/dist/createImagePlugin-BHVUkFBd.js.map +1 -0
- package/dist/createImagePlugin-C-hHZCqj.cjs +435 -0
- package/dist/createImagePlugin-C-hHZCqj.cjs.map +1 -0
- package/dist/defaults/auto-observability.cjs +147 -0
- package/dist/defaults/auto-observability.cjs.map +1 -0
- package/dist/defaults/auto-observability.d.ts +21 -0
- package/dist/defaults/auto-observability.d.ts.map +1 -0
- package/dist/defaults/auto-observability.js +144 -0
- package/dist/defaults/auto-observability.js.map +1 -0
- package/dist/defaults/runtime/browserObservability.d.ts +73 -0
- package/dist/defaults/runtime/browserObservability.d.ts.map +1 -0
- package/dist/defaults/runtime/client-navigation-policy.d.ts +10 -0
- package/dist/defaults/runtime/client-navigation-policy.d.ts.map +1 -0
- package/dist/defaults/runtime/createCachedFetcher.d.ts +17 -0
- package/dist/defaults/runtime/createCachedFetcher.d.ts.map +1 -0
- package/dist/defaults/runtime/defineSiteHooks.cjs +11 -0
- package/dist/defaults/runtime/defineSiteHooks.d.ts +197 -0
- package/dist/defaults/runtime/defineSiteHooks.d.ts.map +1 -0
- package/dist/defaults/runtime/defineSiteHooks.js +3 -0
- package/dist/defaults/runtime/dev-css-handoff.client.d.ts +2 -0
- package/dist/defaults/runtime/dev-css-handoff.client.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-render-inspector.d.ts +57 -0
- package/dist/defaults/runtime/dev-render-inspector.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-rsc-response.client.d.ts +7 -0
- package/dist/defaults/runtime/dev-rsc-response.client.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-commit-boundary.client.d.ts +9 -0
- package/dist/defaults/runtime/dev-style-commit-boundary.client.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-declarations.server.d.ts +15 -0
- package/dist/defaults/runtime/dev-style-declarations.server.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-id.d.ts +9 -0
- package/dist/defaults/runtime/dev-style-id.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-navigation.client.d.ts +26 -0
- package/dist/defaults/runtime/dev-style-navigation.client.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-registry.client.d.ts +19 -0
- package/dist/defaults/runtime/dev-style-registry.client.d.ts.map +1 -0
- package/dist/defaults/runtime/dev-style-resource-dispatcher.server.d.ts +4 -0
- package/dist/defaults/runtime/dev-style-resource-dispatcher.server.d.ts.map +1 -0
- package/dist/defaults/runtime/empty-routes.d.ts +3 -0
- package/dist/defaults/runtime/empty-routes.d.ts.map +1 -0
- package/dist/defaults/runtime/error-boundary.d.ts +9 -0
- package/dist/defaults/runtime/error-boundary.d.ts.map +1 -0
- package/dist/defaults/runtime/error500-template.d.ts +21 -0
- package/dist/defaults/runtime/error500-template.d.ts.map +1 -0
- package/dist/defaults/runtime/head-extras-runtime.d.ts +17 -0
- package/dist/defaults/runtime/head-extras-runtime.d.ts.map +1 -0
- package/dist/defaults/runtime/hydration-shell.d.ts +12 -0
- package/dist/defaults/runtime/hydration-shell.d.ts.map +1 -0
- package/dist/defaults/runtime/i18n-server.d.ts +7 -0
- package/dist/defaults/runtime/i18n-server.d.ts.map +1 -0
- package/dist/defaults/runtime/navigation-history.client.d.ts +16 -0
- package/dist/defaults/runtime/navigation-history.client.d.ts.map +1 -0
- package/dist/defaults/runtime/navigation-request.client.d.ts +5 -0
- package/dist/defaults/runtime/navigation-request.client.d.ts.map +1 -0
- package/dist/defaults/runtime/seo-runtime.d.ts +41 -0
- package/dist/defaults/runtime/seo-runtime.d.ts.map +1 -0
- package/dist/defineSiteHooks-BeVy-qPH.js +720 -0
- package/dist/defineSiteHooks-BeVy-qPH.js.map +1 -0
- package/dist/defineSiteHooks-C3v3WLS8.cjs +755 -0
- package/dist/defineSiteHooks-C3v3WLS8.cjs.map +1 -0
- package/dist/discovery/componentDiscovery.d.ts +71 -0
- package/dist/discovery/componentDiscovery.d.ts.map +1 -0
- package/dist/discovery/directiveParser.d.ts +197 -0
- package/dist/discovery/directiveParser.d.ts.map +1 -0
- package/dist/discovery/exportParser.d.ts +45 -0
- package/dist/discovery/exportParser.d.ts.map +1 -0
- package/dist/discovery/fileSystem.d.ts +33 -0
- package/dist/discovery/fileSystem.d.ts.map +1 -0
- package/dist/discovery/index.d.ts +18 -0
- package/dist/discovery/index.d.ts.map +1 -0
- package/dist/discovery/routeDiscovery.d.ts +121 -0
- package/dist/discovery/routeDiscovery.d.ts.map +1 -0
- package/dist/discovery/scan.d.ts +54 -0
- package/dist/discovery/scan.d.ts.map +1 -0
- package/dist/discovery/types.d.ts +61 -0
- package/dist/discovery/types.d.ts.map +1 -0
- package/dist/engine/ISREngine.d.ts +54 -0
- package/dist/engine/ISREngine.d.ts.map +1 -0
- package/dist/engine/RenderMode.d.ts +23 -0
- package/dist/engine/RenderMode.d.ts.map +1 -0
- package/dist/engine/i18n/types.d.ts +6 -0
- package/dist/engine/i18n/types.d.ts.map +1 -0
- package/dist/engine/seo/PageSeoMeta.d.ts +9 -0
- package/dist/engine/seo/PageSeoMeta.d.ts.map +1 -0
- package/dist/engine/seo/SEOEngine.d.ts +61 -0
- package/dist/engine/seo/SEOEngine.d.ts.map +1 -0
- package/dist/engine/seo/config.d.ts +9 -0
- package/dist/engine/seo/config.d.ts.map +1 -0
- package/dist/engine/seo/index.d.ts +10 -0
- package/dist/engine/seo/index.d.ts.map +1 -0
- package/dist/engine/seo/injectSeoMeta.d.ts +5 -0
- package/dist/engine/seo/injectSeoMeta.d.ts.map +1 -0
- package/dist/engine/seo/resolveSeoConfig.d.ts +15 -0
- package/dist/engine/seo/resolveSeoConfig.d.ts.map +1 -0
- package/dist/engine/seo/types.d.ts +75 -0
- package/dist/engine/seo/types.d.ts.map +1 -0
- package/dist/error500-template-BvZmvKoa.cjs +63 -0
- package/dist/error500-template-BvZmvKoa.cjs.map +1 -0
- package/dist/error500-template-DhaZzLOB.js +63 -0
- package/dist/error500-template-DhaZzLOB.js.map +1 -0
- package/dist/experiments/ExposureQueue.d.ts +54 -0
- package/dist/experiments/ExposureQueue.d.ts.map +1 -0
- package/dist/experiments/ManifestLoader.d.ts +57 -0
- package/dist/experiments/ManifestLoader.d.ts.map +1 -0
- package/dist/i18n-CyJIoYJT.cjs +244 -0
- package/dist/i18n-CyJIoYJT.cjs.map +1 -0
- package/dist/i18n-Dobe0Wxn.js +191 -0
- package/dist/i18n-Dobe0Wxn.js.map +1 -0
- package/dist/image/index.cjs +93 -0
- package/dist/image/index.cjs.map +1 -0
- package/dist/image/index.js +67 -0
- package/dist/image/index.js.map +1 -0
- package/dist/index.d.ts +59 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/isr/ISRRoutes.d.ts +25 -0
- package/dist/isr/ISRRoutes.d.ts.map +1 -0
- package/dist/isr-engine.cjs +2830 -0
- package/dist/isr-engine.cjs.map +1 -0
- package/dist/isr-engine.js +2740 -0
- package/dist/isr-engine.js.map +1 -0
- package/dist/logger/Logger.d.ts +33 -0
- package/dist/logger/Logger.d.ts.map +1 -0
- package/dist/logger/index.d.ts +3 -0
- package/dist/logger/index.d.ts.map +1 -0
- package/dist/manifest/ManifestLoader.d.ts +98 -0
- package/dist/manifest/ManifestLoader.d.ts.map +1 -0
- package/dist/manifest/index.d.ts +8 -0
- package/dist/manifest/index.d.ts.map +1 -0
- package/dist/manifest/types.d.ts +76 -0
- package/dist/manifest/types.d.ts.map +1 -0
- package/dist/metrics/MetricsCollector.d.ts +90 -0
- package/dist/metrics/MetricsCollector.d.ts.map +1 -0
- package/dist/metrics/PromMetrics.d.ts +59 -0
- package/dist/metrics/PromMetrics.d.ts.map +1 -0
- package/dist/metrics/index.d.ts +7 -0
- package/dist/metrics/index.d.ts.map +1 -0
- package/dist/middlewares/ABVariantMiddleware.d.ts +74 -0
- package/dist/middlewares/ABVariantMiddleware.d.ts.map +1 -0
- package/dist/middlewares/LocaleRedirect.d.ts +27 -0
- package/dist/middlewares/LocaleRedirect.d.ts.map +1 -0
- package/dist/middlewares/MiddlewareComposer.d.ts +20 -0
- package/dist/middlewares/MiddlewareComposer.d.ts.map +1 -0
- package/dist/middlewares/PerformanceMiddleware.d.ts +14 -0
- package/dist/middlewares/PerformanceMiddleware.d.ts.map +1 -0
- package/dist/middlewares/TraceMiddleware.d.ts +24 -0
- package/dist/middlewares/TraceMiddleware.d.ts.map +1 -0
- package/dist/middlewares/abVariantContext.d.ts +7 -0
- package/dist/middlewares/abVariantContext.d.ts.map +1 -0
- package/dist/middlewares/index.d.ts +5 -0
- package/dist/middlewares/index.d.ts.map +1 -0
- package/dist/middlewares/types.d.ts +4 -0
- package/dist/middlewares/types.d.ts.map +1 -0
- package/dist/plugin/clientObservabilityConfig.d.ts +16 -0
- package/dist/plugin/clientObservabilityConfig.d.ts.map +1 -0
- package/dist/plugin/coherentCacheStore.d.ts +11 -0
- package/dist/plugin/coherentCacheStore.d.ts.map +1 -0
- package/dist/plugin/createAutomaticImagePlugin.d.ts +4 -0
- package/dist/plugin/createAutomaticImagePlugin.d.ts.map +1 -0
- package/dist/plugin/createCacheInspectorMiddleware.d.ts +16 -0
- package/dist/plugin/createCacheInspectorMiddleware.d.ts.map +1 -0
- package/dist/plugin/createDevCssHandoffPlugin.d.ts +25 -0
- package/dist/plugin/createDevCssHandoffPlugin.d.ts.map +1 -0
- package/dist/plugin/createFontPlugin.d.ts +15 -0
- package/dist/plugin/createFontPlugin.d.ts.map +1 -0
- package/dist/plugin/createImagePlugin.d.ts +46 -0
- package/dist/plugin/createImagePlugin.d.ts.map +1 -0
- package/dist/plugin/createIsrPlugin.d.ts +43 -0
- package/dist/plugin/createIsrPlugin.d.ts.map +1 -0
- package/dist/plugin/createSsgPostBuildPlugin.d.ts +4 -0
- package/dist/plugin/createSsgPostBuildPlugin.d.ts.map +1 -0
- package/dist/plugin/devAssetRequestMiddleware.d.ts +10 -0
- package/dist/plugin/devAssetRequestMiddleware.d.ts.map +1 -0
- package/dist/plugin/index.d.ts +11 -0
- package/dist/plugin/index.d.ts.map +1 -0
- package/dist/plugin/isrCacheMiddleware.d.ts +223 -0
- package/dist/plugin/isrCacheMiddleware.d.ts.map +1 -0
- package/dist/plugin/isrCacheStore.d.ts +88 -0
- package/dist/plugin/isrCacheStore.d.ts.map +1 -0
- package/dist/plugin/remoteImageSource.d.ts +19 -0
- package/dist/plugin/remoteImageSource.d.ts.map +1 -0
- package/dist/plugin/transformDevCssModule.d.ts +3 -0
- package/dist/plugin/transformDevCssModule.d.ts.map +1 -0
- package/dist/renderer/RenderHeaders.d.ts +28 -0
- package/dist/renderer/RenderHeaders.d.ts.map +1 -0
- package/dist/rolldown-runtime-D7D4PA-g.js +13 -0
- package/dist/rolldown-runtime-DakpK96I.cjs +43 -0
- package/dist/route/RouteManager.d.ts +22 -0
- package/dist/route/RouteManager.d.ts.map +1 -0
- package/dist/route/index.d.ts +2 -0
- package/dist/route/index.d.ts.map +1 -0
- package/dist/rsc/ServerActions.d.ts +65 -0
- package/dist/rsc/ServerActions.d.ts.map +1 -0
- package/dist/rsc/browser.cjs +109 -0
- package/dist/rsc/browser.cjs.map +1 -0
- package/dist/rsc/browser.d.ts +59 -0
- package/dist/rsc/browser.d.ts.map +1 -0
- package/dist/rsc/browser.js +85 -0
- package/dist/rsc/browser.js.map +1 -0
- package/dist/rsc/cacheTag.d.ts +52 -0
- package/dist/rsc/cacheTag.d.ts.map +1 -0
- package/dist/rsc/constants.d.ts +10 -0
- package/dist/rsc/constants.d.ts.map +1 -0
- package/dist/rsc/i18n.d.ts +3 -0
- package/dist/rsc/i18n.d.ts.map +1 -0
- package/dist/rsc/index.cjs +33 -0
- package/dist/rsc/index.d.ts +20 -0
- package/dist/rsc/index.d.ts.map +1 -0
- package/dist/rsc/index.js +4 -0
- package/dist/rsc/revalidate.d.ts +77 -0
- package/dist/rsc/revalidate.d.ts.map +1 -0
- package/dist/rsc-H7D_meHu.cjs +239 -0
- package/dist/rsc-H7D_meHu.cjs.map +1 -0
- package/dist/rsc-lvWPTuVD.js +168 -0
- package/dist/rsc-lvWPTuVD.js.map +1 -0
- package/dist/runtime/Image.d.ts +48 -0
- package/dist/runtime/Image.d.ts.map +1 -0
- package/dist/runtime/LocaleContext.d.ts +14 -0
- package/dist/runtime/LocaleContext.d.ts.map +1 -0
- package/dist/runtime/boundary.d.ts +27 -0
- package/dist/runtime/boundary.d.ts.map +1 -0
- package/dist/runtime/edge-context.d.ts +17 -0
- package/dist/runtime/edge-context.d.ts.map +1 -0
- package/dist/runtime/i18n-store.d.ts +11 -0
- package/dist/runtime/i18n-store.d.ts.map +1 -0
- package/dist/runtime/i18n.d.ts +115 -0
- package/dist/runtime/i18n.d.ts.map +1 -0
- package/dist/runtime/index.d.ts +16 -0
- package/dist/runtime/index.d.ts.map +1 -0
- package/dist/runtime/routes.d.ts +88 -0
- package/dist/runtime/routes.d.ts.map +1 -0
- package/dist/runtime/telemetry.d.ts +48 -0
- package/dist/runtime/telemetry.d.ts.map +1 -0
- package/dist/security/cspNonceTemplate.d.ts +10 -0
- package/dist/security/cspNonceTemplate.d.ts.map +1 -0
- package/dist/security/staticCspManifest.d.ts +37 -0
- package/dist/security/staticCspManifest.d.ts.map +1 -0
- package/dist/server/httpServer.d.ts +17 -0
- package/dist/server/httpServer.d.ts.map +1 -0
- package/dist/server/index.d.ts +3 -0
- package/dist/server/index.d.ts.map +1 -0
- package/dist/server/manager.d.ts +17 -0
- package/dist/server/manager.d.ts.map +1 -0
- package/dist/server/middleware.d.ts +87 -0
- package/dist/server/middleware.d.ts.map +1 -0
- package/dist/server/opsConfig.d.ts +17 -0
- package/dist/server/opsConfig.d.ts.map +1 -0
- package/dist/server/productionRuntime.d.ts +41 -0
- package/dist/server/productionRuntime.d.ts.map +1 -0
- package/dist/server/types.d.ts +41 -0
- package/dist/server/types.d.ts.map +1 -0
- package/dist/server/viteDevServer.d.ts +21 -0
- package/dist/server/viteDevServer.d.ts.map +1 -0
- package/dist/ssg/spider.d.ts +142 -0
- package/dist/ssg/spider.d.ts.map +1 -0
- package/dist/types/IFlightData.d.ts +23 -0
- package/dist/types/IFlightData.d.ts.map +1 -0
- package/dist/types/IHelmetData.d.ts +24 -0
- package/dist/types/IHelmetData.d.ts.map +1 -0
- package/dist/types/IRenderMetadata.d.ts +46 -0
- package/dist/types/IRenderMetadata.d.ts.map +1 -0
- package/dist/types/IRenderResult.d.ts +16 -0
- package/dist/types/IRenderResult.d.ts.map +1 -0
- package/dist/types/ISRConfig.d.ts +463 -0
- package/dist/types/ISRConfig.d.ts.map +1 -0
- package/dist/types/ISRContext.d.ts +104 -0
- package/dist/types/ISRContext.d.ts.map +1 -0
- package/dist/types/index.d.ts +7 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/utils/CacheCleanup.d.ts +32 -0
- package/dist/utils/CacheCleanup.d.ts.map +1 -0
- package/dist/utils/cacheDuration.d.ts +12 -0
- package/dist/utils/cacheDuration.d.ts.map +1 -0
- package/dist/utils/cookie.d.ts +7 -0
- package/dist/utils/cookie.d.ts.map +1 -0
- package/dist/utils/hash.d.ts +22 -0
- package/dist/utils/hash.d.ts.map +1 -0
- package/dist/utils/htmlPathname.d.ts +12 -0
- package/dist/utils/htmlPathname.d.ts.map +1 -0
- package/dist/utils/index.d.ts +9 -0
- package/dist/utils/index.d.ts.map +1 -0
- package/dist/utils/resolveFetchHandler.d.ts +4 -0
- package/dist/utils/resolveFetchHandler.d.ts.map +1 -0
- package/dist/utils/trimTrailingSlashes.d.ts +3 -0
- package/dist/utils/trimTrailingSlashes.d.ts.map +1 -0
- package/package.json +200 -4
- package/src/context/RequestContext.ts +68 -0
- package/src/context/createServerRequestContext.ts +104 -0
- package/src/defaults/auto-observability.ts +195 -0
- package/src/defaults/entry.server.ssr.tsx +257 -0
- package/src/defaults/entry.server.tsx +117 -0
- package/src/defaults/entry.tsx +23 -0
- package/src/defaults/runtime/browserObservability.ts +839 -0
- package/src/defaults/runtime/client-navigation-policy.ts +67 -0
- package/src/defaults/runtime/createCachedFetcher.ts +121 -0
- package/src/defaults/runtime/defineClientEntry.tsx +773 -0
- package/src/defaults/runtime/defineServerEntry.tsx +421 -0
- package/src/defaults/runtime/defineSiteHooks.ts +1073 -0
- package/src/defaults/runtime/dev-css-handoff.client.ts +5 -0
- package/src/defaults/runtime/dev-render-inspector.ts +597 -0
- package/src/defaults/runtime/dev-rsc-response.client.ts +48 -0
- package/src/defaults/runtime/dev-style-commit-boundary.client.tsx +20 -0
- package/src/defaults/runtime/dev-style-declarations.server.ts +158 -0
- package/src/defaults/runtime/dev-style-id.ts +91 -0
- package/src/defaults/runtime/dev-style-navigation.client.ts +152 -0
- package/src/defaults/runtime/dev-style-registry.client.ts +744 -0
- package/src/defaults/runtime/dev-style-resource-dispatcher.server.ts +42 -0
- package/src/defaults/runtime/empty-config.ts +5 -0
- package/src/defaults/runtime/empty-routes.ts +2 -0
- package/src/defaults/runtime/error-boundary.style.css +35 -0
- package/src/defaults/runtime/error-boundary.tsx +65 -0
- package/src/defaults/runtime/error500-template.ts +66 -0
- package/src/defaults/runtime/head-extras-runtime.ts +64 -0
- package/src/defaults/runtime/hydration-shell.tsx +20 -0
- package/src/defaults/runtime/i18n-server.ts +27 -0
- package/src/defaults/runtime/navigation-history.client.ts +80 -0
- package/src/defaults/runtime/navigation-request.client.ts +21 -0
- package/src/defaults/runtime/request.tsx +100 -0
- package/src/defaults/runtime/seo-runtime.ts +257 -0
- package/src/defaults/tsconfig.json +10 -0
- package/src/defaults/types.d.ts +23 -0
- package/src/runtime/Image.tsx +124 -0
- package/src/runtime/LocaleContext.tsx +38 -0
- package/src/runtime/boundary.module.css +46 -0
- package/src/runtime/boundary.tsx +136 -0
- package/src/runtime/edge-context.ts +32 -0
- package/src/runtime/i18n-store.ts +76 -0
- package/src/runtime/i18n.ts +189 -0
- package/src/runtime/index.ts +61 -0
- package/src/runtime/routes.tsx +247 -0
- package/src/runtime/scss.d.ts +13 -0
- package/src/runtime/telemetry.ts +116 -0
- package/src/types/IFlightData.ts +27 -0
- package/src/types/IHelmetData.ts +9 -0
- package/src/types/IRenderMetadata.ts +52 -0
- package/src/types/IRenderResult.ts +16 -0
- package/src/types/ISRConfig.ts +512 -0
- package/src/types/ISRContext.ts +106 -0
- package/src/types/index.ts +6 -0
- package/src/utils/CacheCleanup.ts +74 -0
- package/src/utils/cacheDuration.ts +37 -0
- package/src/utils/cookie.ts +59 -0
- package/src/utils/hash.ts +32 -0
- package/src/utils/htmlPathname.ts +75 -0
- package/src/utils/index.ts +9 -0
- package/src/utils/resolveFetchHandler.ts +19 -0
- package/src/utils/trimTrailingSlashes.ts +6 -0
package/README.md
CHANGED
|
@@ -1,3 +1,695 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @novel-isr/engine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Vite + React 19 RSC 的 ISR / SSG / Fallback 编排层。基于 [@vitejs/plugin-rsc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc) 官方插件——**不手写 Flight 协议**。业务只维护一个 `routes` 路由源、一个 `App` 壳和可选的 `SiteHooks` 配置,其余 SSR / ISR / SSG / CSR recovery 协议细节全部由 engine 收口。
|
|
4
|
+
|
|
5
|
+
[](https://vitejs.dev/) [](https://react.dev/) [](https://expressjs.com/) [](https://nodejs.org/) [](./CHANGELOG.md)
|
|
6
|
+
|
|
7
|
+
> **v2.6.2(2026-08-25)** —— Vite dev 首屏 stylesheet 资源身份根治:RSC 输出的
|
|
8
|
+
> SSR 样式统一使用 CSS-only `?direct` URL,与 CSS module 的 JavaScript URL 完全分离,
|
|
9
|
+
> 浏览器首次绘制不再依赖请求头协商或 hydration 注入。业务无需任何样式引导逻辑。
|
|
10
|
+
> 详见 [CHANGELOG.md](./CHANGELOG.md#262---2026-08-25)。
|
|
11
|
+
|
|
12
|
+
> **通用框架,与业务无关**。任何 Vite + React 19 + RSC 站点都可以接。
|
|
13
|
+
> 包名前缀 `@novel-isr` 仅是首发项目代号,与小说业务**无任何耦合**——
|
|
14
|
+
> grep 全仓源码无业务硬编码,运行时无业务假设。发到 GitHub Packages
|
|
15
|
+
> (restricted),不发 public registry;项目仍处于 **alpha** 阶段(详见末尾「生产可用性诚实评估」)。
|
|
16
|
+
|
|
17
|
+
## 30 秒看明白
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# engine + 必需的 peer 依赖(react-server-dom-webpack / rsc-html-stream 给 RSC 流水线用,
|
|
21
|
+
# 严格 pnpm 模式下必须显式装)
|
|
22
|
+
pnpm add @novel-isr/engine@^2.6.2 \
|
|
23
|
+
react@19.3.0-canary-bd6ea412-20260824 \
|
|
24
|
+
react-dom@19.3.0-canary-bd6ea412-20260824 \
|
|
25
|
+
react-server-dom-webpack@19.3.0-canary-bd6ea412-20260824 \
|
|
26
|
+
rsc-html-stream
|
|
27
|
+
pnpm add -D vite typescript @types/react @types/react-dom
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
> ⚠️ **NODE_ENV 禁忌:绝不写 `.env` 文件。** Vite 8 会读 `.env` 锁住 `VITE_USER_NODE_ENV`,让 `vite build` 即使 production 模式也回退 development,esbuild 用 `jsxDev: true` → React 19 `react-server.production.js` 的 `jsxDEV` 是 `void 0` → **SSG 全部预渲染崩**(`TypeError: jsxDEV is not a function`)。NODE_ENV 由 K8s ConfigMap / Docker `ENV` / `pnpm start` 前缀显式注入,详见 [docs/deployment.md](./docs/deployment.md#-node_env-禁忌绝不写-env-文件)。
|
|
31
|
+
|
|
32
|
+
生产推荐接入(含单 routes、API i18n 与 SEO 下发):
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// vite.config.ts
|
|
36
|
+
import { defineConfig } from 'vite';
|
|
37
|
+
import { createIsrPlugin } from '@novel-isr/engine';
|
|
38
|
+
export default defineConfig({ plugins: [...createIsrPlugin()] });
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```jsonc
|
|
42
|
+
// package.json
|
|
43
|
+
{
|
|
44
|
+
"scripts": {
|
|
45
|
+
"dev": "novel-isr dev",
|
|
46
|
+
"build": "vite build",
|
|
47
|
+
"start": "novel-isr start"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
// src/routes.tsx —— 业务唯一路由源;SSR/ISR/SSG/CSR recovery 都复用这一份
|
|
54
|
+
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
55
|
+
|
|
56
|
+
export const { routes } = defineRoutes({
|
|
57
|
+
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
58
|
+
routes: [
|
|
59
|
+
{ path: '/', load: () => import('./pages/HomePage') },
|
|
60
|
+
{ path: '/books/:id', load: () => import('./pages/BookDetailPage') },
|
|
61
|
+
{ path: '/about', load: () => import('./pages/AboutPage') },
|
|
62
|
+
],
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
// src/app.tsx —— App 只负责站点壳和调用 routes;不用 i18n 时可直接传 url.pathname
|
|
68
|
+
import { parseLocale, resolveI18nConfig } from '@novel-isr/engine/runtime';
|
|
69
|
+
import siteHooks from './entry.server';
|
|
70
|
+
import { routes } from './routes';
|
|
71
|
+
|
|
72
|
+
const I18N = resolveI18nConfig(siteHooks.intl);
|
|
73
|
+
|
|
74
|
+
export function App({ url }: { url: URL }) {
|
|
75
|
+
const { locale, pathname } = parseLocale(url.pathname, I18N);
|
|
76
|
+
return (
|
|
77
|
+
<html lang={locale}>
|
|
78
|
+
<body>{routes({ pathname, searchParams: url.searchParams })}</body>
|
|
79
|
+
</html>
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
// ssr.config.ts —— 启动期 / 部署期 / 平台级配置
|
|
86
|
+
import { defineIsrConfig } from '@novel-isr/engine/config';
|
|
87
|
+
import fallbackLocal from './src/config/site-fallback-local.json';
|
|
88
|
+
|
|
89
|
+
export default defineIsrConfig({
|
|
90
|
+
renderMode: 'isr',
|
|
91
|
+
runtime: {
|
|
92
|
+
site: process.env.SITE_URL ?? 'http://localhost:3000',
|
|
93
|
+
services: {
|
|
94
|
+
api: process.env.API_URL ?? 'http://localhost:8080',
|
|
95
|
+
telemetry: process.env.TELEMETRY_API_URL ?? process.env.API_URL ?? 'http://localhost:8080',
|
|
96
|
+
},
|
|
97
|
+
redis: {
|
|
98
|
+
url: process.env.REDIS_URL,
|
|
99
|
+
host: undefined,
|
|
100
|
+
port: undefined,
|
|
101
|
+
password: undefined,
|
|
102
|
+
keyPrefix: 'isr:',
|
|
103
|
+
invalidationChannel: 'isr:invalidate',
|
|
104
|
+
},
|
|
105
|
+
telemetry: {
|
|
106
|
+
app: 'novel-rating',
|
|
107
|
+
release: process.env.APP_VERSION,
|
|
108
|
+
environment: process.env.NODE_ENV,
|
|
109
|
+
includeQueryString: false,
|
|
110
|
+
events: {
|
|
111
|
+
endpoint: '/api/observability/analytics',
|
|
112
|
+
trackInitialPage: true,
|
|
113
|
+
sampleRate: 1,
|
|
114
|
+
batchSize: 20,
|
|
115
|
+
flushIntervalMs: 3000,
|
|
116
|
+
maxQueueSize: 500,
|
|
117
|
+
retryBaseDelayMs: 1000,
|
|
118
|
+
retryMaxDelayMs: 30000,
|
|
119
|
+
},
|
|
120
|
+
errors: {
|
|
121
|
+
endpoint: '/api/observability/errors',
|
|
122
|
+
captureResourceErrors: true,
|
|
123
|
+
sampleRate: 1,
|
|
124
|
+
batchSize: 10,
|
|
125
|
+
flushIntervalMs: 3000,
|
|
126
|
+
maxQueueSize: 200,
|
|
127
|
+
retryBaseDelayMs: 1000,
|
|
128
|
+
retryMaxDelayMs: 30000,
|
|
129
|
+
},
|
|
130
|
+
webVitals: { enabled: true },
|
|
131
|
+
exporters: [],
|
|
132
|
+
integrations: {
|
|
133
|
+
sentry: {
|
|
134
|
+
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
135
|
+
dsn: process.env.SENTRY_DSN,
|
|
136
|
+
tracesSampleRate: 0.1,
|
|
137
|
+
environment: process.env.NODE_ENV,
|
|
138
|
+
release: process.env.APP_VERSION,
|
|
139
|
+
},
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
experiments: {
|
|
143
|
+
'hero-style': { variants: ['classic', 'bold'], weights: [50, 50] },
|
|
144
|
+
},
|
|
145
|
+
i18n: {
|
|
146
|
+
locales: fallbackLocal.site.locales,
|
|
147
|
+
defaultLocale: fallbackLocal.site.defaultLocale,
|
|
148
|
+
prefixDefault: false,
|
|
149
|
+
endpoint: '/api/i18n/{locale}/manifest',
|
|
150
|
+
fallbackLocal: fallbackLocal.i18n.strings,
|
|
151
|
+
ttl: 60_000,
|
|
152
|
+
timeoutMs: 1200,
|
|
153
|
+
remoteSource: 'admin-server',
|
|
154
|
+
fallbackSource: 'fallback-local',
|
|
155
|
+
},
|
|
156
|
+
seo: {
|
|
157
|
+
endpoint: '/api/seo?path={pathname}',
|
|
158
|
+
fallbackLocal: fallbackLocal.seo.entries,
|
|
159
|
+
ttl: 60_000,
|
|
160
|
+
timeoutMs: 1200,
|
|
161
|
+
},
|
|
162
|
+
},
|
|
163
|
+
routes: {
|
|
164
|
+
'/': { mode: 'isr', ttl: 60, staleWhileRevalidate: 300 },
|
|
165
|
+
'/about': 'ssg',
|
|
166
|
+
'/login': 'ssr',
|
|
167
|
+
'/*': 'isr',
|
|
168
|
+
},
|
|
169
|
+
server: {
|
|
170
|
+
port: Number(process.env.PORT ?? 3000),
|
|
171
|
+
host: process.env.HOST,
|
|
172
|
+
strictPort: process.env.NODE_ENV !== 'development',
|
|
173
|
+
ops: {
|
|
174
|
+
authToken: process.env.ISR_OPS_TOKEN,
|
|
175
|
+
tokenHeader: 'x-isr-admin-token',
|
|
176
|
+
health: { enabled: true, public: true },
|
|
177
|
+
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
178
|
+
},
|
|
179
|
+
},
|
|
180
|
+
ssg: {
|
|
181
|
+
routes: ['/about'],
|
|
182
|
+
concurrent: 3,
|
|
183
|
+
requestTimeoutMs: 30_000,
|
|
184
|
+
maxRetries: 3,
|
|
185
|
+
retryBaseDelayMs: 200,
|
|
186
|
+
failBuildThreshold: 0.05,
|
|
187
|
+
},
|
|
188
|
+
revalidate: 3600,
|
|
189
|
+
});
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
// src/entry.server.ts —— 可选:只放请求期 hooks,例如用户、租户、分层、错误上报
|
|
194
|
+
import { defineAdminSiteHooks, readCookie } from '@novel-isr/engine/site-hooks';
|
|
195
|
+
|
|
196
|
+
export default defineAdminSiteHooks({
|
|
197
|
+
beforeRequest: req => ({
|
|
198
|
+
userId: req.headers.get('x-user-id') ?? readCookie(req, 'uid') ?? undefined,
|
|
199
|
+
tenantId: req.headers.get('x-tenant-id') ?? 'public',
|
|
200
|
+
}),
|
|
201
|
+
onError: (err, req, ctx) => {
|
|
202
|
+
console.error('[render error]', { traceId: ctx.traceId, url: req.url, err });
|
|
203
|
+
},
|
|
204
|
+
});
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
`beforeRequest` 返回值会进入当前请求的 `RequestContext`。Server Component 里用
|
|
208
|
+
`getRequestContext()` 读取用户、租户、分群等请求级字段;Client Component 需要由
|
|
209
|
+
Server Component 读取后作为 props 传入。A/B variant 不在 `beforeRequest` 里手写解析,
|
|
210
|
+
页面用 `getVariant()` 读取,engine 负责 sticky cookie 和 ISR variant 缓存隔离。
|
|
211
|
+
完整用法见 [docs/site-hooks.md](./docs/site-hooks.md#beforerequest--onerror)。
|
|
212
|
+
|
|
213
|
+
`pnpm dev` → http://localhost:3000。开发模式会自动注入 **Novel ISR Inspector** 浮层,
|
|
214
|
+
可直接切换/验证 ISR、SSR、SSG、CSR fallback。业务不需要 import 调试组件。
|
|
215
|
+
如需隐藏浮层,新建 `src/entry.tsx`:
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
export default {
|
|
219
|
+
devInspector: false,
|
|
220
|
+
};
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
浏览器埋点和错误上报由 engine 按 endpoint 配置注入轻量 runtime,业务不用重写导航监听或全局错误监听,
|
|
224
|
+
也不需要把第三方 SDK import 到 engine。部署期只在 `ssr.config.ts` 配 telemetry endpoint、
|
|
225
|
+
采样、批量策略和 integration:
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
// ssr.config.ts
|
|
229
|
+
export default {
|
|
230
|
+
runtime: {
|
|
231
|
+
services: {
|
|
232
|
+
api: process.env.API_URL ?? 'https://admin.example.com',
|
|
233
|
+
telemetry: process.env.TELEMETRY_API_URL ?? 'https://admin.example.com',
|
|
234
|
+
},
|
|
235
|
+
telemetry: {
|
|
236
|
+
app: 'novel-rating',
|
|
237
|
+
release: process.env.APP_VERSION,
|
|
238
|
+
environment: process.env.NODE_ENV,
|
|
239
|
+
includeQueryString: false,
|
|
240
|
+
events: {
|
|
241
|
+
endpoint: '/api/observability/analytics',
|
|
242
|
+
trackInitialPage: true,
|
|
243
|
+
sampleRate: 1,
|
|
244
|
+
batchSize: 20,
|
|
245
|
+
flushIntervalMs: 3000,
|
|
246
|
+
maxQueueSize: 500,
|
|
247
|
+
retryBaseDelayMs: 1000,
|
|
248
|
+
retryMaxDelayMs: 30000,
|
|
249
|
+
},
|
|
250
|
+
errors: {
|
|
251
|
+
endpoint: '/api/observability/errors',
|
|
252
|
+
captureResourceErrors: true,
|
|
253
|
+
sampleRate: 1,
|
|
254
|
+
batchSize: 10,
|
|
255
|
+
flushIntervalMs: 3000,
|
|
256
|
+
maxQueueSize: 200,
|
|
257
|
+
retryBaseDelayMs: 1000,
|
|
258
|
+
retryMaxDelayMs: 30000,
|
|
259
|
+
},
|
|
260
|
+
webVitals: { enabled: true },
|
|
261
|
+
exporters: [],
|
|
262
|
+
integrations: {
|
|
263
|
+
sentry: {
|
|
264
|
+
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
265
|
+
dsn: process.env.SENTRY_DSN,
|
|
266
|
+
tracesSampleRate: 0.1,
|
|
267
|
+
environment: process.env.NODE_ENV,
|
|
268
|
+
release: process.env.APP_VERSION,
|
|
269
|
+
},
|
|
270
|
+
},
|
|
271
|
+
},
|
|
272
|
+
},
|
|
273
|
+
};
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
设计边界:`isr-engine` 不 import 业务 SDK,也不绑定 Sentry/Datadog/自研采集端;
|
|
277
|
+
第一方 HTTP 链路只看 `events.endpoint` / `errors.endpoint`,不再在 exporter 里重复配置同一个地址。
|
|
278
|
+
Sentry 是
|
|
279
|
+
`runtime.telemetry.integrations.sentry` 里的完整第三方平台集成,不降级成普通 HTTP exporter;
|
|
280
|
+
它可和第一方 endpoint 同时使用,也可通过关闭 `events/errors` 做二选一。
|
|
281
|
+
engine 不做隐式替换,失败不会影响渲染或其它上报。
|
|
282
|
+
`@novel-isr/analytics` 和 `@novel-isr/error-reporting`
|
|
283
|
+
是独立 SDK,给非 engine 应用或自定义集成使用。
|
|
284
|
+
完整说明见 [docs/observability.md](./docs/observability.md)。
|
|
285
|
+
|
|
286
|
+
业务显式事件不要写 endpoint 上传逻辑,直接用 engine runtime facade:
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
import {
|
|
290
|
+
capture,
|
|
291
|
+
flushTelemetry,
|
|
292
|
+
measure,
|
|
293
|
+
page,
|
|
294
|
+
setTelemetryUser,
|
|
295
|
+
track,
|
|
296
|
+
} from '@novel-isr/engine/runtime';
|
|
297
|
+
|
|
298
|
+
setTelemetryUser({ id: userId, tenantId });
|
|
299
|
+
track('review.submit', { bookId, score }, { tags: { feature: 'reviews' } });
|
|
300
|
+
measure('search.latency', durationMs, { unit: 'ms', tags: { route: '/search' } });
|
|
301
|
+
capture(error, { source: 'rating-widget', extra: { bookId } });
|
|
302
|
+
page('/custom-router/books/1'); // 常规路由不需要,engine 会自动上报 page_view
|
|
303
|
+
await flushTelemetry();
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
这些调用复用 `runtime.telemetry.events/errors` 的同一套队列、采样、重试和 sendBeacon,不需要业务关心 transport。
|
|
307
|
+
API 语义:
|
|
308
|
+
|
|
309
|
+
- `track`:业务事件,例如收藏、评分、搜索提交。
|
|
310
|
+
- `capture`:已知业务失败或组件错误边界,补充 `source/tags/extra/fingerprint`。
|
|
311
|
+
- `measure`:一次原始数值样本,例如请求耗时、队列等待时间、交互延迟。
|
|
312
|
+
- `page`:自定义 router 的页面浏览;普通 `pushState/popstate` 由 engine 自动处理。
|
|
313
|
+
- `setTelemetryUser`:设置后续上报的 user / tenant / segment 上下文。
|
|
314
|
+
- `flushTelemetry`:登出、支付跳转、关闭前主动 flush。
|
|
315
|
+
|
|
316
|
+
`measure()` 只发送一次原始观测值;p95、趋势、慢页面排行和告警阈值应该在后端 /
|
|
317
|
+
dashboard 聚合,不在浏览器里做二级统计。
|
|
318
|
+
Web Vitals / INP 也是同一原则:浏览器只发送 `{ name, value }` 这类事实样本,
|
|
319
|
+
服务端按 route、release、device、tenant 和用户分群计算 p75/p95 与评级。
|
|
320
|
+
|
|
321
|
+
`entry.tsx` 的 hooks 仍然保留,适合补充上下文和业务语义:
|
|
322
|
+
|
|
323
|
+
```ts
|
|
324
|
+
// src/entry.tsx
|
|
325
|
+
export default {
|
|
326
|
+
devInspector: true,
|
|
327
|
+
beforeStart({ telemetry }) {
|
|
328
|
+
telemetry.setUser(readPublicUser());
|
|
329
|
+
telemetry.track('app.client_ready', { source: 'entry' });
|
|
330
|
+
},
|
|
331
|
+
onNavigate(url, { telemetry }) {
|
|
332
|
+
telemetry.track('navigation.section_enter', { path: url.pathname });
|
|
333
|
+
},
|
|
334
|
+
onActionError(error, actionId, { telemetry }) {
|
|
335
|
+
// engine 已自动错误上报;这里只补一条产品漏斗事件。
|
|
336
|
+
telemetry.track('server_action.failure_seen', {
|
|
337
|
+
actionId,
|
|
338
|
+
message: error instanceof Error ? error.message : String(error),
|
|
339
|
+
});
|
|
340
|
+
},
|
|
341
|
+
};
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
完整的「getting started」(含 i18n / SEO / Server Actions)请看 **[docs/getting-started.md](./docs/getting-started.md)**。
|
|
345
|
+
|
|
346
|
+
## 核心卖点
|
|
347
|
+
|
|
348
|
+
```
|
|
349
|
+
┌──────────────────────────────────────────────────────┐
|
|
350
|
+
│ 用户写的代码(业务) │
|
|
351
|
+
│ src/routes.tsx ← 唯一路由源 │
|
|
352
|
+
│ src/app.tsx ← App shell + routes 调用 │
|
|
353
|
+
│ src/pages/, components/ ← 业务组件 │
|
|
354
|
+
│ src/actions/ ← Server Actions │
|
|
355
|
+
│ src/entry.server.tsx ← (可选) 请求期 hooks │
|
|
356
|
+
│ ssr.config.ts ← (可选) 路由级渲染模式 │
|
|
357
|
+
└──────────────────────┬───────────────────────────────┘
|
|
358
|
+
│
|
|
359
|
+
┌──────────────────────▼───────────────────────────────┐
|
|
360
|
+
│ Engine(默认提供,零配置) │
|
|
361
|
+
│ • RSC fetch handler(@vitejs/plugin-rsc) │
|
|
362
|
+
│ • SSR HTML 转换(react-dom/server.edge) │
|
|
363
|
+
│ • 浏览器水合 / 客户端导航 / Server Action 调用 │
|
|
364
|
+
│ • ISR 缓存(LRU + SWR + 标签失效) │
|
|
365
|
+
│ • SSG spider(构建期预生成) │
|
|
366
|
+
│ • SEO sitemap / robots / OG image │
|
|
367
|
+
│ • page-level SEO + API SEO 下发 │
|
|
368
|
+
│ • i18n URL 路由 + 字典缓存 + getI18n() │
|
|
369
|
+
│ • A/B testing │
|
|
370
|
+
│ • csr-shell fallback(server 崩溃自救) │
|
|
371
|
+
│ • dev render inspector(开发态渲染模式浮层) │
|
|
372
|
+
│ • browser analytics / error-reporting 生命周期桥接 │
|
|
373
|
+
│ • Sentry / Datadog / OTel adapter(一行接入) │
|
|
374
|
+
│ • Image / Font 优化插件(next-style) │
|
|
375
|
+
└──────────────────────────────────────────────────────┘
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
**真正甩开 Next.js 的优势**:
|
|
379
|
+
- Vite 8 dev HMR(不是 Webpack/Turbopack)
|
|
380
|
+
- 单 Express 进程,可 hack 中间件链
|
|
381
|
+
- SEO 在 page export + runtime.seo 下发层分层收口,不散落到组件渲染树
|
|
382
|
+
- L1+L2 hybrid cache(进程内 LRU + 可选 Redis 写穿)
|
|
383
|
+
- A/B 变体内建
|
|
384
|
+
- 显式 `RenderModeType = 'ssg' | 'isr' | 'ssr'`,不靠隐式 segment config
|
|
385
|
+
|
|
386
|
+
## 性能 benchmark
|
|
387
|
+
|
|
388
|
+
baseline:[`bench/baseline.json`](./bench/baseline.json) —— 由 [`bench/app/`](./bench/app/)
|
|
389
|
+
(self-contained 最小 ISR 应用)跑出。bench 结果会写入 `bench_protocol` 与
|
|
390
|
+
`runner_id`,只有协议、并发档、时长、Node major 和 runner class 一致时才做
|
|
391
|
+
raw QPS/P95 退化比较;否则只做当前结果健康检查并提示重新播种 baseline。
|
|
392
|
+
|
|
393
|
+
当前基线协议:Node 22 · 单进程 · 3s warmup · 8s/tier · 2s cooldown ·
|
|
394
|
+
tiers 10/100/1000。
|
|
395
|
+
|
|
396
|
+
复现:`cd bench/app && pnpm run build && pnpm start`,
|
|
397
|
+
另一终端跑 `BENCH_TIERS=10,100,1000 BENCH_DURATION=8 pnpm bench`。bench 退化
|
|
398
|
+
追踪走 [`.github/workflows/bench.yml`](./.github/workflows/bench.yml)。GitHub hosted
|
|
399
|
+
runner 跨次硬件不一致时必须重新播种同一 runner class 的 baseline,不能把本地
|
|
400
|
+
Mac/PC 结果直接拿去 gate CI。详细:[docs/performance.md](./docs/performance.md)。
|
|
401
|
+
|
|
402
|
+
## 文档
|
|
403
|
+
|
|
404
|
+
按主题查:
|
|
405
|
+
|
|
406
|
+
| 主题 | 文档 |
|
|
407
|
+
|---|---|
|
|
408
|
+
| 从零搭一个站 | [getting-started.md](./docs/getting-started.md) |
|
|
409
|
+
| 渲染模式(ISR / SSR / SSG / csr-shell) | [render-modes.md](./docs/render-modes.md) |
|
|
410
|
+
| 开发态渲染检查器(Novel ISR Inspector) | [dev-inspector.md](./docs/dev-inspector.md) |
|
|
411
|
+
| 缓存与失效(cacheTag / revalidate / Redis 双层) | [caching.md](./docs/caching.md) |
|
|
412
|
+
| SiteHooks 配置(beforeRequest / i18n / SEO / A/B) | [site-hooks.md](./docs/site-hooks.md) |
|
|
413
|
+
| i18n URL 路由 + 语言协商 | [i18n.md](./docs/i18n.md) |
|
|
414
|
+
| 可观测性(Sentry / Datadog / OTel / Prometheus) | [observability.md](./docs/observability.md) |
|
|
415
|
+
| 生产部署(环境变量 / Docker / Edge runtime / Middleware) | [deployment.md](./docs/deployment.md) |
|
|
416
|
+
| 验证 RSC 是否真的隐藏 server 代码 | [rsc-testing.md](./docs/rsc-testing.md) |
|
|
417
|
+
| 排错与常见坑 | [troubleshooting.md](./docs/troubleshooting.md) |
|
|
418
|
+
| SSR/SPA 失效降级链路 | [deployment/ssr-spa-failover.md](./docs/deployment/ssr-spa-failover.md) |
|
|
419
|
+
|
|
420
|
+
## 渲染模式(一句话)
|
|
421
|
+
|
|
422
|
+
| 模式 | 行为 | 用户级可选 |
|
|
423
|
+
|---|---|---|
|
|
424
|
+
| **isr** | 显式 TTL,过期 SWR 回放 + 后台重渲。命中即入缓存。 | ✅ |
|
|
425
|
+
| **ssr** | 永不入缓存,每次跑完整 RSC + SSR 管线。 | ✅ |
|
|
426
|
+
| **ssg** | 构建期 spider 预生成磁盘 HTML,运行期 TTL × 24。 | ✅ |
|
|
427
|
+
| `csr-shell` | server 崩溃时返回壳 HTML,浏览器自救拉 `_.rsc`。 | ❌(自动兜底) |
|
|
428
|
+
|
|
429
|
+
```
|
|
430
|
+
FallbackChain(自动降级):
|
|
431
|
+
isr → cached → regenerate → server → csr-shell
|
|
432
|
+
ssg → static → regenerate → server → csr-shell
|
|
433
|
+
ssr → server → csr-shell
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
详情:[docs/render-modes.md](./docs/render-modes.md)。
|
|
437
|
+
|
|
438
|
+
## 开发态渲染检查器
|
|
439
|
+
|
|
440
|
+
`pnpm dev` 时,engine 默认 client runtime 会自动注入右下角 **Novel ISR Inspector**。
|
|
441
|
+
它属于 engine,不属于业务 UI:
|
|
442
|
+
|
|
443
|
+
- 通过响应头读取 `x-resolved-mode`、`x-render-strategy`、`x-cache-status`、`x-fallback-used`、`content-language`、`x-i18n-source`
|
|
444
|
+
- 可以在当前 URL 上切换 `?mode=isr|ssr|ssg`,或强制 `?__csr-shell=1` 验证 CSR fallback
|
|
445
|
+
- Shadow DOM 隔离样式,不污染业务 CSS
|
|
446
|
+
- 仅 dev 显示,生产不显示
|
|
447
|
+
|
|
448
|
+
如果业务要关闭它,放到 **client entry**:
|
|
449
|
+
|
|
450
|
+
```ts
|
|
451
|
+
// src/entry.tsx
|
|
452
|
+
export default {
|
|
453
|
+
devInspector: false,
|
|
454
|
+
};
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
不要放到 `src/entry.server.tsx`。`entry.server.tsx` 是 server hooks,不能把 server-only
|
|
458
|
+
配置直接透给浏览器;需要跨端公共配置时应该走 `ssr.config.ts` 或 engine 注入的 client-safe
|
|
459
|
+
public config。详见 [docs/dev-inspector.md](./docs/dev-inspector.md)。
|
|
460
|
+
|
|
461
|
+
## Routes / SEO / i18n 标准写法
|
|
462
|
+
|
|
463
|
+
### Routes:业务只写一个源
|
|
464
|
+
|
|
465
|
+
`defineRoutes({ routes, notFound })` 是业务唯一需要维护的路由声明。不要在业务项目里再拆 `routes.ssr`、`routes.spa`、`spaModules`、`ssrModules` 或手写 loader 分支。第一性原理很简单:一条路由只应该对应一棵 RSC tree,ISR / SSR / SSG / CSR recovery 的执行策略是 engine 的职责。
|
|
466
|
+
|
|
467
|
+
```tsx
|
|
468
|
+
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
469
|
+
|
|
470
|
+
export const { routes } = defineRoutes({
|
|
471
|
+
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
472
|
+
routes: [{ path: '/', load: () => import('./pages/HomePage') }],
|
|
473
|
+
});
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
### Page SEO:页面声明默认值,API 可覆盖
|
|
477
|
+
|
|
478
|
+
页面模块可以导出静态 `seo` 或动态 `seo(ctx)` / `generateSeo(ctx)`。Engine 会在 server entry 里先加载 i18n,再解析 page SEO,因此页面 SEO 里可以直接调用 `getI18n()`。
|
|
479
|
+
|
|
480
|
+
```tsx
|
|
481
|
+
// src/pages/BookDetailPage.tsx
|
|
482
|
+
import { getI18n } from '@novel-isr/engine/runtime';
|
|
483
|
+
|
|
484
|
+
export async function seo({ params }: { params: { id: string } }) {
|
|
485
|
+
const book = await fetchBook(params.id);
|
|
486
|
+
return {
|
|
487
|
+
title: getI18n('seo.book.title', { title: book.title }),
|
|
488
|
+
description: book.summary,
|
|
489
|
+
ogType: 'book',
|
|
490
|
+
image: book.cover,
|
|
491
|
+
};
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
export default async function BookDetailPage() {
|
|
495
|
+
// ...
|
|
496
|
+
}
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
`runtime.seo` 用来接 API / CMS 下发的 SEO:`endpoint`、`ttl`、`fallbackLocal`
|
|
500
|
+
都放在 `ssr.config.ts`。`entry.server.tsx` 不承载 SEO 数据源配置,只负责本次请求的
|
|
501
|
+
用户、租户、分层和错误上报。
|
|
502
|
+
|
|
503
|
+
合并顺序:`page seo` 提供页面默认值,`SiteHooks seo` 提供远端覆盖值;最终 `<title>`、`meta`、canonical、Open Graph、JSON-LD 都由 engine 注入到 SSR HTML 的 `<head>`,业务组件里不需要手写 `<title>` / `<meta>`。
|
|
504
|
+
|
|
505
|
+
### i18n:服务端拉取一次,RSC payload 复用
|
|
506
|
+
|
|
507
|
+
商业项目推荐由 API 下发字典。`runtime.i18n` 统一声明 `locales`、`defaultLocale`、
|
|
508
|
+
`endpoint`、`ttl`、`fallbackLocal`;engine 会生成请求期 loader,页面不需要写 Provider。
|
|
509
|
+
|
|
510
|
+
业务侧统一用 `getI18n(key, params?, fallback?)`,不需要手写 Provider。
|
|
511
|
+
|
|
512
|
+
```tsx
|
|
513
|
+
import { getI18n } from '@novel-isr/engine/runtime';
|
|
514
|
+
|
|
515
|
+
getI18n('home.hero.title');
|
|
516
|
+
getI18n('book.count', { count: 12 }); // 字典里写 "共 {count} 本书"
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
变量占位符是 `{name}`,不是 `$name`。例如:
|
|
520
|
+
|
|
521
|
+
```json
|
|
522
|
+
{
|
|
523
|
+
"book": {
|
|
524
|
+
"count": "共 {count} 本书",
|
|
525
|
+
"rating": "{title} 评分 {score}"
|
|
526
|
+
}
|
|
527
|
+
}
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
性能路径:
|
|
531
|
+
- SSR / ISR / SSG:server 端按 cookie `locale` → `Accept-Language` → `defaultLocale` 协商 locale,远程字典走 TTL + SWR + 并发去重缓存;同一份 `intl` 进入 RSC payload,客户端水合不二次拉取。
|
|
532
|
+
- 客户端导航:浏览器拉 `_.rsc`,payload 带最新 `intl`,engine 自动更新 `getI18n()` 的客户端存储。
|
|
533
|
+
|
|
534
|
+
### Rate limiting / 服务端 trace:不在 engine 范畴
|
|
535
|
+
|
|
536
|
+
业界共识(Next.js / Remix / Astro / SvelteKit):渲染框架不做 rate limiting 和服务端 trace。
|
|
537
|
+
- **Rate limit** 在 CDN / WAF / API Gateway 层做:Cloudflare WAF / AWS WAF / Vercel Edge / Kong / Envoy
|
|
538
|
+
- **Trace + 错误** 走 OpenTelemetry → Honeycomb / Datadog / Sentry
|
|
539
|
+
- **业务事件埋点** 仍在 `runtime.telemetry.events`(engine 提供,跟 client 自动接入)
|
|
540
|
+
|
|
541
|
+
应用层兜底 rate-limit 真有需要的话用独立 middleware(`express-rate-limit` 等),不要进框架。
|
|
542
|
+
|
|
543
|
+
### server.strictPort:端口严格模式
|
|
544
|
+
|
|
545
|
+
`server.strictPort` 是业务可见配置:
|
|
546
|
+
|
|
547
|
+
```ts
|
|
548
|
+
server: {
|
|
549
|
+
port: Number(process.env.PORT ?? 3000),
|
|
550
|
+
host: process.env.HOST,
|
|
551
|
+
strictPort: process.env.NODE_ENV !== 'development',
|
|
552
|
+
ops: {
|
|
553
|
+
authToken: process.env.ISR_OPS_TOKEN,
|
|
554
|
+
tokenHeader: 'x-isr-admin-token',
|
|
555
|
+
health: { enabled: true, public: true },
|
|
556
|
+
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
557
|
+
},
|
|
558
|
+
}
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
- `true`:端口被占用时直接启动失败,适合生产、容器和 CI,避免服务悄悄跑到错误端口。
|
|
562
|
+
- `false`:端口被占用时最多尝试后续 20 个端口,适合本地开发。
|
|
563
|
+
- `server.strictPort` 是公开配置的一部分;生产项目应显式写出,方便审查部署行为。
|
|
564
|
+
|
|
565
|
+
## 与业界方案对比
|
|
566
|
+
|
|
567
|
+
| 能力 | Next.js App Router | Waku | RedwoodJS | **isr-engine** |
|
|
568
|
+
|---|---|---|---|---|
|
|
569
|
+
| RSC 双 entry 模型 | ✅ 自实现 | ✅ plugin-rsc | ✅ 自实现 | ✅ plugin-rsc |
|
|
570
|
+
| ISR 缓存层 | ✅ | ❌ | ⚠️ | ✅ |
|
|
571
|
+
| `revalidatePath` / `revalidateTag` | ✅ | ⚠️ 实验 | ❌ | ✅ |
|
|
572
|
+
| `cacheTag` 精准失效 | ✅ | ❌ | ❌ | ✅ |
|
|
573
|
+
| 路由级 mode 配置 | ⚠️ segment config | ❌ | ❌ | ✅ ssr.config.ts |
|
|
574
|
+
| zero-config 入口 | ⚠️ 必须用 app/ 文件夹 | ✅ | ⚠️ | ✅ routes + app.tsx |
|
|
575
|
+
| csr-shell server 崩溃兜底 | ❌ | ❌ | ❌ | ✅ |
|
|
576
|
+
| 构建栈灵活度 | ❌ 绑死自家栈 | ✅ Vite | ❌ 绑死自家栈 | ✅ Vite |
|
|
577
|
+
| 内置图片 / 字体优化 | ✅ | ❌ | ⚠️ | ✅ |
|
|
578
|
+
| Edge runtime 支持 | ✅ | ⚠️ | ❌ | ✅(CF / Vercel adapter;Deno / Bun 走原生 `{fetch}`) |
|
|
579
|
+
| 单元测试覆盖 | 数千用例 | ⚠️ | ✅ | 60 文件 / 728 tests / ~61% |
|
|
580
|
+
|
|
581
|
+
定位:**中等规模业务的 ISR / SSG / Fallback 编排层**,构建于 React 19 + `@vitejs/plugin-rsc` 官方流水线之上。
|
|
582
|
+
|
|
583
|
+
## 生产可用性诚实评估
|
|
584
|
+
|
|
585
|
+
**当前阶段:alpha** —— 单一首发项目(novel-rating)在自用,外部用户尚未 burn-in。
|
|
586
|
+
v2.1 做了 Security & Reliability 硬化,v2.2 加了 ISR 缓存层 single-flight /
|
|
587
|
+
OOM 防御 / 命名空间失效 / 边缘预热 / CPU-aware 并发 5 项工业级优化,
|
|
588
|
+
v2.3.1 收口了消费侧首跑 0 配置 + express 5 + 入口架构清理,
|
|
589
|
+
v2.5 系列补上 ISR 缓存可观测性(`X-Cache-Stale-Reason` / inventory 端点)、500 兜底页
|
|
590
|
+
和 telemetry 上传退避。但**离 1.0 stable 还差**:
|
|
591
|
+
|
|
592
|
+
✅ **稳的部分**:
|
|
593
|
+
- Flight 协议委托给官方 `@vitejs/plugin-rsc@^0.5.26`,不自维护
|
|
594
|
+
- 依赖全是工业级(Express 5 / Helmet / Prometheus / sitemap / lru-cache / ioredis)
|
|
595
|
+
- 728 tests / ~61% 行覆盖;CI 任何分支 push 都跑 lint+typecheck+test
|
|
596
|
+
- bench 退化追踪走 nightly `bench.yml`(信息性输出,不 gate release)
|
|
597
|
+
- GitHub Packages 发布有 3 段 gate(lint+test+build),任一失败 → 不发布
|
|
598
|
+
- 安全硬化覆盖了 Set-Cookie 跨用户回放、SSG 路径穿越、Redis Buffer 破损、
|
|
599
|
+
Pub/Sub 消息丢失等 10 项审计发现项
|
|
600
|
+
- 消费侧首跑 0 配置:v2.3.1 后 `vite.config.ts` 三件套真的能跑起来(详见 CHANGELOG)
|
|
601
|
+
|
|
602
|
+
⚠️ **真上生产你必须知道**:
|
|
603
|
+
- **只有首发项目在用**,未在第二个独立项目里完整 burn-in 过;社区 review 才刚开始
|
|
604
|
+
- 浏览器侧没有持续跑的 e2e(728 测试主要是 Node 侧单测),靠人工
|
|
605
|
+
smoke test。任何 React 19 / plugin-rsc / Vite 升级都需要先在 bench app 里手验
|
|
606
|
+
- Origin 协议只支持 `http1.1` / `https`;HTTP/2 / HTTP/3 应在 CDN / Nginx / Caddy / ALB 终结
|
|
607
|
+
- bench baseline 跨 GitHub hosted runner 硬件不一致(同 SHA 跑两次能飘 ±60% QPS),
|
|
608
|
+
release 不 gate bench;要做 release-blocking bench gate 需自部 self-hosted runner 锁硬件
|
|
609
|
+
- API 在 v1.0 之前可能有破坏性变更,主要风险面:路由 `defineRoutes` 形态、
|
|
610
|
+
`SiteHooks` 配置 schema、ISR cacheTag/revalidate API。会在 CHANGELOG 中
|
|
611
|
+
明确标注 `BREAKING`,但**没有 codemod**。
|
|
612
|
+
|
|
613
|
+
完整改动列表:[CHANGELOG.md](./CHANGELOG.md)。
|
|
614
|
+
|
|
615
|
+
## 开发
|
|
616
|
+
|
|
617
|
+
```bash
|
|
618
|
+
pnpm install
|
|
619
|
+
pnpm test # vitest run
|
|
620
|
+
pnpm lint # eslint(含 prettier check via eslint-plugin-prettier)
|
|
621
|
+
pnpm type-check # tsc --noEmit
|
|
622
|
+
pnpm bench # autocannon load test(不阻塞)
|
|
623
|
+
pnpm check # type-check + lint + test
|
|
624
|
+
pnpm build # vite build → dist/
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
## 与消费者解耦
|
|
628
|
+
|
|
629
|
+
`@novel-isr/engine` 不发 public npm,只发**私有 registry**(如公司内 Verdaccio /
|
|
630
|
+
npm Enterprise / GitHub Packages)。**任何项目**都可以作为消费方接它,通过语义
|
|
631
|
+
化版本号引用,**不**用 `file:../isr-engine` 这种 sibling 相对路径——sibling 假设
|
|
632
|
+
让两个 repo 互相强耦合,CI checkout 也跑不通。
|
|
633
|
+
|
|
634
|
+
**消费侧 install 步骤**(任何项目通用):
|
|
635
|
+
|
|
636
|
+
```bash
|
|
637
|
+
# 1. 配 .npmrc(一次性)
|
|
638
|
+
@novel-isr:registry=https://npm.your-company.com/
|
|
639
|
+
//npm.your-company.com/:_authToken=${NPM_TOKEN}
|
|
640
|
+
|
|
641
|
+
# 2. package.json 里写语义版本号
|
|
642
|
+
{ "dependencies": { "@novel-isr/engine": "^2.6.2" } }
|
|
643
|
+
|
|
644
|
+
# 3. install
|
|
645
|
+
pnpm install
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
**联动开发**(一边改 engine 一边在某个消费项目里迭代,不用每次发版):
|
|
649
|
+
|
|
650
|
+
```bash
|
|
651
|
+
# engine 端
|
|
652
|
+
cd isr-engine && pnpm build && pnpm link --global
|
|
653
|
+
|
|
654
|
+
# 任何消费项目端
|
|
655
|
+
cd <YOUR_CONSUMER_PROJECT> && pnpm link --global @novel-isr/engine
|
|
656
|
+
# 改完取消 link
|
|
657
|
+
pnpm unlink --global @novel-isr/engine && pnpm install
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
## CI / 发布
|
|
661
|
+
|
|
662
|
+
仓库里 3 个 workflow 各司其职:
|
|
663
|
+
|
|
664
|
+
| Workflow | 触发 | 跑什么 | 失败后果 |
|
|
665
|
+
|---|---|---|---|
|
|
666
|
+
| **`ci.yml`** | 任何分支 push + PR 到 main/develop | type-check / lint / test / build | branch 标红,PR 不可 merge |
|
|
667
|
+
| **`bench.yml`** | nightly 02:00 UTC + 手动 + perf-sensitive 路径 PR | 起 bench app + 跑 bench + 对比 `bench/baseline.json` | 信息性 fail(不阻断 release,只用于追踪退化) |
|
|
668
|
+
| **`release.yml`** | `git push v*.*.*` tag | 3 段 gate(type+lint / test / build)→ `pnpm publish --access restricted` 到 GitHub Packages | 任一段失败 → 不发布 |
|
|
669
|
+
|
|
670
|
+
**发布到 GitHub Packages**:
|
|
671
|
+
|
|
672
|
+
1. 一次性配置:repo `Settings → Actions → General → Workflow permissions` 切到 **Read and write permissions**(让 `GITHUB_TOKEN` 拿到 `write:packages`)。无需手动配 secret。
|
|
673
|
+
2. 本地:
|
|
674
|
+
```bash
|
|
675
|
+
# 改 package.json version 到 X.Y.Z
|
|
676
|
+
git tag vX.Y.Z
|
|
677
|
+
git push --tags
|
|
678
|
+
```
|
|
679
|
+
3. GitHub Actions 自动跑 release.yml;任一 gate 失败 → 不发布。
|
|
680
|
+
|
|
681
|
+
**消费侧**:见 [`.npmrc.example`](./.npmrc.example) 配 GitHub PAT (`read:packages` scope) → `pnpm install`.
|
|
682
|
+
|
|
683
|
+
**不发 public**:`pnpm publish --access restricted`,GitHub Packages 默认私有。
|
|
684
|
+
|
|
685
|
+
## 设计原则
|
|
686
|
+
|
|
687
|
+
1. **约定优于配置** —— 业务只维护一个 `routes` 源和一个 `App` 壳
|
|
688
|
+
2. **第一性原理** —— 不造假概念(csr 不是用户级 mode,是 fallback 兜底)
|
|
689
|
+
3. **横切能力 engine 默认提供** —— trace-id / render-ms / SEO / 安全头自动
|
|
690
|
+
4. **业务扩展用 FaaS hooks** —— 不强制学协议代码
|
|
691
|
+
5. **不手写 Flight** —— 完全依赖 [@vitejs/plugin-rsc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc),与 React 19 / Vite 8 升级路径对齐
|
|
692
|
+
|
|
693
|
+
## License
|
|
694
|
+
|
|
695
|
+
MIT
|