is-spa-project
检测前端项目是否为 SPA（单页应用），判断部署时是否需要配置 Nginx/CDN 回源兜底到 index.html。
支持源码检测和构建产物检测两种模式，覆盖 React、Vue、Angular、Svelte、Next.js、Nuxt、SvelteKit、Remix、React Router 等主流框架。
快速开始
const { needsFallback } = require('is-spa-project')
// 传入任意目录，自动判断
needsFallback('./my-project') // true — 需要配置兜底
needsFallback('./my-project/dist') // true
needsFallback('./my-nuxt-app') // false — 不需要兜底
安装
npm install is-spa-project
API
needsFallback(dir, options?): boolean
推荐使用。 判断是否需要配置回源兜底。
const { needsFallback } = require('is-spa-project')
// 自动模式（默认）— 自动判断源码/产物
needsFallback('./cra-spa') // true
needsFallback('./cra-spa/build') // true
needsFallback('./nuxt-app') // false
// 强制源码检测
needsFallback('./my-project', { mode: 'source' })
// 强制构建产物检测
needsFallback('./my-project/dist', { mode: 'dist' })
options.mode：
| 值 | 说明 |
|---|---|
'auto'（默认） | 自动判断目录是源码还是构建产物 |
'source' | 强制源码检测（分析 package.json、配置文件） |
'dist' | 强制构建产物检测（分析 HTML 和 JS 文件） |
autoDetect(dir): DetectionResult
自动识别目录类型，返回完整检测结果。
const { autoDetect } = require('is-spa-project')
const result = autoDetect('./my-project')
console.log(result.mode) // 'source' | 'dist'
console.log(result.type) // 'spa' | 'mpa' | 'hybrid' | 'ssg' | 'unknown'
console.log(result.confidence) // 'high' | 'medium' | 'low'
console.log(result.reason) // 人类可读的判定原因
detect(projectRoot): DetectionResult
源码检测模式。分析 package.json、配置文件、入口文件。
detectBuildOutput(distDir): DetectionResult
构建产物检测模式。分析 HTML 文件和 JS bundle 中的路由代码。
isSpa(projectRoot): boolean
源码检测简化版，等价于 detect().type === 'spa' || 'hybrid'。
CLI
# 自动模式（自动判断源码/产物）
npx is-spa ./my-project
npx is-spa ./my-project/dist
# 强制构建产物模式
npx is-spa ./my-project/dist --dist
# JSON 输出
npx is-spa ./my-project --json
npx is-spa ./my-project/dist --dist --json
检测结果类型
| 类型 | 含义 | 需要兜底？ | 部署配置 |
|---|---|---|---|
| spa | 构建产物只有单个 index.html | ✅ 需要 | try_files $uri $uri/ /index.html |
| hybrid | SPA 主体 + 独立辅助页面 | ✅ 需要 | 主入口需要兜底 |
| mpa | 多个独立 HTML 入口 | ❌ 不需要 | 每个路由有对应文件 |
| ssg | SSR/SSG 框架，每个路由有对应 HTML | ❌ 不需要 | 框架构建工具自动处理 |
| unknown | 无法判定 | ❌ 不需要 | — |
支持的框架和路由库
框架检测（快速路径）
| 框架 | 依赖 | 默认判定 | 可切换为 SPA？ |
|---|---|---|---|
| Create React App | react-scripts | spa | — |
| Angular CLI | @angular/cli | spa | — |
| Next.js | next | ssg | ❌ |
| Nuxt | nuxt | ssg | ❌（generate 自动处理） |
| Gatsby | gatsby | ssg | ❌ |
| React Router (Framework) | @react-router/dev | ssg | ✅ ssr: false → spa |
| SvelteKit | @sveltejs/kit | ssg | ✅ fallback → spa |
| Remix | @remix-run/react | ssg | ✅ ssr: false → spa |
路由库检测
| 路由库 | 生态 |
|---|---|
vue-router | Vue |
react-router-dom / react-router | React |
@tanstack/react-router | React |
wouter | React |
@angular/router | Angular |
svelte-routing | Svelte |
svelte-spa-router | Svelte |
page (page.js) | Vanilla JS |
navigo | Vanilla JS |
universal-router | Vanilla JS |
检测原理
源码检测
package.json → 匹配已知框架？→ 框架快速路径（可能读取配置文件）
↓ 否
检测路由库依赖 + 入口文件数量 + router 使用 → 综合判定
构建产物检测
根目录有 index.html？
├── 没有 → unknown（不存在回源目标）
└── 有 → 扫描 HTML + JS → 判定
| 信号 | SPA | SSG | MPA |
|---|---|---|---|
| 应用 HTML 数 | 1 | 多个 | 多个 |
| HTML body | 空壳 | 有预渲染内容 | 有各自内容 |
| JS 含路由代码 | ✅ | ✅ | ❌ |
| 多 HTML 共享 JS | — | ✅ | ❌ |
路由代码只统计页面实际加载的 JS：HTML 中的 <script src> / <link rel="modulepreload">，以及这些文件通过静态 import ... from / export ... from 引用到的 chunk。没有被页面引用的懒加载 chunk 不参与判定，只会出现在 details.unreferencedRouterJsFiles 里，便于排查。
关键词按标识符边界匹配，避免 onpopstate 这类字符串被语法高亮数据表误命中；onpopstate 仅在赋值场景（window.onpopstate = ...）才视为路由实现。
产物根目录存在静态 404.html（不含 JS 引用）时，认为作者已经声明了 404 语义，不再自动开启回退。如果 404.html 本身是带 JS 的应用页面（如 Vue CLI / SvelteKit 生成的辅助页），仍按原逻辑判定。
needsFallback 自动检测
传入目录 → 判断是源码还是产物
├── 有 package.json（含 dependencies）或 src/ → 源码检测
└── 否则 → 产物检测
主模式结果 unknown(low) → 回退另一种模式（仅采纳 high 置信度）
构建产物模式：只有 high 置信度、且没有静态 404.html 时才返回 true
测试
npm test # 源码检测（24 个测试项目）
npm run test:dist # 构建产物检测（24 个测试项目）
npm run test:edge # 产物检测边界用例
npm run test:all # 全部运行
测试覆盖 24 个项目：CRA、Vite+React、Vite+Vue、Angular、Vue CLI（SPA/MPA/Hybrid）、Next.js、Nuxt（SSG/SPA）、SvelteKit（SSG/SPA）、Remix（SSR/SPA）、React Router Framework（SPA）、TanStack Router、wouter、svelte-routing、svelte-spa-router、page.js、navigo、universal-router、原生 HTML（单页/多页）。
License
MIT