@ 点击max/ rsbuilding- plugin
在 Clickmax 上建立网站的设置 。 一个插件配置 建设 与回放 19, 尾风 CSS 4和 TanStack 启动,使每个页面在构建时间为静态的 HTML,并将结果包成 Clickmax 可以发布.
您不需要自己配置 React, Tailwind, 路由或输出路径 。 一个 Clickmax 网站的整个配置是:
// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core'
import { clickmax } from '@clickmax/rsbuild-plugin'
export default defineConfig({ plugins: [clickmax()] })
rsbuild dev # local development with hot reload
rsbuild build # production build: dist/client, dist/server and the publishable dist/clickmax/
与软件包匹配的 TypeScript 设置船; 一个站点 tsconfig.json 只需要自己的列表和导入别名 :
{
"extends": "@clickmax/rsbuild-plugin/tsconfig",
"include": ["**/*.ts", "**/*.tsx"],
"compilerOptions": { "paths": { "#/*": ["./src/*"] } }
}
网站的结构
| 路径 | 目的 |
|---|---|
src/routes/ | 文件路线. index.tsx 实值 /, (中文(简体) ), about/team.tsx 实值 /about/team, (中文(简体) ), _layout.tsx 在不添加 URL 片段的情况下将孩子包裹, posts/$slug.tsx 是一条动态路线. |
src/routes/__root.tsx | HTML 文档 shell (<html>, (中文(简体) ), <head>, (中文(简体) ), <body>) (中文(简体) ). |
src/styles.css | 全局样式表,导入于 ?url 从根道. 风道设施在各地都有 src/。 。 。 . |
public/ | 文件逐字复制到站点根:图像、字体、, robots.txt,可下载文档。 以绝对路径参考,例如 /images/logo.png (前缀为 basePath 当站点未挂起时 /) (中文(简体) ). |
src/assets/ (或以下任何地方) src/(中文(简体) ) | 从代码导入的图像和其他文件. 他们的名下藏有大麻 永远藏起来. |
新路线自动取出; 运行 rsbuild build (或保留 rsbuild dev 运行)以重生路径树.
什麽 rsbuild build 担保
网站作为静态文件发布;运行时没有服务器. 该建筑强制执行:
- 每一个有组件且没有路径参数的路由都会向
<route>/index.html. 动态路线($slug) 仅用于您列出的路径prerender.paths。 。 。 . - 页面之间的链接( E)
<a href>页:1 链接到其他网站和文件public/独自一人. - 每个图像,样式表,脚本,字体或文档都存在由同一站点的URL提供的页面引用. 缺少的文件会以页面和引用它的 URL 失败构建 .
- 无法制取的路由( 例如投放加载器) 失败 。 没有部分公布.
- 数据可以在路由内获取
loader与fetch从公共API。 装入器在构建时运行,以便在客户端导航时再次在浏览器中渲染页面,所以它们不得使用节点专用API等fs。 。 。 . 服务器功能( E)createServerFn)和服务器路由处理器不支持: 网站启用后没有服务器 。 使用服务器功能的客户端代码,以及链接到API路由的页面,会以所涉及的文件或URL来失败构建. - 没有发布服务器代码 .
dist/server/仅用于在构建过程中渲染页面.
公布的产出列于 dist/clickmax/manifest.json (路线,文件,大小和散列). dist/clickmax/site.tar.gz 是 Clickmax 接收的归档 .
使控制可以发现
漏斗列出每个已公布的路由, 从路由的最后 HTML 读入
dist/clickmax/manifest.json。只有以 Clickmax 运行时组件标记的元素数:每个
写入 data-cx-component 财务报告和审定财务报表 data-cx-entity-id ,并记录
其 DOM 识别码下的元素。 自定义触发器被宣告为 CxTrigger 从
@clickmax/rsbuild-plugin/runtime/core数字 :
import { CxTrigger, useCxTrigger } from '@clickmax/rsbuild-plugin/runtime/core'
<CxTrigger id="read-70" label="Read 70% of the page" />
// In the site's own code, when the condition is met:
const fire = useCxTrigger('read-70')
fire()
仅通过浏览器的事件 ClickmaxProvider,在绕行的根道上做了一次
<Outlet /> (点击max站点模板已经这样做了). 没有它, CxTrigger 列在
表面的,绝不然.
data-cx-component | 列为 |
|---|---|
button | 按钮点击 |
link | 链接点击 |
visible | 元素可见度 |
lead-form, (中文(简体) ), form | 提交表格和联系方式 |
trigger (单位:千美元)CxTrigger(中文(简体) ) | 自定义触发, 以其命名 label |
规则构建执行, 中断时与路径和元素失败 :
- 每个标记元素都有
id无空白、控制字符或 逗号,在所提供的文档中独一无二。 同一ID可能在不同的路线上被再用. 明确通过 ID; 永远不要用它生成useId(),在建构之间变化. - A 类
CxTrigger标签最多有255个字符,没有换行符。 漏斗显示是... - 一个元素带有运行时标记或浏览器SDK注释,从未两者兼有.
- 未知
data-cx-component值失败;不要用手写属性.
预交时的渲染标记元素:仅客户模式和计算元素不在
HTML 构建读取。 使用 aria-label 或者说 title ;否则,该构建将使用
可见文本、名称、输入值或ID。 检查嵌入和 Vturb 播放器记录为
集成发现,不能证明购买或视频活动支持.
浏览器 SDK 注释 (data-cx-track, (中文(简体) ), form[data-cx-ingest-form], (中文(简体) ), cm-* 继续工作
在浏览器中,但没有列出漏斗。 建筑指纹
capability warning legacy_selector 和每个找到的路线和身份证.
已出版页面之间的导航
使用普通的 TanStack 软件 Link, (中文(简体) ), Navigate, (中文(简体) ), useNavigate() 财务报告和审定财务报表 router.navigate() 电话,或本地
锚. 该网站拥有其目的地. 漏斗箭头手动代表漏斗,永远不要
重写按钮,链接,形成或退出导航.
插件自动观察您已有的路由器返回的路由器 getRouter 工厂何时
已发布的浏览器 SDK 已激活。 没有跟踪帮助器、动作包或路由器注册
应用程序来源中的要求。 水合客户端导航和预先直接输入这两种工作;
不强制重新装入文档进行跟踪.
选项
所有选项都是可选的。 默认匹配 Clickmax 站点模板 .
clickmax({
srcDirectory: 'src', // where the application code lives
basePath: '/', // mount path of the site, e.g. '/landing' for a sub-path deployment
prerender: {
paths: ['/posts/hello'], // concrete paths to render for dynamic routes such as /posts/$slug
crawlLinks: true, // follow same-site links in rendered pages
concurrency: 4, // pages rendered in parallel
},
plugins: [], // extra Rsbuild plugins, registered after the platform ones
limits: { // local packaging limits; the platform enforces its own
maxFiles: 20_000,
maxFileBytes: 100 * 1024 * 1024,
maxTotalBytes: 1024 * 1024 * 1024,
},
})
basePath 还设置了路由器basepath和资产 URL 前缀. 公共档案也在其中提供: basePath: '/landing',文档 public/images/logo.png 实值 /landing/images/logo.png,并提及 /images/logo.png 因为它会404号一旦部署。 链接( E)<a href>)到外出路径 basePath (c) 被作为同一宿主上的另一站点对待,没有被跟踪.
你能够和不能控制的东西 rsbuild.config.ts
其它 defineConfig 键( 例如 source.alias, (中文(简体) ), source.define 对于常客, tools.rspack)照常工作. 下面的密钥为平台所拥有; 设置它们失败的构建, 并有信件命名密钥 :
| 密钥 | 原因 |
|---|---|
output.distPath, (中文(简体) ), environments.*.output.distPath | 平台读取 dist/client 财务报告和审定财务报表 dist/server |
output.assetPrefix, (中文(简体) ), server.base | 使用 basePath |
server.publicDir | 公开文件总是来自 ./public |
output.cleanDistPath: false | 将公布 Stale 文件 |
source.define 提及 CLICKMAX_PUBLISH* 或者说 process.env | 证书永远不能到达浏览器捆绑 |
环境
插件读取这些变量 。 您通常不会自己设置; 点击max 平台运行您的构建时会设置 .
| 变量 | 效果 |
|---|---|
CLICKMAX_SANDBOX=1 | Clickmax 沙盒内部的开发: dev 服务器在端口上听 10143 并允许编辑器预览集成. |
MXD_STUDIO_ORIGIN_SUFFIXES | Clickmax 源代码可驱动编辑器预览 。 由站台设置. |
CLICKMAX_SKIP_VERSION_CHECK=1 | 跳过 npm 上的最新插件版本的一次/ 构建搜索( 当新版本存在时会打印出警告; 构建永远不会依赖于它) . |
CLICKMAX_BASE_PATH | 覆盖作者所挂载的生产架构,包括路由器和资产 URL 。 使用 basePath 发展选择. |
CLICKMAX_PUBLISH_SOURCE_IDENTITY | 可选平台提供源指纹绑入出版物再试. |
CLICKMAX_PUBLISH_ATTEMPT_ID, (中文(简体) ), CLICKMAX_PUBLISH_TOKEN, (中文(简体) ), CLICKMAX_PUBLISH_API_URL | 仅存在于一个建筑中,该平台将运行发布。 包装后, 块上传 site.tar.gz;成功意味着平台接受了它进行处理. 三者须相会相会,而只为相会相会相会相会 rsbuild build。 。 。 . |
没有公布的变量,除了上面的版本搜索之外,一个构建没有网络 I/O 。 证书只在节点构建过程中被读取,从未被写入输出.
在不重建的情况下重试上传
如果一个建筑成功但上传失败, 文物将留在 dist/clickmax/具有新的环境证书:
import { publishArtifact } from '@clickmax/rsbuild-plugin'
await publishArtifact() // verifies dist/clickmax/ against the build's own record, then uploads
重用原始尝试、挂载和准备字节 。 允许更新该标志;
修改约束要求进行新的出版尝试。 不要重运行出版物构建到
重试一个上传. dist/clickmax/status.json 记录本地进度; 接受不是证明
现场直播.
错误
插件所抛出的所有错误都有一个稳定 code 以及一个写着要改变的信息:
ClickmaxConfigError: 配置冲突,在编译前提出.ClickmaxArtifactError:构建输出不能成为完整的站点(缺少引用,服务器功能,不安全文件).ClickmaxPublishError: 上传失败;stage说在哪里(env, (中文(简体) ),prepare, (中文(简体) ),upload, (中文(简体) ),complete和retryable以后再试有没有道理.
支持的工具链
- 节点js 24.16或更新
@rsbuild/core^2.2@tanstack/react-start1.168.60 或较新的(1.x)- 反应 19, 尾风 CSS 4
许可证
仅限GPL-3.0. 见 自由主义。 。 。 .