Environments (SDK)

The envs namespace manages environments — the deployable units that hold your infrastructure resources. (The API calls an environment a stage; the SDK namespace is envs.)

Every method takes a project id, usually as the second argument.

Methods

Deploy and wait

deploy returns as soon as the deployment is queued. Pair it with waitForDeploy to block until every resource reaches a terminal status.

await microtica.envs.deploy(envId, projectId);

const settled = await microtica.envs.waitForDeploy(envId, projectId, {
  timeoutMs: 30 * 60_000,
  pollIntervalMs: 10_000,
});

To deploy only some resources, pass partialResources. Omit a resource's version (or set it to "latest") to deploy its latest build, or pin an exact build id:

await microtica.envs.deploy(envId, projectId, {
  partialResources: [{ name: "VPC" }, { name: "Api", version: "4f3a9c21" }],
});

Clone an environment

clone copies resources and their configurations into a new environment; apps are not copied. The cloudProvider and infrastructureAsCodeTool values are normalized to lowercase for you, so the friendly forms work. Cloning is idempotent — an existing environment of the same name is returned with alreadyExisted: true.

const result = await microtica.envs.clone(sourceEnvId, projectId, {
  name: "Staging",
  description: "Staging stage",
  cloudProvider: "aws",
  infrastructureAsCodeTool: "terraform",
});
// { id: "Staging-G6q5rBbK5a", done: true, alreadyExisted: false }

Update a resource's config

updateResourceConfig merges by default: it fetches the resource's current configuration and folds your overrides on top, so you only pass what changes. Pass { merge: false } to replace the whole set. Configurations accept either the array form or a plain { key: value } map.

// Merge — change one key, keep the rest
await microtica.envs.updateResourceConfig(envId, projectId, "RDS", {
  configurations: { instance_class: "db.t3.medium" },
});

Add a resource

addResource instantiates a component as a new resource. Its configuration must satisfy the component's schema for that version — fetch it first with components.getSchema.

await microtica.envs.addResource(envId, projectId, {
  name: "my-db",
  componentId,
  componentVersion: "latest",
  configurations: { engine: "postgres" },
});

Tear down

undeploy destroys the environment's cloud resources but keeps the Microtica record; delete removes the record. Call undeploy first if resources are still up, or delete leaves orphans.

await microtica.envs.undeploy(envId, projectId);
await microtica.envs.waitForDeploy(envId, projectId);
await microtica.envs.delete(envId, projectId);

Find a resource's last deploy

lastDeploy returns one curated record for the most recent deploy of a resource within an environment, merging the environment run's timestamps with the resource's own commit and status. It returns undefined when nothing matches.

const last = await microtica.envs.lastDeploy("RDS", projectId, { envId });
// last?.envDeployId, last?.commitSha, last?.targetStatus, …

The envDeployId is the id you pass to envs.deploymentLogs to read that run's events.

Next steps

• Deploy applications
• Stream deployment logs
• How environments work