SST项目中TypeScript模块配置的最佳实践

模块系统配置的重要性

在TypeScript项目中，tsconfig.json文件中的模块系统配置直接影响着代码的编译方式和类型检查行为。当使用SST（Serverless Stack）框架时，正确的模块配置尤为重要，因为它关系到类型系统的正常工作。

常见问题现象

许多开发者在将TypeScript项目的module选项设置为"NodeNext"时，会遇到SST类型系统失效的问题。具体表现为：

1. SST提供的类型提示消失（如sst.aws.Function显示为any类型）
2. 需要手动添加sst.config.ts到tsconfig.json的include配置中才能解析路径别名

根本原因分析

这个问题源于SST框架底层使用esbuild作为构建工具。esbuild对TypeScript模块系统的处理方式与Node.js原生模块系统有所不同：

1. esbuild期望使用"module": "ESNext"配置
2. 对应的模块解析策略应为"moduleResolution": "Bundler"

推荐配置方案

对于SST项目，建议在tsconfig.json中使用以下配置：

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

路径别名配置技巧

当需要配置路径别名时，可以这样设置：

{
  "compilerOptions": {
    "paths": {
      "@/infra": ["infra/src/index.ts"]
    }
  }
}

实际应用示例

以下是一个完整的sst.config.ts示例，展示了在正确配置下的类型系统工作状态：

import { invokeCognito } from "@/infra";

export default $config({
  app(input) {
    return {
      name: "init",
      removal: input?.stage === "production" ? "retain" : "remove",
      protect: ["production"].includes(input?.stage),
      home: "aws",
    };
  },
  async run() {
    await invokeCognito();
    const lambdaHandlerCDK = new sst.aws.Function("lambdaApiHandlerCDK", {
      handler: "functions/src/apiHandlerCDK/index.handler",
      memory: "1024 MB",
      storage: "1024 MB",
      timeout: "900 seconds",
    });
  },
});

总结

理解SST框架与TypeScript模块系统的交互方式对于项目配置至关重要。通过采用ESNext和Bundler的配置组合，可以确保SST的类型系统正常工作，同时保持代码的清晰性和可维护性。这种配置不仅解决了类型提示问题，也为项目未来的扩展奠定了良好的基础。