Web Artifacts Builder：复杂 HTML Artifact 构建

▐▎ 双栏模式

快速概览 结构拆解 脚本解读 最佳实践

一句话总结

web-artifacts-builder 是构建复杂 claude.ai HTML Artifact 的脚手架工具——用 init + bundle 两个 Shell 脚本，从空白到单文件 HTML 的完整管线。

核心能力

• 🏗 项目初始化：一键创建 React 18 + TypeScript + Vite + Tailwind + shadcn/ui 项目
• 📦 单文件打包：使用 Parcel + html-inline 将完整项目打包为自包含 HTML
• 🧩 40+ shadcn/ui 组件预装：包括 dialog、form、table、card、dropdown 等
• 🔧 自动兼容：检测 Node.js 版本，自动匹配兼容的 Vite
• 🎨 反”AI 模板风”设计指南：避免通用、千篇一律的视觉风格

触发场景

当用户请求”复杂 Artifact”、“多组件 React 应用”、“需要 shadcn/ui 的页面”、“完整的交互式 UI”等时触发。

文件清单

One-Line Summary

web-artifacts-builder is a scaffolding tool for building complex claude.ai HTML Artifacts — a complete pipeline from blank slate to single-file HTML using two Shell scripts: init + bundle.

Core Capabilities

• 🏗 Project initialization: one-click create React 18 + TypeScript + Vite + Tailwind + shadcn/ui project
• 📦 Single-file bundling: use Parcel + html-inline to bundle the complete project into a self-contained HTML
• 🧩 40+ shadcn/ui components pre-installed: including dialog, form, table, card, dropdown, etc.
• 🔧 Auto-compatibility: detects Node.js version, auto-matches compatible Vite
• 🎨 Anti-”AI template” design guidelines: avoids generic, cookie-cutter visual styles

Trigger Scenarios

Triggers when users request “complex artifact”, “multi-component React app”, “page needing shadcn/ui”, “complete interactive UI”, etc.

File Inventory

• web-artifacts-builder
  • SKILL.md 主入口 · ~75 行 · Markdown
  • LICENSE.txt Apache 2.0
  • scripts Shell 脚本 · 2 个文件
    • init-artifact.sh ~320 行 · ⭐⭐⭐ · 项目初始化
    • bundle-artifact.sh ~55 行 · ⭐⭐ · 单文件打包

目录结构分析

web-artifacts-builder 是**“脚本驱动型”** Skill，结构精炼。2 个 Shell 脚本构成了完整的”开发 → 构建”管线。

• SKILL.md（约 75 行）：定义了 5 步工作流 + 设计风格指南
• scripts/init-artifact.sh（约 320 行）：完整的 React 项目脚手架——从零创建包含 Tailwind、shadcn/ui、Vite、路径别名的项目
• scripts/bundle-artifact.sh（约 55 行）：使用 Parcel 构建 + html-inline 内联，生成自包含单 HTML 文件

SKILL.md 结构解析

5 步工作流

1. 初始化项目（Initialize）：运行 init-artifact.sh <project-name>，创建完整的前端项目
2. 开发 Artifact（Develop）：编辑生成的代码，构建应用
3. 打包为单文件（Bundle）：运行 bundle-artifact.sh，生成 bundle.html
4. 展示给用户（Display）：将 bundle.html 作为 artifact 分享
5. 测试（Test，可选）：仅在需要时测试

技术栈

React 18 + TypeScript + Vite + Parcel（打包）+ Tailwind CSS 3.4.1 + shadcn/ui

设计风格指南

SKILL.md 包含反”AI 模板风”指南——避免过度居中布局、紫色渐变、统一圆角和 Inter 字体。这与 frontend-design 的美学理念一致。

模块关系

Directory Structure Analysis

web-artifacts-builder is a “Script-driven” Skill with a lean structure. 2 Shell scripts form a complete “develop → build” pipeline.

• SKILL.md (~75 lines): Defines 5-step workflow + design style guide
• scripts/init-artifact.sh (~320 lines): Complete React project scaffold — creates a project with Tailwind, shadcn/ui, Vite, path aliases from scratch
• scripts/bundle-artifact.sh (~55 lines): Uses Parcel build + html-inline to generate a self-contained single HTML file

SKILL.md Structure Analysis

5-Step Workflow

