Wasp Basic Starter 模板实战用声明式全栈框架从零搭建带邮箱认证的 ToDo 应用【免费下载链接】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 官方开源的Basic Starter模板位于仓库 waspc/data/Cli/starters/basic完整讲解如何使用 Wasp CLI 从该模板创建项目、配置开发环境并启动一个包含邮箱认证、任务Task与标签Tag管理的 ToDo 全栈应用。读完本文你将掌握wasp new脚手架创建、wasp db migrate-dev数据库迁移、wasp start一键启动的完整开发工作流并通过逐文件剖析模板源码理解 Wasp 中app/page/route/query/action/实体Entity等声明式核心概念的真实调用关系。Basic Starter 是 Wasp 提供的一个“小而全”的入门模板项目描述将其定位为 “a well-rounded template that showcases the most important bits of working with Wasp”即它不是为了演示某个单一特性而是把 Wasp 最关键的开发要素认证、数据建模、查询/操作、页面路由、前端组件一次性打包让新手在最短时间内看到一套完整全栈应用的组织方式。一、前置准备Node.js 与 Wasp CLI在创建项目之前需要保证本机具备两个基础环境Node.js模板官方建议安装最新的 LTS 版本并推荐通过 Node 版本管理器例如nvm来安装方便在不同项目间切换 Node 版本。Wasp CLI通过 npm 全局安装最新版npm i -g wasp.sh/wasp-clilatest安装完成后CLI 会负责后续的模板拉取、代码生成、依赖安装与本地服务启动等全部工作。二、创建项目wasp new的两种等价写法Basic Starter 模板可以直接通过 Wasp CLI 的new命令创建新项目官方 README 给出了两种写法wasp new project-name # 或显式指定模板 wasp new project-name -t basic不带-t参数的写法会走 CLI 的默认 starter 流程带-t basic的写法则显式声明使用 Basic Starter 模板。两种方式最终生成的项目结构一致均以模板目录 waspc/data/Cli/starters/basic 为蓝本生成。值得留意的是模板内部存在一批占位符——如 main.wasp.ts 中的__waspAppName__、__waspVersion__、__waspProjectName__以及 package.json 中的__waspSpecPackageSpecifier__——这些占位符会在 CLI 生成项目时被替换为实际的项目名、Wasp 版本号与 spec 包版本这也是模板可以被任意项目复用的关键机制。三、开发启动四步走install → migrate-dev → start模板 README 给出了一套标准的本地开发流程从克隆/生成项目到浏览器访问应用只需四步安装项目依赖wasp install执行数据库迁移将数据模型同步到最新迁移版本wasp db migrate-dev启动 Wasp 应用wasp start访问前端应用默认运行在localhost:3000在浏览器中打开即可使用客户端界面。这条链路与仓库中其他示例如 examples/ask-the-documents/README.md、examples/kitchen-sink/README.md保持一致是 Wasp 项目统一的开发模式。此外官方建议安装 Wasp 的 VSCode 扩展来增强开发体验提供.wasp.ts声明文件的高亮、补全等能力。四、模板骨架解剖声明式main.wasp.tsBasic Starter 的核心声明文件是 main.wasp.ts整个应用的定义全部浓缩在这里。它导出一个app({...})配置对象包含以下几个关键区段应用基础信息name、wasp.version、title、head示例中注入了一个 favicon 引用认证配置auth绑定User实体启用邮箱密码认证配置发件人信息fromField、注册自定义字段userSignupFields、邮箱验证与密码重置对应的客户端路由并设置了认证成功/失败后的跳转路径onAuthSucceededRedirectTo: /、onAuthFailedRedirectTo: /login邮件发送emailSender默认使用provider: Dummy即本地开发阶段不会真正发信方便直接上手客户端根组件client.rootComponent指向 src/App.tsxspec 声明列表将tasksSpec、tagsSpec两个业务子模块的 spec 并入主应用并声明了登录、注册、请求重置密码、重置密码、邮箱验证 5 个认证相关路由。认证相关的 5 个路由分别绑定到 src/auth/email 目录下的 5 个页面组件LoginPage、SignupPage、RequestPasswordResetPage、PasswordResetPage、EmailVerificationPage并统一复用 src/auth/AuthLayout.tsx 作为认证页面布局。五、数据模型schema.prisma中的 User / Task / Tag模板的数据层使用 Prisma Schema 定义见 schema.prisma。默认数据源为SQLiteprovider sqlite连接串取自DATABASE_URL环境变量这意味着零外部依赖即可跑通全栈开发。Schema 定义了三个模型及它们之间的关联关系模型关键字段关联UseridUUID 主键、username拥有tasks、tags一对多关系Taskid、description、isDone默认false、createdAt默认now()通过userId关联 User与 Tag 为多对多Tagid、name唯一、color通过userId关联 User与 Task 为多对多Task与Tag之间通过各自维护的tags/tasks数组字段形成多对多关系配合 src/tasks/queries.ts 中的include查询可以在一次查询中把任务连同其标签一起取出。六、业务逻辑queries 与 actions 中的实体权限与数据守卫模板的业务逻辑被拆成两个清晰的子模块任务tasks与标签tags每个子模块各有一个声明式 spec 文件、一组操作实现文件和一组查询实现文件。6.1 任务子模块任务模块的声明见 src/tasks/task.wasp.tsexport const tasksSpec: Spec [ route(TasksRoute, /, page(TasksPage, { authRequired: true })), query(getTasks, { entities: [Task, Tag] }), action(createTask, { entities: [Task] }), action(updateTaskStatus, { entities: [Task] }), action(deleteCompletedTasks, { entities: [Task] }), ];这里展现了 Wasp 的核心模式根路由/指向TasksPage并设置authRequired: true——未登录用户访问会被重定向到登录页query/action声明通过entities数组显式声明操作涉及的实体Wasp 会据此自动生成类型安全的context.entitiesAPI。查询实现 src/tasks/queries.ts 中定义了一个带标签的复合返回类型export type TaskWithTags Task { tags: Tag[] };getTasks在查询前先检查context.user未登录直接抛出HttpError(401)随后按createdAt倒序返回当前用户的任务并include按名称升序排列的标签。这种“先鉴权、再按用户过滤”的写法是 Wasp 操作的标准姿势。操作实现 src/tasks/actions.ts 包含三个 action均以HttpError(401)做登录守卫createTask接收{ description, tagIds }将新任务挂到当前用户名下并关联指定标签tags.connect按 id 批量关联updateTaskStatus按id更新任务的isDone状态deleteCompletedTasks批量删除当前用户所有isDone: true的任务deleteManyuserId过滤。6.2 标签子模块标签模块的声明见 src/tags/tags.wasp.ts只包含一个查询和一个操作export const tagsSpec: Spec [ query(getTags, { entities: [Tag] }), action(createTag, { entities: [Tag] }), ];对应的实现 src/tags/actions.ts 中createTag接收{ name, color }并同样以context.user鉴权后创建归属当前用户的标签。配合 src/tags/components/colors.ts 中预置的颜色选项前端可以用 ColorRadioButton 组件让用户为标签挑选颜色。七、前端页面Tailwind react-hook-form 的任务管理界面前端入口 src/App.tsx 挂载整个应用核心业务页 src/tasks/TasksPage.tsx 接收userAuthUser属性直接以user.username渲染个性化标题并组合两个功能区块顶部“新建任务”表单区对应 CreateTaskForm.tsx任务列表区对应 TaskList.tsx含单条任务组件 TaskListItem.tsx。整个模板的 UI 层采用Tailwind CSS 4 react-hook-form组合并封装了可复用的基础组件Button.tsx、Dialog.tsx、Header.tsx、Input.tsx。前端依赖可以在 package.json 中看到全貌React 19、react-dom 19、react-router 8、tailwind-merge、Tailwind 4、Vite 8以及开发期使用的 Prisma 5.19、TypeScript 6、ESLint 9 与 Prettier含 tailwindcss 排序插件并配置了 npm workspaces 将.wasp/out生成的 SDK 纳入统一依赖管理。八、认证细节邮箱登录 自定义注册字段校验模板的邮箱认证并不只是“开箱即用”的默认配置它还演示了如何扩展注册字段。userSignupFields.ts 通过defineUserSignupFields为注册流程增加username字段的自定义校验export const userSignupFields defineUserSignupFields({ username: (data) { if (typeof data.username ! string) { throw new Error(Username is required.); } if (data.username.length 6) { throw new Error(Username must be at least 6 characters long.); } return data.username; }, });这段代码说明了两点其一Wasp 允许在声明层自由追加注册表单字段其二字段级校验可以直接写在服务端函数里校验失败时抛出Error即可阻止注册。由于 main.wasp.ts 中邮箱验证与密码重置都配置了对应的客户端路由模板完整覆盖了“注册 → 邮箱验证 → 登录 → 忘记密码重置”的整套认证闭环。九、延伸阅读从模板到深入 Wasp 的路线图Basic Starter 是一个理想的“最小完整样本”吃透它之后可以顺着仓库继续深入了解wasp new、wasp db migrate-dev、wasp db studio等更多 CLI 命令的细节参见 web/docs/general/cli.md想从零完整走一遍教程可阅读 web/docs/tutorial/01-create.md 起的系列章节它与本模板的教学定位一脉相承想深入认证、CRUD、Jobs、邮件等进阶特性参见 web/docs/auth/overview.md 与 web/docs/advanced 目录仓库中还有更复杂的官方示例可作为对照功能最全的 examples/kitchen-sink、带看板形态的 examples/waspello、以及 examples/ask-the-documents、examples/websockets-realtime-voting 等分别演示了文档问答与 WebSocket 实时投票等不同能力。总结Basic Starter 的价值在于用最小体量串起了 Wasp 全栈开发的完整链路wasp new生成项目、wasp install安装依赖、wasp db migrate-dev建立数据表、wasp start一键起服务再通过声明式main.wasp.ts把认证、路由、查询、操作与 Prisma 数据模型组织成一个可运行、可扩展的真实应用。对刚接触 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 Basic Starter 模板实战：用声明式全栈框架从零搭建带邮箱认证的 ToDo 应用
Wasp Basic Starter 模板实战用声明式全栈框架从零搭建带邮箱认证的 ToDo 应用【免费下载链接】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 官方开源的Basic Starter模板位于仓库 waspc/data/Cli/starters/basic完整讲解如何使用 Wasp CLI 从该模板创建项目、配置开发环境并启动一个包含邮箱认证、任务Task与标签Tag管理的 ToDo 全栈应用。读完本文你将掌握wasp new脚手架创建、wasp db migrate-dev数据库迁移、wasp start一键启动的完整开发工作流并通过逐文件剖析模板源码理解 Wasp 中app/page/route/query/action/实体Entity等声明式核心概念的真实调用关系。Basic Starter 是 Wasp 提供的一个“小而全”的入门模板项目描述将其定位为 “a well-rounded template that showcases the most important bits of working with Wasp”即它不是为了演示某个单一特性而是把 Wasp 最关键的开发要素认证、数据建模、查询/操作、页面路由、前端组件一次性打包让新手在最短时间内看到一套完整全栈应用的组织方式。一、前置准备Node.js 与 Wasp CLI在创建项目之前需要保证本机具备两个基础环境Node.js模板官方建议安装最新的 LTS 版本并推荐通过 Node 版本管理器例如nvm来安装方便在不同项目间切换 Node 版本。Wasp CLI通过 npm 全局安装最新版npm i -g wasp.sh/wasp-clilatest安装完成后CLI 会负责后续的模板拉取、代码生成、依赖安装与本地服务启动等全部工作。二、创建项目wasp new的两种等价写法Basic Starter 模板可以直接通过 Wasp CLI 的new命令创建新项目官方 README 给出了两种写法wasp new project-name # 或显式指定模板 wasp new project-name -t basic不带-t参数的写法会走 CLI 的默认 starter 流程带-t basic的写法则显式声明使用 Basic Starter 模板。两种方式最终生成的项目结构一致均以模板目录 waspc/data/Cli/starters/basic 为蓝本生成。值得留意的是模板内部存在一批占位符——如 main.wasp.ts 中的__waspAppName__、__waspVersion__、__waspProjectName__以及 package.json 中的__waspSpecPackageSpecifier__——这些占位符会在 CLI 生成项目时被替换为实际的项目名、Wasp 版本号与 spec 包版本这也是模板可以被任意项目复用的关键机制。三、开发启动四步走install → migrate-dev → start模板 README 给出了一套标准的本地开发流程从克隆/生成项目到浏览器访问应用只需四步安装项目依赖wasp install执行数据库迁移将数据模型同步到最新迁移版本wasp db migrate-dev启动 Wasp 应用wasp start访问前端应用默认运行在localhost:3000在浏览器中打开即可使用客户端界面。这条链路与仓库中其他示例如 examples/ask-the-documents/README.md、examples/kitchen-sink/README.md保持一致是 Wasp 项目统一的开发模式。此外官方建议安装 Wasp 的 VSCode 扩展来增强开发体验提供.wasp.ts声明文件的高亮、补全等能力。四、模板骨架解剖声明式main.wasp.tsBasic Starter 的核心声明文件是 main.wasp.ts整个应用的定义全部浓缩在这里。它导出一个app({...})配置对象包含以下几个关键区段应用基础信息name、wasp.version、title、head示例中注入了一个 favicon 引用认证配置auth绑定User实体启用邮箱密码认证配置发件人信息fromField、注册自定义字段userSignupFields、邮箱验证与密码重置对应的客户端路由并设置了认证成功/失败后的跳转路径onAuthSucceededRedirectTo: /、onAuthFailedRedirectTo: /login邮件发送emailSender默认使用provider: Dummy即本地开发阶段不会真正发信方便直接上手客户端根组件client.rootComponent指向 src/App.tsxspec 声明列表将tasksSpec、tagsSpec两个业务子模块的 spec 并入主应用并声明了登录、注册、请求重置密码、重置密码、邮箱验证 5 个认证相关路由。认证相关的 5 个路由分别绑定到 src/auth/email 目录下的 5 个页面组件LoginPage、SignupPage、RequestPasswordResetPage、PasswordResetPage、EmailVerificationPage并统一复用 src/auth/AuthLayout.tsx 作为认证页面布局。五、数据模型schema.prisma中的 User / Task / Tag模板的数据层使用 Prisma Schema 定义见 schema.prisma。默认数据源为SQLiteprovider sqlite连接串取自DATABASE_URL环境变量这意味着零外部依赖即可跑通全栈开发。Schema 定义了三个模型及它们之间的关联关系模型关键字段关联UseridUUID 主键、username拥有tasks、tags一对多关系Taskid、description、isDone默认false、createdAt默认now()通过userId关联 User与 Tag 为多对多Tagid、name唯一、color通过userId关联 User与 Task 为多对多Task与Tag之间通过各自维护的tags/tasks数组字段形成多对多关系配合 src/tasks/queries.ts 中的include查询可以在一次查询中把任务连同其标签一起取出。六、业务逻辑queries 与 actions 中的实体权限与数据守卫模板的业务逻辑被拆成两个清晰的子模块任务tasks与标签tags每个子模块各有一个声明式 spec 文件、一组操作实现文件和一组查询实现文件。6.1 任务子模块任务模块的声明见 src/tasks/task.wasp.tsexport const tasksSpec: Spec [ route(TasksRoute, /, page(TasksPage, { authRequired: true })), query(getTasks, { entities: [Task, Tag] }), action(createTask, { entities: [Task] }), action(updateTaskStatus, { entities: [Task] }), action(deleteCompletedTasks, { entities: [Task] }), ];这里展现了 Wasp 的核心模式根路由/指向TasksPage并设置authRequired: true——未登录用户访问会被重定向到登录页query/action声明通过entities数组显式声明操作涉及的实体Wasp 会据此自动生成类型安全的context.entitiesAPI。查询实现 src/tasks/queries.ts 中定义了一个带标签的复合返回类型export type TaskWithTags Task { tags: Tag[] };getTasks在查询前先检查context.user未登录直接抛出HttpError(401)随后按createdAt倒序返回当前用户的任务并include按名称升序排列的标签。这种“先鉴权、再按用户过滤”的写法是 Wasp 操作的标准姿势。操作实现 src/tasks/actions.ts 包含三个 action均以HttpError(401)做登录守卫createTask接收{ description, tagIds }将新任务挂到当前用户名下并关联指定标签tags.connect按 id 批量关联updateTaskStatus按id更新任务的isDone状态deleteCompletedTasks批量删除当前用户所有isDone: true的任务deleteManyuserId过滤。6.2 标签子模块标签模块的声明见 src/tags/tags.wasp.ts只包含一个查询和一个操作export const tagsSpec: Spec [ query(getTags, { entities: [Tag] }), action(createTag, { entities: [Tag] }), ];对应的实现 src/tags/actions.ts 中createTag接收{ name, color }并同样以context.user鉴权后创建归属当前用户的标签。配合 src/tags/components/colors.ts 中预置的颜色选项前端可以用 ColorRadioButton 组件让用户为标签挑选颜色。七、前端页面Tailwind react-hook-form 的任务管理界面前端入口 src/App.tsx 挂载整个应用核心业务页 src/tasks/TasksPage.tsx 接收userAuthUser属性直接以user.username渲染个性化标题并组合两个功能区块顶部“新建任务”表单区对应 CreateTaskForm.tsx任务列表区对应 TaskList.tsx含单条任务组件 TaskListItem.tsx。整个模板的 UI 层采用Tailwind CSS 4 react-hook-form组合并封装了可复用的基础组件Button.tsx、Dialog.tsx、Header.tsx、Input.tsx。前端依赖可以在 package.json 中看到全貌React 19、react-dom 19、react-router 8、tailwind-merge、Tailwind 4、Vite 8以及开发期使用的 Prisma 5.19、TypeScript 6、ESLint 9 与 Prettier含 tailwindcss 排序插件并配置了 npm workspaces 将.wasp/out生成的 SDK 纳入统一依赖管理。八、认证细节邮箱登录 自定义注册字段校验模板的邮箱认证并不只是“开箱即用”的默认配置它还演示了如何扩展注册字段。userSignupFields.ts 通过defineUserSignupFields为注册流程增加username字段的自定义校验export const userSignupFields defineUserSignupFields({ username: (data) { if (typeof data.username ! string) { throw new Error(Username is required.); } if (data.username.length 6) { throw new Error(Username must be at least 6 characters long.); } return data.username; }, });这段代码说明了两点其一Wasp 允许在声明层自由追加注册表单字段其二字段级校验可以直接写在服务端函数里校验失败时抛出Error即可阻止注册。由于 main.wasp.ts 中邮箱验证与密码重置都配置了对应的客户端路由模板完整覆盖了“注册 → 邮箱验证 → 登录 → 忘记密码重置”的整套认证闭环。九、延伸阅读从模板到深入 Wasp 的路线图Basic Starter 是一个理想的“最小完整样本”吃透它之后可以顺着仓库继续深入了解wasp new、wasp db migrate-dev、wasp db studio等更多 CLI 命令的细节参见 web/docs/general/cli.md想从零完整走一遍教程可阅读 web/docs/tutorial/01-create.md 起的系列章节它与本模板的教学定位一脉相承想深入认证、CRUD、Jobs、邮件等进阶特性参见 web/docs/auth/overview.md 与 web/docs/advanced 目录仓库中还有更复杂的官方示例可作为对照功能最全的 examples/kitchen-sink、带看板形态的 examples/waspello、以及 examples/ask-the-documents、examples/websockets-realtime-voting 等分别演示了文档问答与 WebSocket 实时投票等不同能力。总结Basic Starter 的价值在于用最小体量串起了 Wasp 全栈开发的完整链路wasp new生成项目、wasp install安装依赖、wasp db migrate-dev建立数据表、wasp start一键起服务再通过声明式main.wasp.ts把认证、路由、查询、操作与 Prisma 数据模型组织成一个可运行、可扩展的真实应用。对刚接触 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），仅供参考