Haitao Pan 9c877ceb3c feat(dashboard-fresh): migrate and integrate dashboard source

- Add fresh app structure (auth, tenant, mail, insight, docs, panel)
- Include CMS content, API routes, scripts, and config
- Migrate UI components, themes, and extensions to fresh runtime

2025-11-04 18:06:21 +08:00

5.4 KiB

Raw Blame History

Dev Server Fix Report

✅ 修复完成 (Fixes Completed)

1. 修复 Template Manifest 导入错误

问题：

error: Module not found "file:///...//static/_build/template-manifest.json"

原因： routes/api/templates.ts 在模块顶层使用 import 静态导入 JSON 文件，但该文件在开发时不存在（需要通过 prebuild 任务生成）。

解决方案： 改为运行时动态加载，如果文件不存在则返回空的 manifest：

// Before: Static import (fails if file doesn't exist)
import manifest from '../../static/_build/template-manifest.json' with { type: 'json' }

// After: Runtime loading with fallback
async function loadManifest() {
  try {
    const content = await Deno.readTextFile(MANIFEST_PATH)
    return JSON.parse(content)
  } catch (error) {
    console.warn('Template manifest not found, returning empty manifest')
    return { templates: [], stats: { total: 0 }, generatedAt: new Date().toISOString() }
  }
}

修改的文件：

routes/api/templates.ts - 动态加载 template-manifest.json
routes/api/docs.ts - 改进错误处理，返回空数据而非 500 错误
routes/api/downloads.ts - 改进错误处理，返回空数据而非 500 错误

2. 修复 Tailwind Plugin 错误

问题：

error: Cannot find module 'file:///.../npm/registry.npmjs.org/tailwindcss/3.4.3_1/index.js'

原因： Fresh 的 Tailwind 插件 ($fresh/plugins/tailwind.ts) 需要 npm:tailwindcss 包，但在 Deno 2.x 中 npm 模块解析可能存在兼容性问题。

临时解决方案： 禁用 Fresh Tailwind 插件，改用独立的 Tailwind CSS 构建：

// fresh.config.ts
export default defineConfig({
  plugins: [
    // tailwind() - Temporarily disabled
  ],
})

长期解决方案（待实施）：

选项 A: 使用独立的 Tailwind CLI

# 添加 Tailwind 构建任务到 deno.jsonc
"tailwind:build": "deno run -A npm:tailwindcss@3.4.3 -i ./styles/input.css -o ./static/styles/output.css",
"tailwind:watch": "deno run -A npm:tailwindcss@3.4.3 -i ./styles/input.css -o ./static/styles/output.css --watch"

选项 B: 使用 PostCSS + Tailwind

创建 scripts/build-css.ts:

import postcss from 'npm:postcss@8.4.35'
import tailwindcss from 'npm:tailwindcss@3.4.3'
import autoprefixer from 'npm:autoprefixer@10.4.17'

// Process CSS with Tailwind

选项 C: 等待 Fresh 更新

Fresh 可能会在未来版本中修复 Tailwind 插件的 npm 模块解析问题。

3. 添加 nodeModulesDir 配置

修改： 在 deno.jsonc 中添加：

{
  "nodeModulesDir": "auto"
}

这允许 Deno 为 npm 包创建 node_modules 目录，某些包可能需要这个目录结构。

✅ 当前状态

Dev 服务器现在可以启动了！

$ deno task dev

Task dev deno run -A --watch=static/,routes/ dev.ts
Watcher Process started.
The manifest has been generated for 12 routes and 1 islands.

🍋 Fresh ready
    Local: http://localhost:8000/

工作正常的功能

✅ Fresh 路由自动生成 (fresh.gen.ts)
✅ API 端点可以访问
✅ 热重载 (file watching)
✅ Middleware 认证系统
✅ 运行时动态加载 manifests

需要注意的事项

⚠️ Tailwind CSS 插件已禁用
- 需要使用其他方法构建 Tailwind CSS
- 现有的 tailwind.config.ts 和 postcss.config.ts 仍然可用
⚠️ Build manifests 未生成
- /api/templates 返回空数据
- /api/docs 返回空数据
- /api/downloads 返回空数据
- 运行 deno task prebuild 可以生成这些文件

🔧 推荐的下一步

1. 设置 Tailwind CSS 构建

选项 A: 快速方案 - 使用 npm scripts

// deno.jsonc
{
  "tasks": {
    "css:build": "deno run -A npm:tailwindcss@3.4.3 -i ./app/globals.css -o ./static/styles/globals.css",
    "css:watch": "deno run -A npm:tailwindcss@3.4.3 -i ./app/globals.css -o ./static/styles/globals.css --watch",
    "dev:full": "deno task css:watch & deno task dev"
  }
}

选项 B: 集成方案 - 创建 Fresh 插件 创建自定义 Fresh 插件来处理 CSS 构建。

2. 运行 Prebuild 任务

deno task prebuild

这将生成：

static/_build/template-manifest.json
static/_build/docs_index.json
static/_build/dl-index/all.json

3. 更新 _app.tsx 加载 CSS

确保 routes/_app.tsx 正确加载生成的 CSS：

export default function App({ Component }: AppProps) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <link rel="stylesheet" href="/styles/globals.css" />
      </head>
      <body>
        <Component />
      </body>
    </html>
  )
}

📝 修改的文件总结

routes/api/templates.ts - 动态加载 manifest
routes/api/docs.ts - 改进错误处理
routes/api/downloads.ts - 改进错误处理
fresh.config.ts - 禁用 Tailwind 插件
deno.jsonc - 添加 nodeModulesDir

🎯 验证检查清单

deno task dev 启动成功
Fresh manifest 自动生成
API 端点可以访问
热重载工作正常
Tailwind CSS 正确构建
前端样式正确显示
Build manifests 生成完成

🚀 Ready for Development

Fresh + Deno 开发环境现在已经准备就绪！

# 启动开发服务器
deno task dev

# 访问
http://localhost:8000

# API 端点测试
curl http://localhost:8000/api/ping
curl http://localhost:8000/api/templates

5.4 KiB Raw Blame History Unescape Escape