tsParticles CLI 工程脚手架tsparticles-create 从一条命令到可发布插件包的完整解析【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles在 tsParticles 这个大型 monorepo 中粒子引擎的每种能力——shape形状、interaction交互、updater更新器、effect特效、preset预设、palette调色板、path路径、plugin插件、bundle聚合包——都以独立 npm 包的形式组织在仓库对应目录下。官方提供的tsparticles/cli-create命令名tsparticles-create就是这套体系的项目脚手架一条命令即可交互式生成一个包含完整构建配置、可发布结构的扩展工程。读完本篇你将掌握该 CLI 的安装与全部子命令用法并理解它背后提示收集 → 模板复制 → 包元数据改写 → 源码文件生成的完整实现链路从而能快速搭建符合 tsParticles 规范的自定义插件工程。一、安装与快速上手CLI 支持三种常见包管理器进行全局安装依据 cli/commands/create/README.md# NPM npm install -g tsparticles/cli-create# Yarn yarn global add tsparticles/cli-create# PNPM pnpm global add tsparticles/cli-create也可以不安装、直接用 npx 按需运行。查看帮助npx tsparticles/cli-create --help或在全局安装后tsparticles-create --help二、核心命令一览九个 create 子命令README 中定义的用法是create kind folder形式其中folder为目标目录。每个子命令对应 tsParticles 扩展体系的一种包类型子命令用途命令示例两种等价写法bundle聚合包把多个扩展打包进一个入口npx tsparticles/cli-create bundle folder/tsparticles-create bundle foldereffect特效EffectDrawer绘制在粒子之上的效果npx tsparticles/cli-create effect folderinteraction交互行为external / particles 两类npx tsparticles/cli-create interaction folderpalette调色板预设npx tsparticles/cli-create palette folderpath粒子运动路径生成器npx tsparticles/cli-create path folderplugin通用插件含 easing、export、emitters-shape、color-manager 等子类型npx tsparticles/cli-create plugin folderpreset粒子配置预设npx tsparticles/cli-create preset foldershape自定义粒子形状绘制器npx tsparticles/cli-create shape folderupdater粒子属性更新器npx tsparticles/cli-create updater folder从源码看这些子命令的注册集中在 src/create.ts它用 commander 创建了一个名为create的父命令描述为 Create a new tsParticles project然后依次addCommand挂接 9 个来自独立 workspace 包的命令对象例如 create-bundle 包中的 bundleCreateCommand、create-interaction 包中的 interactionCreateCommand、create-updater 包中的 updaterCreateCommand。值得注意的是create.ts 中还注册了一个app子命令来自 cli-command-create-app用于从框架模板生成完整的 tsParticles 应用README 未列出该命令属源码中可确认的额外能力见下文第五节。三、脚手架内部流程从交互提示到工程落盘每个子命令的动作模式高度一致以 bundle.ts 为例先调用promptProjectData收集元数据再把kind: bundle与元数据交给createProjectTemplate完成落盘。这条链路全部实现在共享包tsparticles/cli-create-utils中。3.1 交互提示阶段promptProjectDataprompt-utils.ts 基于prompts库实现了统一的交互流程目标目录getDestinationDir解析命令行传入的folder得到destinationPath名称提示询问 What is the name of the bundle?/effect?/...默认值取自目标目录名initialName destinationPath.split(path.sep).pop()且不允许为空描述提示询问描述信息默认值为目录名首字母大写仓库地址询问 repository URL可选由getRepositoryUrl提供默认值类型选择仅 interaction/plugin 等带select参数的场景追加一个 select 问题例如 interaction 子命令会给出 Generic (external particles) / External interaction / Particles interaction 三个选项默认 Generic见 interaction.ts。返回值是结构化的IProjectPromptResultdescription / destinationPath / name / repositoryUrl / type保证后续模板生成拿到的是经过 trim 的规范值。3.2 模板落盘阶段createProjectTemplatecreate-project.ts 是核心。它按kind选择对应配置生成器createBundleConfig/createEffectConfig/createInteractionConfig/createPaletteConfig/createPathConfig/createPluginConfig/createPresetConfig/createShapeConfig等每个配置生成器决定四件事npm 包名、加载函数名、rollup 构建工厂、需要生成的 src 源码文件内容。落盘过程由 template-utils.ts 提供的基础设施完成copyEmptyTemplateFiles把内置空工程模板位于 cli/commands/create-utils/files/empty-project/递归复制到目标目录并过滤掉node_modules与distupdatePackageFile/updatePackageDistFile改写package.json与package.dist.json的name、description、repository、bugs字段并把publishConfig.access置为public、移除private标记同时替换包产物文件名占位符tsparticles.empty.template.min.js→ 实际产物名runInstall/runBuild若系统存在 npm则在目标目录执行npm install与npm run build用lookpath探测命令是否可用不存在时静默跳过。3.3 空工程模板长什么样生成的工程底座是 empty-project/package.json关键信息publishConfig.directory: distlinkDirectory: true发布时只发布构建产物目录scripts 使用统一的官方构建命令build: tsparticles-build、build:ci: tsparticles-build --ci、prepack: pnpm run build依赖tsparticles/cli-build、tsparticles/rollup-plugin、tsparticles/eslint-config、tsparticles/prettier-config、tsparticles/tsconfig、tsparticles/browserslist-config等 workspace 工具包peerDependencies指向tsparticles/engine即所有扩展包都把引擎作为对等依赖模板还包含完整的 tsconfig 族tsconfig.base.json、tsconfig.browser.json、tsconfig.module.json、tsconfig.types.json与rollup.config.js使生成项目开箱即具备多入口esm/cjs/browser/types构建能力。四、各类型包的命名规范与生成代码create-project.ts中每种 kind 的生成规则是可以直接查证的事实汇总如下以目标名foo为例getNameData会把输入名归一化为 PascalCase / camelCase / kebab-case 三种形态kindnpm 包名加载函数产物文件名rollup 工厂bundletsparticles/fooloadFootsparticles.foo.bundle.min.jsloadParticlesBundleeffecttsparticles/effect-fooloadFooEffecttsparticles.effect.foo.min.jsloadParticlesEffectinteraction(external)tsparticles/interaction-external-fooloadExternalFooInteractiontsparticles.interaction.external.foo.min.jsloadParticlesInteractionExternalinteraction(particles)tsparticles/interaction-particles-fooloadParticlesFooInteractiontsparticles.interaction.particles.foo.min.jsloadParticlesInteractionParticlespalettetsparticles/palette-fooloadFooPalettetsparticles.palette.foo.min.jsloadParticlesPalettepathtsparticles/path-fooloadFooPathtsparticles.path.foo.min.jsloadParticlesPathplugintsparticles/plugin-fooloadFooPlugintsparticles.plugin.foo.min.jsloadParticlesPluginpresettsparticles/preset-fooloadFooPresettsparticles.preset.foo.min.jsloadParticlesPresetplugin 还支持 5 种子类型PluginTypecolor-manager生成IColorManager实现并注册到addColorManager、easing注册缓动函数、emitters-shape注册发射器形状生成器、export导出类插件、generic生成IPluginIContainerPlugin双类结构如PluginInstance/Plugin.ts。以 shape 为例生成器会写出一个实现IShapeDrawer风格的FooShapeDrawer类并在src/index.ts中通过engine.pluginManager.register把绘制器注册到引擎bundle 类型则额外生成src/bundle.ts入口把tsParticles与加载函数挂到globalThis.__tsParticlesInternals供浏览器script场景使用见 createBundleConfig 与 getBrowserFile。同时getRollupConfig会依据 kind 生成对应的rollup.config.js调用tsparticles/rollup-plugin中对应工厂getReadme会生成含 jsDelivr/npm 徽章的包 README并在 Usage 一节给出标准加载写法import { tsParticles } from tsparticles/engine; import { loadFoo } from tsparticles/foo; await loadFoo(tsParticles);这套生成代码与仓库中真实存在的扩展包结构一致——例如 shapes/ 下的 circle、star 等形状包、interactions/external/ 下的 repulse、attract 等交互包都遵循同样的loadXxx pluginManager.register模式生成的骨架与它们是同构的可以直接对照阅读。五、隐藏能力app 子命令与模板应用源码中注册的app子命令app.ts用于Create a new tsParticles app from a template参数与选项比其余子命令更丰富[destination]可选的目标目录缺省为tsparticles-app--framework name指定前端框架缺省自动检测框架与用法的交互式选择定义在 prompts.ts--template name指定模板可用值包括scaffold | login | portfolio | landing | tictactoe | confetti | ribbons | particles | 404对应仓库 templates/ 目录下的同名模板工程--skip-install脚手架完成后跳过npm install。执行完成后会打印引导命令cd dir、npm install若跳过安装、npm run dev。实际脚手架工作由 scaffold.ts 与 template-resolver.ts 完成。因此当你需要的是一个集成 tsParticles 的完整前端应用而非一个可发布的扩展包时app子命令是正确入口。六、构建、测试与发布脚手架命令自身的构建链在 cli/commands/create/package.json 中定义buildclear:dist prettify:src lint compile circular-deps prettify:readme其中compile为tsc -p srccircular-deps用 dependency-cruiser 校验源码无循环依赖配置来自tsparticles/depcruise-config测试使用 vitestcli/commands/create/tests/ 下包含create-shape.test.ts、create-preset.test.ts、create-plugin.test.ts等用例验证方式是把模板生成到tests/tmp-files/临时目录再断言生成的package.json名称符合预期最后清理临时目录发布层面每个生成包的package.dist.json构建后发布版本由tsparticles-build处理配合publishConfig.directory: dist保证只发布 dist 产物package.json中tagVersionPrefix: v表明版本 tag 带v前缀。七、实操清单按下面的顺序走一遍即可产出一个可发布的自定义形状包安装npm install -g tsparticles/cli-create创建npx tsparticles/cli-create shape my-shape或直接tsparticles-create shape my-shape依次回答 name / description / repository URL 提示name 默认为my-shape打开生成的工程在src/index.ts的MyShapeDrawer骨架中实现绘制逻辑替换// TODO处npm run build验证多入口构建产物为tsparticles.shape.myShape.min.js按 markdown/ 中的文档规范补全 README 后即可走 npm 发布流程。整体来看tsparticles-create的价值不在于少写几行配置而在于它把 tsParticles 扩展生态的包命名规范、engine 插件注册模式、多入口构建与发布约定固化成了模板——从源码结构看create-project.ts 中每个createXxxConfig函数就是一份活规范照着它写出来的扩展包与仓库内shapes/、interactions/、updaters/目录下的官方包在结构上完全同构。【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考