企业官网建设流程全解析

Wasp 全栈框架 TypeScript 支持实战：从 JavaScript 项目逐文件迁移到类型安全的 TS 全栈

【免费下载链接】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（当前仓库 waspc 与 examples 目录所对应的开源全栈框架）v0.15 官方文档 TypeScript Support 为主线，系统讲解 Wasp 框架"开箱即用"的 TypeScript 支持、如何将既有 JavaScript 项目按文件粒度平滑迁移到 TypeScript、Wasp 自动生成的实体类型与操作（Query/Action）泛型类型的工作原理，并穿插仓库源码（TodoAppTs 示例、tsconfig 模板、SDK 包）作为佐证。读完本文，你将掌握在 Wasp 项目中用 TypeScript 获得端到端（客户端 ↔ 服务端）类型安全的具体方法，以及迁移过程中常见的编辑器类型报错排查技巧。

Wasp 是一个"内置电池"的全栈 Web 框架：使用声明式.wasp文件描述应用结构，底层由 React（客户端）、Node.js（服务端）与 Prisma（数据库）驱动。TypeScript 作为 JavaScript 的超集，为这类全栈项目带来了构建期静态类型检查与 IDE 自动补全，而 Wasp 从设计之初就把 TypeScript 支持作为一等公民内置其中。

TypeScript 在 Wasp 中的定位

TypeScript 是一门为 JavaScript 增加静态类型分析能力的编程语言，它具备两个核心特性：

• 是 JavaScript 的超集：所有合法的 JavaScript 代码都是合法的 TypeScript 代码，因此你可以随时在.ts文件中书写熟悉的 JS 语法；
• 编译回 JavaScript 后再运行：Node.js 与浏览器最终执行的仍是 JavaScript，TypeScript 只是在开发期与构建期提供类型保障。

它的价值主要体现在两个方面（对应 Wasp 官方文档的表述）：

1. 在构建期捕获错误：类型系统能在代码运行之前发现大量低级错误，从而显著减少运行时错误；
2. 提供基于类型的 IDE 自动补全：编辑器可以依据类型信息推断出对象上可用的属性与方法，提升开发效率与可维护性。

在 Wasp 中，每个功能模块的文档都包含对应的 TypeScript 说明——实体（Entities）、查询（Queries）、动作（Actions）、认证（Auth）、定时任务（Jobs）等均有各自的 TS 专属章节。这意味着 TypeScript 不是 Wasp 的"附加选项"，而是渗透在框架每一个特性里的默认能力。

新建项目：什么都不用做

如果你是从零开始一个新项目，完全不需要任何额外配置：

• 只需按照你感兴趣的功能文档操作即可，文档中的代码示例通常都提供了 JavaScript / TypeScript 双版本（Tab 切换）；
• Wasp 官方建议新手从官方教程开始，教程中的代码块带有 JS/TS 语言切换开关，站点还会记住你的语言偏好；
• 教程明确说明：Wasp 开箱即用地同时支持 JavaScript 和 TypeScript，你完全可以根据需要自由选择甚至混用两者。

仓库中可找到对应的真实示例：examples/tutorials/TodoAppTs就是教程的纯 TypeScript 版本，其src目录下同时存在queries.ts、actions.ts、MainPage.tsx等 TS/TSX 源码（见 examples/tutorials/TodoAppTs/src），而examples/tutorials/TodoApp则是与之对应的 JavaScript 版本——两者并存本身就说明了 Wasp 支持 JS/TS 混用与按项目选择的灵活性。

迁移你的项目到 TypeScript：整体思路

对于已经存在的 JavaScript Wasp 项目，迁移过程出奇地简单，因为Wasp 本身自带开箱即用的 TypeScript 支持：

迁移 = 修改文件扩展名 + 使用 TypeScript 语言特性。

这种设计让你可以按文件粒度渐进式迁移：今天迁移一个queries.js，明天迁移一个组件，业务完全不受影响，main.wasp文件也不需要改动。下面先演示如何迁移单个文件，再推广到整个项目。

迁移单个文件：完整实战示例

官方文档以Task实体与getTaskInfo查询为例，演示了完整的迁移过程。我们先还原出迁移前的项目背景。

迁移前的项目背景

假设schema.prisma中定义了Task实体：

