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

prefab-dev-build

GitHub

指导开发者如何本地构建和预览渲染器及沙盒环境的变更。通过统一命令处理 TS、Python 源码的编译打包与文档生成，避免直接运行原始 npm 命令导致的缓存或配置错误，确保本地开发与部署预览的一致性。

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

Trigger Scenarios

需要本地测试渲染器或组件样式变更修改 Python 源码后需更新沙盒环境构建流程出现资源未加载或代码陈旧问题

Install

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

More Options

Use without installing

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.