laybot-vite-dev 0.1.0

package/README.md

@@ -0,0 +1,159 @@
+# laybot-vite-dev
+
+Vite 开发服务器适配插件，用于 **LarryMS MPA（多页）+ runtime loader（`larryms.use`）** 的开发模式。
+
+它解决的核心问题是：LarryMS 在浏览器里按 **固定 URL 前缀**请求资源（如 `/assets/**`、`/laybot/**`、`/static/**`），但在 Vite dev 下源码实际位于 `src/**`。本插件会在 dev server 中间件层做 URL 重写，使 **开发环境访问路径与生产环境一致**，且不会破坏 Vite HMR WebSocket。
+
+---
+
+## 特性
+
+- **MPA HTML 路由映射**
+    - `/`、`/index.html` → `src/views/index.html`
+    - `/xxx.html` → `src/views/xxx.html`
+- **统一业务根目录 `/assets/`**
+    - `/assets/**` → `/src/**`（去掉 `assets` 前缀）
+    - 推荐 LarryMS MPA 项目统一把业务模块/资源发布在生产环境的 `dist/assets/**`
+- **框架运行时 `/laybot/` 映射**
+    - `/laybot/**` → `/src/laybot/**`
+- **静态资源 `/static/` 映射**
+    - `/static/**` → `/src/static/**`
+- **兼容旧写法 `/app/`**
+    - `/app/**` → `/src/app/**`（可用于过渡期或老项目）
+- **不会破坏 Vite HMR**
+    - 自动放行 WebSocket upgrade 与 Vite 内部路径（`/@vite`、`/@id`、`/@fs`、`/__vite`…）
+
+---
+
+## 适用场景
+
+- 你使用 LarryMS（`larryms.define/larryms.use`）做模块加载
+- 项目是 MPA：每个页面一个 `.html`，不走 Vue/React SPA 路由
+- 构建产物约定：
+    - `dist/index.html`、`dist/login.html`（或更多页面）
+    - `dist/assets/**`（业务模块与资源）
+    - `dist/laybot/**`（框架运行时）
+    - `dist/static/**`（静态资源）
+
+---
+
+## 安装
+
+```bash
+npm i -D laybot-vite-dev
+```
+
+> 如果你使用 pnpm/yarn 也可对应安装。
+
+---
+
+## 使用
+
+在项目的 `vite.config.js` 中引入并加入 plugins：
+
+```js
+import { defineConfig } from 'vite'
+import laybotViteDev from 'laybot-vite-dev'
+
+export default defineConfig({
+  server: { port: 5173 },
+  plugins: [
+    laybotViteDev({
+      debug: false
+    })
+  ]
+})
+```
+
+然后访问：
+
+- http://localhost:5173/        → `src/views/index.html`
+- http://localhost:5173/login.html → `src/views/login.html`
+
+页面里引用的生产路径在 dev 下仍然可用，例如：
+
+```html
+<link rel="stylesheet" href="/laybot/css/larryms.css" />
+<link rel="stylesheet" href="/static/css/admin.dark.css" />
+<script src="/laybot/larryms.js"></script>
+<script src="/assets/app/laybot.js"></script>
+```
+
+---
+
+## 约定与规范（重要）
+
+### 1）业务模块统一发布到 `/assets/`
+LarryMS MPA 建议约定：生产环境业务模块都在 `/assets/` 下。
+
+- 好处：URL 语义统一、构建结构稳定、文档清晰、CDN 缓存策略统一
+- 你的源码可以自由组织（`src/app`、`src/biz`、`src/features`…），最终只要构建输出到 `dist/assets/**` 即可
+
+### 2）框架运行时固定 `/laybot/`
+- `larryms.js` 与框架 css/font/images 固定在 `dist/laybot/**`
+- 业务项目无需理解其内部结构，只要按固定 URL 引用即可
+
+### 3）静态资源固定 `/static/`
+- 例如主题 css、svg、音频等放在 `dist/static/**`
+
+---
+
+## 配置项
+
+```js
+laybotViteDev({
+  viewsDir: '/src/views',     // 默认：/src/views
+  assetsPrefix: '/assets/',   // 默认：/assets/
+  laybotPrefix: '/laybot/',   // 默认：/laybot/
+  staticPrefix: '/static/',   // 默认：/static/
+  appPrefix: '/app/',         // 默认：/app/（兼容用）
+  debug: false                // 默认 false；true 时打印 rewrite 前后关系
+})
+```
+
+### debug
+开启后会输出每次重写的映射结果，便于定位 404：
+
+```bash
+[laybot-vite-dev] /static/css/admin.dark.css => /src/static/css/admin.dark.css
+```
+
+---
+
+## 常见问题
+
+### 1）`[vite] failed to connect to websocket`
+原因：你在 Vite dev 中间件里重写了 WebSocket upgrade 请求（HMR 握手），导致连接失败。
+
+本插件已内置放行：
+- `upgrade: websocket`
+- `/@vite`、`/@id`、`/@fs`、`/__vite` 等 Vite 内部路径
+
+若你自行添加了其它中间件，请确保它们不会重写 WebSocket 请求。
+
+---
+
+### 2）`/laybot/larryms.js 404` 或 `/static/... 404`
+请确认文件存在于源码目录：
+
+- `src/laybot/larryms.js`
+- `src/laybot/css/larryms.css`
+- `src/static/css/...`
+- `src/app/laybot.js`
+
+并确认插件已加入 Vite plugins 列表且 dev server 已重启。
+
+---
+
+### 3）为什么插件要强制统一 `/assets/`？
+因为 LarryMS 的 runtime loader 会动态加载业务模块。如果允许业务模块在 dev/prod 中出现多套 URL 体系（例如 dev 用 `/api/*.js`，prod 用 `/assets/*.js`），很容易出现：
+- 某个页面忘了更新路径导致 404
+- devRewrite 规则越来越多、越来越难维护
+- MPA 页面之间初始化逻辑分裂
+
+统一 `/assets/` 可以让开发环境与生产环境保持一致，减少路径问题。
+
+---
+
+## License
+MIT (建议你根据实际发布策略修改许可证说明)