// ... model Task { id Int @id @default(autoincrement()) description String isDone Boolean }

main.wasp中声明了getTaskInfo查询，并指明其实现从@src/queries导入、操作需要用到Task实体：

query getTaskInfo { fn: import { getTaskInfo } from "@src/queries", entities: [Task] }

待迁移的src/queries.js内容如下：

import HttpError from 'wasp/server' function getInfoMessage(task) { const isDoneText = task.isDone ? 'is done' : 'is not done' return `Task '${task.description}' is ${isDoneText}.` } export const getTaskInfo = async ({ id }, context) => { const Task = context.entities.Task const task = await Task.findUnique({ where: { id } }) if (!task) { throw new HttpError(404) } return getInfoMessage(task) }

这段代码用context.entities.Task通过 Prisma Client 按id查询任务，查不到时抛出 404 错误，最后把任务格式化为一段人类可读的信息。

迁移步骤

迁移这个文件只需要两步：

1. 把文件名从queries.js改为queries.ts；
2. 编写一些类型（并可选地使用 Wasp 的 TypeScript 专属特性）。

迁移前后代码对照

迁移前（src/queries.js）：

import HttpError from '@wasp/core/HttpError.js' function getInfoMessage(task) { const isDoneText = task.isDone ? 'is done' : 'is not done' return `Task '${task.description}' is ${isDoneText}.` } export const getTaskInfo = async ({ id }, context) => { const Task = context.entities.Task const task = await Task.findUnique({ where: { id } }) if (!task) { throw new HttpError(404) } return getInfoMessage(task) }

迁移后（src/queries.ts）：

import HttpError from 'wasp/server' import { type Task } from '@wasp/entities' import { type GetTaskInfo } from '@wasp/server/operations' function getInfoMessage(task: Pick<Task, 'isDone' | 'description'>): string { const isDoneText = task.isDone ? 'is done' : 'is not done' return `Task '${task.description}' is ${isDoneText}.` } export const getTaskInfo: GetTaskInfo<Pick<Task, 'id'>, string> = async ( { id }, context ) => { const Task = context.entities.Task const task = await Task.findUnique({ where: { id } }) if (!task) { throw new HttpError(404) } return getInfoMessage(task) }

可以看到，改动非常克制：辅助函数getInfoMessage补充了入参类型Pick<Task, 'isDone' | 'description'>与返回类型string；查询实现则用GetTaskInfo<Pick<Task, 'id'>, string>标注。除此之外，函数体逻辑与迁移前一模一样。

注意：你不需要对.wasp文件做任何修改——查询声明、实体声明在迁移前后保持一致。

Wasp 的两个 TypeScript 专属特性

上述迁移后的代码用到了 Wasp 自动生成的两个类型特性，它们是理解 Wasp TypeScript 支持的关键：

1.Task实体类型：连接 Prisma 数据模型

import { type Task } from '@wasp/entities'

Task是一个代表Task实体的类型，由 Wasp 根据schema.prisma中的model Task自动生成。使用这个类型，等于把你的业务代码与数据模型定义绑定在了一起：

• 修改schema.prisma中的字段，会同步改变导入的Task类型；
• 如果代码中的对象结构跟不上模型变化，TypeScript 会立刻抛出类型错误，提醒你更新代码。

这种"类型耦合"消除了重复定义，并确保函数签名始终与实体保持一致。官方文档（Entities 文档）还特别说明：实体类型在客户端代码中同样可用——你可以在 React 组件里import { Task } from "wasp/entities"并使用const task: Task = {...}，从而让页面组件与数据模型保持类型同步。

注意：v0.15 文档示例中实体类型从@wasp/entities导入，而当前仓库主分支的示例（如 examples/tutorials/TodoAppTs/src/queries.ts）使用的是无@前缀的wasp/entities，这是不同版本间模块命名约定上的差异，迁移时以你实际安装的 Wasp 版本文档为准。

2.GetTaskInfo<...>操作泛型：全栈类型安全的基石

import { type GetTaskInfo } from '@wasp/server/operations'

GetTaskInfo<...>是 Wasp 根据main.wasp中的query getTaskInfo声明自动生成的泛型类型。当你用它标注查询实现时，编译器自动获得三类信息：

