0
# Pulumi Node.js SDK
1

2
Pulumi's Node.js SDK is a comprehensive infrastructure-as-code platform that enables developers to define, deploy, and manage cloud infrastructure using TypeScript and JavaScript. The SDK provides a declarative resource model with support for major cloud providers including AWS, Azure, Google Cloud Platform, and Kubernetes, featuring strongly-typed APIs, automatic dependency management, and state management.
3

4
## Package Information
5

6
- **Package Name**: @pulumi/pulumi
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pulumi/pulumi`
10

11
## Core Imports
12

13
```typescript
14
import * as pulumi from "@pulumi/pulumi";
15
```
16

17
Import specific components:
18

19
```typescript
20
import { Config, Output, Resource, ComponentResource } from "@pulumi/pulumi";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const pulumi = require("@pulumi/pulumi");
27
const { Config, Output, Resource } = require("@pulumi/pulumi");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import * as pulumi from "@pulumi/pulumi";
34

35
// Configuration management
36
const config = new pulumi.Config();
37
const name = config.get("name") || "world";
38

39
// Resource creation with outputs
40
const bucket = new aws.s3.Bucket("my-bucket", {
41
  website: {
42
    indexDocument: "index.html",
43
  },
44
});
45

46
// Export stack outputs
47
export const bucketName = bucket.id;
48
export const websiteUrl = pulumi.interpolate`http://${bucket.websiteEndpoint}`;
49
```
50

51
## Architecture
52

53
Pulumi's Node.js SDK is built around several key components:
54

55
- **Resource Model**: Declarative resource definitions with dependency tracking
56
- **Output System**: Async value management with automatic dependency resolution
57
- **Configuration**: Secure configuration and secrets management per stack
58
- **Provider System**: Extensible provider architecture supporting 120+ cloud providers
59
- **Automation**: Programmatic stack and workspace management capabilities
60
- **Runtime System**: Serialization, state management, and execution orchestration
61

62
## Capabilities
63

64
### Configuration Management
65

66
Secure configuration and secrets management for different environments and stacks. Supports both plain text and encrypted secret values.
67

68
```typescript { .api }
69
class Config {
70
  constructor(name?: string);
71
  get<K>(key: string, opts?: StringConfigOptions<K>): K | undefined;
72
  getSecret<K>(key: string, opts?: StringConfigOptions<K>): Output<K | undefined>;
73
  require<K>(key: string, opts?: StringConfigOptions<K>): K;
74
  requireSecret<K>(key: string, opts?: StringConfigOptions<K>): Output<K>;
75
  getBoolean(key: string): boolean | undefined;
76
  getNumber(key: string, opts?: NumberConfigOptions): number | undefined;
77
  getObject<T>(key: string): T | undefined;
78
}
79
```
80

81
[Configuration](./configuration.md)
82

83
### Output System
84

85
Async value management with dependency tracking for handling promises and resource dependencies throughout your infrastructure code.
86

87
```typescript { .api }
88
class Output<T> {
89
  apply<U>(func: (t: T) => Input<U>): Output<U>;
90
  isKnown: Promise<boolean>;
91
  isSecret: Promise<boolean>;
92
}
93

94
function output<T>(val: Input<T>): Output<Unwrap<T>>;
95
function secret<T>(val: Input<T>): Output<Unwrap<T>>;
96
function all<T>(values: T): Output<UnwrappedObject<T>>;
97
function interpolate(literals: TemplateStringsArray, ...placeholders: Input<any>[]): Output<string>;
98

99
type Input<T> = T | Promise<T> | OutputInstance<T>;
100
```
101

102
[Output System](./output-system.md)
103

104
### Resource Management
105

106
Core infrastructure resource management with lifecycle management, dependency tracking, and provider integration.
107

108
```typescript { .api }
109
abstract class Resource {
110
  readonly urn: Output<string>;
111
  protected constructor(type: string, name: string, opts?: ResourceOptions);
112
}
113

114
class CustomResource extends Resource {
115
  readonly id: Output<ID>;
116
  protected constructor(type: string, name: string, props?: any, opts?: CustomResourceOptions);
117
}
118

119
class ComponentResource<TData = any> extends Resource {
120
  protected constructor(type: string, name: string, opts?: ComponentResourceOptions);
121
  registerOutputs(outputs?: Inputs | Promise<Inputs> | Output<Inputs>): void;
122
}
123

124
interface ResourceOptions {
125
  dependsOn?: Input<Input<Resource>[]> | Input<Resource>;
126
  protect?: boolean;
127
  parent?: Resource;
128
  provider?: ProviderResource;
129
  version?: string;
130
}
131
```
132

133
[Resource Management](./resource-management.md)
134

135
### Stack References
136

137
Access outputs from other Pulumi stacks for cross-stack dependencies and data sharing.
138

139
```typescript { .api }
140
class StackReference extends CustomResource {
141
  constructor(name: string, args: StackReferenceArgs, opts?: CustomResourceOptions);
142
  getOutput(name: Input<string>): Output<any>;
143
  requireOutput(name: Input<string>): Output<any>;
144
  readonly outputs: Output<{[name: string]: any}>;
145
  readonly secretOutputNames: Output<string[]>;
146
}
147
```
148

149
[Stack References](./stack-references.md)
150

151
### Asset Management
152

153
File and archive management for deploying code, configurations, and other artifacts to cloud resources.
154

155
```typescript { .api }
156
abstract class Asset {}
157
abstract class Archive {}
158

159
class FileAsset extends Asset {
160
  constructor(path: string);
161
}
162

163
class StringAsset extends Asset {
164
  constructor(text: string);
165
}
166

167
class FileArchive extends Archive {
168
  constructor(path: string);
169
}
170