package/dist/index.js

@@ -0,0 +1 @@
+function c(u={}){let i={viewsDir:u.viewsDir||"/src/views",debug:u.debug===!0,assetsPrefix:u.assetsPrefix||"/assets/",laybotPrefix:u.laybotPrefix||"/laybot/",staticPrefix:u.staticPrefix||"/static/",appPrefix:u.appPrefix||"/app/"},l=(...f)=>i.debug&&console.log("[laybot-vite-dev]",...f);return{name:"laybot-vite-dev",enforce:"pre",configureServer(f){f.middlewares.use((r,o,e)=>{let a=r.url||"/",[t,s=""]=a.split("?");if((r.headers.upgrade||"").toLowerCase()==="websocket"||t.startsWith("/@vite")||t.startsWith("/@id")||t.startsWith("/@fs")||t.startsWith("/__vite")||t==="/favicon.ico")return e();if(t==="/"||t==="/index.html")return r.url=`${i.viewsDir}/index.html`+(s?`?${s}`:""),l(a,"=>",r.url),e();if(/\.html$/i.test(t)&&!t.startsWith(i.viewsDir+"/"))return r.url=`${i.viewsDir}${t}`+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.assetsPrefix))return r.url="/src"+t.slice(i.assetsPrefix.length-1)+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.laybotPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.staticPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.appPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();e()})}}}export{c as default};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "laybot-vite-dev",
+  "version": "0.1.0",
+  "description": "Vite dev rewrite plugin for LayBot/LarryMS MPA runtime loader",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "keywords": ["vite", "plugin", "mpa", "larryms", "laybot"],
+  "author": "larry",
+  "license": "MIT",
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "fs-extra": "^11.3.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "npm run build"
+  }
+}