简体中文

Preact+HTM

本教程将帮助你从零开始搭建一个基于 Esmx 的 Preact+HTM SSR 应用。我们将通过一个完整的示例来展示如何使用 Esmx 框架创建服务端渲染应用。

项目结构

首先，让我们了解项目的基本结构：

1.
2├── package.json         # 项目配置文件，定义依赖和脚本命令
3├── tsconfig.json        # TypeScript 配置文件，设置编译选项
4└── src                  # 源代码目录
5    ├── app.ts           # 主应用组件，定义页面结构和交互逻辑
6    ├── create-app.ts    # 应用实例创建工厂，负责初始化应用
7    ├── entry.client.ts  # 客户端入口文件，处理浏览器端渲染
8    ├── entry.node.ts    # Node.js 服务器入口文件，负责开发环境配置和服务器启动
9    └── entry.server.ts  # 服务端入口文件，处理 SSR 渲染逻辑

项目配置

package.json

创建 package.json 文件，配置项目依赖和脚本：

package.json

1{
2  "name": "ssr-demo-preact-htm",
3  "version": "1.0.0",
4  "type": "module",
5  "private": true,
6  "scripts": {
7    "dev": "esmx dev",
8    "build": "npm run build:dts && npm run build:ssr",
9    "build:ssr": "esmx build",
10    "preview": "esmx preview",
11    "start": "NODE_ENV=production node dist/index.mjs",
12    "build:dts": "tsc --declaration --emitDeclarationOnly --outDir dist/src"
13  },
14  "dependencies": {
15    "@esmx/core": "*"
16  },
17  "devDependencies": {
18    "@esmx/rspack": "*",
19    "@types/node": "22.8.6",
20    "htm": "^3.1.1",
21    "preact": "^10.26.2",
22    "preact-render-to-string": "^6.5.13",
23    "typescript": "^5.2.2"
24  }
25}

创建完 package.json 文件后，需要安装项目依赖。你可以使用以下任一命令来安装：

1pnpm install
2# 或
3yarn install
4# 或
5npm install

这将安装所有必需的依赖包，包括 Preact、HTM、TypeScript 和 SSR 相关的依赖。

tsconfig.json

创建 tsconfig.json 文件，配置 TypeScript 编译选项：

tsconfig.json

1{
2    "compilerOptions": {
3        "isolatedModules": true,
4        "experimentalDecorators": true,
5        "resolveJsonModule": true,
6        "types": [
7            "@types/node"
8        ],
9        "target": "ESNext",
10        "module": "ESNext",
11        "moduleResolution": "node",
12        "strict": true,
13        "skipLibCheck": true,
14        "allowSyntheticDefaultImports": true,
15        "paths": {
16            "ssr-demo-preact-htm/src/*": [
17                "./src/*"
18            ],
19            "ssr-demo-preact-htm/*": [
20                "./*"
21            ]
22        }
23    },
24    "include": [
25        "src"
26    ],
27    "exclude": [
28        "dist"
29    ]
30}

源码结构

app.ts

创建主应用组件 src/app.ts，使用 Preact 的类组件和 HTM：

src/app.ts

1/**
2 * @file 示例组件
3 * @description 展示一个带有自动更新时间的页面标题，用于演示 Esmx 框架的基本功能
4 */
5
6import { Component } from 'preact';
7import { html } from 'htm/preact';
8
9export default class App extends Component {
10    state = {
11        time: new Date().toISOString()
12    };
13
14    timer: NodeJS.Timeout | null = null;
15
16    componentDidMount() {
17        this.timer = setInterval(() => {
18            this.setState({
19                time: new Date().toISOString()
20            });
21        }, 1000);
22    }
23
24    componentWillUnmount() {
25        if (this.timer) {
26            clearInterval(this.timer);
27        }
28    }
29
30    render() {
31        const { time } = this.state;
32        return html`
33            <div>
34                <h1><a href="https://www.esmnext.com/guide/frameworks/preact-htm.html" target="_blank">Esmx 快速开始</a></h1>
35                <time datetime=${time}>${time}</time>
36            </div>
37        `;
38    }
39}

create-app.ts

创建 src/create-app.ts 文件，负责创建应用实例：

src/create-app.ts

1/**
2 * @file 应用实例创建
3 * @description 负责创建和配置应用实例
4 */
5
6import type { VNode } from 'preact';
7import { html } from 'htm/preact';
8import App from './app';
9
10export function createApp(): { app: VNode } {
11    const app = html`<${App} />`;
12    return {
13        app
14    };
15}

