 插件、强制选项与开发服务器定制)
Wasp 自定义 Vite 配置完全指南wasp() 插件、强制选项与开发服务器定制【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/waspWasp 使用 Vite 承载客户端的开发服务器与生产构建本文基于 Wasp 0.18 版官方文档 web/versioned_docs/version-0.18/project/custom-vite-config.md系统讲解如何通过项目根目录的vite.config.{js,ts}自定义 Vite 配置。读完本文你将掌握wasp/client/vite插件的正确用法、Wasp 强制保护的核心选项以及调整开发服务器行为、端口与部署路径的完整实战方案。Wasp 与 Vite客户端构建的基石Wasp 生成的客户端是一个标准的 Vite React 应用开发阶段由 Vite 提供热更新HMR服务生产阶段由 Vite 完成打包与静态资源产出。因此Wasp 将vite.config.{js,ts}直接暴露给开发者放在项目根目录作为自定义的切入点。在 Wasp 0.18 中这份配置文件已经存在但不被 Wasp 管理它完全由你掌控。不过这份自由是有前提的——你必须在配置中导入并使用wasp/client/vite提供的wasp()插件该插件承载了 Wasp 全栈应用正常运行所需的一切关键能力全栈应用正常运行所必需的 Vite 配置环境变量校验禁止在客户端代码中导入服务端模块生产构建时的 TypeScript 类型检查。插件最终会把你的配置与 Wasp 内置默认配置做合并merge原始值以 Wasp 侧为准数组类配置则做拼接这保证了用户自定义与框架默认值可以共存。最小可用配置wasp() 插件是唯一硬性要求下面是 Wasp 0.18 的最简合法配置插件数组中的唯一成员就是wasp()import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], })import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], }):::warning 插件顺序是硬约束wasp()插件必须位于plugins数组的第一个位置其余插件如 Tailwind CSS必须排在其后。 :::这一点在仓库中得到了直接印证Wasp 官方 starter 与示例项目均严格遵循该顺序。例如 waspc/data/Cli/starters/basic/vite.config.ts 中wasp()在前、tailwindcss()在后examples/kitchen-sink/vite.config.ts 同样如此并且它还额外演示了如何在自定义配置中扩展test选项排除 e2e 测试目录——这说明自定义配置不会破坏 Wasp 的默认能力只是在其之上叠加。强制选项这些值由 Wasp 锁定不可覆盖wasp()插件的底层实现见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts定义了一组forcedOptions。如果你在自己的vite.config.{js,ts}中显式设置了其中任意一项且与 Wasp 期望值不同插件会在启动时抛出错误并提示你移除这些配置。完整清单如下选项内部值为什么不能自定义base取决于client.baseDir配置项Wasp 将 React Router 的basename设置为同一值二者必须保持一致envPrefixREACT_APP_Wasp 的环境变量校验依赖此前缀build.outDir.wasp/out/web-app/build构建产物必须落在 Wasp 部署流程期望的位置server.port动态分配Wasp 需要自行管理端口以便让服务端与客户端相互感知对方地址改用wasp start --client-port控制server.strictPorttrue若不锁定端口被占用时 Vite 会静默换端口服务端将指向错误 URLpreview.port动态分配与server.port同理但针对wasp build start运行的 preview 服务器改用wasp build start --client-port控制从源码实现看强制逻辑非常清晰throwIfOverridingForcedOptions会遍历上述选项通过getByPath读取用户配置中的对应路径一旦发现冲突就抛出包含修改建议的错误信息。例如把base设为/my-app/会得到提示要从子目录提供服务请在 Wasp 配置中设置client.baseDir设置server.port会被提示改用wasp start --client-port。这种做法避免了用户与框架配置互相覆盖导致的全栈通信错乱。插件选项reactOptions 透传wasp()插件还接受一个可选的reactOptions参数用于透传底层vitejs/plugin-react的配置——包括 Babel 插件、Fast Refresh 设置与 JSX 相关配置import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [ wasp({ reactOptions: { // 这里可以传任意 vitejs/plugin-react 的选项 }, }), ], })实战一控制开发服务器是否自动打开浏览器wasp start默认会自动唤起浏览器。通过自定义server.open选项可以控制这一行为export default { server: { open: false, }, }import { defineConfig } from vite export default defineConfig({ server: { open: false, }, })注意server.open不在强制选项之列你可以自由配置但server.port、server.strictPort属于受保护项直接设置会报错详见上表。实战二自定义开发服务器端口在 Wasp 0.18 中控制开发端口不再需要直接修改 Vite 配置官方推荐使用 CLI 参数。wasp start默认从 3000 起自动挑选第一个可用端口指定端口则使用wasp start --client-port 4000同样wasp build start运行的 preview 服务器使用wasp build start --client-port 4000这是因为server.port与preview.port都由 Wasp 动态分配源码中通过envVarAsNumber从环境变量读取端口值直接写死在 Vite 配置里会被强制选项检查拦截。实战三修改部署基础路径base path如果你希望客户端从/之外的路径提供服务Wasp 0.18 的正确做法同样是走受支持的配置入口而非直接改base它属于强制选项。在main.wasp.ts中通过client.baseDir声明import { app } from wasp.sh/spec export default app({ name: MyApp, client: { baseDir: /my-app, }, // ... })这样当应用部署在https://example.com/my-app时React Router 能正确解析路由所有静态资源也会从https://example.com/my-app加载。Wasp 会将该值同步写入 Vite 的base配置见 web/docs/project/client-config.md。:::caution 配套环境变量 设置baseDir后务必同步更新WASP_WEB_CLIENT_URL环境变量让它也包含该基础目录。例如应用托管在https://example.com/my-app则该变量应设为https://example.com/my-app而非https://example.com详见 web/docs/project/_baseDirEnvNote.md。 :::扩展添加自定义 Vite 插件wasp()之后可以自由追加第三方插件。以厨房水槽示例 examples/kitchen-sink/vite.config.ts 为蓝本常见组合如下import tailwindcss from tailwindcss/vite import { defineConfig } from vite import { wasp } from wasp/client/vite export default defineConfig({ plugins: [wasp(), tailwindcss()], })官方 starter waspc/data/Cli/starters/basic/vite.config.ts 使用的正是这一组合。除插件外你还可以自由调整server的其余行为、build的压缩与分包策略、resolve.alias等 Vite 原生能力——只要不触碰上表中的强制选项即可。小结Wasp 0.18 的 Vite 定制模型可以概括为三点wasp()插件必须第一个加载、六个关键选项被框架锁定通过client.baseDir与--client-port等受支持入口控制、其余配置自由合并。理解wasp()插件背后的强制选项检查机制waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts你就能在安全边界内充分定制开发与构建流程而不会破坏 Wasp 全栈应用的运行时约定。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wasp 自定义 Vite 配置完全指南：wasp() 插件、强制选项与开发服务器定制
Wasp 自定义 Vite 配置完全指南wasp() 插件、强制选项与开发服务器定制【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/waspWasp 使用 Vite 承载客户端的开发服务器与生产构建本文基于 Wasp 0.18 版官方文档 web/versioned_docs/version-0.18/project/custom-vite-config.md系统讲解如何通过项目根目录的vite.config.{js,ts}自定义 Vite 配置。读完本文你将掌握wasp/client/vite插件的正确用法、Wasp 强制保护的核心选项以及调整开发服务器行为、端口与部署路径的完整实战方案。Wasp 与 Vite客户端构建的基石Wasp 生成的客户端是一个标准的 Vite React 应用开发阶段由 Vite 提供热更新HMR服务生产阶段由 Vite 完成打包与静态资源产出。因此Wasp 将vite.config.{js,ts}直接暴露给开发者放在项目根目录作为自定义的切入点。在 Wasp 0.18 中这份配置文件已经存在但不被 Wasp 管理它完全由你掌控。不过这份自由是有前提的——你必须在配置中导入并使用wasp/client/vite提供的wasp()插件该插件承载了 Wasp 全栈应用正常运行所需的一切关键能力全栈应用正常运行所必需的 Vite 配置环境变量校验禁止在客户端代码中导入服务端模块生产构建时的 TypeScript 类型检查。插件最终会把你的配置与 Wasp 内置默认配置做合并merge原始值以 Wasp 侧为准数组类配置则做拼接这保证了用户自定义与框架默认值可以共存。最小可用配置wasp() 插件是唯一硬性要求下面是 Wasp 0.18 的最简合法配置插件数组中的唯一成员就是wasp()import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], })import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [wasp()], }):::warning 插件顺序是硬约束wasp()插件必须位于plugins数组的第一个位置其余插件如 Tailwind CSS必须排在其后。 :::这一点在仓库中得到了直接印证Wasp 官方 starter 与示例项目均严格遵循该顺序。例如 waspc/data/Cli/starters/basic/vite.config.ts 中wasp()在前、tailwindcss()在后examples/kitchen-sink/vite.config.ts 同样如此并且它还额外演示了如何在自定义配置中扩展test选项排除 e2e 测试目录——这说明自定义配置不会破坏 Wasp 的默认能力只是在其之上叠加。强制选项这些值由 Wasp 锁定不可覆盖wasp()插件的底层实现见 waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts定义了一组forcedOptions。如果你在自己的vite.config.{js,ts}中显式设置了其中任意一项且与 Wasp 期望值不同插件会在启动时抛出错误并提示你移除这些配置。完整清单如下选项内部值为什么不能自定义base取决于client.baseDir配置项Wasp 将 React Router 的basename设置为同一值二者必须保持一致envPrefixREACT_APP_Wasp 的环境变量校验依赖此前缀build.outDir.wasp/out/web-app/build构建产物必须落在 Wasp 部署流程期望的位置server.port动态分配Wasp 需要自行管理端口以便让服务端与客户端相互感知对方地址改用wasp start --client-port控制server.strictPorttrue若不锁定端口被占用时 Vite 会静默换端口服务端将指向错误 URLpreview.port动态分配与server.port同理但针对wasp build start运行的 preview 服务器改用wasp build start --client-port控制从源码实现看强制逻辑非常清晰throwIfOverridingForcedOptions会遍历上述选项通过getByPath读取用户配置中的对应路径一旦发现冲突就抛出包含修改建议的错误信息。例如把base设为/my-app/会得到提示要从子目录提供服务请在 Wasp 配置中设置client.baseDir设置server.port会被提示改用wasp start --client-port。这种做法避免了用户与框架配置互相覆盖导致的全栈通信错乱。插件选项reactOptions 透传wasp()插件还接受一个可选的reactOptions参数用于透传底层vitejs/plugin-react的配置——包括 Babel 插件、Fast Refresh 设置与 JSX 相关配置import { wasp } from wasp/client/vite import { defineConfig } from vite export default defineConfig({ plugins: [ wasp({ reactOptions: { // 这里可以传任意 vitejs/plugin-react 的选项 }, }), ], })实战一控制开发服务器是否自动打开浏览器wasp start默认会自动唤起浏览器。通过自定义server.open选项可以控制这一行为export default { server: { open: false, }, }import { defineConfig } from vite export default defineConfig({ server: { open: false, }, })注意server.open不在强制选项之列你可以自由配置但server.port、server.strictPort属于受保护项直接设置会报错详见上表。实战二自定义开发服务器端口在 Wasp 0.18 中控制开发端口不再需要直接修改 Vite 配置官方推荐使用 CLI 参数。wasp start默认从 3000 起自动挑选第一个可用端口指定端口则使用wasp start --client-port 4000同样wasp build start运行的 preview 服务器使用wasp build start --client-port 4000这是因为server.port与preview.port都由 Wasp 动态分配源码中通过envVarAsNumber从环境变量读取端口值直接写死在 Vite 配置里会被强制选项检查拦截。实战三修改部署基础路径base path如果你希望客户端从/之外的路径提供服务Wasp 0.18 的正确做法同样是走受支持的配置入口而非直接改base它属于强制选项。在main.wasp.ts中通过client.baseDir声明import { app } from wasp.sh/spec export default app({ name: MyApp, client: { baseDir: /my-app, }, // ... })这样当应用部署在https://example.com/my-app时React Router 能正确解析路由所有静态资源也会从https://example.com/my-app加载。Wasp 会将该值同步写入 Vite 的base配置见 web/docs/project/client-config.md。:::caution 配套环境变量 设置baseDir后务必同步更新WASP_WEB_CLIENT_URL环境变量让它也包含该基础目录。例如应用托管在https://example.com/my-app则该变量应设为https://example.com/my-app而非https://example.com详见 web/docs/project/_baseDirEnvNote.md。 :::扩展添加自定义 Vite 插件wasp()之后可以自由追加第三方插件。以厨房水槽示例 examples/kitchen-sink/vite.config.ts 为蓝本常见组合如下import tailwindcss from tailwindcss/vite import { defineConfig } from vite import { wasp } from wasp/client/vite export default defineConfig({ plugins: [wasp(), tailwindcss()], })官方 starter waspc/data/Cli/starters/basic/vite.config.ts 使用的正是这一组合。除插件外你还可以自由调整server的其余行为、build的压缩与分包策略、resolve.alias等 Vite 原生能力——只要不触碰上表中的强制选项即可。小结Wasp 0.18 的 Vite 定制模型可以概括为三点wasp()插件必须第一个加载、六个关键选项被框架锁定通过client.baseDir与--client-port等受支持入口控制、其余配置自由合并。理解wasp()插件背后的强制选项检查机制waspc/data/Generator/templates/sdk/wasp/client/vite/plugins/waspConfig.ts你就能在安全边界内充分定制开发与构建流程而不会破坏 Wasp 全栈应用的运行时约定。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