• context对象的类型：包括context.entities中可用的实体（如Task）、以及当查询使用认证时context.user的类型；
• args的类型：查询接收的载荷（payload）类型，即示例中的Pick<Task, 'id'>；
• 查询的返回类型：即示例中的string。

于是，IDE 会自动为context、args提供智能提示（Intellisense）与类型检查，函数体内误用字段会立即报错。其背后原理是：Wasp 会根据.wasp文件中的查询/动作声明，为每个操作生成一个以声明名命名的泛型类型（getFoo→GetFoo），并让context.entities的类型只包含你在entities: [...]中列出的实体——声明里没写的实体在实现中是无法访问的，这从类型层面就杜绝了"用到未声明实体"的隐患。

在 Queries 文档中还有更详细的用法：泛型接受两个可选类型参数——Input（args的类型，默认never）与Output（返回类型，默认unknown）；默认值选择得尽量宽松，如果查询不需要输入/输出，用void作为类型参数即可。另外还推荐用satisfies关键字让 TypeScript 自动推断返回类型：

const getFoo = (async (_args, context) => { const foos = await context.entities.Foo.findMany() return { foos, message: 'Here are some foos!', queriedAt: new Date(), } }) satisfies GetFoo

这样 TypeScript 既能校验context类型，又能自动推断返回结构为{ foos: Foo[], message: string, queriedAt: Date }。

迁移示例在真实仓库中的落地

仓库中的examples/tutorials/TodoAppTs是上述迁移思路的完整落地。以 examples/tutorials/TodoAppTs/src/queries.ts 为例：

import type { Task } from "wasp/entities"; import { HttpError } from "wasp/server"; import type { GetTasks } from "wasp/server/operations"; export const getTasks: GetTasks<void, Task[]> = async (args, context) => { if (!context.user) { throw new HttpError(401); } return context.entities.Task.findMany({ where: { user: { id: context.user.id } }, orderBy: { id: "asc" }, }); };

这段代码用GetTasks<void, Task[]>标注了"无输入参数、返回Task数组"的签名，并且context.user的存在说明getTasks是一个需要认证的查询——这些信息全部由 Wasp 生成的类型自动提供。对应的客户端组件 examples/tutorials/TodoAppTs/src/MainPage.tsx 则演示了全栈类型安全的效果：