1. Initialize Project: Run init-artifact.sh <project-name>, create complete frontend project
2. Develop Artifact: Edit generated code, build the application
3. Bundle to Single File: Run bundle-artifact.sh, generate bundle.html
4. Display to User: Share bundle.html as artifact
5. Test (Optional): Only if needed

Tech Stack

React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS 3.4.1 + shadcn/ui

Design Style Guide

SKILL.md includes anti-”AI template” guidance — avoid excessive centered layouts, purple gradients, uniform rounded corners, and Inter fonts. This aligns with the aesthetic philosophy of frontend-design.

Module Relationships

web-artifacts-builder 工作流

graph LR
  SKILL[SKILL.md] -->|指导| Claude
  Claude -->|Step 1| Init[scripts/init-artifact.sh]
  Claude -->|Step 2| Dev[开发 Artifact]
  Dev -->|Step 3| Bundle[scripts/bundle-artifact.sh]
  Bundle -->|输出| HTML[bundle.html]
  HTML -->|Step 4| User[展示给用户]

  Init -->|创建| Project[React + Vite + Tailwind + shadcn/ui]
  Project --> Dev

  style SKILL fill:#4fc3f7,stroke:#0288d1,color:#000
  style Init fill:#81c784,stroke:#388e3c,color:#000
  style Bundle fill:#81c784,stroke:#388e3c,color:#000
  style HTML fill:#ce93d8,stroke:#7b1fa2,color:#000
  style Project fill:#ffb74d,stroke:#f57c00,color:#000

脚本全量清单

---

init-artifact.sh — 项目脚手架

Full Script Inventory

---

init-artifact.sh — Project Scaffold

脚本	语言	行数	复杂度	功能
init-artifact.sh	Shell	~320	⭐⭐⭐	项目脚手架：React + Vite + Tailwind + shadcn/ui
bundle-artifact.sh	Shell	~55	⭐⭐	单文件打包：Parcel 构建 + html-inline 内联

Script	Language	Lines	Complexity	Function
init-artifact.sh	Shell	~320	⭐⭐⭐	Project scaffold: React + Vite + Tailwind + shadcn/ui
bundle-artifact.sh	Shell	~55	⭐⭐	Single-file bundle: Parcel build + html-inline

init-artifact.sh — 项目初始化（关键阶段） ↗ 源文件

1 set -e 2 3 # Detect Node version 4 NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1) 5 if [ "$NODE_VERSION" -lt 18 ]; then 6 echo "Error: Node.js 18+ required" 7 exit 1 8 fi 9 10 # Detect OS for sed syntax 11 if [[ "$OSTYPE" == "darwin"* ]]; then 12 SED_INPLACE="sed -i ''" 13 else 14 SED_INPLACE="sed -i" 15 fi 16 17 # Create Vite project 18 pnpm create vite "$PROJECT_NAME" --template react-ts 19 20 # Install core dependencies 21 pnpm install 22 pnpm add -D tailwindcss@3.4.1 postcss autoprefixer @types/node tailwindcss-animate 23 pnpm install class-variance-authority clsx tailwind-merge lucide-react next-themes 24 25 # Configure Tailwind with shadcn theme 26 cat > tailwind.config.js << 'TAILWIND_EOF' 27 // ... shadcn/ui color variables theme ... 28 TAILWIND_EOF 29 30 # Install 40+ shadcn/ui components 31 pnpm install @radix-ui/react-accordion @radix-ui/react-dialog @radix-ui/react-dropdown-menu ... 32 33 # Extract pre-built components from tarball 34 tar -xzf "$COMPONENTS_TARBALL" -C src/

代码解读

