@geekmidas/cloud

中文文档
9.6.1发布于 2026/11/16TypeScriptESM + CJS构建来源已验证近 30 天下载 1.3万

SST (ion / Pulumi) integration for @geekmidas apps — opinionated, linkable constructs that map 1:1 to deployable units and validate their environment before deploy, plus the runtime helpers that resolve linked resources into environment variables.

原始使用文档
文档目录8 节
  1. Install
  2. @geekmidas/cloud/sst
  3. App & Stack
  4. Function
  5. Api
  6. Cron
  7. From a gkm build manifest
  8. @geekmidas/cloud/utils (runtime)

@geekmidas/cloud

SST (ion / Pulumi) integration for @geekmidas apps — opinionated, linkable constructs that map 1:1 to deployable units and validate their environment before deploy, plus the runtime helpers that resolve linked resources into environment variables.

Two halves:

  • @geekmidas/cloud/sst — the infra-time constructs you instantiate in sst.config.ts (App, Stack, Function, Api, Cron).
  • @geekmidas/cloud / @geekmidas/cloud/utils — the runtime helpers (buildResourceEnv, ResourceType) that turn SST Resource links into flat environment variables inside a Lambda.

Design notes and rationale live in docs/sst-constructs.md (constructs) and docs/sst-testing.md (testing).

Install

pnpm add @geekmidas/cloud

./sst targets SST v4 (peer dependency sst@^4) and is distributed as raw TypeScript source — it extends the ambient sst.aws.* globals that only exist after sst install in your app.

@geekmidas/cloud/sst

import { App, Api, Function, Cron } from '@geekmidas/cloud/sst';

App & Stack

App is a plain synchronous construct; resolve the hosted zone once at the call site and pass it in. app.stack(name) creates a Stack bound to the app.

const { zoneId } = await aws.route53.getZone({ name: 'example.com' });

const app = new App({
  name: 'my-app',
  stage: 'prod',
  domain: 'example.com',
  hostedZoneId: zoneId,
  region: 'us-east-1',
});

const stack = app.stack('api');
stack.logicalPrefixedName('handler'); // "prod-my-app-api-handler"
stack.select({ prod: 'live', default: 'dev' }); // by-stage value with a default

Function

Extends sst.aws.FunctionArgs (native options pass through), merges standard env defaults, defaults to nodejs24.x + JSON logging, and validates envVars against links at synth time — attaching only the links a function needs (least privilege).

const fn = new Function(stack, 'Processor', {
  handler: 'src/processor.handler',
  links: [db, topic],
  envVars: ['DATABASE_URL'], // validated against links; fails synth if missing
});

Api

Extends sst.aws.ApiGatewayV2Args (CORS/domain/etc. pass through). Routes are a typed table with per-route env validation, least-privilege linking, and a typed authorizer model.

const api = new Api(stack, 'Api', {
  links: [db],
  authorizers: {
    jwt:      { issuer: 'https://issuer', audiences: ['aud'] }, // 'jwt' → JWT settings
    employee: { handler: 'src/employee-auth.handler' },         // custom → Lambda authorizer
  },
  routes: [
    { method: 'GET',  path: '/me',  handler: 'me.handler',  authorizer: 'jwt' },
    { method: 'GET',  path: '/adm', handler: 'adm.handler', authorizer: 'employee' },
    { method: 'POST', path: '/pub', handler: 'pub.handler' }, // public (none)
  ],
});

A route's authorizer is type-constrained to 'iam' | 'none' plus the declared authorizer names — an undeclared name is a compile error, and jwt requires JWT settings while custom authorizers require a handler.

Cron

Wraps sst.aws.CronV2 (sst.aws.Cron is deprecated). processor is a Function (or anything with an arn); schedule is a typed cron(…) / at(…).

const cron = new Cron(stack, 'Nightly', { processor: fn, schedule: 'cron(0 0 * * ? *)' });

From a gkm build manifest

gkm build emits a deployment manifest (types in @geekmidas/manifest). Each construct has a static fromManifest factory that maps it straight into infra:

import routes from './.gkm/routes-manifest.json';

const api     = Api.fromManifest(stack, 'Api', routes, { links: [db], authorizers });
const workers = Function.fromManifest(stack, functionsManifest, { links: [db] });
const crons   = Cron.fromManifest(stack, cronsManifest, { links: [db] });

@geekmidas/cloud/utils (runtime)

import { buildResourceEnv } from '@geekmidas/cloud';

buildResourceEnv turns a record of SST Resource links into flat environment variables at runtime, using the shared ResourceType vocabulary.

版本与发布记录

@geekmidas/cloud 共发布 202 个版本,首次发布于 2025/10/07;过去 12 个月发布了 200 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.6.1latest2026/11/16今天
10.0.0-alpha.185alpha2026/11/16今天
10.0.0-alpha.1842026/11/16今天
10.0.0-alpha.1832026/11/16今天
10.0.0-alpha.1822026/11/132 天前
10.0.0-alpha.1812026/11/133 天前

关于 @geekmidas/cloud 的常见问题

@geekmidas/cloud 是什么?

SST (ion / Pulumi) integration for @geekmidas apps — opinionated, linkable constructs that map 1:1 to deployable units and validate their environment before deploy, plus the runtime helpers that resolve linked resources into environment variables.

如何安装 @geekmidas/cloud?

在项目目录运行 npm install @geekmidas/cloud,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:sst(^4.15.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@geekmidas/cloud 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@geekmidas/cloud 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@geekmidas/cloud 可以商用吗?

@geekmidas/cloud 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@geekmidas/cloud 的下载量有多少?

根据 npm 官方下载统计,@geekmidas/cloud 在 2026/10/16 – 2026/11/14 这 30 天内被下载 12,696 次,日均约 423 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@geekmidas/cloud 还在维护吗?

最新版本 9.6.1 发布于 2026/11/16(今天);至今共发布 202 个版本,其中过去 12 个月发布了 200 个;首次发布于 2025/10/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。