import { createTask, getTasks, updateTask, useQuery } from "wasp/client/operations"; import type { Task } from "wasp/entities"; export const MainPage = ({ user }: { user: AuthUser }) => { const { data: tasks, isLoading, error } = useQuery(getTasks); // tasks 的类型由服务端 getTasks 的返回类型自动推断而来 ... };

这里无需为useQuery(getTasks)的结果手动标注任何类型——客户端看到的返回类型总是与服务端实现一致，这正是官方文档强调的 "full-stack type safety"：类型在客户端和服务端永远保持同步。createTask({ description })与updateTask({ id, isDone })的载荷类型同样由服务端 Action 的类型推导而来，客户端传入错误的参数结构会直接编译报错。

迁移项目的其余部分：三步法推广

单个文件的迁移套路可以推广到整个项目。Wasp 允许你渐进式、按文件粒度地迁移，JS 与 TS 文件可以长期共存（main.wasp中@src/queries这样的导入甚至不需要因为扩展名改变而改动，Wasp 的模块解析会正确处理）。当你想要迁移某个文件时，遵循如下三步：

1. 修改文件扩展名：把.js改为.ts（若涉及 JSX 语法则改为.tsx）；
2. 修复类型错误：运行类型检查（或依赖编辑器提示）修复strict模式下的类型错误，为args、context、辅助函数等补上类型标注；
3. 查阅 Wasp 文档，决定要使用哪些 TypeScript 特性：例如为本文件引入Task实体类型、GetTaskInfo等操作泛型，或者在前端组件中使用自动推断的类型。

每迁移完一个文件，你的项目就多一分类型安全，且整个过程不影响其他仍为 JavaScript 的文件。

迁移后的 TypeScript 工程配置

从源码结构看，Wasp 的 TypeScript 支持是由框架自动生成的多个tsconfig协同完成的。以 TodoAppTs 为例，项目根目录的 tsconfig.json 只负责组织项目引用：

{ "files": [], "references": [ { "path": "./tsconfig.src.json" }, { "path": "./tsconfig.wasp.json" } ] }

其中面向开发者源码的 tsconfig.src.json 采用相当严格的配置（strict: true、jsx: preserve、moduleResolution: bundler等），并把src与.wasp/out/types/app（Wasp 生成的类型目录）一起纳入编译范围：

{ "compilerOptions": { "module": "esnext", "composite": true, "target": "esnext", "moduleResolution": "bundler", "jsx": "preserve", "strict": true, "esModuleInterop": true, "isolatedModules": true, "moduleDetection": "force", "lib": ["dom", "dom.iterable", "esnext"], "skipLibCheck": true, "allowJs": true, "outDir": ".wasp/out/user", "types": ["react", "node"] }, "include": ["src", ".wasp/out/types/app"], "exclude": ["**/*.wasp.ts"] }

另一方面，Wasp 生成代码（如服务端模板）使用的 tsconfig.json 模板 则体现了框架自身的取舍：它继承自@tsconfig/node{version}/tsconfig.json，显式关闭strict、开启allowJs，注释中写道"在实现更完整的 TypeScript 支持之前覆盖此项"。这也从侧面印证：严格类型检查主要面向开发者自己的src源码，Wasp 生成的脚手架代码则保持相对宽松，让迁移初期不会因为框架内部代码而报错。

自动生成的类型来自哪里

Wasp 的实体类型与操作泛型并不是魔法，而是框架在wasp start/wasp build时根据你的schema.prisma与main.wasp动态生成的。生成物被打包为类似 SDK 的模块，例如：

• wasp/entities：根据 Prisma 模型生成的实体类型；
• wasp/server/operations：根据query/action声明生成的操作泛型类型（如GetTaskInfo、GetTasks）及操作包装器；
• wasp/client/operations：客户端可调用的查询/动作函数（含useQuery钩子）。

对应模板可以在仓库的waspc/data/Generator/templates/sdk/wasp/目录下找到（如 sdk/wasp/package.json、server/operations/wrappers.ts等），Wasp 编译时会把这些模板结合你的声明文件实例化到项目内的.wasp/out目录。也正因如此，在wasp start首次运行（生成类型）之前，编辑器可能暂时无法解析wasp/entities等模块——这是预期行为，生成完成后即恢复。

迁移后的常见问题：LSP 与编辑器类型报错

官方文档在迁移指南末尾附加了一条重要的编辑器注意事项（见 web/versioned_docs/version-0.15/_TypescriptServerNote.md）：

LSP 问题警告：使用 TypeScript 时，即使wasp start正在运行，你的编辑器有时仍会报告类型错误或导入错误。

这是因为 Wasp 会动态重新生成类型文件（.wasp/out），而编辑器的 TypeScript Language Server 可能与当前代码状态失同步——类型文件更新了，但语言服务器仍缓存着旧版本。解决方案是手动重启语言服务器：

• 如果你使用 VS Code，打开命令面板（Command Palette）并选择"TypeScript: Restart TS Server"；
• 打开命令面板的快捷键：Windows / Linux 为Ctrl+Shift+P，macOS 为Cmd+Shift+P。

这一技巧在迁移阶段尤其实用：每当你改了schema.prisma或main.wasp后（实体字段、操作声明发生变化），若编辑器出现"莫名"的报错，先重启 TS Server 通常能立刻解决。

小结

Wasp 的 TypeScript 支持遵循"约定优于配置"的原则：

• 零配置起步：新项目开箱即用，JS/TS 可自由混用；
• 渐进式迁移：逐文件改扩展名、补类型即可，main.wasp无需改动；
• 全栈类型安全：wasp/entities的实体类型与wasp/server/operations的操作泛型，让客户端调用的载荷与返回类型永远和服务端实现同步；
• 源码级佐证：TodoAppTs 示例（src/queries.ts、src/MainPage.tsx）展示了生产可用的写法，生成模板（sdk 模板、服务端 tsconfig 模板）揭示了类型的生成机制。

按照"改扩展名 → 修类型错误 → 按需选用 Wasp TS 特性"的三步流程，你可以让整个 Wasp 项目在不中断开发的情况下平滑过渡到 TypeScript，享受构建期错误捕获与 IDE 智能补全带来的长期收益。

【免费下载链接】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