L1 set -e: Shell 脚本最佳实践——遇到任何错误立即退出，避免在失败状态下继续执行。 L3 Node.js 版本检测：检查 >= 18。如果低于 18 直接退出（exit 1）。在 Node 18-19 使用 Vite 5.4.11 兼容版本，Node 20+ 使用 latest。 L8 macOS/Linux 的 sed 兼容性处理。macOS 的 sed -i 需要空字符串参数（`sed -i ""`），Linux 不需要。这个模式是跨平台 Shell 脚本的必备技巧。 L15 使用 pnpm create vite 创建 React + TypeScript 项目。--template react-ts 指定 TypeScript 模板。pnpm 比 npm 更快，且内置了 monorepo 支持。 L17 安装核心依赖。注意 tailwindcss@3.4.1 固定版本——shadcn/ui 对 Tailwind 版本有严格要求。class-variance-authority + clsx + tailwind-merge 是 shadcn/ui 的必备 CSS 工具链。 L24 安装 40+ shadcn/ui 组件依赖。全部是 @radix-ui/* 包——shadcn/ui 的底层交互库。这种"批量安装"模式比逐个安装更高效。 L27 从预构建的 tarball 中解压 shadcn/ui 组件到 src/。这意味着所有 UI 组件已被预先提取并打包——节省了 npx shadcn-ui add 的运行时间。

---

bundle-artifact.sh — 单文件打包

---

bundle-artifact.sh — Single-File Bundling

bundle-artifact.sh — 单文件打包 ↗ 源文件

1 set -e 2 3 # Check prerequisites 4 if [ ! -f "package.json" ]; then 5 echo "Error: No package.json found" 6 exit 1 7 fi 8 if [ ! -f "index.html" ]; then 9 echo "Error: No index.html found" 10 exit 1 11 fi 12 13 # Install bundling dependencies 14 pnpm add -D parcel @parcel/config-default parcel-resolver-tspaths html-inline 15 16 # Create Parcel config with path alias support 17 cat > .parcelrc << 'EOF' 18 { 19 "extends": "@parcel/config-default", 20 "resolvers": ["parcel-resolver-tspaths", "..."] 21 } 22 EOF 23 24 # Clean previous build 25 rm -rf dist bundle.html 26 27 # Build with Parcel 28 pnpm exec parcel build index.html --dist-dir dist --no-source-maps 29 30 # Inline everything into single HTML 31 pnpm exec html-inline dist/index.html > bundle.html 32 33 echo "Bundle complete! Output: bundle.html"

代码解读

L3 先检查 package.json 和 index.html 是否存在——这两个文件是构建的前提条件。fail-fast 确保在不合法状态下不会继续执行。 L12 安装 Parcel 及其插件。parcel-resolver-tspaths 支持 TypeScript 路径别名（@/），html-inline 用于将所有 CSS/JS 内联到 HTML。 L15 .parcelrc 配置路径别名解析器。"..." 表示在自定义 resolver 之后回退到默认 resolvers——Parcel 的插件扩展点。 L24 pnpm exec parcel build：使用 Parcel 构建生产版本。--no-source-maps 不生成 source map（非必须且减少文件体积）。 L27 html-inline 是关键——它将所有外部资产（JS 包、CSS 文件）内联到 HTML 中。生成的 bundle.html 是完全自包含的，可以在 claude.ai 中直接作为 artifact 运行。

脚本依赖关系

init → develop → bundle 构成了完整的”脚手架 → 开发 → 打包”管线。两个脚本相对独立，但 bundle 脚本依赖 init 脚本创建的项目结构。

Script Dependency

init → develop → bundle forms the complete “scaffold → develop → bundle” pipeline. The two scripts are relatively independent, but bundle depends on the project structure created by init.

web-artifacts-builder 脚本依赖图

graph LR
  A[init-artifact.sh] -->|创建项目| B[React + Vite + Tailwind + shadcn/ui]
  B -->|开发| C[用户编辑源码]
  C -->|Step 3| D[bundle-artifact.sh]
  D -->|Parcel 构建| E[dist/]
  E -->|html-inline| F[bundle.html]

  style A fill:#81c784,stroke:#388e3c,color:#000
  style D fill:#81c784,stroke:#388e3c,color:#000
  style F fill:#ce93d8,stroke:#7b1fa2,color:#000

设计亮点

1. “Scaffold + Bundle”模式：先搭建完整项目环境，再打包为自包含文件——兼顾开发体验和部署便捷性
2. Shell 脚本作为 Skill 工具：在需要创建文件系统、安装依赖、运行构建等操作系统级操作时，Shell 比 Python 更自然
3. 预构建组件 tarball：40+ shadcn/ui 组件被预先提取为 tarball，避免了 npx shadcn-ui add 的网络依赖
4. 版本兼容检测：Node.js 版本自动检测 + Vite 版本锁定，确保在不同环境中运行一致
5. 单文件输出：最终产出 bundle.html 是完全自包含的，可直接在 claude.ai 中运行

可复用模式

移植思路

“如果你想为其他框架（Vue、Svelte、Solid）创建类似的脚手架 Skill…”

1. 保留 Scaffold + Bundle 模式：脚手架 + 打包是最通用的模式
2. 替换 init 脚本中的模板：将 React + Vite 替换为你的框架（Vue/Vite、SvelteKit、SolidStart）
3. 保留 bundle 脚本逻辑：Parcel + html-inline 是框架无关的
4. 替换组件库：将 shadcn/ui 替换为你的组件库（PrimeVue、SvelteShadcn、daisyUI）
5. 更新设计指南：在 SKILL.md 中调整风格约束以适应新框架的特性

常见坑

⚠️ shadcn-components.tar.gz 必须存在： init 脚本依赖这个 tarball——如果文件缺失或损坏，整个初始化流程会失败。这需要和脚本一起版本管理

⚠️ pnpm 依赖全局安装： 需要用户系统有 pnpm。脚本会尝试 npm install -g pnpm，但在受限环境中可能失败

⚠️ Node.js 版本兼容： Node 18 使用 Vite 5.4.11（不能使用 Vite 6）——版本锁定逻辑必须紧跟 Vite 的发布节奏

⚠️ Parcel 可能有兼容问题： parcel-resolver-tspaths 的版本需要和 Parcel 主版本匹配——锁定版本号很重要

⚠️ bundle.html 可能很大： 包含 React 运行时 + Tailwind + shadcn/ui 的 bundle 可能超过 1MB——需要在 SKILL.md 中告知用户

Design Highlights

1. “Scaffold + Bundle” Pattern: Build a complete project environment first, then package into a self-contained file — balancing development experience and deployment convenience
2. Shell Scripts as Skill Tools: Shell is more natural than Python for filesystem operations, dependency installation, and build processes
3. Pre-built Component Tarball: 40+ shadcn/ui components pre-packaged as a tarball, avoiding npx shadcn-ui add’s network dependency
4. Version Compatibility Detection: Auto-detect Node.js version + pin Vite version, ensuring consistent behavior across environments
5. Single-File Output: The final bundle.html is fully self-contained, runnable directly in claude.ai

Reusable Patterns

Porting Guide

“If you want to create similar scaffolding Skills for other frameworks (Vue, Svelte, Solid)…”

1. Keep Scaffold + Bundle pattern: scaffolding + bundling is the most universal pattern
2. Replace init script template: swap React + Vite for your framework (Vue/Vite, SvelteKit, SolidStart)
3. Keep bundle script logic: Parcel + html-inline is framework-agnostic
4. Replace component library: swap shadcn/ui for your library (PrimeVue, SvelteShadcn, daisyUI)
5. Update design guide: adjust style constraints in SKILL.md for the new framework’s features

Common Pitfalls

⚠️ shadcn-components.tar.gz must exist: init script depends on this tarball — if missing or corrupted, the entire init flow fails. Must be versioned with the script

⚠️ pnpm requires global install: user system needs pnpm. Script tries npm install -g pnpm but may fail in restricted environments

⚠️ Node.js version compatibility: Node 18 uses Vite 5.4.11 (not Vite 6) — version pinning must keep up with Vite’s release cadence

⚠️ Parcel may have compatibility issues: parcel-resolver-tspaths version must match Parcel main version — pinning versions is important

⚠️ bundle.html can be large: A bundle with React runtime + Tailwind + shadcn/ui may exceed 1MB — inform users in SKILL.md

模式	说明	适用于...
Scaffold + Bundle	先搭建项目 -> 开发 -> 打包为单文件	任何需要"开发环境"+"生产部署"的 skill
Shell 作为工具	用 Shell 处理文件系统、依赖安装、进程管理	需要操作系统级操作的 skill
预构建 tarball	将依赖预打包为 tarball，避免运行时网络请求	需要大量预构建资源的 skill
版本兼容检测	运行时检测环境版本，自动适配	跨平台/跨版本兼容的 skill
单文件输出	将所有资源内联到一个 HTML 文件	claude.ai artifact 发布

Pattern	Description	Applies to...
Scaffold + Bundle	Scaffold project → develop → bundle to single file	Any skill needing "dev environment" + "production deployment"
Shell as Tool	Shell for filesystem, dependency install, process mgmt	Skills needing OS-level operations
Pre-built Tarball	Pre-package dependencies as tarball, avoid runtime network requests	Skills needing large pre-built resources
Version Detection	Detect environment version at runtime, auto-adapt	Cross-platform/cross-version skills
Single-File Output	Inline all resources into one HTML file	claude.ai artifact publishing

↗ 新窗口 ×

加载中...