entry.client.ts

创建客户端入口文件 src/entry.client.ts：

src/entry.client.ts

1/**
2 * @file 客户端入口文件
3 * @description 负责客户端交互逻辑和动态更新
4 */
5
6import { render } from 'preact';
7import { createApp } from './create-app';
8
9// 创建应用实例
10const { app } = createApp();
11
12// 挂载应用实例
13render(app, document.getElementById('app')!);

entry.node.ts

创建 entry.node.ts 文件，配置开发环境和服务器启动：

src/entry.node.ts

1/**
2 * @file Node.js 服务器入口文件
3 * @description 负责开发环境配置和服务器启动，提供 SSR 运行时环境
4 */
5
6import http from 'node:http';
7import type { EsmxOptions } from '@esmx/core';
8
9export default {
10    /**
11     * 配置开发环境的应用创建器
12     * @description 创建并配置 Rspack 应用实例，用于开发环境的构建和热更新
13     * @param esmx Esmx 框架实例，提供核心功能和配置接口
14     * @returns 返回配置好的 Rspack 应用实例，支持 HMR 和实时预览
15     */
16    async devApp(esmx) {
17        return import('@esmx/rspack').then((m) =>
18            m.createRspackHtmlApp(esmx, {
19                config(context) {
20                    // 在此处自定义 Rspack 编译配置
21                }
22            })
23        );
24    },
25
26    /**
27     * 配置并启动 HTTP 服务器
28     * @description 创建 HTTP 服务器实例，集成 Esmx 中间件，处理 SSR 请求
29     * @param esmx Esmx 框架实例，提供中间件和渲染功能
30     */
31    async server(esmx) {
32        const server = http.createServer((req, res) => {
33            // 使用 Esmx 中间件处理请求
34            esmx.middleware(req, res, async () => {
35                // 执行服务端渲染
36                const rc = await esmx.render({
37                    params: { url: req.url }
38                });
39                res.end(rc.html);
40            });
41        });
42
43        server.listen(3000, () => {
44            console.log('服务启动: http://localhost:3000');
45        });
46    }
47} satisfies EsmxOptions;

这个文件是开发环境配置和服务器启动的入口文件，主要包含两个核心功能：

devApp 函数：负责创建和配置开发环境的 Rspack 应用实例，支持热更新和实时预览功能。这里使用 createRspackHtmlApp 来创建专门用于 Preact+HTM 的 Rspack 应用实例。
server 函数：负责创建和配置 HTTP 服务器，集成 Esmx 中间件处理 SSR 请求。

entry.server.ts

创建服务端渲染入口文件 src/entry.server.ts：

src/entry.server.ts

1/**
2 * @file 服务端渲染入口文件
3 * @description 负责服务端渲染流程、HTML 生成和资源注入
4 */
5
6import type { RenderContext } from '@esmx/core';
7import type { VNode } from 'preact';
8import { render } from 'preact-render-to-string';
9import { createApp } from './create-app';
10
11export default async (rc: RenderContext) => {
12    // 创建应用实例
13    const { app } = createApp();
14
15    // 使用 Preact 的 renderToString 生成页面内容
16    const html = render(app);
17
18    // 提交依赖收集，确保所有必要资源都被加载
19    await rc.commit();
20
21    // 生成完整的 HTML 结构
22    rc.html = `<!DOCTYPE html>
23<html lang="zh-CN">
24<head>
25    ${rc.preload()}
26    <title>Esmx 快速开始</title>
27    ${rc.css()}
28</head>
29<body>
30    <div id="app">${html}</div>
31    ${rc.importmap()}
32    ${rc.moduleEntry()}
33    ${rc.modulePreload()}
34</body>
35</html>
36`;
37};

运行项目

完成上述文件配置后，你可以使用以下命令来运行项目：

开发模式：

1npm run dev

构建项目：

1npm run build

生产环境运行：

1npm run start

现在，你已经成功创建了一个基于 Esmx 的 Preact+HTM SSR 应用！访问 http://localhost:3000 即可看到效果。

ON THIS PAGE

Preact+HTM#

项目结构#

项目配置#

package.json#

tsconfig.json#

源码结构#

app.ts#

create-app.ts#

entry.client.ts#

entry.node.ts#

entry.server.ts#

运行项目#

Preact+HTM

项目结构

项目配置

package.json

tsconfig.json

源码结构

app.ts

create-app.ts

entry.client.ts

entry.node.ts

entry.server.ts

运行项目