# @basenative/server 中文文档

规范地址：https://npmcn.com/package/%40basenative/server/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:00.588Z
中文译文更新时间：2026-10-31T16:45:29.438Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basenative/server
原文对照：https://npmcn.com/package/%40basenative/server/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/server#readme
源码仓库：https://github.com/DuganLabs/BaseNative

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-03-20T05:27:52.876Z
- 最新版本发布：2026-10-31T13:47:00.192Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

服务器端呈现，支持BaseNative模板的流

## 安装

```sh
npm install @basenative/server
```

也可以使用：`pnpm add @basenative/server`、`yarn add @basenative/server`、`bun add @basenative/server`

## README

# @basenative /服务器

> 用于BaseNative模板的SSR渲染器-插值，@if, @for， @switch和流

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/server
```

## 快速入门

```js
import { render, renderToStream, renderToReadableStream } from '@basenative/server';

const html = `
<h1>Hello, {{ name }}!</h1>
<template @if="items.length > 0">
  <ul>
    <template @for="item of items; track item.id">
      <li>{{ item.name }}</li>
    </template>
  </ul>
</template>
<template @else>
  <p>No items found.</p>
</template>
`;

const output = render(html, { name: 'World', items: [{ id: 1, name: 'First' }] });
```

## 流媒体

```js
// Express streaming response
renderToStream(html, ctx, res, { hydratable: true });

// Web Streams (Cloudflare Workers, Deno, Bun)
const stream = renderToReadableStream(html, ctx, { hydratable: true });
return new Response(stream);
```

## 模板的指令

-   `{{ expr }}` -将表达式插入到文本或属性值中。
-   `@if="expr"` -有条件地呈现 `<template>` 块。
-   `@else` -紧接在一个 `@if` 模板。
-   `@for="item of list; track item.id"` -迭代列表。循环变量: `$index`， `$first`， `$last`， `$even`， `$odd`.
-   `@empty` -渲染时 `@for` 列表为空。
-   `@switch="expr"` / `@case="value"` / `@default` -开关/案例渲染。
-   `:attr="expr"` -计算表达式并将其设置为HTML属性（省略if） `false` 或者 `null`）。

## API

-   `render(html, ctx, options?)` —同步呈现HTML模板字符串。返回呈现的HTML字符串。
-   `renderToStream(html, ctx, stream, options?)` -渲染和管道输出到Node.js可写流。
-   `renderToReadableStream(html, ctx, options?)` -渲染和返回一个Web流 `ReadableStream`.

### 选项

-   `hydratable` -将指令输出封装在 `<!--bn:*-->` 客户端水化标记。
-   `onDiagnostic(diagnostic)` -模板警告和错误时调用的回调。

## 许可证

apache - 2.0

## 常见问题

### @basenative/server 是什么？

服务器端呈现，支持BaseNative模板的流

### 如何安装 @basenative/server？

在项目目录运行 npm install @basenative/server，或使用 pnpm add / yarn add / bun add。

### @basenative/server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basenative/server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/server 可以商用吗？

@basenative/server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/server 还在维护吗？

最新版本 3\.0\.0 发布于 2026/10/31（2 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。