API

应用 API

应用入口负责创建根组件、安装插件、挂载和卸载组件树。

createApp

名称	签名	说明
`createApp`	`createApp(options?: AppOptions): OneApp`	创建 TSone 应用实例。

import { Component, VNode, createApp } from '@geektech/tsone';

class App extends Component<object, object> {
  protected initState() {
    return {};
  }

  protected initStyles(): void {}

  protected render(): VNode {
    return {
      tag: 'main',
      children: ['Hello TSone'],
    };
  }
}

const app = createApp({
  root: App,
  state: {
    appName: 'TSone',
  },
  config: {
    debug: true,
  },
});

app.mount();

最小应用可以写成 createApp({ root: App })。

应用创建后直接调用 app.mount() 即可。未传 rootElement 时默认挂载到 #app；目标元素不存在时会安全跳过本次挂载。

AppOptions

interface AppOptions<TState, TConfig> {
  root?: ComponentConstructor;
  rootProps?: ComponentProps;
  rootElement?: string | Element;
  state?: TState;
  config?: TConfig;
  document?: AppDocumentOptions;
}

root: 根组件类
rootProps: 传入根组件构造函数的 props
rootElement: 可选挂载点选择器或 DOM 元素，省略时使用 #app
state: 应用级状态
config: 应用级配置
document: HTML 文档壳配置，用于 dev/build 生成入口页

OneApp 方法

mount(): 挂载根组件并触发插件 onMounted
unmount(): 卸载根组件并清空挂载容器
use(plugin): 安装插件，例如路由
update(state): 合并更新应用状态
getState() / setState(state): 读取或替换应用级状态
getContext(): 返回包含 app、version 和 config 的上下文
updateRootComponent(App): 替换根组件
onUnmounted(callback): 注册卸载后的回调
provide(key, value): 提供应用级依赖
inject(key, fallback?): 读取应用级依赖
renderHtmlDocument(options?): 根据应用 document 配置生成完整 HTML 文档

renderHtmlDocument

名称	签名	说明
`OneApp.renderHtmlDocument`	`app.renderHtmlDocument(options?: AppDocumentRenderOptions): string`	根据 createApp 的 document 配置生成完整 HTML 文档壳，默认输出 #app 挂载点，适合 playground、静态站和文档构建。
`renderHtmlDocument`	`renderHtmlDocument(options: HtmlDocumentOptions): string`	底层文档渲染函数，可直接从 TSone 组件或 VNode 生成完整 HTML 文档壳。

createApp 的 document 配置默认输出 #app 挂载节点；传入 rootElement 可以覆盖默认挂载点。需要覆盖文档内容时，body 接收 TSone 组件节点、VNode 或文本节点。文本会被当作文本内容转义，不会解析成 HTML。

在 Bun/Node 静态生成环境中，请先提供 DOM-like document，例如项目文档构建脚本使用的 Happy DOM。

import {
  Component,
  VNode,
  createApp,
  type StyleSheet,
} from '@geektech/tsone';

interface AppProps {
  message: string;
}

class App extends Component<AppProps, object> {
  protected initState() {
    return {};
  }

  protected initStyles(): void {}

  protected render(): VNode {
    return {
      tag: 'main',
      props: { className: 'app' },
      children: [this.props.message],
    };
  }
}

const styles: StyleSheet = [
  {
    selector: '.app',
    properties: { maxWidth: '72rem' },
  },
];

const app = createApp({
  root: App,
  document: {
    lang: 'zh-CN',
    title: 'TSone Docs',
    description: '由 TSone 生成的静态文档',
    styles,
  },
});

const html = app.renderHtmlDocument({
  scripts: [{ type: 'module', src: '/assets/app.js' }],
});

lang: 输出到 html 元素的语言标记，默认 en
title: 文档标题，会进行 HTML 转义
description: 可选 meta description
styles: StyleSheet 对象数组，由框架序列化为 style 标签
scripts: 外部脚本配置，例如 module client bundle

开发工具 API

开发与构建 API 由独立的 @geektech/tsone-cli 包导出，不属于 @geektech/tsone 框架主入口。

名称	签名	说明
`defineConfig`	`defineConfig(config: UserConfig): UserConfig`	返回同一个带类型的普通对象配置。
`resolveConfig`	`resolveConfig(options?: ResolveConfigOptions): Promise<ResolvedConfig>`	校验并合并默认值、tsone.config.ts、直接配置以及 host/port/outDir 覆盖；返回的 root、entry、pages 与 outDir 路径为绝对路径。
`startDevServer`	`startDevServer(options?: StartDevServerOptions): Promise<Bun.Server>`	启动 Bun HTTP 开发服务器；调用方拥有返回的服务器，并负责调用 server.stop()。
`build`	`build(options?: BuildOptions): Promise<BuildResult>`	输出浏览器资源和每个页面一个 HTML 文档，返回绝对的 root/outDir 以及 assetsBuilt。
`createProject`	`createProject(options?: CreateProjectOptions): CreateProjectResult`	把基础 TSone 脚手架（package.json、tsone.config.ts、tsconfig.json、.gitignore、src/main.ts）写入 options.root，默认当前工作目录；拒绝覆盖已有文件。

import {
  build,
  createProject,
  defineConfig,
  resolveConfig,
  startDevServer,
} from '@geektech/tsone-cli';

const config = defineConfig({ build: { outDir: 'dist' } });
const resolved = await resolveConfig({ config });
const server = await startDevServer({ port: 0 });

try {
  console.log(server.url);
} finally {
  server.stop();
}

const result = await build({ outDir: 'release' });
console.log(result.root, result.outDir, result.assetsBuilt);

配置文件只支持普通对象默认导出；不支持函数式配置或函数值配置。配置默认值为入口 src/main.ts、pages {}、server host 127.0.0.1、端口 52211、空的 server.proxy，以及 build.outDir dist。入口必须使用 export const app，并提供 renderHtmlDocument()。pages 选项把路由映射到页面入口，每个入口满足相同的 export const app 契约；根路径 / 由 entry 提供。

开发服务器仅提供 HTTP。代理目标可以使用 HTTP 或 HTTPS。server.proxy 接受字符串规则或 { target, changeOrigin, rewrite } 对象规则。字面前缀按最长匹配优先；查询参数、请求体和端到端请求头会转发，上游连接失败时返回 502 Bad Gateway。

build.outDir 必须是项目根目录内部的安全子目录。CLI 首版配置不提供 plugins、WebSocket、HMR、SSR、函数式配置、public/ 复制以及公开的 minify/sourcemap 配置。