Pulumi

@pulumi/pulumi is the core Node.js/TypeScript SDK for Pulumi, an infrastructure-as-code platform that lets you define, deploy, and manage cloud infrastructure using real programming languages instead of YAML or a bespoke DSL. Programs written against this SDK declare resources — VMs, storage buckets, Kubernetes clusters, serverless functions — that the Pulumi CLI and deployment engine reconcile against a live cloud account, using ordinary language constructs like loops, functions, and classes rather than templating.

Under the hood, the SDK is one language host among several (Go, Python, .NET, Java, YAML) that all talk to the same Go-based deployment engine over gRPC, so the same resource model, state format, and provider ecosystem (AWS, Azure, GCP, Kubernetes, and 300+ others) behave identically regardless of which language a program is written in.

What You Get

• Resource and ComponentResource base classes for authoring first-class, reusable infrastructure abstractions in TypeScript/JavaScript
• An Output<T>/Input<T> type system that handles async, not-yet-known cloud values without callback plumbing
• Automation API for embedding Pulumi’s preview/up/destroy/refresh engine directly inside your own CLIs, services, or CI pipelines
• Built-in stack configuration, encrypted secrets, and StackReference for sharing typed outputs across projects and teams
• Dynamic providers for implementing a custom CRUD resource inline when no first-class provider exists yet

Common Use Cases

• Provisioning multi-cloud infrastructure (AWS + Kubernetes + Azure) from one program and one state file
• Building internal developer platforms with Automation API instead of shelling out to the pulumi CLI
• Migrating existing Terraform/CloudFormation stacks into typed, testable code via pulumi convert
• Sharing typed outputs between stacks/projects with StackReference for platform-team and app-team boundaries
• Embedding infrastructure provisioning as a step inside an existing Node.js deployment or release pipeline

Under The Hood

Architecture Pulumi’s Node SDK (sdk/nodejs) is one of several language hosts (Go, Python, .NET, Java) that sit in front of a shared Go-based deployment engine (pkg/engine, pkg/resource/deploy, pkg/backend); the SDK’s runtime package (sdk/nodejs/runtime) serializes resource registrations over gRPC (defined under proto/) to the engine process, which resolves the desired-state resource graph against provider processes (pkg/resource/provider) and persists results to a configurable backend — local file, S3, or Pulumi Cloud, per docs/architecture/deployment-execution/state.md. On the SDK side, resource.ts and output.ts implement the Resource/ComponentResource class hierarchy and the async-aware Output<T>/Input<T> type that lets values not yet known at preview time flow through ordinary language constructs like .apply().

Tech Stack The npm package itself is pure TypeScript (compiled to sdk/nodejs/dist, targeting Current/Active/Maintenance LTS Node versions) with a lean dependency surface — @grpc/grpc-js and google-protobuf for the wire protocol to the engine, js-yaml/ini for config parsing, semver for version handling, and an OpenTelemetry stack (sdk-trace-node, exporter-otlp-grpc, exporter-zipkin) for optional tracing — while the surrounding monorepo is roughly 77% Go (pkg/, the engine and CLI), with the Python, TypeScript/JavaScript, and other-language SDKs living alongside it under sdk/. Builds use per-language Make targets plus a top-level Makefile, CI runs on GitHub Actions with golangci-lint (a custom-built linter per .custom-gcl.yml) for Go and Biome for the JS/TS code.

Code Quality Test coverage is substantial and multi-layered: 35 spec/test files directly under sdk/nodejs plus 534 *_test.go files across pkg/, and a dedicated tests/ tree at the repo root covering integration, smoke, performance, policy, and roundtrip scenarios against real cloud accounts. The Node SDK enables ESLint with typescript-eslint plus a header-check plugin that enforces the Apache license banner on every file, and the repo carries a codecov.yml for coverage tracking — though large portions of cross-language behavior (e.g. gRPC wire compatibility between language hosts and the engine) are necessarily verified via the integration suite rather than pure unit tests, given the inherently multi-process architecture.

API Design The public API favors idiomatic TypeScript over ceremony: declaring a resource is new aws.ec2.Instance(name, args, opts), config is read via new pulumi.Config().require(key), and cross-resource dependencies are expressed by simply passing one resource’s property into another’s arguments — the Output<T>/apply() model handles the async plumbing invisibly. Documentation is extensive (docs/architecture, per-language README files under sdk/*/, and the public pulumi.com/docs site) and pulumi new scaffolds a working project in a single command, though newcomers do need to learn the Output/apply mental model and the preview-then-up workflow — a real but shallow learning curve for anyone coming from Terraform or hand-written provisioning scripts.