# Stage

An abstract application modeling unit consisting of Stacks that should be deployed together.

Derive a subclass of `Stage` and use it to model a single instance of your
application.

You can then instantiate your subclass multiple times to model multiple
copies of your application which should be deployed to different
environments.

Extends: Construct › Stage
Implements: IConstruct, IDependable
Superclass of: App

- Source: [`core/lib/stage.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/core/lib/stage.ts#L121)
- Type last changed: v2.262.0 · 22 Jul 2026

## Example

```ts
declare const synth: pipelines.ShellStep;
const stage = new MyApplicationStage(this, 'MyApplication');
const pipeline = new pipelines.CodePipeline(this, 'Pipeline', { synth });

pipeline.addStage(stage, {
  post: [
    new pipelines.ShellStep('Approve', {
      // Use the contents of the 'integ' directory from the synth step as the input
      input: synth.addOutputDirectory('integ'),
      commands: ['cd integ && ./run.sh'],
    }),
  ],
});
```

## Initializer

```ts
new Stage(scope: Construct, id: string, props?: StageProps)
```

## Construct Props

- `env`: [Environment](/cdk/api/v2/docs/aws-cdk-lib.Environment.html) — Default AWS environment (account/region) for `Stack`s in this `Stage`.

  **Default:** The environments should be configured on the `Stack`s.

  Stacks defined inside this `Stage` with either `region` or `account` missing
  from its env will use the corresponding field given here.

  If either `region` or `account`is is not configured for `Stack` (either on
  the `Stack` itself or on the containing `Stage`), the Stack will be
  *environment-agnostic*.

  Environment-agnostic stacks can be deployed to any environment, may not be
  able to take advantage of all features of the CDK. For example, they will
  not be able to use environmental context lookups, will not automatically
  translate Service Principals to the right format based on the environment's
  AWS partition, and other such enhancements.

  ```ts
  // Use a concrete account and region to deploy this Stage to
  new Stage(app, 'Stage1', {
    env: { account: '123456789012', region: 'us-east-1' },
  });

  // Use the CLI's current credentials to determine the target environment
  new Stage(app, 'Stage2', {
    env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
  });
  ```

- `outdir`: string — The output directory into which to emit synthesized artifacts.

  **Default:** for nested stages, outdir will be determined as a relative directory to the outdir of the app. For apps, if outdir is not specified, a temporary directory will be created.

  Can only be specified if this stage is the root stage (the app). If this is
  specified and this stage is nested within another stage, an error will be
  thrown.

- `permissionsBoundary`: [PermissionsBoundary](/cdk/api/v2/docs/aws-cdk-lib.PermissionsBoundary.html) — Options for applying a permissions boundary to all IAM Roles and Users created within this Stage.

  **Default:** no permissions boundary is applied

  Be aware that this feature uses Aspects, and the Aspects are applied at the
  Stack level with a priority of `MUTATING` (if the feature flag
  `@aws-cdk/core:aspectPrioritiesMutating` is set) or `DEFAULT` (if the flag
  is not set). This is relevant if you are both using your own Aspects to
  assign Permissions Boundaries, as well as specifying this property.  The
  Aspect added by this property will overwrite the Permissions Boundary
  assigned by your own Aspect if both: (a) your Aspect has a lower or equal
  priority to the automatic Aspect, and (b) your Aspect is applied *above*
  the Stack level.  If either of those conditions are not true, your own
  Aspect will win.

  We recommend assigning Permissions Boundaries only using the provided APIs,
  and not using custom Aspects.

- `policyValidationBeta1`: [IPolicyValidationPluginBeta1](/cdk/api/v2/docs/aws-cdk-lib.IPolicyValidationPluginBeta1.html)[] — Use `Validations.of(stage).addPlugins()` instead.

  **Default:** no validation plugins are used

  If any plugin reports any violation,
  synthesis will be interrupted and the report displayed to the user.

- `propertyInjectors`: [IPropertyInjector](/cdk/api/v2/docs/aws-cdk-lib.IPropertyInjector.html)[] — A list of IPropertyInjector attached to this Stage.

  **Default:** no PropertyInjectors

- `stageName`: string — Name of this stage.

  **Default:** Derived from the id.

## Properties

- `account`: string — The default account for all resources defined within this stage.

- `artifactId`: string — Artifact ID of the assembly if it is a nested stage. The root stage (app) will return an empty string.

  Derived from the construct path.

- `assetOutdir`: string — The cloud assembly asset output directory.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `outdir`: string — The cloud assembly output directory.

- `parentStage`: [Stage](/cdk/api/v2/docs/aws-cdk-lib.Stage.html) — The parent stage or `undefined` if this is the app.

  *

- `policyValidationBeta1`: [IPolicyValidationPluginBeta1](/cdk/api/v2/docs/aws-cdk-lib.IPolicyValidationPluginBeta1.html)[] — Do not use this function to look up validation plugins. Use `Validations.of(stage).plugins` instead.

  **Default:** no validation plugins are used

  If any plugin reports any violation,
  synthesis will be interrupted and the report displayed to the user.

- `region`: string — The default region for all resources defined within this stage.

- `stageName`: string — The name of the stage.

  Based on names of the parent stages separated by
  hypens.

## Methods

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isStage(x: any): boolean` (static) — Test whether the given construct is a stage.

- `of(construct: IConstruct): Stage // chainable` (static) — Return the stage this construct is contained with, if available.

  If called
  on a nested stage, returns its parent.

- `synth(options?: StageSynthesisOptions): CloudAssembly` — Synthesize this stage into a cloud assembly.

  Once an assembly has been synthesized, it cannot be modified. Subsequent
  calls will return the same assembly.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.

  **Parameters**

  - `mixins` — The mixins to apply.

  **Returns:** This construct for chaining