171
class AssetArchive extends Archive {
172
  constructor(assets: AssetMap);
173
}
174

175
type AssetMap = {[name: string]: Asset | Archive};
176
```
177

178
[Asset Management](./asset-management.md)
179

180
### Automation
181

182
Programmatic stack and workspace management for building deployment tooling and CI/CD integration.
183

184
```typescript { .api }
185
class LocalWorkspace {
186
  static create(args?: LocalWorkspaceOptions): Promise<LocalWorkspace>;
187
  static createStack(args: LocalProgramArgs): Promise<Stack>;
188
  static selectStack(args: LocalProgramArgs): Promise<Stack>;
189
}
190

191
class Stack {
192
  constructor(name: string, workspace: Workspace);
193
  up(opts?: UpOptions): Promise<UpResult>;
194
  preview(opts?: PreviewOptions): Promise<PreviewResult>;
195
  destroy(opts?: DestroyOptions): Promise<DestroyResult>;
196
  refresh(opts?: RefreshOptions): Promise<RefreshResult>;
197
}
198
```
199

200
[Automation](./automation.md)
201

202
### Dynamic Resources
203

204
Create custom resource providers in TypeScript/JavaScript for managing resources not supported by existing providers.
205

206
```typescript { .api }
207
class dynamic.Resource extends CustomResource {
208
  constructor(
209
    provider: ResourceProvider<Inputs, Outputs>,
210
    name: string,
211
    props: Inputs,
212
    opts?: CustomResourceOptions
213
  );
214
}
215

216
interface ResourceProvider<Inputs, Outputs> {
217
  create?(inputs: Inputs): Promise<CreateResult<Outputs>>;
218
  read?(id: string, props?: any): Promise<ReadResult<Outputs>>;
219
  update?(id: string, olds: Outputs, news: Inputs): Promise<UpdateResult<Outputs>>;
220
  delete?(id: string, props: Outputs): Promise<void>;
221
}
222
```
223

224
[Dynamic Resources](./dynamic-resources.md)
225

226
### Provider Development
227

228
Build and maintain custom Pulumi resource providers for new cloud services and infrastructure platforms.
229

230
```typescript { .api }
231
interface Provider {
232
  check?(urn: string, olds: any, news: any): Promise<CheckResult>;
233
  create?(urn: string, inputs: any): Promise<CreateResult>;
234
  read?(id: string, urn: string, props?: any): Promise<ReadResult>;
235
  update?(id: string, urn: string, olds: any, news: any): Promise<UpdateResult>;
236
  delete?(id: string, urn: string, props: any): Promise<void>;
237
  construct?(name: string, type: string, inputs: any, options: any): Promise<ConstructResult>;
238
  invoke?(token: string, inputs: any): Promise<InvokeResult>;
239
}
240

241
function main(provider: Provider, args?: string[]): Promise<void>;
242
```
243

244
[Provider Development](./provider-development.md)
245

246
### Runtime Operations
247

248
Low-level runtime functions for resource registration, serialization, and state management.
249

250
```typescript { .api }
251
function registerResource(
252
  res: Resource,
253
  type: string,
254
  name: string,
255
  props: Inputs,
256
  opts?: ResourceOptions
257
): Promise<void>;
258

259
function invoke(
260
  token: string,
261
  props: Inputs,
262
  opts?: InvokeOptions
263
): Promise<any>;
264

265
function invokeOutput(
266
  token: string,
267
  props: Inputs,
268
  opts?: InvokeOutputOptions
269
): Output<any>;
270
```
271

272
[Runtime Operations](./runtime-operations.md)
273

274
### Logging and Diagnostics
275

276
Structured logging and error handling for infrastructure deployment diagnostics.
277

278
```typescript { .api }
279
function debug(msg: string, resource?: Resource): void;
280
function info(msg: string, resource?: Resource): void;
281
function warn(msg: string, resource?: Resource): void;
282
function error(msg: string, resource?: Resource): void;
283

284
class RunError extends Error {}
285
class ResourceError extends Error {
286
  constructor(message: string, resource: Resource | undefined, hideStack?: boolean);
287
}
288
```
289

290
[Logging and Diagnostics](./logging-diagnostics.md)
291

292
### Utilities
293

294
Helper functions and utilities for common operations in Pulumi programs.
295

296
```typescript { .api }
297
function isInstance<T>(obj: any, name: string): obj is T;
298
function hasTrueBooleanMember(obj: any, memberName: string): boolean;
299
function values(obj: any): any[];
300

301
function getOrganization(): string;
302
function getProject(): string;
303
function getStack(): string;
304
function getRootDirectory(): string;
305
```
306

307
[Utilities](./utilities.md)
308

309
## Error Handling
310

311
Pulumi provides structured error types for different failure scenarios:
312

313
```typescript { .api }
314
class RunError extends Error {}
315
class ResourceError extends Error {
316
  constructor(message: string, resource: Resource | undefined, hideStack?: boolean);
317
}
318
class InputPropertyError extends Error {
319
  propertyPath: string;
320
  reason: string;
321
}
322
class InputPropertiesError extends Error {
323
  properties: string[];
324
  reasons: string[];
325
}
326
```
327

328
## Types
329

330
```typescript { .api }
331
type Input<T> = T | Promise<T> | OutputInstance<T>;
332
type Inputs = Record<string, Input<any>>;
333
type ID = string;
334
type URN = string;
335

336
type Unwrap<T> = T extends OutputInstance<infer U> ? U :
337
  T extends Promise<infer U> ? U :
338
  T;
339

340
type Lifted<T> = {
341
  [K in keyof T]: Output<T[K]>;
342
};
343
```