Wasp 0.18 App 声明完全指南自定义标题、Head 与各组件配置【免费下载链接】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本指南围绕 Wasp 0.18 版本app声明的完整配置展开。app是每个 Wasp 项目中唯一的顶层声明它集中定义应用的标题、HTMLhead内容以及认证、客户端、服务端、数据库、邮件发送与 WebSocket 等组件的配置入口。读完本文你将掌握app声明的全部字段语义、常见自定义场景如修改浏览器标签页标题、注入第三方样式表与脚本并能对照源码理解每个字段在 Wasp 编译与代码生成链路中的真实作用。为什么需要app声明在 Wasp 的声明式模型中一个项目有且仅有一个app类型声明。它是整个应用的总配置入口——无论是页面page、路由route、查询query、操作action还是实体entity最终都服务于这个app定义的上下文。从编译器的角度看app声明会被解析为一个结构化的 App 对象。在 waspc/src/Wasp/AppSpec/App.hs 中可以看到它的数据定义data App App { wasp :: Wasp, title :: String, deployment :: Maybe Deployment, head :: Maybe [String], auth :: Maybe Auth, server :: Maybe Server, client :: Maybe Client, db :: Maybe Db, emailSender :: Maybe EmailSender, webSocket :: Maybe WebSocket }也就是说app声明在内部被拆分为十个字段wasp编译器版本要求、title标题、deployment部署模式、head头部注入内容、auth认证、server服务端、client客户端、db数据库、emailSender邮件发送与webSocketWebSocket。除wasp和title外其余字段均为可选Maybe类型这正是只配置你需要的那部分这一设计哲学在类型层面的体现。一个最小的app声明app todoApp { wasp: { version: ^0.18.0 }, title: ToDo App, head: [ link rel\stylesheet\ href\https://fonts.googleapis.com/css?familyRoboto:300,400,500displayswap\ / ] }修改应用标题浏览器标签页中 favicon 旁边显示的标题正是由app声明的title字段控制的。修改它只需要改动一行app myApp { wasp: { version: ^0.18.0 }, title: BookFace }需要留意的是title是必填字段在 App.hs 中它的类型是String而非Maybe String因此每个app声明都必须显式提供。标题最终会写入生成应用的 HTML 文档标题中与 favicon 一同展示在浏览器标签页上。向head添加额外内容如果你需要引入额外的样式表、脚本或 meta 标签可以将它们以字符串形式添加到head字段。head是一个字符串数组每个元素对应一行将被注入 HTML 文档head的内容app myApp { wasp: { version: ^0.18.0 }, title: My App, head: [ // optional link rel\stylesheet\ href\https://fonts.googleapis.com/css?familyRoboto:300,400,500displayswap\ /, script src\https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.9.3/Chart.min.js\/script, meta name\viewport\ content\minimum-scale1, initial-scale1, widthdevice-width\ / ] }常见用途包括引入第三方字体如 Google Fonts加载 CDN 上的 JS 库如 Chart.js覆盖或补充 viewport、description 等 meta 信息设置自定义 faviconlink relicon href/favicon.ico /。从源码结构看head :: Maybe [String]App.hs决定了它是一个可选的字符串列表——不配置时生成器不会注入任何额外头部内容配置后按数组顺序逐行写入。一个来自仓库的实例在当前仓库的示例 examples/ask-the-documents/main.wasp.ts 中可以找到真实项目对title与head的组合使用export default app({ name: askTheDocuments, wasp: { version: 0.26.0 }, title: PG Vector Example, head: [link relicon href/favicon.ico /], // ... });注意当前仓库示例已迁移到基于wasp.sh/spec的 TypeScript Spec 格式main.wasp.ts而 0.18 文档讲解的是经典.waspDSL。两者在声明能力上是一一对应的name/title/head等字段的语义完全一致只是书写语法不同。本指南以 0.18 的 DSL 语法为准。app声明 API 参考app声明支持的全部字段如下app todoApp { wasp: { version: ^0.18.0 }, title: ToDo App, head: [ link rel\stylesheet\ href\https://fonts.googleapis.com/css?familyRoboto:300,400,500displayswap\ / ], auth: { // ... }, client: { // ... }, server: { // ... }, db: { // ... }, emailSender: { // ... }, webSocket: { // ... } }字段逐项说明wasp: dict必填Wasp 编译器配置。它是一个字典目前只包含一个字段version: string必填声明该应用兼容的 Wasp 版本范围。取值必须是合法的 SemVer 范围如^0.18.0。在 waspc/src/Wasp/AppSpec/App/Wasp.hs 中Wasp数据结构只有一个version :: String字段与文档描述完全吻合。需要注意目前version字段只支持 caret 范围即^x.y.z形式完整的 SemVer 规范支持将在未来版本中提供。如果填写的版本不兼容Wasp 编译器会拒绝编译该应用。title: string必填应用标题显示在浏览器标签页中 favicon 旁边。head: [string]可选要注入 HTML 文档head的额外行如link或script标签列表。其余字段均为可选各自有独立文档章节字段类型用途深入阅读authdict认证配置authentication 章节clientdict客户端配置client configuration 章节serverdict服务端配置server configuration 章节dbdict数据库配置database configuration 章节emailSenderdict邮件发送配置email sending 章节webSocketdictWebSocket 配置WebSocket 章节从源码理解各组件的可选性设计App数据类型中auth、server、client、db、emailSender、webSocket全部是Maybe包装的可选值App.hs。这意味着你可以只声明titlehead构建一个不带认证、不带自定义服务端配置的最简应用也可以逐步叠加auth、client、server等配置块让应用能力渐进增强。client字段的底层能力在 waspc/src/Wasp/AppSpec/App/Client.hs 中可以看到client字典实际支持的能力data Client Client { setupFn :: Maybe ExtImport, -- 客户端初始化函数如导入 CSS rootComponent :: Maybe ExtImport, -- 根组件如自定义 Layout baseDir :: Maybe String, -- 客户端代码目录如 /client envValidationSchema :: Maybe ExtImport -- 客户端环境变量校验 schema }server字段的底层能力同理waspc/src/Wasp/AppSpec/App/Server.hs 揭示了服务端配置块的内部结构data Server Server { setupFn :: Maybe ExtImport, -- 服务端启动前执行的 setup 函数 middlewareConfigFn :: Maybe ExtImport, -- 中间件配置函数 envValidationSchema :: Maybe ExtImport -- 服务端环境变量校验 schema }这些子字段的语义与对应文档章节client-config、server-config中的说明一致读者在深入配置client/server时可以直接对照源码确认每个键的职责。实战配置一个带认证与自定义根组件的应用将上面的知识点组合起来一个较完整的app声明如下app myApp { wasp: { version: ^0.18.0 }, title: BookFace, head: [ link rel\stylesheet\ href\https://fonts.googleapis.com/css?familyRoboto:300,400,500displayswap\ /, meta name\viewport\ content\minimum-scale1, initial-scale1, widthdevice-width\ / ], auth: { userEntity: User, methods: { usernameAndPassword: {} }, onAuthFailedRedirectTo: /login }, client: { rootComponent: App }, server: { setupFn: myServerSetup }, db: { system: PostgreSQL } }配置要点auth.userEntity指向在entity中声明的用户实体methods.usernameAndPassword启用用户名密码登录client.rootComponent引用src/下的 React 根组件用于包裹所有页面server.setupFn指向服务端初始化逻辑适合在启动时执行数据库种子或环境检查db.system指定数据库系统例如PostgreSQL或SQLite。小结app声明是 Wasp 项目唯一的顶层配置入口每个项目只能有一个title与wasp.version为必填head与auth/client/server/db/emailSender/webSocket均为可选修改标题、注入样式与脚本是最常见的两种自定义操作只需改动title和head两个字段编译器内部通过 App.hs 中的App数据类型承载这些配置Maybe字段设计保证了按需配置、最小可用想深入了解某个组件块的完整配置项请按上文表格进入对应文档章节想直接查看真实项目写法可参考 examples/tutorials/TodoApp/main.wasp.ts 与 examples/ask-the-documents/main.wasp.ts后者为新版 TypeScript Spec 语法。【免费下载链接】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），仅供参考
