TSone CLI

指南

命令参考

开发与构建选项刻意分开：create 不接受选项；dev 接受 --host、--port 与 --no-watch；build 只接受 --out-dir。选项覆盖 tsone.config.ts。分离写法与等号写法都可用，例如 --port 3000、--port=3000、--out-dir output、--out-dir=output。

tsone create
tsone dev [--host <host>] [--port <port>] [--no-watch]
tsone build [--out-dir <path>]

tsone create

在当前目录生成基础项目脚手架，不覆盖任何已存在文件。

tsone dev

tsone dev 默认监听项目：当源码、样式或配置文件变化时，它会重建当前页面，并通过 /__tsone/reload 的 server-sent events 流通知已连接的浏览器刷新。监听模式为每个入口只保留最新成功构建的产物代，在通知刷新前删除上一代，旧资源 URL 返回 404。构建失败时保留最后可用的页面和产物，且不通知刷新；tsone.config.ts 的变更会以新配置重启开发服务器，并在旧实例停止且待处理请求完成后删除该实例的会话产物。传入 --no-watch 可关闭文件监听，使用保留各代产物的纯按需构建。

开发服务器在 / 与 /index.html 提供生成的 HTML，并为每个配置的页面提供一条路由。每个文档构建会在 dist/dev/h5/ 目录下写入一个不可变的浏览器 ESM 产物代，并引用精确的 /dev/<session>/<generation>/... JavaScript 与样式表 URL。Bun 将该精确产物代 URL 用作公共路径，因此跨并发页面也能从文档 URL 正确解析文件资源。/bundle.js 保持为兼容别名：它重建并重定向到最新的根入口 URL。其他未匹配路径返回 404。dist/dev/ 目录是工具生成的产物，可在开发服务器停止后删除；解析到项目外部的 dist 符号链接路径会在开发服务器启动前被拒绝。

tsone build

tsone build 将 Bun 浏览器 bundle 与每个页面的 HTML 文档写入安全的输出目录。入口 JavaScript 和导入的样式表 bundle 使用带内容 hash 的文件名（如 main-<hash>.js），HTML 自动引用实际产物；内容不变时 hash 保持稳定，更新后使用新 URL。library 构建保留固定导出文件名。build.outDir 必须解析为项目根目录内的子目录：项目根本身、外部路径以及通过符号链接逃逸的路径都会在删除输出目录前被拒绝。

多页应用

站点 build 和 dev 自动将 document.styles 和固定 initStyles / 新建 StyleManager 的初始化规则输出为 tsone-static-<sha256>.css；build 放在 HTML 同目录，dev 使用 /dev/<session>/<generation>/ 资源 URL。字面量、局部/模块 forEach 数组和支持的纯主题表达式无需改写；props/state、可见修改或未知调用继续动态处理。组件先同步内联，匹配 CSS 外链加载成功后按实例激活；修改恢复原位置，卸载清理本实例。外链激活时 styleElement 为 null，规则仍留在 bundle 支持回退，首次初始化仍序列化。相对/片段 URL、@import、不明确 URL 和 base 元素回退。发现阶段增加一次构建；缺少可信 Bun 模块 metadata 时跳过组件提取。watch 成功后一起替换脚本和 CSS，失败保留上一版；非 watch dev 保留各次构建资源，library 保持原流程。无需新配置。

用 pages 选项为每个路由配置独立的页面入口，每个入口必须满足与 entry 相同的 app 约定。路由键必须以 / 开头且可嵌套；结尾斜杠会被归一化（/about/ 与 /about 同样生效）。根路由 / 不能在 pages 中重新定义——请用 entry。每条路由独立打包与渲染。

import { defineConfig } from '@geektech/tsone-cli';

export default defineConfig({
  entry: 'src/main.ts',
  pages: {
    '/about': 'src/about.ts',
    '/docs/guide': 'src/guide.ts',
  },
});

开发时每个配置的页面在对应路由提供：/about/ 与 /about/index.html 也解析到 /about，且每个页面都有独立的 live-reload 注入。tsone build 为每个页面输出一份 HTML，使用页面路由作为文件名（/ 输出 index.html，/about 输出 about.html，/docs/guide 输出 docs/guide.html），资源 URL 相对该文档解析。

v1 范围

  • 开发服务器仅提供 HTTP；代理目标可使用 HTTP 或 HTTPS。
  • CLI v1 没有配置 plugins、WebSocket、HMR、SSR、函数式配置、public/ 目录复制，也没有公开的 minify 与 sourcemap 配置。
  • 开发 bundle 使用内部内联 source map；tsone build 默认压缩生产输出，压缩与 source map 控制刻意不可配置。