---
title: TypeScript
url: /docs/esc/languages-sdks/javascript/
---
Pulumi ESC provides a TypeScript SDK for managing environments and reading their configuration and secrets from your own code. The SDK is written for TypeScript and can also be used from JavaScript on Node.js.

> **Note:** Use the ESC SDK to retrieve environment values from your application workloads at runtime and to manage environments programmatically. If you want to consume an environment from within a Pulumi IaC program, use [config](/docs/esc/guides/integrate-with-pulumi-iac/) instead of the SDK.

Here are some of the scenarios the SDK can automate:

* List environments and read environment definitions
* Open environments to access config and resolve secrets
* Create, update, decrypt, and delete environment definitions
* Supports both structured types and yaml text
* List environment revisions and create new revision tags
* Check environment definitions for errors

## Runtime support

The SDK supports Node.js [Current, Active, and Maintenance LTS versions](https://nodejs.org/en/about/previous-releases). We recommend using the latest LTS version for the best experience.

## Languages

Pulumi ESC fully supports both TypeScript and JavaScript. You can use either language to work with the SDK:

* **TypeScript**: Get additional type safety and IDE support with TypeScript (recommended)
* **JavaScript**: Write programs using standard JavaScript syntax

> **Note:** The examples on this page are shown in both TypeScript and JavaScript. The SDK also works with any other language that compiles to JavaScript and runs on Node.js. For the most consistent experience, we recommend using TypeScript.

## Install the SDK package

Run `npm install @pulumi/esc-sdk` or `yarn add @pulumi/esc-sdk` to install the SDK package.

## Initializing the SDK client

The easiest way to initialize an ESC SDK client is to run:

<!-- chooser: language -->

<!-- option: typescript -->
```typescript
import * as esc from "@pulumi/esc-sdk";

const client = esc.DefaultClient();

```

<!-- /option -->

<!-- option: javascript -->
```javascript
const esc = require("@pulumi/esc-sdk");

const client = esc.DefaultClient();

```

<!-- /option -->

<!-- /chooser -->

This method will first look for the `PULUMI_ACCESS_TOKEN` environment variable, and if it's not present, it will fall back to CLI credentials that are present on your machine if you have logged in using Pulumi CLI or ESC CLI.

If the default behavior does not work for you, you can always manually initialize the client configuration and pass it into the client constructor:

<!-- chooser: language -->

<!-- option: typescript -->
```typescript
import * as esc from "@pulumi/esc-sdk";

const configuration = new esc.Configuration({
    accessToken: myAccessToken
})
const client = new esc.EscApi(configuration);

```

<!-- /option -->

<!-- option: javascript -->
```javascript
const esc = require("@pulumi/esc-sdk");

const configuration = new esc.Configuration({
    accessToken: myAccessToken
})
const client = new esc.EscApi(configuration);

```

<!-- /option -->

<!-- /chooser -->

## Examples

All of these examples expect a `PULUMI_ACCESS_TOKEN` and `PULUMI_ORG` environment variable to be set.

### Manage environment example

This example creates a new environment, opens that environment to access a secret, and then lists the environments.

<!-- chooser: language -->

<!-- option: typescript -->
```typescript
import * as esc from "@pulumi/esc-sdk";

async function main() {
    const orgName = process.env.PULUMI_ORG!;
    const client = esc.DefaultClient();

    const projName = "examples";
    const envName = "sdk-typescript-example";

    // Create a new environment
    await client.createEnvironment(orgName, projName, envName);

    const envDef: esc.EnvironmentDefinition = {
        values: {
            my_secret: {
                "fn::secret": "shh! don't tell anyone",
            },
        },
    };

    // Update the environment with the new definition
    await client.updateEnvironment(orgName, projName, envName, envDef);

    // Open and read the environment
    const openEnv = await client.openAndReadEnvironment(orgName, projName, envName);

    if (!openEnv) {
        console.error("Failed to open and read the environment");
        return;
    }

    // Access the value of the secret
    const secretValue = openEnv.values?.my_secret;
    console.log(`Secret value: ${secretValue}\n`);

    // List all the environments in the organization
    const orgEnvs = await client.listEnvironments(orgName);
    if (!orgEnvs || !orgEnvs.environments) {
        console.log("No environments found");
        return;
    }

    for (const env of orgEnvs.environments) {
        console.log(`Environment: ${env.project}/${env.name}`);
    }
}

(async ()=>{
    await main();
})();

```

<!-- /option -->

<!-- option: javascript -->
```javascript
const esc = require("@pulumi/esc-sdk");

async function main() {
    const orgName = process.env.PULUMI_ORG;
    const client = esc.DefaultClient();

    const projName = "examples";
    const envName = "sdk-javascript-example";

    // Create a new environment
    await client.createEnvironment(orgName, projName, envName);

    const envDef = {
        values: {
            my_secret: {
                "fn::secret": "shh! don't tell anyone",
            },
        },
    };

    // Update the environment with the new definition
    await client.updateEnvironment(orgName, projName, envName, envDef);

    // Open and read the environment
    const openEnv = await client.openAndReadEnvironment(orgName, projName, envName);

    if (!openEnv) {
        console.error("Failed to open and read the environment");
        return;
    }

    // Access the value of the secret
    const secretValue = openEnv.values?.my_secret;
    console.log(`Secret value: ${secretValue}\n`);

    // List all the environments in the organization
    const orgEnvs = await client.listEnvironments(orgName);
    if (!orgEnvs || !orgEnvs.environments) {
        console.log("No environments found");
        return;
    }

    for (const env of orgEnvs.environments) {
        console.log(`Environment: ${env.project}/${env.name}`);
    }
}

(async () => {
    await main();
})();

```

<!-- /option -->

<!-- /chooser -->

### Tag revision example

This example lists revisions for an environment, tags a revision, and lists revision tags.

<!-- chooser: language -->

<!-- option: typescript -->
```typescript
import * as esc from "@pulumi/esc-sdk";

async function main() {
    const orgName = process.env.PULUMI_ORG!;
    const client = esc.DefaultClient();

    const projName = "examples";
    const envName = "sdk-typescript-example";

    // List environment revisions
    const revisions = await client.listEnvironmentRevisions(orgName, projName, envName);

    if (!revisions || revisions.length < 2) {
        throw new Error(`Expected at least 2 revisions for environment ${projName}/${envName}`);
    }

    // Get the second latest revision
    const revision = revisions[1];
    await client.createEnvironmentRevisionTag(orgName, projName, envName, "stable", revision.number);

    console.log(`Tagged revision ${revision.number} as 'stable'`);

    // List tags
    const tags = await client.listEnvironmentRevisionTags(orgName, projName, envName);
    if (!tags || !tags.tags) {
        throw new Error(`Expected tags for environment ${projName}/${envName}`);
    }

    for (const tag of tags?.tags) {
        console.log(`Tag ${tag.name} at revision ${tag.revision}`);
    }
}

(async ()=>{
    await main();
})();

```

<!-- /option -->

<!-- option: javascript -->
```javascript
const esc = require("@pulumi/esc-sdk");

async function main() {
    const orgName = process.env.PULUMI_ORG;
    const client = esc.DefaultClient();

    const projName = "examples";
    const envName = "sdk-javascript-example";

    // List environment revisions
    const revisions = await client.listEnvironmentRevisions(orgName, projName, envName);

    if (!revisions || revisions.length < 2) {
        throw new Error(`Expected at least 2 revisions for environment ${projName}/${envName}`);
    }

    // Get the second latest revision
    const revision = revisions[1];
    await client.createEnvironmentRevisionTag(orgName, projName, envName, "stable", revision.number);

    console.log(`Tagged revision ${revision.number} as 'stable'`);

    // List tags
    const tags = await client.listEnvironmentRevisionTags(orgName, projName, envName);
    if (!tags || !tags.tags) {
        throw new Error(`Expected tags for environment ${projName}/${envName}`);
    }

    for (const tag of tags.tags) {
        console.log(`Tag ${tag.name} at revision ${tag.revision}`);
    }
}

(async () => {
    await main();
})();

```

<!-- /option -->

<!-- /chooser -->

## Documentation

* [API Reference Documentation](/docs/reference/pkg/nodejs/pulumi/esc-sdk/)
* [npm package](https://www.npmjs.com/package/@pulumi/esc-sdk)