Agent Skills › PrefectHQ/prefab › prefab-dev-build

prefab-dev-build

GitHub

指导如何构建和预览渲染器及游乐场更改。提供单一命令以触发包含缓存的完整构建流水线，涵盖前端资源生成、Python代码打包及文档部署，并指出常见错误与本地预览方法。

skills/prefab-dev-build/SKILL.md PrefectHQ/prefab

触发场景

修改了渲染器源码（如主题、组件、样式）修改了游乐场代码或Python源文件需要本地预览UI变更效果

安装

npx skills add PrefectHQ/prefab --skill prefab-dev-build -g -y

更多选项

不安装直接使用

npx skills use PrefectHQ/prefab@prefab-dev-build

指定 Agent (Claude Code)

npx skills add PrefectHQ/prefab --skill prefab-dev-build -a claude-code -g -y

安装 repo 全部 skill

npx skills add PrefectHQ/prefab --all -g -y

预览 repo 内 skill

npx skills add PrefectHQ/prefab --list

SKILL.md

Frontmatter

{
    "name": "prefab-dev-build",
    "description": "How to build and preview renderer\/playground changes locally. Use this skill when modifying the renderer (themes, components, styles), the playground (theme picker, examples), or any Python source that needs to appear in the playground. Covers the build pipeline, common pitfalls, and how to iterate."
}

Building and Previewing Renderer/Playground Changes

The One Command

After changing renderer source, Python source, or playground code:

uv run prefab dev build-docs

This is the only command you should use. It orchestrates the full pipeline with smart caching (only rebuilds what changed). Never run raw npm build commands (npm run build:playground, npm run build:renderer) directly — they skip critical steps.

What the Pipeline Does

Renderer build (if TS source changed) — npm run build:renderer builds the code-split ESM bundle for CDN delivery (the primary renderer artifact)
Python bundle generation — serializes all src/prefab_ui/**/*.py into renderer/src/playground/bundle.json for Pyodide
Playground build (if playground source changed) — runs Vite with VITE_LOCAL_PLAYGROUND=1 so the Python bundle is inlined
Copy to docs/ — puts built files where prefab playground and mintlify dev expect them

Note: build-docs builds the CDN renderer. The bundled single-file renderer (airgapped fallback) is built separately via prefab dev build-renderers.

Previewing

# Start the playground (serves from docs/)
uv run prefab playground

# Or start the full docs site
mintlify dev --dir docs

The playground runs on port 5174 by default.

Common Mistakes

"attempted to install wheel before downloading it" — the playground was built without VITE_LOCAL_PLAYGROUND=1. This happens when you run npm run build:playground directly instead of prefab dev build-docs. Fix: run the full pipeline.

Playground shows stale Python code — bundle.json is stale. The full pipeline regenerates it; raw npm commands don't.

Renderer changes not visible in deploy previews — deploy previews load chunks from the CDN (@latest), not from the branch. Test renderer changes locally.