projen

projen

Version 0.91.26
Published 3 days ago
12.9 MB
14 dependencies
Apache-2.0 license

Install

npm i projen

yarn add projen

pnpm add projen

Overview

CDK for software projects

Index

Variables

variable CHANGES_SINCE_LAST_RELEASE

const CHANGES_SINCE_LAST_RELEASE: string;

This command determines if there were any changes since the last release in a cross-platform compatible way. It is used as a condition for both the bump and the release tasks.
Explanation: - log commits | git log - limit log output to a single line per commit | --oneline - looks only at the most recent commit | -1 - silent grep output | grep -q - exits with code 0 if a match is found | grep -q "chore(release):" - exits with code 1 if a match is found (reverse-match) | grep -qv "chore(release):"

Functions

function filteredRunsOnOptions

filteredRunsOnOptions: (
    runsOn?: string[],
    runsOnGroup?: GroupRunnerOptions
) => { runsOnGroup: GroupRunnerOptions } | { runsOn: string[] };

function filteredWorkflowRunsOnOptions

filteredWorkflowRunsOnOptions: (
    workflowRunsOn?: string[],
    workflowRunsOnGroup?: GroupRunnerOptions
) =>
    | { workflowRunsOnGroup: GroupRunnerOptions }
    | { workflowRunsOn: string[] }
    | string[];

Classes

class Component

class Component extends Construct {}

Represents a project component.
Parameter project
Parameter id
Unique id of the component. If not provided, an unstable AutoId is generated.

constructor

constructor(scope: IConstruct, id?: string);

property project

readonly project: Project;

method isComponent

static isComponent: (x: any) => x is Component;

Test whether the given construct is a component.

method postSynthesize

postSynthesize: () => void;

Called after synthesis. Order is *not* guaranteed.

method synthesize

synthesize: () => void;

Synthesizes files to the project output directory.

class Dependencies

class Dependencies extends Component {}

The Dependencies component is responsible to track the list of dependencies a project has, and then used by project types as the model for rendering project-specific dependency manifests such as the dependencies section package.json files.
To add a dependency you can use a project-type specific API such as nodeProject.addDeps() or use the generic API of project.deps:

constructor

constructor(project: Project);

Adds a dependencies component to the project.
Parameter project
The parent project

property all

readonly all: Dependency[];

A copy of all dependencies recorded for this project.
The list is sorted by type->name->version

property MANIFEST_FILE

static readonly MANIFEST_FILE: string;

The project-relative path of the deps manifest file.

method addDependency

addDependency: (
    spec: string,
    type: DependencyType,
    metadata?: { [key: string]: any }
) => Dependency;

Adds a dependency to this project.
Parameter spec
The dependency spec in the format MODULE[@VERSION] where MODULE is the package-manager-specific module name and VERSION is an optional semantic version requirement (e.g. ^3.4.0).
Parameter type
The type of the dependency.

method getDependency

getDependency: (name: string, type?: DependencyType) => Dependency;

Returns a dependency by name.
Fails if there is no dependency defined by that name or if type is not provided and there is more then one dependency type for this dependency.
Parameter name
The name of the dependency
Parameter type
The dependency type. If this dependency is defined only for a single type, this argument can be omitted.
Returns
a copy (cannot be modified)

method isDependencySatisfied

isDependencySatisfied: (
    name: string,
    type: DependencyType,
    expectedRange: string
) => boolean;

Checks if an existing dependency satisfies a dependency requirement.
Parameter name
The name of the dependency to check (without the version).
Parameter type
The dependency type.
Parameter expectedRange
The version constraint to check (e.g. ^3.4.0). The constraint of the dependency must be a subset of the expected range to satisfy the requirements.
Returns
true if the dependency exists and its version satisfies the provided constraint. false otherwise. Notably returns false if a dependency exists, but has no version.

method parseDependency

static parseDependency: (spec: string) => DependencyCoordinates;

Returns the coordinates of a dependency spec.
Given foo@^3.4.0 returns { name: "foo", version: "^3.4.0" }. Given bar@npm:@bar/legacy returns { name: "bar", version: "npm:@bar/legacy" }.

method removeDependency

removeDependency: (name: string, type?: DependencyType) => void;

Removes a dependency.
Parameter name
The name of the module to remove (without the version)
Parameter type
The dependency type. This is only required if there the dependency is defined for multiple types.

method tryGetDependency

tryGetDependency: (
    name: string,
    type?: DependencyType
) => Dependency | undefined;

Returns a dependency by name.
Returns undefined if there is no dependency defined by that name or if type is not provided and there is more then one dependency type for this dependency.
Parameter name
The name of the dependency
Parameter type
The dependency type. If this dependency is defined only for a single type, this argument can be omitted.
Returns
a copy (cannot be modified) or undefined if there is no match

class DevEnvironmentDockerImage

class DevEnvironmentDockerImage {}

Options for specifying the Docker image of the container.

property dockerFile

readonly dockerFile?: string;

The relative path of a Dockerfile that defines the container contents.

property image

readonly image?: string;

A publicly available Docker image.

method fromFile

static fromFile: (dockerFile: string) => DevEnvironmentDockerImage;

The relative path of a Dockerfile that defines the container contents.
Parameter dockerFile
a relative path
Example 1
'.gitpod.Docker'

method fromImage

static fromImage: (image: string) => DevEnvironmentDockerImage;

A publicly available Docker image.
Parameter image
a Docker image
Example 1
'ubuntu:latest'

constructor

constructor(project: Project, props?: DockerComposeProps);

property file

readonly file: YamlFile;

The Docker Compose file

method addService

addService: (
    serviceName: string,
    description: DockerComposeServiceDescription
) => DockerComposeService;

Add a service to the docker-compose file.
Parameter serviceName
name of the service
Parameter description
a service description

method bindVolume

static bindVolume: (
    sourcePath: string,
    targetPath: string
) => IDockerComposeVolumeBinding;

Create a bind volume that binds a host path to the target path in the container.
Parameter sourcePath
Host path name
Parameter targetPath
Target path name

method namedVolume

static namedVolume: (
    volumeName: string,
    targetPath: string,
    options?: DockerComposeVolumeConfig
) => IDockerComposeVolumeBinding;

Create a named volume and mount it to the target path. If you use this named volume in several services, the volume will be shared. In this case, the volume configuration of the first-provided options are used.
Parameter volumeName
Name of the volume
Parameter targetPath
Target path
Parameter options
volume configuration (default: docker compose defaults)

method network

static network: (
    networkName: string,
    options?: DockerComposeNetworkConfig
) => IDockerComposeNetworkBinding;

Create a named network and mount it to the target path. If you use this named network in several services, the network will be shared. In this case, the network configuration of the first-provided options are used.
Parameter networkName
Name of the network
Parameter options
network configuration

method portMapping

static portMapping: (
    publishedPort: number,
    targetPort: number,
    options?: DockerComposePortMappingOptions
) => DockerComposeServicePort;

Create a port mapping.
Parameter publishedPort
Published port number
Parameter targetPort
Container's port number
Parameter options
Port mapping options

constructor

constructor(
    serviceName: string,
    serviceDescription: DockerComposeServiceDescription
);

property command

readonly command?: string[];

Command to run in the container.

property dependsOn

readonly dependsOn: IDockerComposeServiceName[];

Other services that this service depends on.

property image

readonly image?: string;

Docker image.

property labels

readonly labels: Record<string, string>;

Attached labels.

property networks

readonly networks: IDockerComposeNetworkBinding[];

Networks mounted in the container.

property platform

readonly platform?: string;

Target platform

property ports

readonly ports: DockerComposeServicePort[];

Published ports.

property volumes

readonly volumes: IDockerComposeVolumeBinding[];

Volumes mounted in the container.

method addDependsOn

addDependsOn: (serviceName: IDockerComposeServiceName) => void;

Make the service depend on another service.
Parameter serviceName

method addEnvironment

addEnvironment: (name: string, value: string) => void;

Add an environment variable
Parameter name
environment variable name
Parameter value
value of the environment variable

method addLabel

addLabel: (name: string, value: string) => void;

Add a label
Parameter name
environment variable name
Parameter value
value of the environment variable

method addNetwork

addNetwork: (network: IDockerComposeNetworkBinding) => void;

Add a network to the service.
Parameter network

method addPort

addPort: (
    publishedPort: number,
    targetPort: number,
    options?: DockerComposePortMappingOptions
) => void;

Add a port mapping
Parameter publishedPort
Published port number
Parameter targetPort
Container's port number
Parameter options
Port mapping options

method addVolume

addVolume: (volume: IDockerComposeVolumeBinding) => void;

Add a volume to the service.
Parameter volume

class FileBase

abstract class FileBase extends Component {}

constructor

constructor(scope: IConstruct, filePath: string, options?: FileBaseOptions);

property changed

readonly changed: boolean;

Indicates if the file has been changed during synthesis. This property is only available in postSynthesize() hooks. If this is undefined, the file has not been synthesized yet.

property executable

executable: boolean;

Indicates if the file should be marked as executable

property marker

readonly marker: string;

The projen marker, used to identify files as projen-generated.
Value is undefined if the project is being ejected.

property path

readonly path: string;

The file path, relative to the project's outdir.

property readonly

readonly: boolean;

Indicates if the file should be read-only or read-write.

method synthesize

synthesize: () => void;

Writes the file to the project's output directory

method synthesizeContent

protected abstract synthesizeContent: (
    resolver: IResolver
) => string | undefined;

Implemented by derived classes and returns the contents of the file to emit.
Parameter resolver
Call resolver.resolve(obj) on any objects in order to resolve token functions.
Returns
the content to synthesize or undefined to skip the file

class GitAttributesFile

class GitAttributesFile extends FileBase {}

Assign attributes to file names in a git repository.
See Also
- https://git-scm.com/docs/gitattributes

constructor

constructor(scope: IConstruct, options?: GitAttributesFileOptions);

property endOfLine

readonly endOfLine: EndOfLine;

The default end of line character for text files.

property hasLfsPatterns

readonly hasLfsPatterns: boolean;

Whether the current gitattributes file has any LFS patterns

method addAttributes

addAttributes: (glob: string, ...attributes: string[]) => void;

Maps a set of attributes to a set of files.
Parameter glob
Glob pattern to match files in the repo
Parameter attributes
Attributes to assign to these files.

method addLfsPattern

addLfsPattern: (glob: string) => void;

Add attributes necessary to mark these files as stored in LFS

method preSynthesize

preSynthesize: () => void;

method synthesizeContent

protected synthesizeContent: (_: IResolver) => string | undefined;

class Gitpod

class Gitpod extends Component implements IDevEnvironment {}

The Gitpod component which emits .gitpod.yml

constructor

constructor(project: Project, options?: GitpodOptions);

property config

readonly config: any;

Direct access to the gitpod configuration (escape hatch)

method addCustomTask

addCustomTask: (options: GitpodTask) => void;

Add a task with more granular options.
By default, all tasks will be run in parallel. To run tasks in sequence, create a new Task and set the other tasks as subtasks.
Parameter options
The task parameters

method addDockerImage

addDockerImage: (image: DevEnvironmentDockerImage) => void;

Add a custom Docker image or Dockerfile for the container.
Parameter image
The Docker image

method addPorts

addPorts: (...ports: string[]) => void;

Add ports that should be exposed (forwarded) from the container.
Parameter ports
The new ports

method addPrebuilds

addPrebuilds: (config: GitpodPrebuilds) => void;

Add a prebuilds configuration for the Gitpod App
Parameter config
The configuration

method addTasks

addTasks: (...tasks: Task[]) => void;

Add tasks to run when gitpod starts.
By default, all tasks will be run in parallel. To run tasks in sequence, create a new Task and specify the other tasks as subtasks.
Parameter tasks
The new tasks

method addVscodeExtensions

addVscodeExtensions: (...extensions: GitpodCodeExtensionId[]) => void;

Add a list of VSCode extensions that should be automatically installed in the container.
These must be in the format defined in the Open VSX registry.
Parameter extensions
The extension IDs
Example 1
'scala-lang.scala@0.3.9:O5XmjwY5Gz+0oDZAmqneJw=='
See Also
- https://www.gitpod.io/docs/vscode-extensions/

class IgnoreFile

class IgnoreFile extends FileBase {}

constructor

constructor(project: Project, filePath: string, options?: IgnoreFileOptions);

Parameter project
The project to tie this file to.
Parameter filePath
the relative path in the project to put the file
Parameter minify
whether comments/blank lines should be filtered

property filterCommentLines

readonly filterCommentLines: boolean;

property filterEmptyLines

readonly filterEmptyLines: boolean;

method addPatterns

addPatterns: (...patterns: string[]) => void;

Add ignore patterns. Files that match this pattern will be ignored. If the pattern starts with a negation mark !, files that match will _not_ be ignored.
Comment lines (start with #) and blank lines ("") are filtered by default but can be included using options specified when instantiating the component.
Parameter patterns
Ignore patterns.

method exclude

exclude: (...patterns: string[]) => void;

Ignore the files that match these patterns.
Parameter patterns
The patterns to match.

method include

include: (...patterns: string[]) => void;

Always include the specified file patterns.
Parameter patterns
Patterns to include in git commits.

method removePatterns

removePatterns: (...patterns: string[]) => void;

Removes patterns previously added from the ignore file.
If addPattern() is called after this, the pattern will be added again.
Parameter patterns
patters to remove.

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

constructor

constructor(project: Project, filePath: string, options: IniFileOptions);

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

constructor

constructor(scope: IConstruct, filePath: string, options: JsonFileOptions);

property supportsComments

readonly supportsComments: boolean;

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

class JsonPatch

class JsonPatch {}

Utility for applying RFC-6902 JSON-Patch to a document.
Use the the JsonPatch.apply(doc, ...ops) function to apply a set of operations to a JSON document and return the result.
Operations can be created using the factory methods JsonPatch.add(), JsonPatch.remove(), etc.
Example 1
const output = JsonPatch.apply(input, JsonPatch.replace('/world/hi/there', 'goodbye'), JsonPatch.add('/world/foo/', 'boom'), JsonPatch.remove('/hello'));

method add

static add: (path: string, value: any) => JsonPatch;

Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.
Example 1
JsonPatch.add('/biscuits/1', { "name": "Ginger Nut" })

method apply

static apply: (document: any, ...ops: JsonPatch[]) => any;

Applies a set of JSON-Patch (RFC-6902) operations to document and returns the result.
Parameter document
The document to patch
Parameter ops
The operations to apply
Returns
The result document

method copy

static copy: (from: string, path: string) => JsonPatch;

Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers.
Example 1
JsonPatch.copy('/biscuits/0', '/best_biscuit')

method escapePath

static escapePath: (path: string) => string;

Escapes a json pointer path
Parameter path
The raw pointer the Escaped path

method move

static move: (from: string, path: string) => JsonPatch;

Moves a value from one location to the other. Both from and path are JSON Pointers.
Example 1
JsonPatch.move('/biscuits', '/cookies')

method remove

static remove: (path: string) => JsonPatch;

Removes a value from an object or array.
Example 1
JsonPatch.remove('/biscuits')
Example 2
JsonPatch.remove('/biscuits/0')

method replace

static replace: (path: string, value: any) => JsonPatch;

Replaces a value. Equivalent to a “remove” followed by an “add”.
Example 1
JsonPatch.replace('/biscuits/0/name', 'Chocolate Digestive')

method test

static test: (
    path: string,
    value: any,
    failureBehavior?: TestFailureBehavior
) => JsonPatch;

Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.
Example 1
JsonPatch.test('/best_biscuit/name', 'Choco Leibniz')

class License

class License extends FileBase {}

constructor

constructor(project: Project, options: LicenseOptions);

method synthesizeContent

protected synthesizeContent: (_: IResolver) => string | undefined;

constructor

constructor(scope: IConstruct, options?: LoggerOptions);

method debug

debug: (...text: any[]) => void;

Log a message to stderr with DEBUG severity
Parameter text
strings or objects to print

method error

error: (...text: any[]) => void;

Log a message to stderr with ERROR severity
Parameter text
strings or objects to print

method info

info: (...text: any[]) => void;

Log a message to stderr with INFO severity
Parameter text
strings or objects to print

method log

log: (level: LogLevel, ...text: any[]) => void;

Log a message to stderr with a given logging level. The message will be printed as long as logger.level is set to the message's severity or higher.
Parameter level
Logging verbosity
Parameter text
strings or objects to print

method verbose

verbose: (...text: any[]) => void;

Log a message to stderr with VERBOSE severity
Parameter text
strings or objects to print

method warn

warn: (...text: any[]) => void;

Log a message to stderr with WARN severity
Parameter text
strings or objects to print

constructor

constructor(project: Project, filePath: string, options?: MakefileOptions);

property rules

readonly rules: Rule[];

List of rule definitions.

method addAll

addAll: (target: string) => Makefile;

Add a target to all

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

constructor

constructor(scope: IConstruct, filePath: string, options: ObjectFileOptions);

property omitEmpty

readonly omitEmpty: boolean;

Indicates if empty objects and arrays are omitted from the output object.

method addDeletionOverride

addDeletionOverride: (path: string) => void;

Syntactic sugar for addOverride(path, undefined).
Parameter path
The path of the value to delete

method addOverride

addOverride: (path: string, value: any) => void;

Adds an override to the synthesized object file.
If the override is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.
To include a literal . in the property name, prefix with a \. In most programming languages you will need to write this as "\\." because the \ itself will need to be escaped.
For example,
project.tsconfig.file.addOverride('compilerOptions.alwaysStrict', true); project.tsconfig.file.addOverride('compilerOptions.lib', ['dom', 'dom.iterable', 'esnext']);
would add the overrides
"compilerOptions": { "alwaysStrict": true, "lib": [ "dom", "dom.iterable", "esnext" ] ... } ...
Parameter path
The path of the property, you can use dot notation to override values in complex types. Any intermediate keys will be created as needed.
Parameter value
The value. Could be primitive or complex.

method addToArray

addToArray: (path: string, ...values: any) => void;

Adds to an array in the synthesized object file.
If the array is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.
To include a literal . in the property name, prefix with a \. In most programming languages you will need to write this as "\\." because the \ itself will need to be escaped.
For example, with the following object file
"compilerOptions": { "exclude": ["node_modules"], "lib": ["es2020"] ... } ...
project.tsconfig.file.addToArray('compilerOptions.exclude', 'coverage'); project.tsconfig.file.addToArray('compilerOptions.lib', 'dom', 'dom.iterable', 'esnext');
would result in the following object file
"compilerOptions": { "exclude": ["node_modules", "coverage"], "lib": ["es2020", "dom", "dom.iterable", "esnext"] ... } ...
Parameter path
The path of the property, you can use dot notation to att to arrays in complex types. Any intermediate keys will be created as needed.
Parameter values
The values to add. Could be primitive or complex.

method patch

patch: (...patches: JsonPatch[]) => void;

Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

For example, with the following object file

"compilerOptions": {
  "exclude": ["node_modules"],
  "lib": ["es2020"]
  ...
}
...

project.tsconfig.file.patch(JsonPatch.add("/compilerOptions/exclude/-", "coverage"));
project.tsconfig.file.patch(JsonPatch.replace("/compilerOptions/lib", ["dom", "dom.iterable", "esnext"]));

would result in the following object file

"compilerOptions": {
  "exclude": ["node_modules", "coverage"],
  "lib": ["dom", "dom.iterable", "esnext"]
  ...
}
...

Parameter patches

The patch operations to apply

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

constructor

constructor(options: ProjectOptions);

property buildTask

readonly buildTask: Task;

property commitGenerated

readonly commitGenerated: boolean;

Whether to commit the managed files by default.

property compileTask

readonly compileTask: Task;

property components

readonly components: Component[];

Returns all the components within this project.

property DEFAULT_TASK

static readonly DEFAULT_TASK: string;

The name of the default task (the task executed when projen is run without arguments). Normally this task should synthesize the project files.

property defaultTask

readonly defaultTask?: Task;

This is the "default" task, the one that executes "projen". Undefined if the project is being ejected.

property deps

readonly deps: Dependencies;

Project dependencies.

property ejected

readonly ejected: boolean;

Whether or not the project is being ejected.

property files

readonly files: FileBase[];

All files in this project.

property gitattributes

readonly gitattributes: GitAttributesFile;

The .gitattributes file for this repository.

property initProject

readonly initProject?: InitProject;

The options used when this project is bootstrapped via projen new. It includes the original set of options passed to the CLI and also the JSII FQN of the project type.

property logger

readonly logger: Logger;

Logging utilities.

property name

readonly name: string;

Project name.

property outdir

readonly outdir: string;

Absolute output directory of this project.

property packageTask

readonly packageTask: Task;

property parent

readonly parent?: Project;

A parent project. If undefined, this is the root project.

property postCompileTask

readonly postCompileTask: Task;

property preCompileTask

readonly preCompileTask: Task;

property projectBuild

readonly projectBuild: ProjectBuild;

Manages the build process of the project.

property projenCommand

readonly projenCommand: string;

The command to use in order to run the projen CLI.

property root

readonly root: Project;

The root project.

property subprojects

readonly subprojects: Project[];

Returns all the subprojects within this project.

property tasks

readonly tasks: Tasks;

Project tasks.

property testTask

readonly testTask: Task;

method addExcludeFromCleanup

addExcludeFromCleanup: (...globs: string[]) => void;

Exclude the matching files from pre-synth cleanup. Can be used when, for example, some source files include the projen marker and we don't want them to be erased during synth.
Parameter globs
The glob patterns to match

method addGitIgnore

addGitIgnore: (pattern: string) => void;

Adds a .gitignore pattern.
Parameter pattern
The glob pattern to ignore.

method addPackageIgnore

addPackageIgnore: (_pattern: string) => void;

Exclude these files from the bundled package. Implemented by project types based on the packaging mechanism. For example, NodeProject delegates this to .npmignore.
Parameter _pattern
The glob pattern to exclude

method addTask

addTask: (name: string, props?: TaskOptions) => Task;

Adds a new task to this project. This will fail if the project already has a task with this name.
Parameter name
The task name to add
Parameter props
Task properties

method addTip

addTip: (message: string) => void;

Prints a "tip" message during synthesis.
Parameter message
The message
Deprecated
- use project.logger.info(message) to show messages during synthesis

method annotateGenerated

annotateGenerated: (_glob: string) => void;

Consider a set of files as "generated". This method is implemented by derived classes and used for example, to add git attributes to tell GitHub that certain files are generated.
Parameter _glob
the glob pattern to match (could be a file path).

method isProject

static isProject: (x: any) => x is Project;

Test whether the given construct is a project.

method of

static of: (construct: IConstruct) => Project;

Find the closest ancestor project for given construct. When given a project, this it the project itself.
Throws
when no project is found in the path to the root

method postSynthesize

postSynthesize: () => void;

Called after all components are synthesized. Order is *not* guaranteed.

method preSynthesize

preSynthesize: () => void;

Called before all components are synthesized.

method removeTask

removeTask: (name: string) => Task | undefined;

Removes a task from a project.
Parameter name
The name of the task to remove.
Returns
The Task that was removed, otherwise undefined.

method runTaskCommand

runTaskCommand: (task: Task) => string;

Returns the shell command to execute in order to run a task.
By default, this is npx projen@<version> <task>
Parameter task
The task for which the command is required

method synth

synth: () => void;

Synthesize all project files into outdir.
1. Call "this.preSynthesize()" 2. Delete all generated files 3. Synthesize all subprojects 4. Synthesize all components of this project 5. Call "postSynthesize()" for all components of this project 6. Call "this.postSynthesize()"

method tryFindFile

tryFindFile: (filePath: string) => FileBase | undefined;

Finds a file at the specified relative path within this project and all its subprojects.
Parameter filePath
The file path. If this path is relative, it will be resolved from the root of _this_ project.
Returns
a FileBase or undefined if there is no file in that path

method tryFindJsonFile

tryFindJsonFile: (filePath: string) => JsonFile | undefined;

Finds a json file by name.
Parameter filePath
The file path.
Deprecated
use tryFindObjectFile

method tryFindObjectFile

tryFindObjectFile: (filePath: string) => ObjectFile | undefined;

Finds an object file (like JsonFile, YamlFile, etc.) by name.
Parameter filePath
The file path.

method tryRemoveFile

tryRemoveFile: (filePath: string) => FileBase | undefined;

Finds a file at the specified relative path within this project and removes it.
Parameter filePath
The file path. If this path is relative, it will be resolved from the root of _this_ project.
Returns
a FileBase if the file was found and removed, or undefined if the file was not found.

class ProjectBuild

class ProjectBuild extends Component {}

Manages a standard build process for all projects.
Build spawns these tasks in order: 1. default 2. pre-compile 3. compile 4. post-compile 5. test 6. package

constructor

constructor(project: Project);

property buildTask

readonly buildTask: Task;

The task responsible for a full release build.

property compileTask

readonly compileTask: Task;

Compiles the code. By default for node.js projects this task is empty.

property testTask

readonly testTask: Task;

Tests the code.

method createProject

static createProject: (options: CreateProjectOptions) => void;

Creates a new project with defaults.
This function creates the project type in-process (with in VM) and calls .synth() on it (if options.synth is not false).
At the moment, it also generates a .projenrc.js file with the same code that was just executed. In the future, this will also be done by the project type, so we can easily support multiple languages of projenrc.
An environment variable (PROJEN_CREATE_PROJECT=true) is set within the VM so that custom project types can detect whether the current synthesis is the result of a new project creation (and take additional steps accordingly)

class ProjectTree

class ProjectTree extends Component {}

constructor

constructor(project: Project);

property file

file: JsonFile;

class ProjenrcFile

abstract class ProjenrcFile extends Component {}

A component representing the projen runtime configuration

property filePath

abstract readonly filePath: string;

The path of the projenrc file.

method of

static of: (project: Project) => ProjenrcFile | undefined;

Returns the Projenrc instance associated with a project or undefined if there is no Projenrc.
Parameter project
The project
Returns
A Projenrc

method preSynthesize

preSynthesize: () => void;

class ProjenrcJson

class ProjenrcJson extends ProjenrcFile {}

Sets up a project to use JSON for projenrc.

constructor

constructor(project: Project, options?: ProjenrcJsonOptions);

property filePath

readonly filePath: string;

class ReleasableCommits

class ReleasableCommits {}

Find commits that should be considered releasable to decide if a release is required.

property cmd

cmd: string;

method everyCommit

static everyCommit: (path?: string) => ReleasableCommits;

Release every commit
This will only not release if the most recent commit is tagged with the latest matching tag.
Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the bump task, i.e. to only consider commits of a subproject use ".".

method exec

static exec: (cmd: string) => ReleasableCommits;

Use an arbitrary shell command to find releasable commits since the latest tag.
A new release will be initiated, if the number of returned commits is greater than zero. Must return a newline separate list of commits that should considered releasable. $LATEST_TAG will be replaced with the actual latest tag for the given prefix.*
Example 1
"git log --oneline $LATEST_TAG..HEAD -- ."

method featuresAndFixes

static featuresAndFixes: (path?: string) => ReleasableCommits;

Release only features and fixes
Shorthand for ReleasableCommits.onlyOfType(['feat', 'fix']).
Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the bump task, i.e. to only consider commits of a subproject use ".".

method ofType

static ofType: (types: string[], path?: string) => ReleasableCommits;

Limit commits by their conventional commit type
This will only release commit that match one of the provided types. Commits are required to follow the conventional commit spec and will be ignored otherwise.
Parameter types
List of conventional commit types that should be released
Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the bump task, i.e. to only consider commits of a subproject use ".".

class Renovatebot

class Renovatebot extends Component {}

Defines renovatebot configuration for projen project.
Ignores the versions controlled by Projen.

constructor

constructor(project: Project, options?: RenovatebotOptions);

property file

readonly file: JsonFile;

The file holding the renovatebot configuration

class SampleDir

class SampleDir extends Component {}

Renders the given files into the directory if the directory does not exist. Use this to create sample code files

constructor

constructor(project: Project, dir: string, options: SampleDirOptions);

Create sample files in the given directory if the given directory does not exist
Parameter project
Parent project to add files to.
Parameter dir
directory to add files to. If directory already exists, nothing is added.
Parameter options
options for which files to create.

method synthesize

synthesize: () => void;

class SampleFile

class SampleFile extends Component {}

Produces a file with the given contents but only once, if the file doesn't already exist. Use this for creating example code files or other resources.

constructor

constructor(project: Project, filePath: string, options: SampleFileOptions);

Creates a new SampleFile object
Parameter project
the project to tie this file to.
Parameter filePath
the relative path in the project to put the file
Parameter options
the options for the file.

method synthesize

synthesize: () => void;

class SampleReadme

class SampleReadme extends SampleFile {}

Represents a README.md sample file. You are expected to manage this file after creation.
Parameter text
The initial contents of the README.md file. Defaults to '# replace this'

constructor

constructor(project: Project, props?: SampleReadmeProps);

class Semver

class Semver {}

Deprecated
This class will be removed in upcoming releases. if you wish to specify semver requirements in deps, devDeps, etc, specify them like so express@^2.1.

property mode

readonly mode?: string;

property spec

readonly spec: string;

property version

readonly version: string;

method caret

static caret: (version: string) => Semver;

Accept any minor version.
>= version < next major version

method latest

static latest: () => Semver;

Latest version.

method of

static of: (spec: string) => Semver;

method pinned

static pinned: (version: string) => Semver;

Accept only an exact version

method tilde

static tilde: (version: string) => Semver;

Accept patches.
>= version < next minor version

constructor

constructor(project: Project, filePath: string, options?: SourceCodeOptions);

property filePath

readonly filePath: string;

property marker

readonly marker: string;

method close

close: (code?: string) => void;

Decreases the indentation level and closes a code block.
Parameter code
The code after the block is closed (e.g. }).

method line

line: (code?: string) => void;

Emit a line of code.
Parameter code
The contents, if not specified, just adds a newline

method open

open: (code?: string) => void;

Opens a code block and increases the indentation level.
Parameter code
The code before the block starts (e.g. export class {).

class Task

class Task {}

A task that can be performed on the project. Modeled as a series of shell commands and subtasks.

constructor

constructor(name: string, props?: TaskOptions);

property condition

readonly condition: string;

A command to execute which determines if the task should be skipped. If it returns a zero exit code, the task will not be executed.

property cwd

cwd: string;

Returns the working directory for this task.

property envVars

readonly envVars: Readonly<{ [name: string]: string }>;

Returns all environment variables in the task level

property name

readonly name: string;

Task name.

property steps

readonly steps: TaskStep[];

Returns an immutable copy of all the step specifications of the task.

method addCondition

addCondition: (...condition: string[]) => void;

Add a command to execute which determines if the task should be skipped.
If a condition already exists, the new condition will be appended with && delimiter.
Parameter condition
The command to execute.
See Also
- Task.condition

method builtin

builtin: (name: string) => void;

Execute a builtin task.
Builtin tasks are programs bundled as part of projen itself and used as helpers for various components.
In the future we should support built-in tasks from external modules.
Parameter name
The name of the builtin task to execute (e.g. release/resolve-version).

method env

env: (name: string, value: string) => void;

Adds an environment variable to this task.
Parameter name
The name of the variable
Parameter value
The value. If the value is surrounded by $(), we will evaluate it within a subshell and use the result as the value of the environment variable.

method exec

exec: (command: string, options?: TaskStepOptions) => void;

Executes a shell command
Parameter command
Shell command
Parameter options
Options

method insertStep

insertStep: (index: number, ...steps: TaskStep[]) => void;

Insert one or more steps at a given index
Parameter index
Steps will be inserted before this index. May be negative to count backwards from the end, or may be == steps().length to insert at the end.
Parameter steps
The steps to insert

method lock

lock: () => void;

Forbid additional changes to this task.

method prepend

prepend: (shell: string, options?: TaskStepOptions) => void;

Adds a command at the beginning of the task.
Parameter shell
The command to add.
Deprecated
use prependExec()

method prependExec

prependExec: (shell: string, options?: TaskStepOptions) => void;

Adds a command at the beginning of the task.
Parameter shell
The command to add.

method prependSay

prependSay: (message: string, options?: TaskStepOptions) => void;

Says something at the beginning of the task.
Parameter message
Your message

method prependSpawn

prependSpawn: (subtask: Task, options?: TaskStepOptions) => void;

Adds a spawn instruction at the beginning of the task.
Parameter subtask
The subtask to execute.

method removeStep

removeStep: (index: number) => void;

Parameter index
The index of the step to remove

method reset

reset: (command?: string, options?: TaskStepOptions) => void;

Reset the task so it no longer has any commands.
Parameter command
the first command to add to the task after it was cleared.

method say

say: (message: string, options?: TaskStepOptions) => void;

Say something.
Parameter message
Your message
Parameter options
Options

method spawn

spawn: (subtask: Task, options?: TaskStepOptions) => void;

Spawns a sub-task.
Parameter subtask
The subtask to execute.

method updateStep

updateStep: (index: number, step: TaskStep) => void;

Parameter index
The index of the step to edit
Parameter step
The new step to replace the old one entirely, it is not merged with the old step

class TaskRuntime

class TaskRuntime {}

The runtime component of the tasks engine.

constructor

constructor(workdir: string);

property manifest

readonly manifest: TasksManifest;

The contents of tasks.json

property MANIFEST_FILE

static readonly MANIFEST_FILE: string;

The project-relative path of the tasks manifest file.

property tasks

readonly tasks: TaskSpec[];

The tasks in this project.

property workdir

readonly workdir: string;

The root directory of the project and the cwd for executing tasks.

method runTask

runTask: (
    name: string,
    parents?: string[],
    args?: Array<string | number>,
    env?: { [name: string]: string }
) => void;

Runs the task.
Parameter name
The task name.

method tryFindTask

tryFindTask: (name: string) => TaskSpec | undefined;

Find a task by name, or undefined if not found.

class Tasks

class Tasks extends Component {}

Defines project tasks.
Tasks extend the projen CLI by adding subcommands to it. Task definitions are synthesized into .projen/tasks.json.

constructor

constructor(project: Project);

property all

readonly all: Task[];

All tasks.

property env

readonly env: { [key: string]: string };

Returns a copy of the currently global environment for this project.

method addEnvironment

addEnvironment: (name: string, value: string) => void;

Adds global environment.
Parameter name
Environment variable name
Parameter value
Value

method addTask

addTask: (name: string, options?: TaskOptions) => Task;

Adds a task to a project.
Parameter name
The name of the task
Parameter options
Task options.

method removeTask

removeTask: (name: string) => undefined | Task;

Removes a task from a project.
Parameter name
The name of the task to remove.
Returns
The Task that was removed, otherwise undefined.

method synthesize

synthesize: () => void;

method tryFind

tryFind: (name: string) => undefined | Task;

Finds a task by name. Returns undefined if the task cannot be found.
Parameter name
The name of the task

class Testing

class Testing {}

A Testing static class with a .synth helper for getting a snapshots of construct outputs. Useful for snapshot testing with Jest.
Example 1
expect(Testing.synth(someProject)).toMatchSnapshot()

method synth

static synth: (
    project: Project,
    options?: SnapshotOptions
) => Record<string, any>;

Produces a simple JS object that represents the contents of the projects with field names being file paths.
Parameter project
the project to produce a snapshot for { [filename:string]: any }

constructor

constructor(scope: IConstruct, filePath: string, options?: TextFileOptions);

Defines a text file.
Parameter project
The project
Parameter filePath
File path
Parameter options
Options

method addLine

addLine: (line: string) => void;

Adds a line to the text file.
Parameter line
the line to add (can use tokens)

method synthesizeContent

protected synthesizeContent: (_: IResolver) => string | undefined;

constructor

constructor(project: Project, filePath: string, options: TomlFileOptions);

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

class Version

class Version extends Component {}

constructor

constructor(scope: IConstruct, options: VersionOptions);

property bumpPackage

readonly bumpPackage: string;

The package used to bump package versions, as a dependency string. This is a commit-and-tag-version compatible package.

property bumpTask

readonly bumpTask: Task;

property changelogFileName

readonly changelogFileName: string;

The name of the changelog file (under artifactsDirectory).

property releaseTagFileName

readonly releaseTagFileName: string;

The name of the file that contains the release tag (under artifactsDirectory).

property STANDARD_VERSION

static readonly STANDARD_VERSION: string;

Deprecated
use version.bumpPackage on the component instance instead

property unbumpTask

readonly unbumpTask: Task;

property versionFileName

readonly versionFileName: string;

The name of the file that contains the version (under artifactsDirectory).

method envForBranch

envForBranch: (branchOptions: VersionBranchOptions) => Record<string, string>;

Return the environment variables to modify the bump command for release branches.
These options are used to modify the behavior of the version bumping script for additional branches, by setting environment variables.
No settings are inherited from the base Version object (but any parameters that control versions do conflict with the use of a nextVersionCommand).

class XmlFile

class XmlFile extends ObjectFile {}

Represents an XML file.
Objects passed in will be synthesized using the npm "xml" library.
See Also
- https://www.npmjs.com/package/xml

constructor

constructor(project: Project, filePath: string, options?: XmlFileOptions);

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

constructor

constructor(scope: IConstruct, filePath: string, options: YamlFileOptions);

property lineWidth

lineWidth: number;

Maximum line width (set to 0 to disable folding).

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

Interfaces

interface CreateProjectOptions

interface CreateProjectOptions {}

property dir

readonly dir: string;

Directory that the project will be generated in.

property optionHints

readonly optionHints?: InitProjectOptionHints;

Should we render commented-out default options in the projenrc file? Does not apply to projenrc.json files.
InitProjectOptionHints.FEATURED

property post

readonly post?: boolean;

Should we execute post synthesis hooks? (usually package manager install).
true

property projectFqn

readonly projectFqn: string;

Fully-qualified name of the project type (usually formatted as projen.module.ProjectType).
Example 1
projen.typescript.TypescriptProject

property projectOptions

readonly projectOptions: Record<string, any>;

Project options. Only JSON-like values can be passed in (strings, booleans, numbers, enums, arrays, and objects that are not derived from classes).
Consult the API reference of the project type you are generating for information about what fields and types are available.

property synth

readonly synth?: boolean;

Should we call project.synth() or instantiate the project (could still have side-effects) and render the .projenrc file.
true

property metadata

readonly metadata?: {
    [key: string]: any;
};

Additional JSON metadata associated with the dependency (package manager specific). {}

property type

readonly type: DependencyType;

Which type of dependency this is (runtime, build-time, etc).

interface DependencyCoordinates

interface DependencyCoordinates {}

Coordinates of the dependency (name and version).

property name

readonly name: string;

The package manager name of the dependency (e.g. leftpad for npm).
NOTE: For package managers that use complex coordinates (like Maven), we will codify it into a string somehow.

property version

readonly version?: string;

Semantic version version requirement.
- requirement is managed by the package manager (e.g. npm/yarn).

interface DepsManifest

interface DepsManifest {}

interface DevEnvironmentOptions

interface DevEnvironmentOptions {}

Base options for configuring a container-based development environment.

property dockerImage

readonly dockerImage?: DevEnvironmentDockerImage;

A Docker image or Dockerfile for the container.

property ports

readonly ports?: string[];

An array of ports that should be exposed from the container.

property tasks

readonly tasks?: Task[];

An array of tasks that should be run when the container starts.

property vscodeExtensions

readonly vscodeExtensions?: string[];

An array of extension IDs that specify the extensions that should be installed inside the container when it is created.

interface DockerComposeBuild

interface DockerComposeBuild {}

Build arguments for creating a docker image.

property args

readonly args?: Record<string, string>;

Build args. - none are provided

property context

readonly context: string;

Docker build context directory.

interface DockerComposeNetworkConfig

interface DockerComposeNetworkConfig {}

Network configuration

property attachable

readonly attachable?: boolean;

Set to true to indicate that standalone containers can attach to this network, in addition to services. - unset

property bridge

readonly bridge?: boolean;

Set to true to indicate that the network is a bridge network. - unset

property driver

readonly driver?: string;

Driver to use for the network - value is not provided

property driverOpts

readonly driverOpts?: object;

Options for the configured driver. Those options are driver-dependent - consult the driver’s documentation for more information - value is not provided

property external

readonly external?: boolean;

Set to true to indicate that the network is externally created. - unset, indicating that docker-compose creates the network

property internal

readonly internal?: boolean;

Set to true to indicate that you want to create an externally isolated overlay network - unset

property ipam

readonly ipam?: DockerComposeNetworkIpamConfig;

Specify custom IPAM config. - unset

property labels

readonly labels?: string[];

Attach labels to the network - unset

property name

readonly name?: string;

Name of the network for when the network name isn't going to work in YAML. - unset, indicating that docker-compose creates networks as usual

property overlay

readonly overlay?: boolean;

Set to true to indicate that the network is an overlay network. - unset

interface DockerComposeNetworkIpamConfig

interface DockerComposeNetworkIpamConfig {}

IPAM configuration

property config

readonly config?: DockerComposeNetworkIpamSubnetConfig[];

A list with zero or more config blocks specifying custom IPAM configuration. - value is not provided

property driver

readonly driver?: string;

Driver to use for custom IPAM config. - value is not provided

interface DockerComposeNetworkIpamSubnetConfig

interface DockerComposeNetworkIpamSubnetConfig {}

IPAM subnet configuration

property subnet

readonly subnet?: string;

Subnet in CIDR format that represents a network segment - value is not provided

interface DockerComposePortMappingOptions

interface DockerComposePortMappingOptions {}

Options for port mappings.

property protocol

readonly protocol?: DockerComposeProtocol;

Port mapping protocol. DockerComposeProtocol.TCP

property nameSuffix

readonly nameSuffix?: string;

A name to add to the docker-compose.yml filename.
Example 1
'myname' yields 'docker-compose.myname.yml' - no name is added

property schemaVersion

readonly schemaVersion?: string;

Docker Compose schema version do be used - no version is provided
Deprecated
- The top level version field is obsolete per the Compose Specification.

property services

readonly services?: Record<string, DockerComposeServiceDescription>;

Service descriptions.

interface DockerComposeServiceDescription

interface DockerComposeServiceDescription {}

Description of a docker-compose.yml service.

property command

readonly command?: string[];

Provide a command to the docker container. - use the container's default command

property dependsOn

readonly dependsOn?: IDockerComposeServiceName[];

Names of other services this service depends on. - no dependencies

property environment

readonly environment?: Record<string, string>;

Add environment variables. - no environment variables are provided

property image

readonly image?: string;

Use a docker image. Note: You must specify either build or image key.
See Also
- imageBuild

property imageBuild

readonly imageBuild?: DockerComposeBuild;

Build a docker image. Note: You must specify either imageBuild or image key.
See Also
- image

property labels

readonly labels?: Record<string, string>;

Add labels. - no labels are provided

property networks

readonly networks?: IDockerComposeNetworkBinding[];

Add some networks to the service.
See Also
- DockerCompose.network() to create & mount a named network

property platform

readonly platform?: string;

Add platform - no platform is provided

property ports

readonly ports?: DockerComposeServicePort[];

Map some ports. - no ports are mapped

property privileged

readonly privileged?: boolean;

Run in privileged mode - no privileged mode flag is provided

property volumes

readonly volumes?: IDockerComposeVolumeBinding[];

Mount some volumes into the service. Use one of the following to create volumes:
See Also
- DockerCompose.bindVolume() to mount a host path
- DockerCompose.namedVolume() to create & mount a named volume

interface DockerComposeServicePort

interface DockerComposeServicePort {}

A service port mapping

property mode

readonly mode: string;

Port mapping mode.

property protocol

readonly protocol: DockerComposeProtocol;

Network protocol

property target

readonly target: number;

Target port number

interface DockerComposeVolumeConfig

interface DockerComposeVolumeConfig {}

Volume configuration

property driver

readonly driver?: string;

Driver to use for the volume - value is not provided

property external

readonly external?: boolean;

Set to true to indicate that the volume is externally created. - unset, indicating that docker-compose creates the volume

property name

readonly name?: string;

Name of the volume for when the volume name isn't going to work in YAML. - unset, indicating that docker-compose creates volumes as usual

interface DockerComposeVolumeMount

interface DockerComposeVolumeMount {}

Service volume mounting information.

property source

readonly source: string;

Volume source

property target

readonly target: string;

Volume target

property type

readonly type: string;

Type of volume.

interface FileBaseOptions

interface FileBaseOptions {}

property committed

readonly committed?: boolean;

Indicates whether this file should be committed to git or ignored. By default, all generated files are committed and anti-tamper is used to protect against manual modifications.
true

property editGitignore

readonly editGitignore?: boolean;

Update the project's .gitignore file true

property executable

readonly executable?: boolean;

Whether the generated file should be marked as executable.
false

property marker

readonly marker?: boolean;

Adds the projen marker to the file.
- marker will be included as long as the project is not ejected

property readonly

readonly readonly?: boolean;

Whether the generated file should be readonly.
true

interface GitAttributesFileOptions

interface GitAttributesFileOptions {}

Options for GitAttributesFile.

property endOfLine

readonly endOfLine?: EndOfLine;

The default end of line character for text files.
endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting explicitly: { endOfLine: EndOfLine.NONE }.
EndOfLine.LF

property endOfLine

readonly endOfLine?: EndOfLine;

The default end of line character for text files.
endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting: endOfLine: EndOfLine.NONE.
EndOfLine.LF

property lfsPatterns

readonly lfsPatterns?: string[];

File patterns to mark as stored in Git LFS
- No files stored in LFS

interface GitpodOptions

interface GitpodOptions extends DevEnvironmentOptions {}

Constructor options for the Gitpod component.
By default, Gitpod uses the 'gitpod/workspace-full' docker image.
See Also
- https://github.com/gitpod-io/workspace-images/blob/master/full/Dockerfile
  By default, all tasks will be run in parallel. To run the tasks in sequence, create a new task and specify the other tasks as subtasks.

property prebuilds

readonly prebuilds?: GitpodPrebuilds;

Optional Gitpod's Github App integration for prebuilds If this is not set and Gitpod's Github App is installed, then Gitpod will apply these defaults: https://www.gitpod.io/docs/prebuilds/#configure-the-github-app undefined

property onOpen

readonly onOpen?: GitpodOnOpen;

What to do when a service on a port is detected.
GitpodOnOpen.NOTIFY

property port

readonly port?: string;

A port that should be exposed (forwarded) from the container.
Example 1
"8080"

property visibility

readonly visibility?: GitpodPortVisibility;

Whether the port visibility should be private or public.
GitpodPortVisibility.PUBLIC

interface GitpodPrebuilds

interface GitpodPrebuilds {}

Configure the Gitpod App for prebuilds. Currently only GitHub is supported.
See Also
- https://www.gitpod.io/docs/prebuilds/

property addBadge

readonly addBadge?: boolean;

Add a "Review in Gitpod" button to the pull request's description false

property addCheck

readonly addCheck?: boolean;

Add a check to pull requests true

property addComment

readonly addComment?: boolean;

Add a "Review in Gitpod" button as a comment to pull requests false

property addLabel

readonly addLabel?: boolean;

Add a label once the prebuild is ready to pull requests false

property branches

readonly branches?: boolean;

Enable for all branches in this repo false

property master

readonly master?: boolean;

Enable for the master/default branch true

property pullRequests

readonly pullRequests?: boolean;

Enable for pull requests coming from this repo true

property pullRequestsFromForks

readonly pullRequestsFromForks?: boolean;

Enable for pull requests coming from forks false

interface GitpodTask

interface GitpodTask {}

Configure options for a task to be run when opening a Gitpod workspace (e.g. running tests, or starting a dev server).
Start Mode | Execution Fresh Workspace | before && init && command Restart Workspace | before && command Snapshot | before && command Prebuild | before && init && prebuild

property before

readonly before?: string;

In case you need to run something even before init, that is a requirement for both init and command, you can use the before property.

property command

readonly command: string;

Required. The shell command to run

property init

readonly init?: string;

The init property can be used to specify shell commands that should only be executed after a workspace was freshly cloned and needs to be initialized somehow. Such tasks are usually builds or downloading dependencies. Anything you only want to do once but not when you restart a workspace or start a snapshot.

property name

readonly name?: string;

A name for this task. - task names are omitted when blank

property openIn

readonly openIn?: GitpodOpenIn;

You can configure where in the IDE the terminal should be opened GitpodOpenIn.BOTTOM

property openMode

readonly openMode?: GitpodOpenMode;

You can configure how the terminal should be opened relative to the previous task. GitpodOpenMode.TAB_AFTER

property prebuild

readonly prebuild?: string;

The optional prebuild command will be executed during prebuilds. It is meant to run additional long running processes that could be useful, e.g. running test suites.

interface GroupRunnerOptions

interface GroupRunnerOptions {}

property group

readonly group: string;

property labels

readonly labels?: string[];

interface ICompareString

interface ICompareString {}

method compare

compare: (a: string, b: string) => number;

Parameter a
The first string
Parameter b
The second string
Returns
It is expected to return a negative value if the first argument is less than the second argument, zero if they're equal, and a positive value otherwise.

interface IDevEnvironment

interface IDevEnvironment {}

Abstract interface for container-based development environments, such as Gitpod and GitHub Codespaces.

method addDockerImage

addDockerImage: (image: DevEnvironmentDockerImage) => void;

Add a custom Docker image or Dockerfile for the container.
Parameter image
The Docker image

method addPorts

addPorts: (...ports: string[]) => void;

Adds ports that should be exposed (forwarded) from the container.
Parameter ports
The new ports

method addTasks

addTasks: (...tasks: Task[]) => void;

Adds tasks to run when the container starts.
Parameter tasks
The new tasks

method addVscodeExtensions

addVscodeExtensions: (...extensions: string[]) => void;

Adds a list of VSCode extensions that should be automatically installed in the container.
Parameter extensions
The extension IDs

interface IDockerComposeNetworkBinding

interface IDockerComposeNetworkBinding {}

Network binding information.

method bind

bind: (networkConfig: IDockerComposeNetworkConfig) => string;

Binds the requested network to the docker-compose network configuration and provide mounting instructions for synthesis.
Parameter networkConfig
the network configuration
Returns
the service name

interface IDockerComposeNetworkConfig

interface IDockerComposeNetworkConfig {}

Storage for network configuration.

method addNetworkConfiguration

addNetworkConfiguration: (
    networkName: string,
    configuration: DockerComposeNetworkConfig
) => void;

Add network configuration to the repository.
Parameter networkName
Parameter configuration

interface IDockerComposeServiceName

interface IDockerComposeServiceName {}

An interface providing the name of a docker compose service.

interface IDockerComposeVolumeBinding

interface IDockerComposeVolumeBinding {}

Volume binding information.

method bind

bind: (volumeConfig: IDockerComposeVolumeConfig) => DockerComposeVolumeMount;

Binds the requested volume to the docker-compose volume configuration and provide mounting instructions for synthesis.
Parameter volumeConfig
the volume configuration
Returns
mounting instructions for the service.

interface IDockerComposeVolumeConfig

interface IDockerComposeVolumeConfig {}

Storage for volume configuration.

method addVolumeConfiguration

addVolumeConfiguration: (
    volumeName: string,
    configuration: DockerComposeVolumeConfig
) => void;

Add volume configuration to the repository.
Parameter volumeName
Parameter configuration

interface IgnoreFileOptions

interface IgnoreFileOptions {}

interface InitProject

interface InitProject {}

Information passed from projen new to the project object when the project is first created. It is used to generate projenrc files in various languages.

property args

readonly args: Record<string, any>;

Initial arguments passed to projen new.

property comments

readonly comments: InitProjectOptionHints;

Include commented out options. Does not apply to projenrc.json files. InitProjectOptionHints.FEATURED

property fqn

readonly fqn: string;

The JSII FQN of the project type.

property type

readonly type: inventory.ProjectType;

Project metadata.

interface IResolvable

interface IResolvable {}

method toJSON

toJSON: () => any;

Resolves and returns content.

interface IResolver

interface IResolver {}

API for resolving tokens when synthesizing file content.

method resolve

resolve: (value: any, options?: ResolveOptions) => any;

Given a value (object/string/array/whatever, looks up any functions inside the object and returns an object where all functions are called.
Parameter value
The value to resolve options Resolve options

property allowComments

readonly allowComments?: boolean;

Allow the use of comments in this file. - false for .json files, true for .json5 and .jsonc files

property newline

readonly newline?: boolean;

Adds a newline at the end of the file. true

interface LicenseOptions

interface LicenseOptions {}

property copyrightOwner

readonly copyrightOwner?: string;

property copyrightPeriod

readonly copyrightPeriod?: string;

Period of license (e.g. "1998-2023")
The string $copyright_period will be substituted with this string.
- current year (e.g. "2020")

property spdx

readonly spdx: string;

License type (SPDX).
See Also
- https://github.com/projen/projen/tree/main/license-text for list of supported licenses

property level

readonly level?: LogLevel;

The logging verbosity. The levels available (in increasing verbosity) are OFF, ERROR, WARN, INFO, DEBUG, and VERBOSE.
LogLevel.INFO

property usePrefix

readonly usePrefix?: boolean;

Include a prefix for all logging messages with the project name.
false

property all

readonly all?: string[];

List of targets to build when Make is invoked without specifying any targets.
[]

property rules

readonly rules?: Rule[];

Rules to include in the Makefile.
[]

property obj

readonly obj?: any;

The object that will be serialized. You can modify the object's contents before synthesis.
Serialization of the object is similar to JSON.stringify with few enhancements: - values that are functions will be called during synthesis and the result will be serialized - this allow to have lazy values. - Set will be converted to array - Map will be converted to a plain object ({ key: value, ... }}) - RegExp without flags will be converted to string representation of the source
{} an empty object (use file.obj to mutate).

property commitGenerated

readonly commitGenerated?: boolean;

Whether to commit the managed files by default.
true

property gitIgnoreOptions

readonly gitIgnoreOptions?: IgnoreFileOptions;

Configuration options for .gitignore file

property logging

readonly logging?: LoggerOptions;

Configure logging options such as verbosity. {}

property name

readonly name: string;

This is the name of your project.
$BASEDIR

property outdir

readonly outdir?: string;

The root directory of the project.
Relative to this directory, all files are synthesized.
If this project has a parent, this directory is relative to the parent directory and it cannot be the same as the parent or any of it's other subprojects.
"."

property parent

readonly parent?: Project;

The parent project, if this project is part of a bigger project.

property projenCommand

readonly projenCommand?: string;

The shell command to use in order to run the projen CLI.
Can be used to customize in special environments.
"npx projen"

property projenrcJson

readonly projenrcJson?: boolean;

Generate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation.
false

property projenrcJsonOptions

readonly projenrcJsonOptions?: ProjenrcJsonOptions;

Options for .projenrc.json - default options

property renovatebot

readonly renovatebot?: boolean;

Use renovatebot to handle dependency upgrades.
false

property renovatebotOptions

readonly renovatebotOptions?: RenovatebotOptions;

Options for renovatebot.
- default options

interface ProjenrcJsonOptions

interface ProjenrcJsonOptions {}

property filename

readonly filename?: string;

The name of the projenrc file. ".projenrc.json"

property ignore

readonly ignore?: string[];

You can use the ignore option to customize which dependencies are updated. The ignore option supports just package name. []

property ignoreProjen

readonly ignoreProjen?: boolean;

Ignores updates to projen.
This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.
Projen upgrades are covered through the ProjenUpgrade class.
true

property labels

readonly labels?: string[];

List of labels to apply to the created PR's.

property marker

readonly marker?: boolean;

property overrideConfig

readonly overrideConfig?: any;

property scheduleInterval

readonly scheduleInterval?: string[];

How often to check for new versions and raise pull requests.
Can be given in CRON or LATER format, and use multiple schedules (e.g. different for weekdays and weekends). Multiple rules are handles as OR.
Some normal scheduling values defined in enum RenovatebotScheduleInterval.
See Also
- https://docs.renovatebot.com/configuration-options/#schedule ["at any time"]

property args

readonly args?: any[];

Context arguments. []

interface Rule

interface Rule {}

A Make rule.

property phony

readonly phony?: boolean;

Marks whether the target is phony.
false

property prerequisites

readonly prerequisites?: string[];

Files that are used as inputs to create a target.
[]

property recipe

readonly recipe?: string[];

Commands that are run (using prerequisites as inputs) to create a target.
[]

property targets

readonly targets: string[];

Files to be created or updated by this rule.
If the rule is phony then instead this represents the command's name(s).

property files

readonly files?: {
    [fileName: string]: string;
};

The files to render into the directory. These files get added after any files from source if that option is specified (replacing if names overlap).

property sourceDir

readonly sourceDir?: string;

Absolute path to a directory to copy files from (does not need to be text files).
If your project is typescript-based and has configured testdir to be a subdirectory of src, sample files should outside of the src directory otherwise they may not be copied. For example:
new SampleDir(this, 'public', { source: path.join(__dirname, '..', 'sample-assets') });

property contents

readonly contents?: string;

The contents of the file to write.

property sourcePath

readonly sourcePath?: string;

Absolute path to a file to copy the contents from (does not need to be a text file).
If your project is Typescript-based and has configured testdir to be a subdirectory of src, sample files should outside of the src directory, otherwise they may not be copied. For example:
new SampleFile(this, 'assets/icon.png', { sourcePath: path.join(__dirname, '..', 'sample-assets', 'icon.png') });

property contents

readonly contents?: string;

The contents "# replace this"

property filename

readonly filename?: string;

The name of the README.md file
"README.md"
Example 1
"readme.md"

property parseJson

readonly parseJson?: boolean;

Parse .json files as a JS object for improved inspection. This will fail if the contents are invalid JSON.
true parse .json files into an object

property indent

readonly indent?: number;

Indentation size. 2

property readonly

readonly readonly?: boolean;

Whether the generated file should be readonly.
true

interface TaskCommonOptions

interface TaskCommonOptions {}

property condition

readonly condition?: string;

A shell command which determines if the this task should be executed. If the program exits with a zero exit code, steps will be executed. A non-zero code means that task will be skipped.

property cwd

readonly cwd?: string;

The working directory for all steps in this task (unless overridden by the step).
- process.cwd()

property description

readonly description?: string;

The description of this build command. - the task name

property env

readonly env?: {
    [name: string]: string;
};

Defines environment variables for the execution of this task. Values in this map will be evaluated in a shell, so you can do stuff like $(echo "foo"). {}

property requiredEnv

readonly requiredEnv?: string[];

A set of environment variables that must be defined in order to execute this task. Task execution will fail if one of these is not defined.

interface TaskOptions

interface TaskOptions extends TaskCommonOptions {}

property args

readonly args?: string[];

Should the provided exec shell command receive fixed args.
See Also
- TaskStepOptions.args
  - no arguments are passed to the step

property exec

readonly exec?: string;

Shell command to execute as the first command of the task. - add steps using task.exec(command) or task.spawn(subtask)

property receiveArgs

readonly receiveArgs?: boolean;

Should the provided exec shell command receive args passed to the task.
See Also
- TaskStepOptions.receiveArgs
  false

property steps

readonly steps?: TaskStep[];

List of task steps to run.

property env

readonly env?: {
    [name: string]: string;
};

Environment for all tasks.

property tasks

readonly tasks?: {
    [name: string]: TaskSpec;
};

All tasks available for this project.

interface TaskSpec

interface TaskSpec extends TaskCommonOptions {}

Specification of a single task.

property name

readonly name: string;

Task name.

property steps

readonly steps?: TaskStep[];

Task steps.

interface TaskStep

interface TaskStep extends TaskStepOptions {}

A single step within a task. The step could either be the execution of a shell command or execution of a sub-task, by name.

property builtin

readonly builtin?: string;

The name of a built-in task to execute.
Built-in tasks are node.js programs baked into the projen module and as component runtime helpers.
The name is a path relative to the projen lib/ directory (without the .task.js extension). For example, if your built in builtin task is under src/release/resolve-version.task.ts, then this would be release/resolve-version.
- do not execute a builtin task

property exec

readonly exec?: string;

Shell command to execute
- don't execute a shell command

property say

readonly say?: string;

Print a message. - don't say anything

property spawn

readonly spawn?: string;

Subtask to execute
- don't spawn a subtask

property args

readonly args?: string[];

A list of fixed arguments always passed to the step.
Useful to re-use existing tasks without having to re-define the whole task.\ Fixed args are always passed to the step, even if receiveArgs is false and are always passed before any args the task is called with.
If the step executes a shell commands, args are passed through at the end of the exec shell command.\ The position of the args can be changed by including the marker $@ inside the command string.
If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect.
If the step calls a builtin script, args are passed to the script. It is up to the script to use or discard the arguments.
Example 1
task.spawn("deploy", { args: ["--force"] });
- no arguments are passed to the step

property condition

readonly condition?: string;

A shell command which determines if the this step should be executed. If the program exits with a zero exit code, the step will be executed. A non-zero code means the step will be skipped (subsequent task steps will still be evaluated/executed).

property cwd

readonly cwd?: string;

The working directory for this step.
- determined by the task

property env

readonly env?: {
    [name: string]: string;
};

Defines environment variables for the execution of this step (exec and builtin only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g. $(echo "foo").
Example 1
{ "foo": "bar", "boo": "$(echo baz)" }
- no environment variables defined in step

property name

readonly name?: string;

Step name
- no name

property receiveArgs

readonly receiveArgs?: boolean;

Should this step receive args passed to the task.
If true, args are passed through at the end of the exec shell command.\ The position of the args can be changed by including the marker $@ inside the command string.
If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion.
If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect.
Example 1
task.exec("echo Hello $@ World!", { receiveArgs: true });
false

property lines

readonly lines?: string[];

The contents of the text file. You can use addLine() to append lines.
[] empty file

interface VersionBranchOptions

interface VersionBranchOptions {}

Options to pass to modifyBranchEnvironment

property majorVersion

readonly majorVersion?: number;

The major versions released from this branch.

property minorVersion

readonly minorVersion?: number;

The minor versions released from this branch.

property prerelease

readonly prerelease?: string;

Bump the version as a pre-release tag.
- normal releases

property tagPrefix

readonly tagPrefix?: string;

Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.
Note: this prefix is used to detect the latest tagged version when bumping, so if you change this on a project with an existing version history, you may need to manually tag your latest release with the new prefix.
- no prefix

property artifactsDirectory

readonly artifactsDirectory: string;

The name of the directory into which changelog.md and version.txt files are emitted.

property bumpPackage

readonly bumpPackage?: string;

The commit-and-tag-version compatible package used to bump the package version, as a dependency string.
This can be any compatible package version, including the deprecated standard-version@9.
"commit-and-tag-version@12"

property nextVersionCommand

readonly nextVersionCommand?: string;

A shell command to control the next version to release.
If present, this shell command will be run before the bump is executed, and it determines what version to release. It will be executed in the following environment:
- Working directory: the project directory. - $VERSION: the current version. Looks like 1.2.3. - $LATEST_TAG: the most recent tag. Looks like prefix-v1.2.3, or may be unset. - $SUGGESTED_BUMP: the suggested bump action based on commits. One of major|minor|patch|none.
The command should print one of the following to stdout:
- Nothing: the next version number will be determined based on commit history. - x.y.z: the next version number will be x.y.z. - major|minor|patch: the next version number will be the current version number with the indicated component bumped.
- The next version will be determined based on the commit history and project settings.

property releasableCommits

readonly releasableCommits?: ReleasableCommits;

Find commits that should be considered releasable Used to decide if a release is required.
ReleasableCommits.everyCommit()

property tagPrefix

readonly tagPrefix?: string;

The tag prefix corresponding to this version.

property versionInputFile

readonly versionInputFile: string;

A name of a .json file to set the version field in after a bump.
Example 1
"package.json"

property versionrcOptions

readonly versionrcOptions?: Record<string, any>;

Custom configuration for versionrc file used by standard-release

property lineWidth

readonly lineWidth?: number;

Maximum line width (set to 0 to disable folding).
- 0

Enums

member BUILD

BUILD = 'build'

The dependency is required to run the build task.

member BUNDLED

BUNDLED = 'bundled'

The dependency is bundled and shipped with the module, so consumers are not required to install it.

member DEVENV

DEVENV = 'devenv'

The dependency is required for development (e.g. IDE plugins).

member OPTIONAL

OPTIONAL = 'optional'

An optional dependency that may be used at runtime if available, but is not required. It is expected to be installed by the consumer.

member OVERRIDE

OVERRIDE = 'override'

Transient dependency that needs to be overwritten.
Available for Node packages

member PEER

PEER = 'peer'

The dependency is required at runtime but expected to be installed by the consumer.

member RUNTIME

RUNTIME = 'runtime'

The dependency is required for the program/library during runtime.

member TEST

TEST = 'test'

The dependency is required to run the test task.

member TCP

TCP = 'tcp'

TCP protocol

member UDP

UDP = 'udp'

UDP protocol

enum EndOfLine

enum EndOfLine {
    AUTO = 'auto',
    CRLF = 'crlf',
    LF = 'lf',
    NONE = 'none',
}

The end of line characters supported by git.

member AUTO

AUTO = 'auto'

Maintain existing (mixed values within one file are normalised by looking at what's used after the first line)

member CRLF

CRLF = 'crlf'

Carriage Return + Line Feed characters (\r\n), common on Windows

member LF

LF = 'lf'

Line Feed only (\n), common on Linux and macOS as well as inside git repos

member NONE

NONE = 'none'

Disable and do not configure the end of line character

enum GitpodOnOpen

enum GitpodOnOpen {
    OPEN_BROWSER = 'open-browser',
    OPEN_PREVIEW = 'open-preview',
    NOTIFY = 'notify',
    IGNORE = 'ignore',
}

What to do when a service on a port is detected.

member IGNORE

IGNORE = 'ignore'

Do nothing.

member NOTIFY

NOTIFY = 'notify'

Show a notification asking the user what to do (default)

member OPEN_PREVIEW

OPEN_PREVIEW = 'open-preview'

Open a preview on the right side of the IDE

enum GitpodOpenIn

enum GitpodOpenIn {
    BOTTOM = 'bottom',
    LEFT = 'left',
    RIGHT = 'right',
    MAIN = 'main',
}

Configure where in the IDE the terminal should be opened.

member BOTTOM

BOTTOM = 'bottom'

the bottom panel (default)

member LEFT

LEFT = 'left'

the left panel

member MAIN

MAIN = 'main'

the main editor area

member RIGHT

RIGHT = 'right'

the right panel

enum GitpodOpenMode

enum GitpodOpenMode {
    TAB_AFTER = 'tab-after',
    TAB_BEFORE = 'tab-before',
    SPLIT_RIGHT = 'split-right',
    SPLIT_LEFT = 'split-left',
    SPLIT_TOP = 'split-top',
    SPLIT_BOTTOM = 'split-bottom',
}

Configure how the terminal should be opened relative to the previous task.

member SPLIT_BOTTOM

SPLIT_BOTTOM = 'split-bottom'

Splits and adds the terminal to the bottom

member SPLIT_RIGHT

SPLIT_RIGHT = 'split-right'

Splits and adds the terminal to the right

member TAB_AFTER

TAB_AFTER = 'tab-after'

Opens in the same tab group right after the previous tab

member TAB_BEFORE

TAB_BEFORE = 'tab-before'

Opens in the same tab group left before the previous tab

enum GitpodPortVisibility

enum GitpodPortVisibility {
    PUBLIC = 'public',
    PRIVATE = 'private',
}

Whether the port visibility should be private or public

member PRIVATE

PRIVATE = 'private'

Only allows users with workspace access to access the port

member PUBLIC

PUBLIC = 'public'

Allows everyone with the port URL to access the port (default)

enum InitProjectOptionHints

enum InitProjectOptionHints {
    ALL = 'all',
    FEATURED = 'featured',
    NONE = 'none',
}

Choices for how to display commented out options in projenrc files. Does not apply to projenrc.json files.

member ALL

ALL = 'all'

Display all possible options (grouped by which interface they belong to).

member FEATURED

FEATURED = 'featured'

Display only featured options, in alphabetical order.

member NONE

NONE = 'none'

Display no extra options.

member DEBUG

DEBUG = '40.debug'

member ERROR

ERROR = '10.error'

member INFO

INFO = '30.info'

member OFF

OFF = '00.off'

member VERBOSE

VERBOSE = '50.verbose'

member WARN

WARN = '20.warn'

enum ProjectType

enum ProjectType {
    UNKNOWN = 'unknown',
    LIB = 'lib',
    APP = 'app',
}

Which type of project this is.
Deprecated
no longer supported at the base project level

member APP

APP = 'app'

This is an app (service, tool, website, etc). Its artifacts are intended to be deployed or published for end-user consumption.

member LIB

LIB = 'lib'

This is a library, intended to be published to a package manager and consumed by other projects.

member UNKNOWN

UNKNOWN = 'unknown'

This module may be a either a library or an app.

enum RenovatebotScheduleInterval

enum RenovatebotScheduleInterval {
    ANY_TIME = 'at any time',
    EARLY_MONDAYS = 'before 3am on Monday',
    DAILY = 'before 2am',
    WEEKLY = 'before 3am on Monday',
    MONTHLY = 'before 3am on the first day of the month',
    QUARTERLY = 'every 3 months on the first day of the month',
    WEEKENDS = 'every weekend',
    WEEKDAYS = 'every weekday',
}

How often to check for new versions and raise pull requests for version updates.
See Also
- https://docs.renovatebot.com/presets-schedule/

member DAILY

DAILY = 'before 2am'

Schedule daily

member WEEKLY

WEEKLY = 'before 3am on Monday'

Schedule weekly

enum TestFailureBehavior

enum TestFailureBehavior {
    SKIP = 'skip',
    FAIL_SYNTHESIS = 'fail',
}

member SKIP

SKIP = 'skip'

Skip the current patch operation and continue with the next operation.

Namespaces

namespace awscdk

module 'lib/awscdk/index.d.ts' {}

class AutoDiscover

class AutoDiscover extends Component {}

Discovers and creates integration tests and lambdas from code in the project's source and test trees.

constructor

constructor(project: Project, options: AutoDiscoverOptions);

class AwsCdkConstructLibrary

class AwsCdkConstructLibrary extends ConstructLibrary {}

AWS CDK construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the AWS CDK with a friendly workflow and automatic publishing to the construct catalog.
awscdk-construct

constructor

constructor(options: AwsCdkConstructLibraryOptions);

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

property version

readonly version: string;

Deprecated
use cdkVersion

method addCdkDependencies

addCdkDependencies: (...deps: string[]) => void;

Adds dependencies to AWS CDK modules.
Since this is a library project, dependencies will be added as peer dependencies.
Parameter deps
names of cdk modules (e.g. @aws-cdk/aws-lambda).
Deprecated
Not supported in v2. For v1, use project.cdkDeps.addV1Dependencies()

method addCdkTestDependencies

addCdkTestDependencies: (...deps: string[]) => void;

Adds AWS CDK modules as dev dependencies.
Parameter deps
names of cdk modules (e.g. @aws-cdk/aws-lambda).
Deprecated
Not supported in v2. For v1, use project.cdkDeps.addV1DevDependencies()

constructor

constructor(project: Project, options: AwsCdkDepsOptions);

property cdkCliVersion

readonly cdkCliVersion: string;

The dependency requirement for the CDK CLI (e.g. '^2.3.4').
Will return ^2 if the version was unspecified by the user.

property cdkDependenciesAsDeps

readonly cdkDependenciesAsDeps: boolean;

Whether CDK dependencies are added as normal dependencies (and peer dependencies).
Deprecated
Not used for CDK 2.x

property cdkMajorVersion

readonly cdkMajorVersion: number;

The major version of the AWS CDK (e.g. 1, 2, ...)

property cdkMinimumVersion

readonly cdkMinimumVersion: string;

The minimum version of the AWS CDK (e.g. 2.0.0).

property cdkVersion

readonly cdkVersion: string;

The dependency requirement for AWS CDK (e.g. ^2.0.0).

method addV1Dependencies

addV1Dependencies: (...deps: string[]) => void;

Adds dependencies to AWS CDK modules.
The type of dependency is determined by the dependencyType option.
This method is not supported in CDK v2. Use project.addPeerDeps() or project.addDeps() as appropriate.
Parameter deps
names of cdk modules (e.g. @aws-cdk/aws-lambda).

method addV1DevDependencies

addV1DevDependencies: (...deps: string[]) => void;

Adds AWS CDK modules as dev dependencies.
This method is not supported in CDK v2. Use project.addPeerDeps() or project.addDeps() as appropriate.
Parameter deps
fully qualified names of cdk modules (e.g. @aws-cdk/aws-lambda).

method packageNames

protected abstract packageNames: () => AwsCdkPackageNames;

Return a configuration object with information about package naming in various languages

method preSynthesize

preSynthesize: () => void;

class AwsCdkDepsJava

class AwsCdkDepsJava extends AwsCdkDeps {}

Manages dependencies on the AWS CDK for Java projects.

method packageNames

protected packageNames: () => AwsCdkPackageNames;

class AwsCdkDepsJs

class AwsCdkDepsJs extends AwsCdkDeps {}

Manages dependencies on the AWS CDK for Node.js projects.

method packageNames

protected packageNames: () => AwsCdkPackageNames;

class AwsCdkDepsPy

class AwsCdkDepsPy extends AwsCdkDeps {}

Manages dependencies on the AWS CDK for Python projects.

method packageNames

protected packageNames: () => AwsCdkPackageNames;

constructor

constructor(options: AwsCdkJavaAppOptions);

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

CDK dependency management helper class

property cdkTasks

readonly cdkTasks: CdkTasks;

CDK tasks.

property mainClass

readonly mainClass: string;

The full name of the main class of the java app (package.Class).

property mainClassName

readonly mainClassName: string;

The name of the Java class with the static main() method.

property mainPackage

readonly mainPackage: string;

The name of the Java package that includes the main class.

method addCdkDependency

addCdkDependency: (...modules: string[]) => void;

Adds an AWS CDK module dependencies
Parameter modules
The list of modules to depend on (e.g. "software.amazon.awscdk/aws-lambda", "software.amazon.awscdk/aws-iam", etc)
Deprecated
In CDK 2.x all modules are available by default. Alpha modules should be added using the standard 'deps'

constructor

constructor(options: AwsCdkPythonAppOptions);

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

property cdkTasks

readonly cdkTasks: CdkTasks;

Common CDK tasks.

property sampleTestdir

readonly sampleTestdir: string;

The directory in which the python sample tests reside.

property testdir

readonly testdir: string;

The directory in which the python tests reside.
Deprecated
Use sampleTestdir instead.

constructor

constructor(options: AwsCdkTypeScriptAppOptions);

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

property cdkTasks

readonly cdkTasks: CdkTasks;

Common CDK tasks.

method addCdkDependency

addCdkDependency: (...modules: string[]) => void;

Adds an AWS CDK module dependencies
Parameter modules
The list of modules to depend on

constructor

constructor(project: Project, options: CdkConfigOptions);

property cdkout

readonly cdkout: string;

Name of the cdk.out directory.

property exclude

readonly exclude: string[];

List of glob patterns to be excluded by CDK.

property include

readonly include: string[];

List of glob patterns to be included by CDK.

property json

readonly json: JsonFile;

Represents the JSON file.

method addExcludes

addExcludes: (...patterns: string[]) => void;

Add excludes to cdk.json.
Parameter patterns
The excludes to add.

method addIncludes

addIncludes: (...patterns: string[]) => void;

Add includes to cdk.json.
Parameter patterns
The includes to add.

class CdkTasks

class CdkTasks extends Component {}

Adds standard AWS CDK tasks to your project.

constructor

constructor(project: Project);

property deploy

readonly deploy: Task;

Deploys your app.

property destroy

readonly destroy: Task;

Destroys all the stacks.

property diff

readonly diff: Task;

Diff against production.

property synth

readonly synth: Task;

Synthesizes your app.

property synthSilent

readonly synthSilent: Task;

Synthesizes your app and suppresses stdout.

property watch

readonly watch: Task;

Watch task.

class EdgeLambdaAutoDiscover

class EdgeLambdaAutoDiscover extends AutoDiscoverBase {}

Creates edge lambdas from entry points discovered in the project's source tree.

constructor

constructor(project: Project, options: EdgeLambdaAutoDiscoverOptions);

constructor

constructor(project: Project, options: IntegrationTestOptions);

class IntegrationTestAutoDiscover

class IntegrationTestAutoDiscover extends IntegrationTestAutoDiscoverBase {}

Creates integration tests from entry points discovered in the test tree.

constructor

constructor(project: Project, options: IntegrationTestAutoDiscoverOptions);

class LambdaAutoDiscover

class LambdaAutoDiscover extends AutoDiscoverBase {}

Creates lambdas from entry points discovered in the project's source tree.

constructor

constructor(project: Project, options: LambdaAutoDiscoverOptions);

constructor

constructor(project: Project, options: LambdaExtensionOptions);

class LambdaExtensionAutoDiscover

class LambdaExtensionAutoDiscover extends AutoDiscoverBase {}

Creates Lambda Extensions from entrypoints discovered in the project's source tree.

constructor

constructor(project: Project, options: LambdaExtensionAutoDiscoverOptions);

class LambdaFunction

class LambdaFunction extends Component {}

Generates a pre-bundled AWS Lambda function construct from handler code.
To use this, create an AWS Lambda handler file under your source tree with the .lambda.ts extension and add a LambdaFunction component to your typescript project pointing to this entrypoint.
This will add a task to your "compile" step which will use esbuild to bundle the handler code into the build directory. It will also generate a file src/foo-function.ts with a custom AWS construct called FooFunction which extends @aws-cdk/aws-lambda.Function which is bound to the bundled handle through an asset.
Example 1
new LambdaFunction(myProject, { srcdir: myProject.srcdir, entrypoint: 'src/foo.lambda.ts', });

constructor

constructor(project: Project, options: LambdaFunctionOptions);

Defines a pre-bundled AWS Lambda function construct from handler code.
Parameter project
The project to use
Parameter options
Options

constructor

constructor(
    functionRuntime: string,
    esbuildTarget: string,
    options?: LambdaRuntimeOptions
);

property defaultExternals

readonly defaultExternals: string[];

property esbuildPlatform

readonly esbuildPlatform: string;

property NODEJS_10_X

static readonly NODEJS_10_X: LambdaRuntime;

Node.js 10.x
Deprecated
Node.js 10 runtime has been deprecated on Jul 30, 2021

property NODEJS_12_X

static readonly NODEJS_12_X: LambdaRuntime;

Node.js 12.x
Deprecated
Node.js 12 runtime has been deprecated on Mar 31, 2023

property NODEJS_14_X

static readonly NODEJS_14_X: LambdaRuntime;

Node.js 14.x
Deprecated
Node.js 14 runtime has been deprecated on Dec 4, 2023

property NODEJS_16_X

static readonly NODEJS_16_X: LambdaRuntime;

Node.js 16.x
Deprecated
Node.js 16 runtime has been deprecated on Jun 12, 2024

property NODEJS_18_X

static readonly NODEJS_18_X: LambdaRuntime;

Node.js 18.x
Advanced notice: Node.js 18 runtime will be deprecated on Jul 31, 2025

interface AutoDiscoverCommonOptions

interface AutoDiscoverCommonOptions {}

Common options for auto discovering project subcomponents.

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

AWS CDK dependency manager.

property tsconfigPath

readonly tsconfigPath: string;

Path to the tsconfig file to use for integration tests.

property edgeLambdaAutoDiscover

readonly edgeLambdaAutoDiscover?: boolean;

Auto-discover edge lambda functions.
true

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Auto-discover integration tests.
true

property lambdaExtensionAutoDiscover

readonly lambdaExtensionAutoDiscover?: boolean;

Auto-discover lambda extensions.
true

interface AwsCdkConstructLibraryOptions

interface AwsCdkConstructLibraryOptions
    extends ConstructLibraryOptions,
        AwsCdkDepsCommonOptions {}

Options for AwsCdkConstructLibrary.

property edgeLambdaAutoDiscover

readonly edgeLambdaAutoDiscover?: boolean;

Automatically adds an cloudfront.experimental.EdgeFunction for each .edge-lambda.ts handler in your source tree. If this is disabled, you can manually add an awscdk.AutoDiscover component to your project.
true

property experimentalIntegRunner

readonly experimentalIntegRunner?: boolean;

Enable experimental support for the AWS CDK integ-runner.
false
Modifiers
- @experimental

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Automatically discovers and creates integration tests for each .integ.ts file under your test directory.
true

property lambdaAutoDiscover

readonly lambdaAutoDiscover?: boolean;

Automatically adds an aws_lambda.Function for each .lambda.ts handler in your source tree. If this is disabled, you either need to explicitly call aws_lambda.Function.autoDiscover() or define a `new aws_lambda.Function()` for each handler.
true

property lambdaExtensionAutoDiscover

readonly lambdaExtensionAutoDiscover?: boolean;

Automatically adds an awscdk.LambdaExtension for each .lambda-extension.ts entrypoint in your source tree. If this is disabled, you can manually add an awscdk.AutoDiscover component to your project
true

property lambdaOptions

readonly lambdaOptions?: LambdaFunctionCommonOptions;

Common options for all AWS Lambda functions.
- default options

interface AwsCdkDepsCommonOptions

interface AwsCdkDepsCommonOptions {}

Options for AwsCdkDeps

property cdkAssert

readonly cdkAssert?: boolean;

Warning: NodeJS only. Install the @aws-cdk/assert library?
- will be included by default for AWS CDK >= 1.0.0 < 2.0.0
Deprecated
The @aws-cdk/assert library is deprecated in favor of @aws-cdk/assertions (in V1) and included in aws-cdk-lib for V2.

property cdkAssertions

readonly cdkAssertions?: boolean;

Install the assertions library?
Only needed for CDK 1.x. If using CDK 2.x then assertions is already included in 'aws-cdk-lib'
- will be included by default for AWS CDK >= 1.111.0 < 2.0.0

property cdkCliVersion

readonly cdkCliVersion?: string;

Version range of the AWS CDK CLI to depend on.
Can be either a specific version, or an NPM version range.
By default, the latest 2.x version will be installed; you can use this option to restrict it to a specific version or version range.
"^2"

property cdkDependencies

readonly cdkDependencies?: string[];

Which AWS CDKv1 modules this project requires
Deprecated
For CDK 2.x use "deps" instead. (or "peerDeps" if you're building a library)

property cdkDependenciesAsDeps

readonly cdkDependenciesAsDeps?: boolean;

If this is enabled (default), all modules declared in cdkDependencies will be also added as normal dependencies (as well as peerDependencies).
This is to ensure that downstream consumers actually have your CDK dependencies installed when using npm < 7 or yarn, where peer dependencies are not automatically installed. If this is disabled, cdkDependencies will be added to devDependencies to ensure they are present during development.
Note: this setting only applies to construct library projects
true
Deprecated
Not supported in CDK v2.

property cdkTestDependencies

readonly cdkTestDependencies?: string[];

AWS CDK modules required for testing.
Deprecated
For CDK 2.x use 'devDeps' (in node.js projects) or 'testDeps' (in java projects) instead

property cdkVersion

readonly cdkVersion: string;

Minimum version of the AWS CDK to depend on.
"2.1.0"

property cdkVersionPinning

readonly cdkVersionPinning?: boolean;

Use pinned version instead of caret version for CDK.
You can use this to prevent mixed versions for your CDK dependencies and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.

property constructsVersion

readonly constructsVersion?: string;

Minimum version of the constructs library to depend on.
- for CDK 1.x the default is "3.2.27", for CDK 2.x the default is "10.0.5".

interface AwsCdkDepsOptions

interface AwsCdkDepsOptions extends AwsCdkDepsCommonOptions {}

property dependencyType

readonly dependencyType: DependencyType;

The type of dependency to use for runtime AWS CDK and constructs modules.
For libraries, use peer dependencies and for apps use runtime dependencies.

interface AwsCdkJavaAppOptions

interface AwsCdkJavaAppOptions
    extends JavaProjectOptions,
        CdkConfigCommonOptions,
        AwsCdkDepsCommonOptions {}

property mainClass

readonly mainClass: string;

The name of the Java class with the static main() method. This method should call app.synth() on the CDK app.
"org.acme.MyApp"

property assert

readonly assert?: string;

Fully qualified name of the assert library package Can be empty as it's only really available for javascript projects

property assertions

readonly assertions: string;

Fully qualified name of the assertions library package

property constructs

readonly constructs: string;

Fully qualified name of the constructs library package

property coreV1

readonly coreV1: string;

Fully qualified name of the core framework package for CDKv1

property coreV2

readonly coreV2: string;

Fully qualified name of the core framework package for CDKv2

interface AwsCdkPythonAppOptions

interface AwsCdkPythonAppOptions
    extends PythonProjectOptions,
        CdkConfigCommonOptions,
        AwsCdkDepsCommonOptions {}

Options for AwsCdkPythonApp

property appEntrypoint

readonly appEntrypoint?: string;

The CDK app's entrypoint (relative to the source directory, which is "src" by default).
"app.py"

property testdir

readonly testdir?: string;

Python sources directory.
"tests"
Deprecated
Use sampleTestdir instead.

interface AwsCdkTypeScriptAppOptions

interface AwsCdkTypeScriptAppOptions
    extends TypeScriptProjectOptions,
        CdkConfigCommonOptions,
        AwsCdkDepsCommonOptions {}

property app

readonly app?: string;

The command line to execute in order to synthesize the CDK application (language specific).

property appEntrypoint

readonly appEntrypoint?: string;

The CDK app's entrypoint (relative to the source directory, which is "src" by default).
"main.ts"

property edgeLambdaAutoDiscover

readonly edgeLambdaAutoDiscover?: boolean;

Automatically adds an cloudfront.experimental.EdgeFunction for each .edge-lambda.ts handler in your source tree. If this is disabled, you can manually add an awscdk.AutoDiscover component to your project.
true

property experimentalIntegRunner

readonly experimentalIntegRunner?: boolean;

Enable experimental support for the AWS CDK integ-runner.
false
Modifiers
- @experimental

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Automatically discovers and creates integration tests for each .integ.ts file in under your test directory.
true

property lambdaAutoDiscover

readonly lambdaAutoDiscover?: boolean;

Automatically adds an awscdk.LambdaFunction for each .lambda.ts handler in your source tree. If this is disabled, you can manually add an awscdk.AutoDiscover component to your project.
true

property lambdaExtensionAutoDiscover

readonly lambdaExtensionAutoDiscover?: boolean;

Automatically adds an awscdk.LambdaExtension for each .lambda-extension.ts entrypoint in your source tree. If this is disabled, you can manually add an awscdk.AutoDiscover component to your project
true

property lambdaOptions

readonly lambdaOptions?: LambdaFunctionCommonOptions;

Common options for all AWS Lambda functions.
- default options

interface CdkConfigCommonOptions

interface CdkConfigCommonOptions {}

Common options for cdk.json.

property buildCommand

readonly buildCommand?: string;

A command to execute before synthesis. This command will be called when running cdk synth or when cdk watch identifies a change in your source code before redeployment.
- no build command

property cdkout

readonly cdkout?: string;

cdk.out directory.
"cdk.out"

property context

readonly context?: {
    [key: string]: any;
};

Additional context to include in cdk.json.
- no additional context

property featureFlags

readonly featureFlags?: boolean;

Include all feature flags in cdk.json
true

property requireApproval

readonly requireApproval?: ApprovalLevel;

To protect you against unintended changes that affect your security posture, the AWS CDK Toolkit prompts you to approve security-related changes before deploying them.
ApprovalLevel.BROADENING

property watchExcludes

readonly watchExcludes?: string[];

Glob patterns to exclude from cdk watch.
[]

property watchIncludes

readonly watchIncludes?: string[];

Glob patterns to include in cdk watch.
[]

property app

readonly app: string;

The command line to execute in order to synthesize the CDK application (language specific).

interface ConstructLibraryAwsOptions

interface ConstructLibraryAwsOptions extends AwsCdkConstructLibraryOptions {}

Deprecated
use AwsCdkConstructLibraryOptions

interface EdgeLambdaAutoDiscoverOptions

interface EdgeLambdaAutoDiscoverOptions extends AutoDiscoverCommonOptions {}

Options for EdgeLambdaAutoDiscover

property srcdir

readonly srcdir: string;

Project source tree (relative to project output directory).

interface IntegrationTestAutoDiscoverOptions

interface IntegrationTestAutoDiscoverOptions
    extends AutoDiscoverCommonOptions,
        IntegrationTestAutoDiscoverBaseOptions {}

Options for IntegrationTestAutoDiscover

property integrationTestOptions

readonly integrationTestOptions?: IntegrationTestCommonOptions;

Options for integration tests.

interface IntegrationTestCommonOptions

interface IntegrationTestCommonOptions {}

property destroyAfterDeploy

readonly destroyAfterDeploy?: boolean;

Destroy the test app after a successful deployment. If disabled, leaves the app deployed in the dev account. true

property pathMetadata

readonly pathMetadata?: boolean;

Enables path metadata, adding aws:cdk:path, with the defining construct's path, to the CloudFormation metadata for each synthesized resource. false

interface IntegrationTestOptions

interface IntegrationTestOptions
    extends IntegrationTestCommonOptions,
        IntegrationTestBaseOptions {}

Options for IntegrationTest.

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

AWS CDK dependency manager.

property stacks

readonly stacks?: string[];

A list of stacks within the integration test to deploy/destroy. ["**"]

interface LambdaAutoDiscoverOptions

interface LambdaAutoDiscoverOptions extends AutoDiscoverCommonOptions {}

Options for LambdaAutoDiscover

property srcdir

readonly srcdir: string;

Project source tree (relative to project output directory).

interface LambdaExtensionAutoDiscoverOptions

interface LambdaExtensionAutoDiscoverOptions extends AutoDiscoverCommonOptions {}

Options for LambdaExtensionAutoDiscover

property lambdaExtensionOptions

readonly lambdaExtensionOptions?: LambdaExtensionCommonOptions;

Options for lambda extensions.

property srcdir

readonly srcdir: string;

Project source tree (relative to project output directory).

interface LambdaExtensionCommonOptions

interface LambdaExtensionCommonOptions {}

Common options for creating lambda extensions.

property bundlingOptions

readonly bundlingOptions?: BundlingOptions;

Bundling options for this AWS Lambda extension.
If not specified the default bundling options specified for the project Bundler instance will be used.
- defaults

interface LambdaExtensionOptions

interface LambdaExtensionOptions extends LambdaExtensionCommonOptions {}

Options for creating lambda extensions.

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

AWS CDK dependency manager.

property constructFile

readonly constructFile?: string;

The name of the generated TypeScript source file. This file should also be under the source tree.
- The name of the entrypoint file, with the -layer-version.ts suffix instead of .lambda-extension.ts.

property constructName

readonly constructName?: string;

The name of the generated lambda.LayerVersion subclass.
- A pascal cased version of the name of the entrypoint file, with the extension LayerVersion (e.g. AppConfigLayerVersion).

property entrypoint

readonly entrypoint: string;

A path from the project root directory to a TypeScript file which contains the AWS Lambda extension entrypoint (stand-alone script).
This is relative to the root directory of the project.
Example 1
"src/subdir/foo.lambda-extension.ts"

property name

readonly name?: string;

Name of the extension
- Derived from the entrypoint filename.

interface LambdaFunctionCommonOptions

interface LambdaFunctionCommonOptions {}

Common options for LambdaFunction. Applies to all functions in auto-discovery.

property awsSdkConnectionReuse

readonly awsSdkConnectionReuse?: boolean;

Whether to automatically reuse TCP connections when working with the AWS SDK for JavaScript.
This sets the AWS_NODEJS_CONNECTION_REUSE_ENABLED environment variable to 1.
Not applicable when edgeLambda is set to true because environment variables are not supported in Lambda@Edge.
See Also
- https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
  true

property bundlingOptions

readonly bundlingOptions?: BundlingOptions;

Bundling options for this AWS Lambda function.
If not specified the default bundling options specified for the project Bundler instance will be used.
- defaults

property edgeLambda

readonly edgeLambda?: boolean;

Whether to create a cloudfront.experimental.EdgeFunction instead of a lambda.Function.
false

property runtime

readonly runtime?: LambdaRuntime;

The node.js version to target.
Runtime.NODEJS_18_X

interface LambdaFunctionOptions

interface LambdaFunctionOptions extends LambdaFunctionCommonOptions {}

Options for Function.

property cdkDeps

readonly cdkDeps: AwsCdkDeps;

AWS CDK dependency manager.

property constructFile

readonly constructFile?: string;

The name of the generated TypeScript source file. This file should also be under the source tree.
- The name of the entrypoint file, with the -function.ts suffix instead of .lambda.ts.

property constructName

readonly constructName?: string;

The name of the generated lambda.Function subclass.
- A pascal cased version of the name of the entrypoint file, with the extension Function (e.g. ResizeImageFunction).

property entrypoint

readonly entrypoint: string;

A path from the project root directory to a TypeScript file which contains the AWS Lambda handler entrypoint (exports a handler function).
This is relative to the root directory of the project.
Example 1
"src/subdir/foo.lambda.ts"

interface LambdaRuntimeOptions

interface LambdaRuntimeOptions {}

Options for the AWS Lambda function runtime

property defaultExternals

readonly defaultExternals?: string[];

Packages that are considered externals by default when bundling
['@aws-sdk/*']

enum ApprovalLevel

enum ApprovalLevel {
    NEVER = 'never',
    ANY_CHANGE = 'any-change',
    BROADENING = 'broadening',
}

Which approval is required when deploying CDK apps.

member ANY_CHANGE

ANY_CHANGE = 'any-change'

Requires approval on any IAM or security-group-related change

member BROADENING

BROADENING = 'broadening'

Requires approval when IAM statements or traffic rules are added; removals don't require approval

member NEVER

NEVER = 'never'

Approval is never required

namespace build

module 'lib/build/index.d.ts' {}

class BuildWorkflow

class BuildWorkflow extends Component {}

constructor

constructor(project: Project, options: BuildWorkflowOptions);

property buildJobIds

readonly buildJobIds: string[];

Returns a list of job IDs that are part of the build.

property name

readonly name: string;

Name of generated github workflow

method addPostBuildJob

addPostBuildJob: (id: string, job: Job) => void;

Adds another job to the build workflow which is executed after the build job succeeded.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter id
The id of the new job
Parameter job
The job specification

method addPostBuildJobCommands

addPostBuildJobCommands: (
    id: string,
    commands: string[],
    options?: AddPostBuildJobCommandsOptions
) => void;

Run a sequence of commands as a job within the build workflow which is executed after the build job succeeded.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter options
Specify tools and other options

method addPostBuildJobTask

addPostBuildJobTask: (task: Task, options?: AddPostBuildJobTaskOptions) => void;

Run a task as a job within the build workflow which is executed after the build job succeeded.
The job will have access to build artifacts and will install project dependencies in order to be able to run any commands used in the tasks.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter options
Specify tools and other options

method addPostBuildSteps

addPostBuildSteps: (...steps: JobStep[]) => void;

Adds steps that are executed after the build.
Parameter steps
The job steps

interface AddPostBuildJobCommandsOptions

interface AddPostBuildJobCommandsOptions {}

Options for BuildWorkflow.addPostBuildJobCommands

property checkoutRepo

readonly checkoutRepo?: boolean;

Check out the repository at the pull request branch before commands are run.
false

property installDeps

readonly installDeps?: boolean;

Install project dependencies before running commands. checkoutRepo must also be set to true.
Currently only supported for NodeProject.
false

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property tools

readonly tools?: Tools;

Tools that should be installed before the commands are run.

interface AddPostBuildJobTaskOptions

interface AddPostBuildJobTaskOptions {}

Options for BuildWorkflow.addPostBuildJobTask

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property tools

readonly tools?: Tools;

Tools that should be installed before the task is run.

interface BuildWorkflowCommonOptions

interface BuildWorkflowCommonOptions {}

property name

readonly name?: string;

Name of the buildfile (e.g. "build" becomes "build.yml").
"build"

property permissions

readonly permissions?: JobPermissions;

Permissions granted to the build job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE } { contents: JobPermission.WRITE }

property workflowTriggers

readonly workflowTriggers?: Triggers;

Build workflow triggers "{ pullRequest: {}, workflowDispatch: {} }"

interface BuildWorkflowOptions

interface BuildWorkflowOptions extends BuildWorkflowCommonOptions {}

property artifactsDirectory

readonly artifactsDirectory?: string;

A name of a directory that includes build artifacts. "dist"

property buildTask

readonly buildTask: Task;

The task to execute in order to build the project.

property containerImage

readonly containerImage?: string;

The container image to use for builds. - the default workflow container

property env

readonly env?: {
    [key: string]: string;
};

Build environment variables. {}

property gitIdentity

readonly gitIdentity?: GitIdentity;

Git identity to use for the workflow. - default identity

property mutableBuild

readonly mutableBuild?: boolean;

Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
This is enabled by default only if githubTokenSecret is set. Otherwise it is disabled, which implies that file changes that happen during build will not be pushed back to the branch.
true

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

namespace cdk

module 'lib/cdk/index.d.ts' {}

class AutoDiscoverBase

abstract class AutoDiscoverBase extends Component {}

Base class for auto-discovering and creating project subcomponents.

constructor

constructor(project: Project, options: AutoDiscoverBaseOptions);

property entrypoints

readonly entrypoints: string[];

Auto-discovered entry points with paths relative to the project directory.

class ConstructLibrary

abstract class ConstructLibrary extends JsiiProject {}

A multi-language library for CDK constructs.

constructor

constructor(options: ConstructLibraryOptions);

class IntegrationTestAutoDiscoverBase

class IntegrationTestAutoDiscoverBase extends AutoDiscoverBase {}

Base class for locating integration tests in the project's test tree.

constructor

constructor(project: Project, options: IntegrationTestAutoDiscoverBaseOptions);

class IntegrationTestBase

abstract class IntegrationTestBase extends Component {}

constructor

constructor(project: Project, options: IntegrationTestBaseOptions);

property assertTask

readonly assertTask: Task;

Synthesizes the integration test and compares against a local copy (runs during build).

property deployTask

readonly deployTask: Task;

Deploy the integration test and update the snapshot upon success.

property name

protected readonly name: string;

Integration test name.

property snapshotTask

readonly snapshotTask: Task;

Just update snapshot (without deployment).

property tmpDir

protected readonly tmpDir: string;

Temporary directory for each integration test.

class JsiiDocgen

class JsiiDocgen extends Component {}

Creates a markdown file based on the jsii manifest: - Adds a docgen script to package.json - Runs jsii-docgen after compilation - Enforces that markdown file is checked in

constructor

constructor(scope: IConstruct, options?: JsiiDocgenOptions);

constructor

constructor(options: JsiiProjectOptions);

interface AutoDiscoverBaseOptions

interface AutoDiscoverBaseOptions {}

Options for AutoDiscoverBase

property extension

readonly extension: string;

Locate files with the given extension.
Example 1
".integ.ts"

property projectdir

readonly projectdir: string;

Locate entrypoints in the given project directory.
Example 1
"test"

interface Catalog

interface Catalog {}

property announce

readonly announce?: boolean;

Should we announce new versions? true

property twitter

readonly twitter?: string;

Twitter account to in announcement tweet.

interface ConstructLibraryOptions

interface ConstructLibraryOptions extends JsiiProjectOptions {}

property catalog

readonly catalog?: Catalog;

Libraries will be picked up by the construct catalog when they are published to npm as jsii modules and will be published under:
https://awscdk.io/packages/[@SCOPE/]PACKAGE@VERSION
The catalog will also post a tweet to https://twitter.com/awscdkio with the package name, description and the above link. You can disable these tweets through { announce: false }.
You can also add a Twitter handle through { twitter: 'xx' } which will be mentioned in the tweet.
See Also
- https://github.com/construct-catalog/catalog
  - new version will be announced

interface IntegrationTestAutoDiscoverBaseOptions

interface IntegrationTestAutoDiscoverBaseOptions {}

Options for IntegrationTestAutoDiscoverBase

property testdir

readonly testdir: string;

Test source tree.

interface IntegrationTestBaseOptions

interface IntegrationTestBaseOptions {}

Options for IntegrationTest

property entrypoint

readonly entrypoint: string;

A path from the project root directory to a TypeScript file which contains the integration test app.
This is relative to the root directory of the project.
Example 1
"test/subdir/foo.integ.ts"

property name

readonly name?: string;

Name of the integration test - Derived from the entrypoint filename.

property tsconfigPath

readonly tsconfigPath: string;

The path of the tsconfig.json file to use when running integration test cdk apps.

property filePath

readonly filePath?: string;

File path for generated docs. "API.md"

property version

readonly version?: string;

A semver version string to install a specific version of jsii-docgen.
'*'

interface JsiiDotNetTarget

interface JsiiDotNetTarget extends NugetPublishOptions {}

property dotNetNamespace

readonly dotNetNamespace: string;

property iconUrl

readonly iconUrl?: string;

property packageId

readonly packageId: string;

property moduleName

readonly moduleName: string;

The name of the target repository in which this module will be published (e.g. github.com/owner/repo).
The module itself will always be published under a subdirectory named according to the packageName of the module (e.g. github.com/foo/bar/pkg).
Example 1
github.com/owner/repo

property packageName

readonly packageName?: string;

The name of the Go package name.
If not specified, package name will be derived from the JavaScript module name by removing non-alphanumeric characters (e.g. @projen/foo-bar will be projenfoobar).
- derived from the JavaScript module name

property versionSuffix

readonly versionSuffix?: string;

A suffix appended at the end of the module version (e.g "-devprefix").
- none

interface JsiiJavaTarget

interface JsiiJavaTarget extends MavenPublishOptions {}

property javaPackage

readonly javaPackage: string;

property mavenArtifactId

readonly mavenArtifactId: string;

property mavenGroupId

readonly mavenGroupId: string;

interface JsiiProjectOptions

interface JsiiProjectOptions extends TypeScriptProjectOptions {}

property author

readonly author: string;

The name of the library author. $GIT_USER_NAME

property authorAddress

readonly authorAddress: string;

Email or URL of the library author. $GIT_USER_EMAIL

property compat

readonly compat?: boolean;

Automatically run API compatibility test against the latest version published to npm after compilation.
- You can manually run compatibility tests using yarn compat if this feature is disabled. - You can ignore compatibility failures by adding lines to a ".compatignore" file.
false

property compatIgnore

readonly compatIgnore?: string;

Name of the ignore file for API compatibility tests.
".compatignore"

property compressAssembly

readonly compressAssembly?: boolean;

Emit a compressed version of the assembly false

property dotnet

readonly dotnet?: JsiiDotNetTarget;

Deprecated
use publishToNuget

property excludeTypescript

readonly excludeTypescript?: string[];

Accepts a list of glob patterns. Files matching any of those patterns will be excluded from the TypeScript compiler input.
By default, jsii will include all *.ts files (except .d.ts files) in the TypeScript compiler input. This can be problematic for example when the package's build or test procedure generates .ts files that cannot be compiled with jsii's compiler settings.

property jsiiVersion

readonly jsiiVersion?: string;

Version of the jsii compiler to use.
Set to "*" if you want to manually manage the version of jsii in your project by managing updates to package.json on your own.
NOTE: The jsii compiler releases since 5.0.0 are not semantically versioned and should remain on the same minor, so we recommend using a ~ dependency (e.g. ~5.0.0).
"~5.6.0" "~5.8.0"

property publishToGo

readonly publishToGo?: JsiiGoTarget;

Publish Go bindings to a git repository. - no publishing

property python

readonly python?: JsiiPythonTarget;

Deprecated
use publishToPyPi

property rootdir

readonly rootdir?: string;

interface JsiiPythonTarget

interface JsiiPythonTarget extends PyPiPublishOptions {}

property distName

readonly distName: string;

property module

readonly module: string;

enum Stability

enum Stability {
    EXPERIMENTAL = 'experimental',
    STABLE = 'stable',
    DEPRECATED = 'deprecated',
}

member DEPRECATED

DEPRECATED = 'deprecated'

member EXPERIMENTAL

EXPERIMENTAL = 'experimental'

member STABLE

STABLE = 'stable'

namespace cdk8s

module 'lib/cdk8s/index.d.ts' {}

class AutoDiscover

class AutoDiscover extends Component {}

Automatically discovers and creates IntegrationTests from entry points found in the test tree.

constructor

constructor(project: Project, options: AutoDiscoverOptions);

constructor

constructor(project: Project, options: Cdk8sDepsOptions);

property cdk8sMajorVersion

readonly cdk8sMajorVersion: number;

The major version of the CDK8s (e.g. 1, 2, ...)

property cdk8sMinimumVersion

readonly cdk8sMinimumVersion: string;

The minimum version of the CDK8s (e.g. 2.0.0)

method packageNames

protected abstract packageNames: () => Cdk8sPackageNames;

Return a configuration object with information about package naming in various languages

class Cdk8sDepsPy

class Cdk8sDepsPy extends Cdk8sDeps {}

method packageNames

protected packageNames: () => Cdk8sPackageNames;

constructor

constructor(options: Cdk8sPythonOptions);

property cdk8sDeps

readonly cdk8sDeps: Cdk8sDeps;

constructor

constructor(options: Cdk8sTypeScriptAppOptions);

property cdk8sDeps

readonly cdk8sDeps: Cdk8sDeps;

class ConstructLibraryCdk8s

class ConstructLibraryCdk8s extends ConstructLibrary {}

CDK8s construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the CDK for Kubernetes (CDK8s), with a friendly workflow and automatic publishing to the construct catalog.
cdk8s-construct

constructor

constructor(options: ConstructLibraryCdk8sOptions);

property constructsVersion

readonly constructsVersion: string;

The constructs version this app is using.

constructor

constructor(project: Project, options: IntegrationTestOptions);

class IntegrationTestAutoDiscover

class IntegrationTestAutoDiscover extends IntegrationTestAutoDiscoverBase {}

Discovers and creates integration tests from files in the test root.

constructor

constructor(project: Project, options: IntegrationTestAutoDiscoverOptions);

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Automatically discover integration tests
true

interface Cdk8sDepsCommonOptions

interface Cdk8sDepsCommonOptions {}

Options for Cdk8sDeps

property cdk8sCliVersion

readonly cdk8sCliVersion?: string;

Minimum version of the cdk8s-cli to depend on.
"2.0.28"

property cdk8sCliVersionPinning

readonly cdk8sCliVersionPinning?: boolean;

Use pinned version instead of caret version for cdk8s-cli.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property cdk8sPlusVersion

readonly cdk8sPlusVersion?: string;

Minimum version of the cdk8s-plus-XX to depend on.
"2.0.0-rc.26"

property cdk8sPlusVersionPinning

readonly cdk8sPlusVersionPinning?: boolean;

Use pinned version instead of caret version for cdk8s-plus-17.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property cdk8sVersion

readonly cdk8sVersion: string;

Minimum version of the cdk8s to depend on.
"2.3.33"

property cdk8sVersionPinning

readonly cdk8sVersionPinning?: boolean;

Use pinned version instead of caret version for cdk8s.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property constructsVersion

readonly constructsVersion?: string;

Minimum version of the constructs library to depend on.
"10.1.42"

property constructsVersionPinning

readonly constructsVersionPinning?: boolean;

Use pinned version instead of caret version for constructs.
You can use this to prevent yarn to mix versions for your consructs package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property k8sMinorVersion

readonly k8sMinorVersion?: number;

The cdk8s-plus library depends of Kubernetes minor version For example, cdk8s-plus-22 targets kubernetes version 1.22.0 cdk8s-plus-21 targets kubernetes version 1.21.0
22

interface Cdk8sDepsOptions

interface Cdk8sDepsOptions extends Cdk8sDepsCommonOptions {}

property cdk8sCliDependency

readonly cdk8sCliDependency: boolean;

Add cdk8s-cli only to Node projects
false

property dependencyType

readonly dependencyType: DependencyType;

The type of dependency to use for runtime CDK8s and constructs modules.
For libraries, use peer dependencies and for apps use runtime dependencies.

interface Cdk8sPackageNames

interface Cdk8sPackageNames {}

property cdk8s

readonly cdk8s: string;

Fully qualified name of the core framework package

property cdk8sClient

readonly cdk8sClient?: string;

Fully qualified name of the client package. Used only on Node projects

property cdk8sPlus

readonly cdk8sPlus: string;

Fully qualified name of the cdk9s-plus-XX library package

property constructs

readonly constructs: string;

Fully qualified name of the constructs library package

property cdk8sImports

readonly cdk8sImports?: string[];

Import additional specs
- no additional specs imported

property k8sSpecVersion

readonly k8sSpecVersion?: string;

Import a specific Kubernetes spec version.
- Use the cdk8s default

interface Cdk8sTypeScriptAppOptions

interface Cdk8sTypeScriptAppOptions
    extends TypeScriptProjectOptions,
        Cdk8sDepsCommonOptions {}

property appEntrypoint

readonly appEntrypoint?: string;

The CDK8s app's entrypoint (relative to the source directory, which is "src" by default).
"main.ts"

property cdk8sImports

readonly cdk8sImports?: string[];

Import additional specs
- no additional specs imported

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Automatically adds an cdk8s.IntegrationTest for each .integ.ts app in your test directory. If this is disabled, you can manually add an cdk8s.AutoDiscover component to your project.
true

property k8sSpecVersion

readonly k8sSpecVersion?: string;

Import a specific Kubernetes spec version.
- Use the cdk8s default

interface ConstructLibraryCdk8sOptions

interface ConstructLibraryCdk8sOptions extends ConstructLibraryOptions {}

property cdk8sPlusVersionPinning

readonly cdk8sPlusVersionPinning?: boolean;

Use pinned version instead of caret version for cdk8s-plus-17.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property cdk8sVersion

readonly cdk8sVersion: string;

Minimum target version this library is tested against.
"1.4.10"

property cdk8sVersionPinning

readonly cdk8sVersionPinning?: boolean;

Use pinned version instead of caret version for CDK8s.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property constructsVersionPinning

readonly constructsVersionPinning?: boolean;

Use pinned version instead of caret version for constructs.
You can use this to prevent yarn to mix versions for your consructs package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false

property integrationTestAutoDiscover

readonly integrationTestAutoDiscover?: boolean;

Automatically adds an cdk8s.IntegrationTest for each .integ.ts app in your test directory. If this is disabled, you can manually add an cdk8s.AutoDiscover component to your project.
true

interface IntegrationTestAutoDiscoverOptions

interface IntegrationTestAutoDiscoverOptions
    extends IntegrationTestAutoDiscoverBaseOptions {}

property tsconfigPath

readonly tsconfigPath: string;

Path to the tsconfig file to use for integration tests.

interface IntegrationTestOptions

interface IntegrationTestOptions extends IntegrationTestBaseOptions {}

Options for IntegrationTest

namespace cdktf

module 'lib/cdktf/index.d.ts' {}

class ConstructLibraryCdktf

class ConstructLibraryCdktf extends ConstructLibrary {}

CDKTF construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the CDK for Terraform (CDKTF), with a friendly workflow and automatic publishing to the construct catalog.
cdktf-construct

constructor

constructor(options: ConstructLibraryCdktfOptions);

interface ConstructLibraryCdktfOptions

interface ConstructLibraryCdktfOptions extends ConstructLibraryOptions {}

property cdktfVersion

readonly cdktfVersion: string;

Minimum target version this library is tested against. "^0.13.0"

namespace circleci

module 'lib/circleci/index.d.ts' {}

variable FilterMainBranchOnly

const FilterMainBranchOnly: Filter;

constant to create a filter to make a job or workflow only run on master

function isObjectContainingFieldExactly

isObjectContainingFieldExactly: (obj: any, field: string) => boolean;

class Circleci

class Circleci extends Component {}

Circleci Class to manage .circleci/config.yml. Check projen's docs for more information.
See Also
- https://circleci.com/docs/2.0/configuration-reference/

constructor

constructor(project: Project, options?: CircleCiProps);

property file

readonly file: YamlFile;

The yaml file for the Circleci pipeline

method addOrb

addOrb: (name: string, orb: string) => void;

Add a Circleci Orb to pipeline. Will throw error if the orb already exists
Parameter name
Parameter orb

method addWorkflow

addWorkflow: (workflow: Workflow) => void;

add new workflow to existing pipeline
Parameter workflow

interface CircleCiProps

interface CircleCiProps {}

Options for class Circleci
See Also
- https://circleci.com/docs/2.0/configuration-reference/

property jobs

readonly jobs?: Job[];

List of Jobs to create unique steps per pipeline, e.g.

jobs: [{
 identifier: "compile",
 docker: { image: "golang:alpine" }
 steps: ["checkout", run: {command: "go build ."}]
}]

property orbs

readonly orbs?: Record<string, string>;

Contains a map of CirclCi Orbs

orbs: {
 node: "circleci/node@5.0.1"
 slack: "circleci/slack@4.8.3"
}

property setup

readonly setup?: boolean;

The setup field enables you to conditionally trigger configurations from outside the primary .circleci parent directory, update pipeline parameters, or generate customized configurations.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#setup

property version

readonly version?: number;

pipeline version
2.1
See Also
- https://circleci.com/docs/2.0/configuration-reference/#version

property workflows

readonly workflows?: Workflow[];

List of Workflows of pipeline, e.g.

workflows: {
  {
    identifier: "build",
      jobs: [{
         identifier: "node/install",
         context: ["npm"],
      }]
  }
}

interface Docker

interface Docker {}

Options for docker executor
See Also
- https://circleci.com/docs/2.0/configuration-reference/#docker

property auth

readonly auth?: Record<string, string>;

Authentication for registries using standard docker login credentials

property awsAuth

readonly awsAuth?: Record<string, string>;

Authentication for AWS Elastic Container Registry (ECR)

property command

readonly command?: string[];

The command used as pid 1 (or args for entrypoint) when launching the container

property entrypoint

readonly entrypoint?: string[];

The command used as executable when launching the container

property environment

readonly environment?: Record<string, string | number | boolean>;

A map of environment variable names and values

property image

readonly image: string;

The name of a custom docker image to use

property name

readonly name?: string;

The name the container is reachable by. By default, container services are accessible through localhost

property user

readonly user?: string;

Which user to run commands as within the Docker container

interface Filter

interface Filter {}

The branches key controls whether the current branch should have a schedule trigger created for it, where current branch is the branch containing the config.yml file with the trigger stanza. That is, a push on the main branch will only schedule a workflow for the main branch.
Branches can have the keys only and ignore which either map to a single string naming a branch. You may also use regular expressions to match against branches by enclosing them with /’s, or map to a list of such strings. Regular expressions must match the entire string.
Any branches that match only will run the job. Any branches that match ignore will not run the job. If neither only nor ignore are specified then all branches will run the job. If both only and ignore are specified the only is considered before ignore.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#filters

property branches

readonly branches?: FilterConfig;

property tags

readonly tags?: FilterConfig;

interface FilterConfig

interface FilterConfig {}

set an inclusive or exclusive filter
See Also
- https://circleci.com/docs/2.0/configuration-reference/#filters

property ignore

readonly ignore?: string[];

Either a single branch specifier, or a list of branch specifiers

property only

readonly only?: string[];

Either a single branch specifier, or a list of branch specifiers

interface Job

interface Job extends INamed {}

A Workflow is comprised of one or more uniquely named jobs. Jobs are specified in the jobs map, see Sample 2.0 config.yml for two examples of a job map. The name of the job is the key in the map, and the value is a map describing the job.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#jobs

interface Job

interface Job {}

Each job consists of the job’s name as a key and a map as a value. A name should be case insensitive unique within a current jobs list.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#job_name

property docker

readonly docker?: Docker[];

property environment

readonly environment?: Record<string, string | number | boolean>;

A map of environment variable names and values.

property machine

readonly machine?: Machine;

property macos

readonly macos?: Macos;

property parallelism

readonly parallelism?: number;

Number of parallel instances of this job to run (default: 1)

property parameters

readonly parameters?: Record<string, PipelineParameter>;

Parameters for making a job explicitly configurable in a workflow.

property shell

readonly shell?: string;

Shell to use for execution command in all steps. Can be overridden by shell in each step

property steps

readonly steps?: any[];

no type support here, for syntax

property workingDirectory

readonly workingDirectory?: string;

In which directory to run the steps. Will be interpreted as an absolute path. Default: ~/project

interface Machine

interface Machine {}

property dockerLayerCaching

readonly dockerLayerCaching?: string;

enable docker layer caching
See Also
- https://circleci.com/docs/2.0/configuration-reference/#available-machine-images

property image

readonly image: string;

The VM image to use.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#available-machine-images

interface Macos

interface Macos {}

CircleCI supports running jobs on macOS, to allow you to build, test, and deploy apps for macOS, iOS, tvOS and watchOS. To run a job in a macOS virtual machine, you must add the macos key to the top-level configuration for the job and specify the version of Xcode you would like to use.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#macos

property xcode

readonly xcode: string;

The version of Xcode that is installed on the virtual machine

interface Matrix

interface Matrix {}

The matrix stanza allows you to run a parameterized job multiple times with different arguments.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#matrix-requires-version-21

property alias

readonly alias?: string;

An alias for the matrix, usable from another job’s requires stanza. Defaults to the name of the job being executed

property parameters

readonly parameters?: Record<string, string[] | number[]>;

A map of parameter names to every value the job should be called with

interface PipelineParameter

interface PipelineParameter {}

Parameters are declared by name under a job, command, or executor.
See Also
- https://circleci.com/docs/2.0/reusing-config#using-the-parameters-declaration

property default

readonly default?: string | number | boolean;

The default value for the parameter. If not present, the parameter is implied to be required.

property description

readonly description?: string;

Used to generate documentation for your orb.

property type

readonly type: PipelineParameterType;

The parameter type, required.

interface Run

interface Run {}

Used for invoking all command-line programs, taking either a map of configuration values, or, when called in its short-form, a string that will be used as both the command and name. Run commands are executed using non-login shells by default, so you must explicitly source any dotfiles as part of the command.
Not used because type incompatible types in steps array
See Also
- https://circleci.com/docs/2.0/configuration-reference/#run

property background

readonly background?: string;

Whether this step should run in the background (default: false)

property command

readonly command: string;

Command to run via the shell

property environment

readonly environment?: string;

Additional environmental variables, locally scoped to command

property name

readonly name?: string;

Title of the step to be shown in the CircleCI UI (default: full command)

property noOutputTimeout

readonly noOutputTimeout?: string;

Elapsed time the command can run without output such as “20m”, “1.25h”, “5s”. The default is 10 minutes

property shell

readonly shell?: string;

Shell to use for execution command

property when

readonly when?: JobWhen | string;

Specify when to enable or disable the step.

property workingDirectory

readonly workingDirectory?: string;

In which directory to run this step. Will be interpreted relative to the working_directory of the job). (default: .)

interface Schedule

interface Schedule {}

A workflow may have a schedule indicating it runs at a certain time.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#schedule

property cron

readonly cron?: string;

The cron key is defined using POSIX crontab syntax.

property filters

readonly filters: Filter;

interface StepRun

interface StepRun {}

Execution steps for Job
See Also
- https://circleci.com/docs/2.0/configuration-reference/#steps

property run

readonly run?: Run;

interface Triggers

interface Triggers {}

Specifies which triggers will cause this workflow to be executed. Default behavior is to trigger the workflow when pushing to a branch.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#triggers

property schedule

readonly schedule?: Schedule;

interface Workflow

interface Workflow extends INamed {}

Used for orchestrating all jobs. Each workflow consists of the workflow name as a key and a map as a value. A name should be unique within the current config.yml. The top-level keys for the Workflows configuration are version and jobs.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#workflows

property jobs

readonly jobs?: WorkflowJob[];

property triggers

readonly triggers?: Triggers[];

property when

readonly when?: any;

when is too dynamic to be casted to interfaces. Check Docu as reference
See Also
- https://circleci.com/docs/2.0/configuration-reference/#logic-statement-examples

interface WorkflowJob

interface WorkflowJob extends INamed {}

A Job is part of Workflow. A Job can be created with Job or it can be provided by the orb
See Also
- https://circleci.com/docs/2.0/configuration-reference/#jobs-in-workflow

property context

readonly context?: string[];

The name of the context(s). The initial default name is org-global. Each context name must be unique.

property filters

readonly filters?: Filter;

Job Filters can have the key branches or tags

property matrix

readonly matrix?: Matrix;

property name

readonly name?: string;

A replacement for the job name. Useful when calling a job multiple times

property orbParameters

readonly orbParameters?: Record<string, string | number | boolean>;

Parameters passed to job when referencing a job from orb

property requires

readonly requires?: string[];

A list of jobs that must succeed for the job to start.

property type

readonly type?: JobType;

A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed.

enum JobType

enum JobType {
    APPROVAL = 'approval',
}

A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed
See Also
- https://circleci.com/docs/2.0/configuration-reference/#type

member APPROVAL

APPROVAL = 'approval'

enum JobWhen

enum JobWhen {
    ALWAYS = 'always',
    ON_SUCCESS = 'on_success',
    ON_FAIL = 'on_fail',
}

Specify when to enable or disable the step.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#steps

member ALWAYS

ALWAYS = 'always'

member ON_FAIL

ON_FAIL = 'on_fail'

member ON_SUCCESS

ON_SUCCESS = 'on_success'

enum PipelineParameterType

enum PipelineParameterType {
    STRING = 'string',
    BOOLEAN = 'boolean',
    INTEGER = 'integer',
    ENUM = 'enum',
}

Pipeline parameter types
See Also
- https://circleci.com/docs/2.0/reusing-config#parameter-syntax

member BOOLEAN

BOOLEAN = 'boolean'

member ENUM

ENUM = 'enum'

member INTEGER

INTEGER = 'integer'

member STRING

STRING = 'string'

enum ResourceClass

enum ResourceClass {
    SMALL = 'small',
    MEDIUM = 'medium',
    MEDIUM_PLUS = 'medium+',
    LARGE_X = 'xlarge',
    LARGE_2X = '2xlarge',
    LARGE_2X_PLUS = '2xlarge+',
}

The resource_class feature allows configuring CPU and RAM resources for each job. Different resource classes are available for different executors, as described in the tables below.
See Also
- https://circleci.com/docs/2.0/configuration-reference/#resourceclass

member LARGE_2X

LARGE_2X = '2xlarge'

member LARGE_2X_PLUS

LARGE_2X_PLUS = '2xlarge+'

member LARGE_X

LARGE_X = 'xlarge'

member MEDIUM

MEDIUM = 'medium'

member MEDIUM_PLUS

MEDIUM_PLUS = 'medium+'

member SMALL

SMALL = 'small'

namespace github

module 'lib/github/index.d.ts' {}

class AutoApprove

class AutoApprove extends Component {}

Auto approve pull requests that meet a criteria

constructor

constructor(github: GitHub, options?: AutoApproveOptions);

property label

readonly label: string;

class AutoMerge

class AutoMerge extends Component {}

Automatically merge Pull Requests using Mergify
> [!NOTE] > GitHub now natively provides the same features, so you don't need Mergify > anymore. See GitHubOptions.mergeQueue and MergeQueueOptions.autoQueue.
If buildJob is specified, the specified GitHub workflow job ID is required to succeed in order for the PR to be merged.
approvedReviews specified the number of code review approvals required for the PR to be merged.
See Also
- https://mergify.com/

constructor

constructor(github: GitHub, options?: AutoMergeOptions);

method addConditions

addConditions: (...conditions: string[]) => void;

Adds conditions to the auto merge rule.
Parameter conditions
The conditions to add (mergify syntax)

method addConditionsLater

addConditionsLater: (later: IAddConditionsLater) => void;

Adds conditions that will be rendered only during synthesis.
Parameter later
The later

class AutoQueue

class AutoQueue extends Component {}

Automatically add pull requests to the merge queue PRs will be merged once they pass required checks.

constructor

constructor(scope: IConstruct, options?: gh.AutoQueueOptions);

class Dependabot

class Dependabot extends Component {}

Defines dependabot configuration for node projects.
Since module versions are managed in projen, the versioning strategy will be configured to "lockfile-only" which means that only updates that can be done on the lockfile itself will be proposed.

constructor

constructor(github: GitHub, options?: DependabotOptions);

property config

readonly config: any;

The raw dependabot configuration.
See Also
- https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates

property ignoresProjen

readonly ignoresProjen: boolean;

Whether or not projen is also upgraded in this config,

method addAllow

addAllow: (dependencyName: string) => void;

Allows a dependency from automatic updates.
Parameter dependencyName
Use to allow updates for dependencies with matching names, optionally using * to match zero or more characters.

method addIgnore

addIgnore: (dependencyName: string, ...versions: string[]) => void;

Ignores a dependency from automatic updates.
Parameter dependencyName
Use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters.
Parameter versions
Use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager (for example: ^1.0.0 for npm, or ~> 2.0 for Bundler).

class GitHub

class GitHub extends Component {}

constructor

constructor(project: Project, options?: GitHubOptions);

property actions

readonly actions: GitHubActionsProvider;

The GitHub Actions provider used to manage the versions of actions used in steps

property downloadLfs

readonly downloadLfs: boolean;

Whether downloading from LFS is enabled for this GitHub project

property mergeQueue

readonly mergeQueue?: MergeQueue;

The MergeQueue component configured on this repository This is undefined if merge queues are not enabled for this repository.

property mergify

readonly mergify?: Mergify;

The Mergify component configured on this repository This is undefined if Mergify is not enabled for this repository.

property projenCredentials

readonly projenCredentials: GithubCredentials;

GitHub API authentication method used by projen workflows.

method addDependabot

addDependabot: (options?: DependabotOptions) => Dependabot;

method addPullRequestTemplate

addPullRequestTemplate: (...content: string[]) => PullRequestTemplate;

method addWorkflow

addWorkflow: (name: string) => GithubWorkflow;

Adds a workflow to the project.
Parameter name
Name of the workflow
Returns
a GithubWorkflow instance

method of

static of: (project: Project) => GitHub | undefined;

Returns the GitHub component of a project or undefined if the project does not have a GitHub component.

method tryFindWorkflow

tryFindWorkflow: (name: string) => undefined | GithubWorkflow;

Finds a GitHub workflow by name. Returns undefined if the workflow cannot be found.
Parameter name
The name of the GitHub workflow

class GitHubActionsProvider

class GitHubActionsProvider {}

Manage the versions used for GitHub Actions used in steps

method get

get: (action: string) => string;

Resolve an action name to the version that should be used, taking into account any overrides.

method set

set: (action: string, override: string) => void;

Define an override for a given action.
Specify the action name without a version to override all usages of the action. You can also override a specific action version, by providing the version string. Specific overrides take precedence over overrides without a version.
If an override for the same action name is set multiple times, the last override is used.
Example 1
// Force any use of actions/checkout to use a pin a specific commit project.github.actions.set("actions/checkout", "actions/checkout@aaaaaa");
// But pin usage of v4 to a different commit project.github.actions.set("actions/checkout@v4", "actions/checkout@ffffff");

class GithubCredentials

class GithubCredentials {}

Represents a method of providing GitHub API access for projen workflows.

property setupSteps

readonly setupSteps: JobStep[];

Setup steps to obtain GitHub credentials.

property tokenRef

readonly tokenRef: string;

The value to use in a workflow when a GitHub token is expected. This typically looks like "${{ some.path.to.a.value }}".

method fromApp

static fromApp: (options?: GithubCredentialsAppOptions) => GithubCredentials;

Provide API access through a GitHub App.
The GitHub App must be installed on the GitHub repo, its App ID and a private key must be added as secrets to the repo. The name of the secrets can be specified here.
See Also
- https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app
- https://projen.io/docs/integrations/github/#github-app - app id stored in "PROJEN_APP_ID" and private key stored in "PROJEN_APP_PRIVATE_KEY" with all permissions attached to the app

method fromPersonalAccessToken

static fromPersonalAccessToken: (
    options?: GithubCredentialsPersonalAccessTokenOptions
) => GithubCredentials;

Provide API access through a GitHub personal access token.
The token must be added as a secret to the GitHub repo, and the name of the secret can be specified here.
See Also
- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token - a secret named "PROJEN_GITHUB_TOKEN"

class GitHubProject

class GitHubProject extends Project {}

GitHub-based project.
Deprecated
This is a *temporary* class. At the moment, our base project types such as NodeProject and JavaProject are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.

constructor

constructor(options: GitHubProjectOptions);

property devContainer

readonly devContainer: DevContainer;

Access for .devcontainer.json (used for GitHub Codespaces)
This will be undefined if devContainer boolean is false

property github

readonly github: GitHub;

Access all github components.
This will be undefined for subprojects.

property gitpod

readonly gitpod: Gitpod;

Access for Gitpod
This will be undefined if gitpod boolean is false

property projectType

readonly projectType: ProjectType;

property vscode

readonly vscode: VsCode;

Access all VSCode components.
This will be undefined for subprojects.

method annotateGenerated

annotateGenerated: (glob: string) => void;

Marks the provided file(s) as being generated. This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.
Parameter glob
the glob pattern to match (could be a file path).
See Also
- https://github.com/github/linguist/blob/master/docs/overrides.md

class GithubWorkflow

class GithubWorkflow extends Component {}

Workflow for GitHub.
A workflow is a configurable automated process made up of one or more jobs.
See Also
- https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

constructor

constructor(github: GitHub, name: string, options?: GithubWorkflowOptions);

Parameter github
The GitHub component of the project this workflow belongs to.
Parameter name
The name of the workflow, displayed under the repository's "Actions" tab.
Parameter options
Additional options to configure the workflow.

property concurrency

readonly concurrency?: ConcurrencyOptions;

The concurrency configuration of the workflow. undefined means no concurrency limitations.

property env

readonly env?: Record<string, string>;

Additional environment variables to set for the workflow.

property file

readonly file: YamlFile;

The workflow YAML file. May not exist if workflowsEnabled is false on GitHub.

property name

readonly name: string;

The name of the workflow. GitHub displays the names of your workflows under your repository's "Actions" tab.
See Also
- https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name

property projenCredentials

readonly projenCredentials: GithubCredentials;

GitHub API authentication method used by projen workflows.

property runName

runName?: string;

The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a push or pull_request event, it is set as the commit message.
This value can include expressions and can reference github and inputs contexts.

method addJob

addJob: (
    id: string,
    job: workflows.Job | workflows.JobCallingReusableWorkflow
) => void;

Adds a single job to the workflow.
Parameter id
The job name (unique within the workflow)
Parameter job
The job specification

method addJobs

addJobs: (
    jobs: Record<string, workflows.Job | workflows.JobCallingReusableWorkflow>
) => void;

Add jobs to the workflow.
Parameter jobs
Jobs to add.

method getJob

getJob: (id: string) => workflows.Job | workflows.JobCallingReusableWorkflow;

Get a single job from the workflow.
Parameter id
The job name (unique within the workflow)

method on

on: (events: workflows.Triggers) => void;

Add events to triggers the workflow.
Parameter events
The event(s) to trigger the workflow.

method removeJob

removeJob: (id: string) => void;

Removes a single job to the workflow.
Parameter id
The job name (unique within the workflow)

method updateJob

updateJob: (
    id: string,
    job: workflows.Job | workflows.JobCallingReusableWorkflow
) => void;

Updates a single job to the workflow.
Parameter id
The job name (unique within the workflow)

method updateJobs

updateJobs: (
    jobs: Record<string, workflows.Job | workflows.JobCallingReusableWorkflow>
) => void;

Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs
Parameter jobs
Jobs to update.

constructor

constructor(scope: IConstruct, options?: MergeQueueOptions);

method preSynthesize

preSynthesize: () => void;

class Mergify

class Mergify extends Component {}

constructor

constructor(github: GitHub, options?: MergifyOptions);

method addQueue

addQueue: (queue: MergifyQueue) => void;

method addRule

addRule: (rule: MergifyRule) => void;

class PullRequestBackport

class PullRequestBackport extends Component {}

constructor

constructor(scope: IConstruct, options?: PullRequestBackportOptions);

property file

readonly file: JsonFile;

property workflow

readonly workflow: GithubWorkflow;

class PullRequestLint

class PullRequestLint extends Component {}

Configure validations to run on GitHub pull requests. Only generates a file if at least one linter is configured.

constructor

constructor(github: GitHub, options?: PullRequestLintOptions);

method preSynthesize

preSynthesize: () => void;

constructor

constructor(github: GitHub, options?: PullRequestTemplateOptions);

method of

static of: (project: Project) => PullRequestTemplate | undefined;

Returns the PullRequestTemplate instance associated with a project or undefined if there is no PullRequestTemplate.
Parameter project
The project
Returns
A PullRequestTemplate

class Stale

class Stale extends Component {}

Warns and then closes issues and PRs that have had no activity for a specified amount of time.
The default configuration will:
* Add a "Stale" label to pull requests after 14 days and closed after 2 days * Add a "Stale" label to issues after 60 days and closed after 7 days * If a comment is added, the label will be removed and timer is restarted.
See Also
- https://github.com/actions/stale

constructor

constructor(github: GitHub, options?: StaleOptions);

class TaskWorkflow

class TaskWorkflow extends GithubWorkflow {}

A GitHub workflow for common build tasks within a project.

constructor

constructor(github: GitHub, options: TaskWorkflowOptions);

property artifactsDirectory

readonly artifactsDirectory?: string;

property jobId

readonly jobId: string;

class TaskWorkflowJob

class TaskWorkflowJob extends Component {}

The primary or initial job of a TaskWorkflow.
{Job}

constructor

constructor(scope: IConstruct, task: Task, options: TaskWorkflowJobOptions);

Parameter scope
should be part of the project the Task belongs to.
Parameter task
the main task that is run as part of this job.
Parameter options
options to configure the TaskWorkflowJob.

property concurrency

readonly concurrency?: {};

property container

readonly container?: ContainerOptions;

property continueOnError

readonly continueOnError?: boolean;

property defaults

readonly defaults?: JobDefaults;

property env

readonly env?: Record<string, string>;

property environment

readonly environment?: {};

property if

readonly if?: string;

property name

readonly name?: string;

property needs

readonly needs?: string[];

property outputs

readonly outputs?: Record<string, JobStepOutput>;

property permissions

readonly permissions: JobPermissions;

property runsOn

readonly runsOn?: string[];

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

property services

readonly services?: Record<string, ContainerOptions>;

property steps

readonly steps: JobStep[];

property strategy

readonly strategy?: JobStrategy;

property timeoutMinutes

readonly timeoutMinutes?: number;

property tools

readonly tools?: Tools;

class WorkflowActions

class WorkflowActions {}

A set of utility functions for creating GitHub actions in workflows.

method checkoutWithPatch

static checkoutWithPatch: (options?: CheckoutWithPatchOptions) => JobStep[];

Checks out a repository and applies a git patch that was created using uploadGitPatch.
Parameter options
Options
Returns
Job steps

method createPullRequest

static createPullRequest: (options: CreatePullRequestOptions) => JobStep[];

A step that creates a pull request based on the current repo state.
Parameter options
Options
Returns
Job steps

method setupGitIdentity

static setupGitIdentity: (id: GitIdentity) => JobStep[];

Configures the git identity (user name and email).
Parameter id
The identity to use
Returns
Job steps
Deprecated
use WorkflowSteps.setupGitIdentity instead

method uploadGitPatch

static uploadGitPatch: (options: UploadGitPatchOptions) => JobStep[];

Creates a .patch file from the current git diff and uploads it as an artifact. Use checkoutWithPatch to download and apply in another job.
If a patch was uploaded, the action can optionally fail the job.
Parameter options
Options
Returns
Job steps

class WorkflowJobs

class WorkflowJobs {}

A set of utility functions for creating jobs in GitHub Workflows.

method pullRequestFromPatch

static pullRequestFromPatch: (options: PullRequestFromPatchOptions) => Job;

Creates a pull request with the changes of a patch file.
Returns
Job

class WorkflowSteps

class WorkflowSteps {}

A collection of very commonly used, individual, GitHub Workflow Job steps.

method checkout

static checkout: (options?: CheckoutOptions) => JobStep;

Checks out a repository.
Parameter options
Options to configure the checkout JobStep
Returns
A JobStep that checks out a repository

method downloadArtifact

static downloadArtifact: (options?: DownloadArtifactOptions) => JobStep;

Downloads an artifact.
Parameter options
Options to configure the download-artifact JobStep
Returns
A JobStep that downloads an artifact

method setupGitIdentity

static setupGitIdentity: (options: SetupGitIdentityOptions) => JobStep;

Configures the git identity (user name and email).
Parameter options
Options to configure the git identity JobStep
Returns
Job step that configures the provided git identity

method tagExists

static tagExists: (tag: string, options: JobStepConfiguration) => JobStep;

Checks if a tag exists.
Requires a checkout step to have been run before this step with "fetch-depth" set to "0".
Outputs: - exists: A string value of 'true' or 'false' indicating if the tag exists.
Parameter tag
The tag to check. You may use valid bash code instead of a literal string in this field.
Parameter options
Options to configure the tag-exists JobStep
Returns
Job step that checks if the provided tag exists

method uploadArtifact

static uploadArtifact: (options: UploadArtifactOptions) => JobStep;

Uploads an artifact.
Parameter options
Options to configure the upload-artifact JobStep
Returns
A JobStep that uploads an artifact

property allowedUsernames

readonly allowedUsernames?: string[];

Only pull requests authored by these Github usernames will be auto-approved. ['github-bot']

property label

readonly label?: string;

Only pull requests with this label will be auto-approved. 'auto-approve'

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property secret

readonly secret?: string;

A GitHub secret name which contains a GitHub Access Token with write permissions for the pull_request scope.
This token is used to approve pull requests.
Github forbids an identity to approve its own pull request. If your project produces automated pull requests using the Github default token - - that you would like auto approved, such as when using the depsUpgrade property in NodeProjectOptions, then you must use a different token here.
"GITHUB_TOKEN"

interface AutoMergeOptions

interface AutoMergeOptions {}

property blockingLabels

readonly blockingLabels?: string[];

List of labels that will prevent auto-merging. ['do-not-merge']

property ruleName

readonly ruleName?: string;

Name of the mergify rule 'Automatic merge on approval and successful build'

property allowedUsernames

readonly allowedUsernames?: string[];

Only pull requests authored by these Github usernames will have auto-queue enabled. - pull requests from all users are eligible for auto-queuing

property labels

readonly labels?: string[];

Only pull requests with one of this labels will have auto-queue enabled. - all pull requests are eligible for auto-queueing

property mergeMethod

readonly mergeMethod?: MergeMethod;

The method used to add the PR to the merge queue Any branch protection rules must allow this merge method. MergeMethod.SQUASH

property projenCredentials

readonly projenCredentials?: gh.GithubCredentials;

Choose a method for authenticating with GitHub to enable auto-queue on pull requests.
The workflow cannot use a default github token. Queuing a PR with the default token will not trigger any merge queue workflows, which results in the PR just not getting merged at all.
See Also
- https://projen.io/docs/integrations/github/ - uses credentials from the GitHub component

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"]

property targetBranches

readonly targetBranches?: string[];

The branch names that we should auto-queue for
This set of branches should be a subset of MergeQueueOptions.targetBranches.
Be sure not to enable autoQueue for branches that don't have branch rules with merge requirements set up, otherwise new PRs will be merged immediately after creating without a chance for review.
## Automatically merging a set of Stacked PRs
If you set this to ['main'] you can automatically merge a set of Stacked PRs in the right order. It works like this:
- Create PR #1 from branch a, targeting main. - Create PR #2 from branch b, targeting branch a. - Create PR #3 from branch c, targeting branch b.
Initially, PR #1 will be set to auto-merge, PRs #2 and #3 will not.
Once PR #1 passes all of its requirements it will merge. That will delete branch a and change the target branch of PR #2 change to main. At that point, auto-queueing will switch on for PR #2 and it gets merged, etc.
> [!IMPORTANT] > This component will never disable AutoMerge, only enable it. So if a PR is > initially targeted at one of the branches in this list, and then > subsequently retargeted to another branch, *AutoMerge is not > automatically turned off*.

interface CheckoutOptions

interface CheckoutOptions extends JobStepConfiguration {}

property with

readonly with?: CheckoutWith;

Options for checkout.

property fetchDepth

readonly fetchDepth?: number;

Number of commits to fetch. 0 indicates all history for all branches and tags.
1

property lfs

readonly lfs?: boolean;

Whether LFS is enabled for the GitHub repository
false

property path

readonly path?: string;

Relative path under $GITHUB_WORKSPACE to place the repository - $GITHUB_WORKSPACE

property ref

readonly ref?: string;

Branch or tag name. - the default branch is implicitly used

property repository

readonly repository?: string;

The repository (owner/repo) to use. - the default repository is implicitly used

property token

readonly token?: string;

A GitHub token to use when checking out the repository.
If the intent is to push changes back to the branch, then you must use a PAT with repo (and possibly workflows) permissions. - the default GITHUB_TOKEN is implicitly used

interface CheckoutWithPatchOptions

interface CheckoutWithPatchOptions extends CheckoutWith {}

Options for checkoutWithPatch.

property patchFile

readonly patchFile?: string;

The name of the artifact the patch is stored as. ".repo.patch"

property cancelInProgress

readonly cancelInProgress?: boolean;

When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow?
false

property group

readonly group?: string;

Concurrency group controls which workflow runs will share the same concurrency limit. For example, if you specify ${{ github.workflow }}-${{ github.ref }}, workflow runs triggered on the same branch cannot run concurrenty, but workflows runs triggered on different branches can.
- ${{ github.workflow }}
See Also
- https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency#example-concurrency-groups

interface ContributorStatementOptions

interface ContributorStatementOptions {}

Options for requiring a contributor statement on Pull Requests

property exemptLabels

readonly exemptLabels?: string[];

Pull requests with one of these labels are exempted from a contributor statement. - no labels are excluded

property exemptUsers

readonly exemptUsers?: string[];

Pull requests from these GitHub users are exempted from a contributor statement. - no users are exempted

interface CreatePullRequestOptions

interface CreatePullRequestOptions {}

property assignees

readonly assignees?: string[];

Assignees to add on the PR.
- no assignees

property baseBranch

readonly baseBranch?: string;

Sets the pull request base branch.
- The branch checked out in the workflow.

property branchName

readonly branchName?: string;

The pull request branch name.
github-actions/${options.workflowName}

property credentials

readonly credentials?: GithubCredentials;

The job credentials used to create the pull request.
Provided credentials must have permissions to create a pull request on the repository.

property gitIdentity

readonly gitIdentity?: GitIdentity;

The git identity used to create the commit. - the default github-actions user

property labels

readonly labels?: string[];

Labels to apply on the PR.
- no labels.

property pullRequestDescription

readonly pullRequestDescription: string;

Description added to the pull request.
Providence information are automatically added.

property pullRequestTitle

readonly pullRequestTitle: string;

The full title used to create the pull request.
If PR titles are validated in this repo, the title should comply with the respective rules.

property signoff

readonly signoff?: boolean;

Add Signed-off-by line by the committer at the end of the commit log message.
true

property stepId

readonly stepId?: string;

The step ID which produces the output which indicates if a patch was created. "create_pr"

property stepName

readonly stepName?: string;

The name of the step displayed on GitHub. "Create Pull Request"

property workflowName

readonly workflowName: string;

The name of the workflow that will create the PR

interface DependabotAllow

interface DependabotAllow {}

You can use the allow option to customize which dependencies are updated. The allow option supports the following options.

property dependencyName

readonly dependencyName: string;

Use to allow updates for dependencies with matching names, optionally using * to match zero or more characters.
For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.

interface DependabotGroup

interface DependabotGroup {}

Defines a single group for dependency updates

property excludePatterns

readonly excludePatterns?: string[];

Optionally you can use this to exclude certain dependencies from the group.

property patterns

readonly patterns: string[];

Define a list of strings (with or without wildcards) that will match package names to form this dependency group.

interface DependabotIgnore

interface DependabotIgnore {}

You can use the ignore option to customize which dependencies are updated. The ignore option supports the following options.

property dependencyName

readonly dependencyName: string;

Use to ignore updates for dependencies with matching names, optionally using * to match zero or more characters.
For Java dependencies, the format of the dependency-name attribute is: groupId:artifactId, for example: org.kohsuke:github-api.

property versions

readonly versions?: string[];

Use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager (for example: ^1.0.0 for npm, or ~> 2.0 for Bundler).

interface DependabotOptions

interface DependabotOptions {}

property allow

readonly allow?: DependabotAllow[];

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow
Use the allow option to customize which dependencies are updated. This applies to both version and security updates.
[]

property assignees

readonly assignees?: string[];

Specify individual assignees or teams of assignees for all pull requests raised for a package manager. []

property groups

readonly groups?: {
    [name: string]: DependabotGroup;
};

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups
You can create groups to package dependency updates together into a single PR.
[]

property ignore

readonly ignore?: DependabotIgnore[];

You can use the ignore option to customize which dependencies are updated. The ignore option supports the following options. []

property ignoreProjen

readonly ignoreProjen?: boolean;

Ignores updates to projen.
This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.
Projen upgrades are covered through the ProjenUpgrade class.
true

property labels

readonly labels?: string[];

List of labels to apply to the created PR's.

property openPullRequestsLimit

readonly openPullRequestsLimit?: number;

Sets the maximum of pull requests Dependabot opens for version updates. Dependabot will not open any new requests until some of those open requests are merged or closed.
5

property registries

readonly registries?: {
    [name: string]: DependabotRegistry;
};

Map of package registries to use - use public registries

property reviewers

readonly reviewers?: string[];

Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager. []

property scheduleInterval

readonly scheduleInterval?: DependabotScheduleInterval;

How often to check for new versions and raise pull requests.
ScheduleInterval.DAILY

property targetBranch

readonly targetBranch?: string;

https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against

property versioningStrategy

readonly versioningStrategy?: VersioningStrategy;

The strategy to use when edits manifest and lock files.
VersioningStrategy.LOCKFILE_ONLY The default is to only update the lock file because package.json is controlled by projen and any outside updates will fail the build.

interface DependabotRegistry

interface DependabotRegistry {}

Use to add private registry support for dependabot
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries

property key

readonly key?: string;

A reference to a Dependabot secret containing an access key for this registry undefined

property organization

readonly organization?: string;

Used with the hex-organization registry type.
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization undefined

property password

readonly password?: string;

A reference to a Dependabot secret containing the password for the specified user undefined

property replacesBase

readonly replacesBase?: boolean;

For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple) undefined

property token

readonly token?: string;

Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}' undefined

property type

readonly type: DependabotRegistryType;

Registry type e.g. 'npm-registry' or 'docker-registry'

property url

readonly url: string;

Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'

property username

readonly username?: string;

The username that Dependabot uses to access the registry - do not authenticate

interface DownloadArtifactOptions

interface DownloadArtifactOptions extends JobStepConfiguration {}

property with

readonly with: DownloadArtifactWith;

Options for download-artifact.

interface DownloadArtifactWith

interface DownloadArtifactWith {}

property mergeMultiple

readonly mergeMultiple?: boolean;

When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path
false

property name

readonly name?: string;

Name of the artifact to download
- If unspecified, all artifacts for the run are downloaded

property path

readonly path?: string;

A file, directory or wildcard pattern that describes what to download. Supports basic tilde expansion.
- $GITHUB_WORKSPACE

property pattern

readonly pattern?: string;

A glob pattern to the artifacts that should be downloaded This is ignored if name is specified

property repository

readonly repository?: string;

The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from
- ${{ github.repository }}

property runId

readonly runId?: string;

The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from
- ${{ github.run_id }}

property token

readonly token?: string;

The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run
- If unspecified, the action will download artifacts from the current repo and the current workflow run

interface GithubCredentialsAppOptions

interface GithubCredentialsAppOptions {}

Options for GithubCredentials.fromApp

property appIdSecret

readonly appIdSecret?: string;

The secret containing the GitHub App ID
"PROJEN_APP_ID"

property owner

readonly owner?: string;

The owner of the GitHub App installation
- if empty, defaults to the current repository owner

property permissions

readonly permissions?: AppPermissions;

The permissions granted to the token.
- all permissions granted to the app

property privateKeySecret

readonly privateKeySecret?: string;

The secret containing the GitHub App private key
Escaped newlines (\n) will be automatically replaced with actual newlines.
"PROJEN_APP_PRIVATE_KEY"

property repositories

readonly repositories?: string[];

List of repositories to grant access to
- if owner is set and repositories is empty, access will be scoped to all repositories in the provided repository owner's installation. If owner and repositories are empty, access will be scoped to only the current repository.

interface GithubCredentialsPersonalAccessTokenOptions

interface GithubCredentialsPersonalAccessTokenOptions {}

Options for GithubCredentials.fromPersonalAccessToken

property secret

readonly secret?: string;

interface GitHubOptions

interface GitHubOptions {}

property downloadLfs

readonly downloadLfs?: boolean;

Download files in LFS in workflows
true if the associated project has lfsPatterns, false otherwise

property mergeQueue

readonly mergeQueue?: boolean;

Whether a merge queue should be used on this repository to merge pull requests. Requires additional configuration of the repositories branch protection rules.
false

property mergeQueueOptions

readonly mergeQueueOptions?: MergeQueueOptions;

Options for MergeQueue.
- default options

property mergify

readonly mergify?: boolean;

Whether mergify should be enabled on this repository or not.
true

property projenCredentials

readonly projenCredentials?: GithubCredentials;

Choose a method of providing GitHub API access for projen workflows.
- use a personal access token named PROJEN_GITHUB_TOKEN

property projenTokenSecret

readonly projenTokenSecret?: string;

The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. This token needs to have the repo, workflows and packages scope.
"PROJEN_GITHUB_TOKEN"
Deprecated
- use projenCredentials

property pullRequestBackport

readonly pullRequestBackport?: boolean;

Add a workflow that allows backport of PRs to other branches using labels. When opening a new PR add a backport label to it, and the PR will be backported to the target branches once the PR is merged.
Should not be used together with mergify.
false

property pullRequestBackportOptions

readonly pullRequestBackportOptions?: PullRequestBackportOptions;

Options for configuring pull request backport.
- see defaults in PullRequestBackportOptions

property pullRequestLint

readonly pullRequestLint?: boolean;

Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits.
true

property pullRequestLintOptions

readonly pullRequestLintOptions?: PullRequestLintOptions;

Options for configuring a pull request linter.
- see defaults in PullRequestLintOptions

property workflows

readonly workflows?: boolean;

Enables GitHub workflows. If this is set to false, workflows will not be created.
true

interface GitHubProjectOptions

interface GitHubProjectOptions extends ProjectOptions {}

Options for GitHubProject.

property autoApproveOptions

readonly autoApproveOptions?: AutoApproveOptions;

Enable and configure the 'auto approve' workflow. - auto approve is disabled

property autoMerge

readonly autoMerge?: boolean;

Enable automatic merging on GitHub. Has no effect if github.mergify is set to false. true

property autoMergeOptions

readonly autoMergeOptions?: AutoMergeOptions;

Configure options for automatic merging on GitHub. Has no effect if github.mergify or autoMerge is set to false.
- see defaults in AutoMergeOptions

property clobber

readonly clobber?: boolean;

Add a clobber task which resets the repo to origin. - true, but false for subprojects

property devContainer

readonly devContainer?: boolean;

Add a VSCode development environment (used for GitHub Codespaces)
false

property github

readonly github?: boolean;

Enable GitHub integration.
Enabled by default for root projects. Disabled for non-root projects.
true

property githubOptions

readonly githubOptions?: GitHubOptions;

Options for GitHub integration
- see GitHubOptions

property gitpod

readonly gitpod?: boolean;

Add a Gitpod development environment
false

property mergify

readonly mergify?: boolean;

Whether mergify should be enabled on this repository or not.
true
Deprecated
use githubOptions.mergify instead

property mergifyOptions

readonly mergifyOptions?: MergifyOptions;

Options for mergify
- default options
Deprecated
use githubOptions.mergifyOptions instead

property projectType

readonly projectType?: ProjectType;

Which type of project this is (library/app). ProjectType.UNKNOWN
Deprecated
no longer supported at the base project level

property projenCredentials

readonly projenCredentials?: GithubCredentials;

Choose a method of providing GitHub API access for projen workflows.
- use a personal access token named PROJEN_GITHUB_TOKEN

property projenTokenSecret

readonly projenTokenSecret?: string;

The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. This token needs to have the repo, workflows and packages scope.
"PROJEN_GITHUB_TOKEN"
Deprecated
use projenCredentials

property readme

readonly readme?: SampleReadmeProps;

The README setup.
- { filename: 'README.md', contents: '# replace this' }
Example 1
"{ filename: 'readme.md', contents: '# title' }"

property stale

readonly stale?: boolean;

Auto-close of stale issues and pull request. See staleOptions for options.
false

property staleOptions

readonly staleOptions?: StaleOptions;

Auto-close stale issues and pull requests. To disable set stale to false.
- see defaults in StaleOptions

property vscode

readonly vscode?: boolean;

Enable VSCode integration.
Enabled by default for root projects. Disabled for non-root projects.
true

interface GithubWorkflowOptions

interface GithubWorkflowOptions {}

Options for GithubWorkflow.

property concurrencyOptions

readonly concurrencyOptions?: ConcurrencyOptions;

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. Currently in beta.
- { group: ${{ github.workflow }}, cancelInProgress: false }
See Also
- https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#concurrency

property env

readonly env?: Record<string, string>;

Additional environment variables to set for the workflow.
- no additional environment variables

property fileName

readonly fileName?: string;

Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension.
Use this option to set a file name for the workflow file, that is different than the display name.
Example 1
"build-new.yml"
Example 2
"my-workflow.yaml"
- a path-safe version of the workflow name plus the .yml file ending, e.g. build.yml

property force

readonly force?: boolean;

Force the creation of the workflow even if workflows is disabled in GitHub.
false

property limitConcurrency

readonly limitConcurrency?: boolean;

Enable concurrency limitations. Use concurrencyOptions to configure specific non default values.
false

property email

readonly email: string;

The email address of the git user.

property name

readonly name: string;

The name of the user.

interface IAddConditionsLater

interface IAddConditionsLater {}

method render

render: () => string[];

property autoQueue

readonly autoQueue?: boolean;

Should pull requests be queued automatically to be merged once they pass required checks true

property autoQueueOptions

readonly autoQueueOptions?: AutoQueueOptions;

Configure auto-queue pull requests - see AutoQueueOptions

property targetBranches

readonly targetBranches?: string[];

The branches that can be merged into using MergeQueue
- all branches

interface MergifyConditionalOperator

interface MergifyConditionalOperator {}

The Mergify conditional operators that can be used are: or and and. Note: The number of nested conditions is limited to 3.
See Also
- https://docs.mergify.io/conditions/#combining-conditions-with-operators

property and

readonly and?: MergifyCondition[];

property or

readonly or?: MergifyCondition[];

interface MergifyOptions

interface MergifyOptions {}

property queues

readonly queues?: MergifyQueue[];

property rules

readonly rules?: MergifyRule[];

interface MergifyQueue

interface MergifyQueue {}

property commitMessageTemplate

readonly commitMessageTemplate: string;

Template to use as the commit message when using the merge or squash merge method.

property conditions

readonly conditions: MergifyCondition[];

A list of Conditions string that must match against the pull request for the pull request to be added to the queue.
See Also
- https://docs.mergify.com/conditions/#conditions

property mergeMethod

readonly mergeMethod?: string;

Merge method to use.
Possible values are merge, squash, rebase or fast-forward. fast-forward is not supported on queues with speculative_checks > 1, batch_size > 1, or with allow_inplace_checks set to false.
"merge"

property name

readonly name: string;

The name of the queue.

property updateMethod

readonly updateMethod?: string;

Method to use to update the pull request with its base branch when the speculative check is done in-place.
Possible values: - merge to merge the base branch into the pull request. - rebase to rebase the pull request against its base branch.
Note that the rebase method has some drawbacks, see Mergify docs for details.
See Also
- https://docs.mergify.com/actions/queue/#queue-rules
  - merge for all merge methods except fast-forward where rebase is used

interface MergifyRule

interface MergifyRule {}

property actions

readonly actions: {
    [action: string]: any;
};

A dictionary made of Actions that will be executed on the matching pull requests.
See Also
- https://docs.mergify.io/actions/#actions

property conditions

readonly conditions: MergifyCondition[];

A list of Conditions string that must match against the pull request for the rule to be applied.
See Also
- https://docs.mergify.io/conditions/#conditions

property name

readonly name: string;

The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule.

interface PullRequestBackportOptions

interface PullRequestBackportOptions {}

property autoApproveBackport

readonly autoApproveBackport?: boolean;

Automatically approve backport PRs if the 'auto approve' workflow is available.
true

property backportBranchNamePrefix

readonly backportBranchNamePrefix?: string;

The prefix used to name backport branches.
Make sure to include a separator at the end like / or _.
"backport/"

property backportPRLabels

readonly backportPRLabels?: string[];

The labels added to the created backport PR.
["backport"]

property branches

readonly branches?: string[];

List of branches that can be a target for backports
- allow backports to all release branches

property createWithConflicts

readonly createWithConflicts?: boolean;

Should this created Backport PRs with conflicts.
Conflicts will have to be resolved manually, but a PR is always created. Set to false to prevent the backport PR from being created if there are conflicts.
true

property labelPrefix

readonly labelPrefix?: string;

The prefix used to detect PRs that should be backported.
"backport-to-"

interface PullRequestFromPatchOptions

interface PullRequestFromPatchOptions extends CreatePullRequestOptions {}

property jobName

readonly jobName?: string;

The name of the job displayed on GitHub. "Create Pull Request"

property patch

readonly patch: PullRequestPatchSource;

Information about the patch that is used to create the pull request.

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

interface PullRequestLintOptions

interface PullRequestLintOptions {}

Options for PullRequestLint

property contributorStatement

readonly contributorStatement?: string;

Require a contributor statement to be included in the PR description. For example confirming that the contribution has been made by the contributor and complies with the project's license.
Appends the statement to the end of the Pull Request template.
- no contributor statement is required

property contributorStatementOptions

readonly contributorStatementOptions?: ContributorStatementOptions;

Options for requiring a contributor statement on Pull Requests - none

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property semanticTitle

readonly semanticTitle?: boolean;

Validate that pull request titles follow Conventional Commits.
true
See Also
- https://www.conventionalcommits.org/

property semanticTitleOptions

readonly semanticTitleOptions?: SemanticTitleOptions;

Options for validating the conventional commit title linter. - title must start with "feat", "fix", or "chore"

interface PullRequestPatchSource

interface PullRequestPatchSource extends CheckoutWithPatchOptions {}

property jobId

readonly jobId: string;

The id of the job that created the patch file

property outputName

readonly outputName: string;

The name of the output that indicates if a patch has been created

interface PullRequestTemplateOptions

interface PullRequestTemplateOptions {}

Options for PullRequestTemplate.

property lines

readonly lines?: string[];

The contents of the template. You can use addLine() to add additional lines.
- a standard default template will be created.

interface SemanticTitleOptions

interface SemanticTitleOptions {}

Options for linting that PR titles follow Conventional Commits.
See Also
- https://www.conventionalcommits.org/

property requireScope

readonly requireScope?: boolean;

Configure that a scope must always be provided. e.g. feat(ui), fix(core) false

property types

readonly types?: string[];

Configure a list of commit types that are allowed. ["feat", "fix", "chore"]

interface SetupGitIdentityOptions

interface SetupGitIdentityOptions extends JobStepConfiguration {}

property closeMessage

readonly closeMessage?: string;

The comment to add to the issue/PR when it's closed
"Closing this pull request as it hasn't seen activity for a while. Please add a comment a maintainer when you are ready to continue."

property daysBeforeClose

readonly daysBeforeClose?: number;

Days until the issue/PR is closed after it is marked as "Stale". Set to -1 to disable. -

property daysBeforeStale

readonly daysBeforeStale?: number;

How many days until the issue or pull request is marked as "Stale". Set to -1 to disable. -

property enabled

readonly enabled?: boolean;

Determines if this behavior is enabled.
Same as setting daysBeforeStale and daysBeforeClose to -1.
true

property exemptLabels

readonly exemptLabels?: string[];

Label which exempt an issue/PR from becoming stale. Set to [] to disable.
- ["backlog"]

property staleLabel

readonly staleLabel?: string;

The label to apply to the issue/PR when it becomes stale. "stale"

property staleMessage

readonly staleMessage?: string;

The comment to add to the issue/PR when it becomes stale. "This pull request is now marked as stale because hasn't seen activity for a while. Add a comment or it will be closed soon."

property issues

readonly issues?: StaleBehavior;

How to handle stale issues.
- By default, stale issues with no activity will be marked as stale after 60 days and closed within 7 days.

property pullRequest

readonly pullRequest?: StaleBehavior;

How to handle stale pull requests.
- By default, pull requests with no activity will be marked as stale after 14 days and closed within 2 days with relevant comments.

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

interface TaskWorkflowJobOptions

interface TaskWorkflowJobOptions {}

Options to create the Job associated with a TaskWorkflow.

property artifactsDirectory

readonly artifactsDirectory?: string;

A directory name which contains artifacts to be uploaded (e.g. dist). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.
- not set

property checkoutWith

readonly checkoutWith?: CheckoutWith;

Override for the with property of the source code checkout step.
- not set

property downloadLfs

readonly downloadLfs?: boolean;

Whether to download files from Git LFS for this workflow
- Use the setting on the corresponding GitHub project

property env

readonly env?: Record<string, string>;

Workflow environment variables. {}

property gitIdentity

readonly gitIdentity?: GitIdentity;

The git identity to use in this workflow.

property jobDefaults

readonly jobDefaults?: JobDefaults;

Default settings for all steps in the TaskWorkflow Job.

property outputs

readonly outputs?: {
    [name: string]: JobStepOutput;
};

Mapping of job output names to values/expressions.
{}

property postBuildSteps

readonly postBuildSteps?: JobStep[];

Actions to run after the main build step.
- not set

property preBuildSteps

readonly preBuildSteps?: JobStep[];

Steps to run before the main build step.
- not set

property preCheckoutSteps

readonly preCheckoutSteps?: JobStep[];

Initial steps to run before the source code checkout.
- not set

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property jobId

readonly jobId?: string;

The primary job id. "build"

property name

readonly name: string;

The workflow name.

property task

readonly task: Task;

The main task to be executed.

property triggers

readonly triggers?: Triggers;

The triggers for the workflow.
- by default workflows can only be triggered by manually.

interface UploadArtifactOptions

interface UploadArtifactOptions extends JobStepConfiguration {}

property with

readonly with: UploadArtifactWith;

Options for upload-artifact.

interface UploadArtifactWith

interface UploadArtifactWith {}

property compressionLevel

readonly compressionLevel?: number;

The level of compression for Zlib to be applied to the artifact archive.
The value can range from 0 to 9. For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
6

property ifNoFilesFound

readonly ifNoFilesFound?: 'error' | 'warn' | 'ignore';

The desired behavior if no files are found using the provided path. Available Options: warn: Output a warning but do not fail the action error: Fail the action with an error message ignore: Do not output any warnings or errors, the action does not fail
"warn"

property includeHiddenFiles

readonly includeHiddenFiles?: boolean;

Whether to include hidden files in the provided path in the artifact
The file contents of any hidden files in the path should be validated before enabled this to avoid uploading sensitive information.
false

property name

readonly name?: string;

Name of the artifact to upload.
"artifact"

property overwrite

readonly overwrite?: boolean;

Whether action should overwrite an existing artifact with the same name (should one exist)
Introduced in v4 and represents a breaking change from the behavior of the v3 action. To maintain backwards compatibility with existing, this should be set the true (the default).
true

property path

readonly path: string;

A file, directory or wildcard pattern that describes what to upload

property retentionDays

readonly retentionDays?: number;

Duration after which artifact will expire in days. 0 means using default repository retention.
Minimum 1 day. Maximum 90 days unless changed from the repository settings page.
- The default repository retention

interface UploadGitPatchOptions

interface UploadGitPatchOptions {}

Options for uploadGitPatch.

property mutationError

readonly mutationError?: string;

Fail if a mutation was found and print this error message. - do not fail upon mutation

property outputName

readonly outputName: string;

The name of the output to emit. It will be set to true if there was a diff.

property patchFile

readonly patchFile?: string;

The name of the artifact the patch is stored as. ".repo.patch"

property stepId

readonly stepId: string;

The step ID which produces the output which indicates if a patch was created.

property stepName

readonly stepName?: string;

The name of the step. "Find mutations"

enum DependabotRegistryType

enum DependabotRegistryType {
    COMPOSER_REGISTRY = 'composer-registry',
    DOCKER_REGISTRY = 'docker-registry',
    GIT = 'git',
    HEX_ORGANIZATION = 'hex-organization',
    MAVEN_REPOSITORY = 'maven-repository',
    NPM_REGISTRY = 'npm-registry',
    NUGET_FEED = 'nuget-feed',
    PYTHON_INDEX = 'python-index',
    RUBYGEMS_SERVER = 'rubygems-server',
    TERRAFORM_REGISTRY = 'terraform-registry',
}

Each configuration type requires you to provide particular settings. Some types allow more than one way to connect
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries

member COMPOSER_REGISTRY

COMPOSER_REGISTRY = 'composer-registry'

The composer-repository type supports username and password.
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#composer-repository

member DOCKER_REGISTRY

DOCKER_REGISTRY = 'docker-registry'

The docker-registry type supports username and password. The docker-registry type can also be used to pull from Amazon ECR using static AWS credentials
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#docker-registry

member GIT

GIT = 'git'

The git type supports username and password
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#git

member HEX_ORGANIZATION

HEX_ORGANIZATION = 'hex-organization'

The hex-organization type supports organization and key
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization

member MAVEN_REPOSITORY

MAVEN_REPOSITORY = 'maven-repository'

The maven-repository type supports username and password, or token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#maven-repository

member NPM_REGISTRY

NPM_REGISTRY = 'npm-registry'

The npm-registry type supports username and password, or token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#npm-registry

member NUGET_FEED

NUGET_FEED = 'nuget-feed'

The nuget-feed type supports username and password, or token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#nuget-feed

member PYTHON_INDEX

PYTHON_INDEX = 'python-index'

The python-index type supports username and password, or token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#python-index

member RUBYGEMS_SERVER

RUBYGEMS_SERVER = 'rubygems-server'

The rubygems-server type supports username and password, or token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#rubygems-server

member TERRAFORM_REGISTRY

TERRAFORM_REGISTRY = 'terraform-registry'

The terraform-registry type supports a token
See Also
- https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#terraform-registry

enum DependabotScheduleInterval

enum DependabotScheduleInterval {
    DAILY = 'daily',
    WEEKLY = 'weekly',
    MONTHLY = 'monthly',
}

How often to check for new versions and raise pull requests for version updates.

member DAILY

DAILY = 'daily'

Runs on every weekday, Monday to Friday.

member MONTHLY

MONTHLY = 'monthly'

Runs once each month. This is on the first day of the month.

member WEEKLY

WEEKLY = 'weekly'

Runs once each week. By default, this is on Monday.

enum MergeMethod

enum MergeMethod {
    SQUASH = 'squash',
    MERGE = 'merge',
    REBASE = 'rebase',
}

The merge method used to add the PR to the merge queue
Behavior can be further configured in repository settings.

member MERGE

MERGE = 'merge'

member REBASE

REBASE = 'rebase'

member SQUASH

SQUASH = 'squash'

enum VersioningStrategy

enum VersioningStrategy {
    LOCKFILE_ONLY = 'lockfile-only',
    AUTO = 'auto',
    WIDEN = 'widen',
    INCREASE = 'increase',
    INCREASE_IF_NECESSARY = 'increase-if-necessary',
}

The strategy to use when edits manifest and lock files.

member AUTO

AUTO = 'auto'

- For apps, the version requirements are increased. - For libraries, the range of versions is widened.

member INCREASE

INCREASE = 'increase'

Always increase the version requirement to match the new version.

member INCREASE_IF_NECESSARY

INCREASE_IF_NECESSARY = 'increase-if-necessary'

Increase the version requirement only when required by the new version.

member LOCKFILE_ONLY

LOCKFILE_ONLY = 'lockfile-only'

Only create pull requests to update lockfiles updates. Ignore any new versions that would require package manifest changes.

member WIDEN

WIDEN = 'widen'

Relax the version requirement to include both the new and old version, when possible.

type MergifyCondition

type MergifyCondition = string | MergifyConditionalOperator;

namespace workflows

module 'lib/github/workflows-model.d.ts' {}

The name of the job displayed on GitHub.

interface AppPermissions

interface AppPermissions {}

The permissions available to a GitHub App.
Typically a token for a GitHub App has all the available scopes/permissions available to the app itself; however, a more limited set of permissions can be specified. When permissions are provided, **only** the specified permissions are granted to the token.
See Also
- https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app
- https://github.com/actions/create-github-app-token/blob/main/action.yml#L28

property actions

readonly actions?: AppPermission;

property administration

readonly administration?: AppPermission;

property attestations

readonly attestations?: AppPermission;

property checks

readonly checks?: AppPermission;

property codespaces

readonly codespaces?: AppPermission;

property contents

readonly contents?: AppPermission;

property dependabotSecrets

readonly dependabotSecrets?: AppPermission;

property deployments

readonly deployments?: AppPermission;

property emailAddresses

readonly emailAddresses?: AppPermission;

property environments

readonly environments?: AppPermission;

property followers

readonly followers?: AppPermission;

property gitSshKeys

readonly gitSshKeys?: AppPermission;

property gpgKeys

readonly gpgKeys?: AppPermission;

property interactionLimits

readonly interactionLimits?: AppPermission;

property issues

readonly issues?: AppPermission;

property members

readonly members?: AppPermission;

property metadata

readonly metadata?: AppPermission;

property organizationAdministration

readonly organizationAdministration?: AppPermission;

property organizationAnnouncementBanners

readonly organizationAnnouncementBanners?: AppPermission;

property organizationCopilotSeatManagement

readonly organizationCopilotSeatManagement?: AppPermission;

property organizationCustomOrgRoles

readonly organizationCustomOrgRoles?: AppPermission;

property organizationCustomProperties

readonly organizationCustomProperties?: AppPermission;

property organizationCustomRoles

readonly organizationCustomRoles?: AppPermission;

property organizationEvents

readonly organizationEvents?: AppPermission;

property organizationHooks

readonly organizationHooks?: AppPermission;

property organizationPackages

readonly organizationPackages?: AppPermission;

property organizationPersonalAccessTokenRequests

readonly organizationPersonalAccessTokenRequests?: AppPermission;

property organizationPersonalAccessTokens

readonly organizationPersonalAccessTokens?: AppPermission;

property organizationPlan

readonly organizationPlan?: AppPermission;

property organizationProjects

readonly organizationProjects?: AppPermission;

property organizationSecrets

readonly organizationSecrets?: AppPermission;

property organizationSelfHostedRunners

readonly organizationSelfHostedRunners?: AppPermission;

property orgnaizationUserBlocking

readonly orgnaizationUserBlocking?: AppPermission;

property packages

readonly packages?: AppPermission;

property pages

readonly pages?: AppPermission;

property profile

readonly profile?: AppPermission;

property pullRequests

readonly pullRequests?: AppPermission;

property repositoryAnnouncementBanners

readonly repositoryAnnouncementBanners?: AppPermission;

Deprecated
removed by GitHub

property repositoryCustomProperties

readonly repositoryCustomProperties?: AppPermission;

property repositoryHooks

readonly repositoryHooks?: AppPermission;

property repositoryProjects

readonly repositoryProjects?: AppPermission;

property secrets

readonly secrets?: AppPermission;

property secretScanningAlerts

readonly secretScanningAlerts?: AppPermission;

property securityEvents

readonly securityEvents?: AppPermission;

property singleFile

readonly singleFile?: AppPermission;

property starring

readonly starring?: AppPermission;

property statuses

readonly statuses?: AppPermission;

property teamDiscussions

readonly teamDiscussions?: AppPermission;

property vulnerabilityAlerts

readonly vulnerabilityAlerts?: AppPermission;

property workflows

readonly workflows?: AppPermission;

interface BranchProtectionRuleOptions

interface BranchProtectionRuleOptions {}

Branch Protection Rule options

property types

readonly types?: Array<'created' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    'create' | 'rerequested' | 'completed' | 'requested_action'
>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<'completed' | 'requested' | 'rerequested'>;

Which activity types to trigger on.
- all activity types

interface CommonJobDefinition

interface CommonJobDefinition {}

property concurrency

readonly concurrency?: unknown;

Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context.
Modifiers
- @experimental

property if

readonly if?: string;

You can use the if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.

property name

readonly name?: string;

The name of the job displayed on GitHub.

property needs

readonly needs?: string[];

Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.

property permissions

readonly permissions: JobPermissions;

You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.
Use { contents: READ } if your job only needs to clone code.
This is intentionally a required field since it is required in order to allow workflows to run in GitHub repositories with restricted default access.
See Also
- https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token

property strategy

readonly strategy?: JobStrategy;

A strategy creates a build matrix for your jobs. You can define different variations to run each job in.

interface ContainerCredentials

interface ContainerCredentials {}

Credentials to use to authenticate to Docker registries.

property password

readonly password: string;

The password.

property username

readonly username: string;

The username.

interface ContainerOptions

interface ContainerOptions {}

Options pertaining to container environments.

property credentials

readonly credentials?: ContainerCredentials;

f the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password. The credentials are the same values that you would provide to the docker login command.

property env

readonly env?: Record<string, string>;

Sets a map of environment variables in the container.

property image

readonly image: string;

The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.

property options

readonly options?: string[];

Additional Docker container resource options.
See Also
- https://docs.docker.com/engine/reference/commandline/create/#options

property ports

readonly ports?: number[];

Sets an array of ports to expose on the container.

property volumes

readonly volumes?: string[];

Sets an array of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
To specify a volume, you specify the source and destination path: <source>:<destinationPath>.

property cron

readonly cron: string;

See Also
- https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07

interface DeploymentStatusOptions

interface DeploymentStatusOptions {}

The Deployment status event accepts no options.

interface DiscussionCommentOptions

interface DiscussionCommentOptions {}

Discussion comment options

property types

readonly types?: Array<'created' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    | 'created'
    | 'edited'
    | 'transferred'
    | 'pinned'
    | 'unpinned'
    | 'labeled'
    | 'unlabeled'
    | 'locked'
    | 'unlocked'
    | 'category_changed'
    | 'answered'
    | 'unanswered'
>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<'created' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    | 'opened'
    | 'edited'
    | 'deleted'
    | 'transferred'
    | 'pinned'
    | 'unpinned'
    | 'closed'
    | 'reopened'
    | 'assigned'
    | 'unassigned'
    | 'labeled'
    | 'unlabeled'
    | 'locked'
    | 'unlocked'
    | 'milestoned'
    | 'demilestoned'
>;

Which activity types to trigger on.
- all activity types

interface Job

interface Job extends CommonJobDefinition {}

A GitHub Workflow job definition.

property container

readonly container?: ContainerOptions;

A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.

property continueOnError

readonly continueOnError?: boolean;

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

property defaults

readonly defaults?: JobDefaults;

A map of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow.

property env

readonly env?: Record<string, string>;

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step.

property environment

readonly environment?: unknown;

The environment that the job references. All environment protection rules must pass before a job referencing the environment is sent to a runner.
See Also
- https://docs.github.com/en/actions/reference/environments

property outputs

readonly outputs?: Record<string, JobStepOutput>;

A map of outputs for a job. Job outputs are available to all downstream jobs that depend on this job.

property runsOn

readonly runsOn?: string[];

The type of machine to run the job on. The machine can be either a GitHub-hosted runner or a self-hosted runner.
Example 1
["ubuntu-latest"]

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property services

readonly services?: Record<string, ContainerOptions>;

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

property steps

readonly steps: JobStep[];

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

property timeoutMinutes

readonly timeoutMinutes?: number;

The maximum number of minutes to let a job run before GitHub automatically cancels it.
360

property tools

readonly tools?: Tools;

Tools required for this job. Translates into actions/setup-xxx steps at the beginning of the job.

interface JobCallingReusableWorkflow

interface JobCallingReusableWorkflow extends CommonJobDefinition {}

A GitHub Workflow Job calling a reusable workflow

property secrets

readonly secrets?: string | Record<string, string>;

When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.
Use the 'inherit' keyword to pass all the calling workflow's secrets to the called workflow

property uses

readonly uses: string;

The location and version of a reusable workflow file to run as a job.

property with

readonly with?: Record<string, string | boolean>;

When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.
Allowed expression contexts: github, and needs.

interface JobDefaults

interface JobDefaults {}

Default settings for all steps in the job.

property run

readonly run?: RunSettings;

Default run settings.

interface JobMatrix

interface JobMatrix {}

A job matrix.

property domain

readonly domain?: Record<string, string | JobMatrixValue[]>;

Each option you define in the matrix has a key and value. The keys you define become properties in the matrix context and you can reference the property in other areas of your workflow file. For example, if you define the key os that contains an array of operating systems, you can use the matrix.os property as the value of the runs-on keyword to create a job for each operating system.

property exclude

readonly exclude?: Array<Record<string, JobMatrixValue>>;

You can remove a specific configurations defined in the build matrix using the exclude option. Using exclude removes a job defined by the build matrix.

property include

readonly include?: Array<Record<string, JobMatrixValue>>;

You can add additional configuration options to a build matrix job that already exists. For example, if you want to use a specific version of npm when the job that uses windows-latest and version 8 of node runs, you can use include to specify that additional option.

interface JobPermissions

interface JobPermissions {}

The available scopes and access values for workflow permissions. If you specify the access for any of these scopes, all those that are not specified are set to JobPermission.NONE, instead of the default behavior when none is specified.
See Also
- https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#defining-access-for-the-github_token-permissions

property actions

readonly actions?: JobPermission;

property attestations

readonly attestations?: JobPermission;

property checks

readonly checks?: JobPermission;

property contents

readonly contents?: JobPermission;

property deployments

readonly deployments?: JobPermission;

property discussions

readonly discussions?: JobPermission;

property idToken

readonly idToken?: JobPermission;

property issues

readonly issues?: JobPermission;

property models

readonly models?: JobPermission;

property packages

readonly packages?: JobPermission;

property pages

readonly pages?: JobPermission;

property pullRequests

readonly pullRequests?: JobPermission;

property securityEvents

readonly securityEvents?: JobPermission;

property statuses

readonly statuses?: JobPermission;

interface JobStep

interface JobStep extends Step, JobStepConfiguration {}

JobSteps run as part of a GitHub Workflow Job.
See Also
- https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps

interface JobStepConfiguration

interface JobStepConfiguration extends StepConfiguration {}

These settings are unique to a JobStep from the fields contained within the metadata action.yaml file present in when creating a new GitHub Action. These fields are not present in action.yml, but are in JobStep, which are using when creating workflows.

property continueOnError

readonly continueOnError?: boolean;

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

property timeoutMinutes

readonly timeoutMinutes?: number;

The maximum number of minutes to run the step before killing the process.

property outputName

readonly outputName: string;

The name of the job output that is being bound.

property stepId

readonly stepId: string;

The ID of the step that exposes the output.

interface JobStrategy

interface JobStrategy {}

A strategy creates a build matrix for your jobs. You can define different variations to run each job in.

property failFast

readonly failFast?: boolean;

When set to true, GitHub cancels all in-progress jobs if any matrix job fails. Default: true

property matrix

readonly matrix?: JobMatrix;

You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.
A job matrix can generate a maximum of 256 jobs per workflow run. This limit also applies to self-hosted runners.

property maxParallel

readonly maxParallel?: number;

The maximum number of jobs that can run simultaneously when using a matrix job strategy. By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.

property types

readonly types?: Array<'created' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property branches

readonly branches?: string[];

When using the merge_group events, you can configure a workflow to run on specific base branches. If not specified, all branches will trigger the workflow.

property types

readonly types?: Array<'created' | 'closed' | 'opened' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<'created' | 'moved' | 'converted' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

interface ProjectColumnOptions

interface ProjectColumnOptions {}

Probject column options

property types

readonly types?: Array<'created' | 'updated' | 'moved' | 'deleted'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    'created' | 'updated' | 'closed' | 'reopened' | 'edited' | 'deleted'
>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    | 'assigned'
    | 'unassigned'
    | 'labeled'
    | 'unlabeled'
    | 'opened'
    | 'edited'
    | 'closed'
    | 'reopened'
    | 'synchronize'
    | 'ready_for_review'
    | 'locked'
    | 'unlocked'
    | 'review_requested'
    | 'review_request_removed'
>;

Which activity types to trigger on.
- all activity types

interface PullRequestReviewCommentOptions

interface PullRequestReviewCommentOptions {}

Pull request review comment options

property types

readonly types?: Array<'created' | 'edited' | 'deleted'>;

Which activity types to trigger on.
- all activity types

interface PullRequestReviewOptions

interface PullRequestReviewOptions {}

Pull request review options

property types

readonly types?: Array<'submitted' | 'edited' | 'dismissed'>;

Which activity types to trigger on.
- all activity types

interface PullRequestTargetOptions

interface PullRequestTargetOptions extends PushOptions {}

Pull request target options.

property types

readonly types?: Array<
    | 'assigned'
    | 'unassigned'
    | 'labeled'
    | 'unlabeled'
    | 'opened'
    | 'edited'
    | 'closed'
    | 'reopened'
    | 'synchronize'
    | 'ready_for_review'
    | 'locked'
    | 'unlocked'
    | 'review_requested'
    | 'review_request_removed'
>;

Which activity types to trigger on.
- all activity types

property branches

readonly branches?: string[];

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags. For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.
See Also
- https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

property paths

readonly paths?: string[];

When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths. Path filters are not evaluated for pushes to tags.
See Also
- https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

property tags

readonly tags?: string[];

When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags. For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.
See Also
- https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet

interface RegistryPackageOptions

interface RegistryPackageOptions {}

Registry package options

property types

readonly types?: Array<'published' | 'updated'>;

Which activity types to trigger on.
- all activity types

property types

readonly types?: Array<
    | 'published'
    | 'unpublished'
    | 'created'
    | 'edited'
    | 'deleted'
    | 'prereleased'
    | 'released'
>;

Which activity types to trigger on.
- all activity types

interface RepositoryDispatchOptions

interface RepositoryDispatchOptions {}

Repository dispatch options.

property types

readonly types?: string[];

Which activity types to trigger on.
- all activity types

property shell

readonly shell?: string;

Which shell to use for running the step.
Example 1
"bash"

property workingDirectory

readonly workingDirectory?: string;

Working directory to use when running the step.

interface Step

interface Step extends StepConfiguration {}

This contains the fields that are common amongst both: - JobStep, which is a step that is part of a Job in Github Actions. This is by far the most common use case. - The metadata file action.yaml that is used to define an Action when you are creating one. As in, if you were creating an Action to be used in a JobStep. There is some overlap between the two, and this captures that overlap.
See Also
- https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions

property run

readonly run?: string;

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

property uses

readonly uses?: string;

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

property with

readonly with?: Record<string, any>;

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

interface StepConfiguration

interface StepConfiguration {}

Fields that describe the How, Why, When, and Who of a Step. These fields can have none present, but can be present on every Step, and have no effect on one another.
This stands in contrast to the Command (non-Configuration) fields, which are mutually exclusive, and describe the What.

property env

readonly env?: Record<string, string>;

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job.

property id

readonly id?: string;

A unique identifier for the step. You can use the id to reference the step in contexts.

property if

readonly if?: string;

You can use the if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.

property name

readonly name?: string;

A name for your step to display on GitHub.

property workingDirectory

readonly workingDirectory?: string;

Specifies a working directory for a step. Overrides a job's working directory.

property version

readonly version: string;

interface Tools

interface Tools {}

Supported tools.

property dotnet

readonly dotnet?: ToolRequirement;

Setup .NET Core - not installed

property go

readonly go?: ToolRequirement;

Setup golang. - not installed

property java

readonly java?: ToolRequirement;

Setup java (temurin distribution). - not installed

property node

readonly node?: ToolRequirement;

Setup node.js - not installed

property python

readonly python?: ToolRequirement;

Setup python. - not installed

interface Triggers

interface Triggers {}

The set of available triggers for GitHub Workflows.
See Also
- https://docs.github.com/en/actions/reference/events-that-trigger-workflows

property branchProtectionRule

readonly branchProtectionRule?: BranchProtectionRuleOptions;

Runs your workflow anytime the branch_protection_rule event occurs.

property checkRun

readonly checkRun?: CheckRunOptions;

Runs your workflow anytime the check_run event occurs.

property checkSuite

readonly checkSuite?: CheckSuiteOptions;

Runs your workflow anytime the check_suite event occurs.

property create

readonly create?: CreateOptions;

Runs your workflow anytime someone creates a branch or tag, which triggers the create event.

property delete

readonly delete?: DeleteOptions;

Runs your workflow anytime someone deletes a branch or tag, which triggers the delete event.

property deployment

readonly deployment?: DeploymentOptions;

Runs your workflow anytime someone creates a deployment, which triggers the deployment event. Deployments created with a commit SHA may not have a Git ref.

property deploymentStatus

readonly deploymentStatus?: DeploymentStatusOptions;

Runs your workflow anytime a third party provides a deployment status, which triggers the deployment_status event. Deployments created with a commit SHA may not have a Git ref.

property discussion

readonly discussion?: DiscussionOptions;

Runs your workflow anytime the discussion event occurs. More than one activity type triggers this event.
See Also
- https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions

property discussionComment

readonly discussionComment?: DiscussionCommentOptions;

Runs your workflow anytime the discussion_comment event occurs. More than one activity type triggers this event.
See Also
- https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions

property fork

readonly fork?: ForkOptions;

Runs your workflow anytime when someone forks a repository, which triggers the fork event.

property gollum

readonly gollum?: GollumOptions;

Runs your workflow when someone creates or updates a Wiki page, which triggers the gollum event.

property issueComment

readonly issueComment?: IssueCommentOptions;

Runs your workflow anytime the issue_comment event occurs.

property issues

readonly issues?: IssuesOptions;

Runs your workflow anytime the issues event occurs.

property label

readonly label?: LabelOptions;

Runs your workflow anytime the label event occurs.

property mergeGroup

readonly mergeGroup?: MergeGroupOptions;

Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group.
experimental

property milestone

readonly milestone?: MilestoneOptions;

Runs your workflow anytime the milestone event occurs.

property pageBuild

readonly pageBuild?: PageBuildOptions;

Runs your workflow anytime someone pushes to a GitHub Pages-enabled branch, which triggers the page_build event.

property project

readonly project?: ProjectOptions;

Runs your workflow anytime the project event occurs.

property projectCard

readonly projectCard?: ProjectCardOptions;

Runs your workflow anytime the project_card event occurs.

property projectColumn

readonly projectColumn?: ProjectColumnOptions;

Runs your workflow anytime the project_column event occurs.

property public

readonly public?: PublicOptions;

Runs your workflow anytime someone makes a private repository public, which triggers the public event.

property pullRequest

readonly pullRequest?: PullRequestOptions;

Runs your workflow anytime the pull_request event occurs.

property pullRequestReview

readonly pullRequestReview?: PullRequestReviewOptions;

Runs your workflow anytime the pull_request_review event occurs.

property pullRequestReviewComment

readonly pullRequestReviewComment?: PullRequestReviewCommentOptions;

Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the pull_request_review_comment event.

property pullRequestTarget

readonly pullRequestTarget?: PullRequestTargetOptions;

This event runs in the context of the base of the pull request, rather than in the merge commit as the pull_request event does. This prevents executing unsafe workflow code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows you to do things like create workflows that label and comment on pull requests based on the contents of the event payload.
WARNING: The pull_request_target event is granted read/write repository token and can access secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should make sure that you do not check out, build, or run untrusted code from the pull request with this event. Additionally, any caches share the same scope as the base branch, and to help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered.
See Also
- https://securitylab.github.com/research/github-actions-preventing-pwn-requests

property push

readonly push?: PushOptions;

Runs your workflow when someone pushes to a repository branch, which triggers the push event.

property registryPackage

readonly registryPackage?: RegistryPackageOptions;

Runs your workflow anytime a package is published or updated.

property release

readonly release?: ReleaseOptions;

Runs your workflow anytime the release event occurs.

property repositoryDispatch

readonly repositoryDispatch?: RepositoryDispatchOptions;

You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub.

property schedule

readonly schedule?: CronScheduleOptions[];

You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.
See Also
- https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07

property status

readonly status?: StatusOptions;

Runs your workflow anytime the status of a Git commit changes, which triggers the status event.

property watch

readonly watch?: WatchOptions;

Runs your workflow anytime the watch event occurs.

property workflowCall

readonly workflowCall?: WorkflowCallOptions;

Can be called from another workflow
See Also
- https://docs.github.com/en/actions/learn-github-actions/reusing-workflows

property workflowDispatch

readonly workflowDispatch?: WorkflowDispatchOptions;

You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When the workflow runs, you can access the input values in the github.event.inputs context.

property workflowRun

readonly workflowRun?: WorkflowRunOptions;

This event occurs when a workflow run is requested or completed, and allows you to execute a workflow based on the finished result of another workflow. A workflow run is triggered regardless of the result of the previous workflow.

property types

readonly types?: Array<'started'>;

Which activity types to trigger on.
- all activity types

interface WorkflowCallOptions

interface WorkflowCallOptions {}

The Workflow Call event accepts no options.

interface WorkflowDispatchOptions

interface WorkflowDispatchOptions {}

The Workflow dispatch event accepts no options.

property branches

readonly branches?: Array<string>;

Which branches or branch-ignore to limit the trigger to.
- no branch limits

property types

readonly types?: Array<'completed' | 'requested'>;

Which activity types to trigger on.
- all activity types

property workflows

readonly workflows?: Array<string>;

Which workflow to trigger on.
- any workflows

enum AppPermission

enum AppPermission {
    READ = 'read',
    WRITE = 'write',
    ADMIN = 'admin',
}

The permissions available for an access token for a GitHub App.

member ADMIN

ADMIN = 'admin'

Read-write and admin access.
Not all permissions support admin.

member READ

READ = 'read'

Read-only acccess

member WRITE

WRITE = 'write'

Read-write access

enum JobPermission

enum JobPermission {
    READ = 'read',
    WRITE = 'write',
    NONE = 'none',
}

Access level for workflow permission scopes.

member NONE

NONE = 'none'

No access at all

member READ

READ = 'read'

Read-only access

member WRITE

WRITE = 'write'

Read-write access

namespace gitlab

module 'lib/gitlab/index.d.ts' {}

class CiConfiguration

class CiConfiguration extends Component {}

CI for GitLab. A CI is a configurable automated process made up of one or more stages/jobs.
See Also
- https://docs.gitlab.com/ee/ci/yaml/

constructor

constructor(project: Project, name: string, options?: CiConfigurationOptions);

property defaultAfterScript

readonly defaultAfterScript: string[];

Defines default scripts that should run *after* all jobs. Can be overriden by the job level afterScript.

property defaultArtifacts

readonly defaultArtifacts?: Artifacts;

Default list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to Gitlab where they can be downloaded.

property defaultBeforeScript

readonly defaultBeforeScript: string[];

Defines default scripts that should run *before* all jobs. Can be overriden by the job level afterScript.

property defaultCache

readonly defaultCache: Cache[];

property defaultIdTokens

readonly defaultIdTokens?: Record<string, IDToken>;

Default ID tokens (JSON Web Tokens) that are used for CI/CD authentication to use globally for all jobs.

property defaultImage

readonly defaultImage?: Image;

Specifies the default docker image to use globally for all jobs.

property defaultInterruptible

readonly defaultInterruptible?: boolean;

The default behavior for whether a job should be canceled when a newer pipeline starts before the job completes (Default: false).

property defaultRetry

readonly defaultRetry?: Retry;

How many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.

property defaultTags

readonly defaultTags: string[];

Used to select a specific runner from the list of all runners that are available for the project.

property defaultTimeout

readonly defaultTimeout?: string;

A default timeout job written in natural language (Ex. one hour, 3600 seconds, 60 minutes).

property file

readonly file: YamlFile;

The workflow YAML file.

property jobs

readonly jobs: Record<string, Job>;

The jobs in the CI configuration.

property name

readonly name: string;

The name of the configuration.

property pages

readonly pages?: Job;

A special job used to upload static sites to Gitlab pages. Requires a public/ directory with artifacts.path pointing to it.

property path

readonly path: string;

Path to CI file generated by the configuration.

property stages

readonly stages: string[];

Groups jobs into stages. All jobs in one stage must complete before next stage is executed. Defaults to ['build', 'test', 'deploy'].

property variables

readonly variables: Record<string, string | number | VariableConfig>;

Global variables that are passed to jobs. If the job already has that variable defined, the job-level variable takes precedence.

property workflow

readonly workflow?: Workflow;

Used to control pipeline behavior.

method addDefaultCaches

addDefaultCaches: (caches: Cache[]) => void;

Adds up to 4 default caches configuration to the CI configuration.
Parameter caches
Caches to add.

method addGlobalVariables

addGlobalVariables: (variables: Record<string, any>) => void;

Add a globally defined variable to the CI configuration.
Parameter variables
The variables to add.

method addIncludes

addIncludes: (...includes: Include[]) => void;

Add additional yml/yaml files to the CI includes
Parameter includes
The includes to add.

method addJobs

addJobs: (jobs: Record<string, Job>) => void;

Add jobs and their stages to the CI configuration.
Parameter jobs
Jobs to add.

method addServices

addServices: (...services: Service[]) => void;

Add additional services.
Parameter services
The services to add.

method addStages

addStages: (...stages: string[]) => void;

Add stages to the CI configuration if not already present.
Parameter stages
stages to add.

class GitlabConfiguration

class GitlabConfiguration extends CiConfiguration {}

A GitLab CI for the main .gitlab-ci.yml file.

constructor

constructor(project: Project, options?: CiConfigurationOptions);

property nestedTemplates

readonly nestedTemplates: Record<string, NestedConfiguration>;

method createNestedTemplates

createNestedTemplates: (config: Record<string, CiConfigurationOptions>) => void;

Creates and adds nested templates to the includes of the main CI. Additionally adds their stages to the main CI if they are not already present. You can futher customize nested templates through the nestedTemplates property. E.g. gitlabConfig.nestedTemplates['templateName']?.addStages('stageName')
Parameter config
a record the names and configuraitons of the templates.

class NestedConfiguration

class NestedConfiguration extends CiConfiguration {}

A GitLab CI for templates that are created and included in the .gitlab-ci.yml file.

constructor

constructor(
    project: Project,
    parent: GitlabConfiguration,
    name: string,
    options?: CiConfigurationOptions
);

property parent

readonly parent: GitlabConfiguration;

interface AllowFailure

interface AllowFailure {}

Exit code that are not considered failure. The job fails for any other exit code. You can list which exit codes are not considered failures. The job fails for any other exit code.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#allow_failure

property exitCodes

readonly exitCodes: number[] | number;

interface Artifacts

interface Artifacts {}

Used to specify a list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to Gitlab where they can be downloaded.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#artifacts

property exclude

readonly exclude?: string[];

A list of paths to files/folders that should be excluded in the artifact.

property expireIn

readonly expireIn?: string;

How long artifacts should be kept. They are saved 30 days by default. Artifacts that have expired are removed periodically via cron job. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'.

property exposeAs

readonly exposeAs?: string;

Can be used to expose job artifacts in the merge request UI. GitLab will add a link <expose_as> to the relevant merge request that points to the artifact.

property name

readonly name?: string;

Name for the archive created on job success. Can use variables in the name, e.g. '$CI_JOB_NAME'

property paths

readonly paths?: string[];

A list of paths to files/folders that should be included in the artifact.

property reports

readonly reports?: Reports;

Reports will be uploaded as artifacts, and often displayed in the Gitlab UI, such as in Merge Requests.

property untracked

readonly untracked?: boolean;

Whether to add all untracked files (along with 'artifacts.paths') to the artifact.

property when

readonly when?: CacheWhen;

Configure when artifacts are uploaded depended on job status.

interface Assets

interface Assets {}

Asset configuration for a release.

property links

readonly links: Link[];

Include asset links in the release.

interface Cache

interface Cache {}

Cache Definition.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#cache

property fallbackKeys

readonly fallbackKeys?: string[];

Use cache:fallback_keys to specify a list of keys to try to restore cache from if there is no cache found for the cache:key. Caches are retrieved in the order specified in the fallback_keys section.

property key

readonly key?: string | CacheKeyFiles;

Used the to give each cache a unique identifying key. All jobs that use the same cache key use the same cache.

property paths

readonly paths?: string[];

Defines which files or directories to cache.

property policy

readonly policy?: CachePolicy;

Defines the upload and download behaviour of the cache.

property untracked

readonly untracked?: boolean;

If set to true all files that are untracked in your Git repository will be cached.

property when

readonly when?: CacheWhen;

Defines when to save the cache, based on the status of the job (Default: Job Success).

interface CacheKeyFiles

interface CacheKeyFiles {}

Use this construct to generate a new key when one or two specific files change.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#cachekeyfiles

property files

readonly files: string[];

The files that are checked against. If the SHA checksum changes, the cache becomes invalid.

property prefix

readonly prefix?: string;

Adds a custom prefix to the checksums computed.

interface CiConfigurationOptions

interface CiConfigurationOptions {}

Options for CiConfiguration.

property default

readonly default?: Default;

Default settings for the CI Configuration. Jobs that do not define one or more of the listed keywords use the value defined in the default section.

property jobs

readonly jobs?: Record<string, Job>;

An initial set of jobs to add to the configuration.

property pages

readonly pages?: Job;

A special job used to upload static sites to Gitlab pages. Requires a public/ directory with artifacts.path pointing to it.

property path

readonly path?: string;

The path of the file to generate.

property stages

readonly stages?: string[];

Groups jobs into stages. All jobs in one stage must complete before next stage is executed. If no stages are specified. Defaults to ['build', 'test', 'deploy'].

property variables

readonly variables?: Record<string, any>;

Global variables that are passed to jobs. If the job already has that variable defined, the job-level variable takes precedence.

property workflow

readonly workflow?: Workflow;

Used to control pipeline behavior.

interface CoverageReport

interface CoverageReport {}

Code coverage report interface https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscoverage_report

property coverageFormat

readonly coverageFormat: string;

property path

readonly path: string;

interface Default

interface Default {}

Default settings for the CI Configuration. Jobs that do not define one or more of the listed keywords use the value defined in the default section.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#default

property afterScript

readonly afterScript?: string[];

property artifacts

readonly artifacts?: Artifacts;

property beforeScript

readonly beforeScript?: string[];

property cache

readonly cache?: Cache[];

property idTokens

readonly idTokens?: Record<string, IDToken>;

Specifies the default ID tokens (JSON Web Tokens) that are used for CI/CD authentication to use globally for all jobs.

property image

readonly image?: Image;

property interruptible

readonly interruptible?: boolean;

property retry

readonly retry?: Retry;

property services

readonly services?: Service[];

property tags

readonly tags?: string[];

property timeout

readonly timeout?: string;

interface Engine

interface Engine {}

The engine configuration for a secret.

property name

readonly name: string;

Name of the secrets engine.

property path

readonly path: string;

Path to the secrets engine.

property action

readonly action?: Action;

Specifies what this job will do. 'start' (default) indicates the job will start the deployment. 'prepare' indicates this will not affect the deployment. 'stop' indicates this will stop the deployment.

property autoStopIn

readonly autoStopIn?: string;

The amount of time it should take before Gitlab will automatically stop the environment. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'.

property deploymentTier

readonly deploymentTier?: DeploymentTier;

Explicitly specifies the tier of the deployment environment if non-standard environment name is used.

property kubernetes

readonly kubernetes?: KubernetesConfig;

Used to configure the kubernetes deployment for this environment. This is currently not supported for kubernetes clusters that are managed by Gitlab.

property name

readonly name: string;

The name of the environment, e.g. 'qa', 'staging', 'production'.

property onStop

readonly onStop?: string;

The name of a job to execute when the environment is about to be stopped.

property url

readonly url?: string;

When set, this will expose buttons in various places for the current environment in Gitlab, that will take you to the defined URL.

interface Filter

interface Filter {}

Filtering options for when a job will run.

property changes

readonly changes?: string[];

Filter job creation based on files that were modified in a git push.

property kubernetes

readonly kubernetes?: KubernetesEnum;

Filter job based on if Kubernetes integration is active.

property refs

readonly refs?: string[];

Control when to add jobs to a pipeline based on branch names or pipeline types.

property variables

readonly variables?: string[];

Filter job by checking comparing values of environment variables. Read more about variable expressions: https://docs.gitlab.com/ee/ci/variables/README.html#variables-expressions

interface IDToken

interface IDToken {}

id_tokens Definition.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#id_tokens

property aud

aud: string[] | string;

The required aud sub-keyword is used to configure the aud claim for the JWT.

interface Image

interface Image {}

Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of Gitlab runner executor.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#image

property entrypoint

readonly entrypoint?: any[];

Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array.

property name

readonly name: string;

Full name of the image that should be used. It should contain the Registry part if needed.

interface Include

interface Include {}

An included YAML file.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#include

property file

readonly file?: string[];

Files from another private project on the same GitLab instance. You can use file in combination with project only.

property local

readonly local?: string;

Relative path from local repository root (/) to the yaml/yml file template. The file must be on the same branch, and does not work across git submodules.

property project

readonly project?: string;

Path to the project, e.g. group/project, or group/sub-group/project.

property ref

readonly ref?: string;

Branch/Tag/Commit-hash for the target project.

property remote

readonly remote?: string;

URL to a yaml/yml template file using HTTP/HTTPS.

property rules

readonly rules?: IncludeRule[];

Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.

property template

readonly template?: string;

Use a .gitlab-ci.yml template as a base, e.g. Nodejs.gitlab-ci.yml.

interface IncludeRule

interface IncludeRule {}

Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.
See Also
- https://docs.gitlab.com/ee/ci/yaml/includes.html#use-rules-with-include

property allowFailure

readonly allowFailure?: boolean | AllowFailure;

property changes

readonly changes?: string[];

property exists

readonly exists?: string[];

property if

readonly if?: string;

property needs

readonly needs?: string[];

property startIn

readonly startIn?: string;

property variables

readonly variables?: Record<string, string>;

property when

readonly when?: JobWhen;

interface Inherit

interface Inherit {}

Controls inheritance of globally-defined defaults and variables. Boolean values control inheritance of all default: or variables: keywords. To inherit only a subset of default: or variables: keywords, specify what you wish to inherit. Anything not listed is not inherited.

property default

readonly default?: DefaultElement[] | boolean;

Whether to inherit all globally-defined defaults or not. Or subset of inherited defaults

property variables

readonly variables?: string[] | boolean;

Whether to inherit all globally-defined variables or not. Or subset of inherited variables

interface Job

interface Job {}

Jobs are the most fundamental element of a .gitlab-ci.yml file.
See Also
- https://docs.gitlab.com/ee/ci/jobs/

property afterScript

readonly afterScript?: string[];

property allowFailure

readonly allowFailure?: boolean | AllowFailure;

Whether to allow the pipeline to continue running on job failure (Default: false).

property artifacts

readonly artifacts?: Artifacts;

property beforeScript

readonly beforeScript?: string[];

property cache

readonly cache?: Cache[];

property coverage

readonly coverage?: string;

Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+.\d+/'

property dependencies

readonly dependencies?: string[];

Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts.

property environment

readonly environment?: Environment | string;

Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project.

property except

readonly except?: string[] | Filter;

Job will run *except* for when these filtering options match.

property extends

readonly extends?: string[];

The name of one or more jobs to inherit configuration from.

property idTokens

readonly idTokens?: Record<string, IDToken>;

Configurable ID tokens (JSON Web Tokens) that are used for CI/CD authentication

property image

readonly image?: Image;

property inherit

readonly inherit?: Inherit;

Controls inheritance of globally-defined defaults and variables. Boolean values control inheritance of all default: or variables: keywords. To inherit only a subset of default: or variables: keywords, specify what you wish to inherit. Anything not listed is not inherited.

property interruptible

readonly interruptible?: boolean;

property needs

readonly needs?: Array<Need | string>;

The list of jobs in previous stages whose sole completion is needed to start the current job.

property only

readonly only?: string[] | Filter;

Job will run *only* when these filtering options match.

property parallel

readonly parallel?: Parallel | number;

Parallel will split up a single job into several, and provide CI_NODE_INDEX and CI_NODE_TOTAL environment variables for the running jobs.

property release

readonly release?: Release;

Indicates that the job creates a Release.

property resourceGroup

readonly resourceGroup?: string;

Limit job concurrency. Can be used to ensure that the Runner will not run certain jobs simultaneously.

property retry

readonly retry?: Retry;

property rules

readonly rules?: IncludeRule[];

Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.

property script

readonly script?: string[];

Shell scripts executed by the Runner. The only required property of jobs. Be careful with special characters (e.g. :, {, }, &) and use single or double quotes to avoid issues.

property secrets

readonly secrets?: Record<string, Record<string, Secret>>;

CI/CD secrets

property services

readonly services?: Service[];

property stage

readonly stage?: string;

Define what stage the job will run in.

property startIn

readonly startIn?: string;

property tags

readonly tags?: string[];

property timeout

readonly timeout?: string;

property trigger

readonly trigger?: Trigger | string;

Trigger allows you to define downstream pipeline trigger. When a job created from trigger definition is started by GitLab, a downstream pipeline gets created. Read more: https://docs.gitlab.com/ee/ci/yaml/README.html#trigger

property variables

readonly variables?: Record<string, string>;

Configurable values that are passed to the Job.

property when

readonly when?: JobWhen;

Describes the conditions for when to run the job. Defaults to 'on_success'.

interface KubernetesConfig

interface KubernetesConfig {}

Used to configure the kubernetes deployment for this environment. This is currently not supported for kubernetes clusters that are managed by Gitlab.

property namespace

readonly namespace?: string;

The kubernetes namespace where this environment should be deployed to.

interface Link

interface Link {}

Link configuration for an asset.

property filepath

readonly filepath?: string;

The redirect link to the url.

property linkType

readonly linkType?: LinkType;

The content kind of what users can download via url.

property name

readonly name: string;

The name of the link.

property url

readonly url: string;

The URL to download a file.

interface Need

interface Need {}

A jobs in a previous stage whose sole completion is needed to start the current job.

property artifacts

readonly artifacts?: boolean;

property job

readonly job: string;

property optional

readonly optional?: boolean;

property pipeline

readonly pipeline?: string;

property project

readonly project?: string;

property ref

readonly ref?: string;

interface Parallel

interface Parallel {}

Used to run a job multiple times in parallel in a single pipeline.

property matrix

readonly matrix: Record<string, any[]>[];

Defines different variables for jobs that are running in parallel.

interface Release

interface Release {}

Indicates that the job creates a Release.

property assets

readonly assets?: Assets;

property description

readonly description: string;

Specifies the longer description of the Release.

property milestones

readonly milestones?: string[];

The title of each milestone the release is associated with.

property name

readonly name?: string;

The Release name. If omitted, it is populated with the value of release: tag_name.

property ref

readonly ref?: string;

If the release: tag_name doesn’t exist yet, the release is created from ref. ref can be a commit SHA, another tag name, or a branch name.

property releasedAt

readonly releasedAt?: string;

The date and time when the release is ready. Defaults to the current date and time if not defined. Should be enclosed in quotes and expressed in ISO 8601 format.

property tagName

readonly tagName: string;

The tag_name must be specified. It can refer to an existing Git tag or can be specified by the user.

interface Reports

interface Reports {}

Reports will be uploaded as artifacts, and often displayed in the Gitlab UI, such as in Merge Requests.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#artifactsreports

property cobertura

readonly cobertura?: string[];

Path for file(s) that should be parsed as Cobertura XML coverage report
Deprecated
per https://docs.gitlab.com/ee/update/deprecations.html#artifactsreportscobertura-keyword use coverageReport instead

property codequality

readonly codequality?: string[];

Path to file or list of files with code quality report(s) (such as Code Climate).

property containerScanning

readonly containerScanning?: string[];

Path to file or list of files with Container scanning vulnerabilities report(s).

property dast

readonly dast?: string[];

Path to file or list of files with DAST vulnerabilities report(s).

property dependencyScanning

readonly dependencyScanning?: string[];

Path to file or list of files with Dependency scanning vulnerabilities report(s).

property dotenv

readonly dotenv?: string[];

Path to file or list of files containing runtime-created variables for this job.

property junit

readonly junit?: string[];

Path for file(s) that should be parsed as JUnit XML result

property licenseManagement

readonly licenseManagement?: string[];

Deprecated in 12.8: Path to file or list of files with license report(s).

property licenseScanning

readonly licenseScanning?: string[];

Path to file or list of files with license report(s).

property lsif

readonly lsif?: string[];

Path to file or list of files containing code intelligence (Language Server Index Format).

property metrics

readonly metrics?: string[];

Path to file or list of files with custom metrics report(s).

property performance

readonly performance?: string[];

Path to file or list of files with performance metrics report(s).

property requirements

readonly requirements?: string[];

Path to file or list of files with requirements report(s).

property sast

readonly sast?: string[];

Path to file or list of files with SAST vulnerabilities report(s).

property secretDetection

readonly secretDetection?: string[];

Path to file or list of files with secret detection report(s).

property terraform

readonly terraform?: string[];

Path to file or list of files with terraform plan(s).

interface Retry

interface Retry {}

How many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#retry

property max

readonly max?: number;

0 (default), 1, or 2.

property when

readonly when?: any;

Either a single or array of error types to trigger job retry.

interface Secret

interface Secret {}

A CI/CD secret

property vault

readonly vault: VaultConfig;

interface Service

interface Service {}

Used to specify an additional Docker image to run scripts in. The service image is linked to the image specified in the image keyword.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#services

property alias

readonly alias?: string;

Additional alias that can be used to access the service from the job's container. Read Accessing the services for more information.

property command

readonly command?: string[];

Command or script that should be used as the container's command. It will be translated to arguments passed to Docker after the image's name. The syntax is similar to Dockerfile's CMD directive, where each shell token is a separate string in the array.

property entrypoint

readonly entrypoint?: string[];

Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array.

property name

readonly name: string;

Full name of the image that should be used. It should contain the Registry part if needed.

property pullPolicy

readonly pullPolicy?: PullPolicy[];

The pull policy that the runner uses to fetch the Docker image

property variables

readonly variables?: Record<string, string>;

Additional environment variables that are passed exclusively to the service..

interface Trigger

interface Trigger {}

Trigger a multi-project or a child pipeline. Read more:
See Also
- https://docs.gitlab.com/ee/ci/yaml/README.html#simple-trigger-syntax-for-multi-project-pipelines
- https://docs.gitlab.com/ee/ci/yaml/README.html#trigger-syntax-for-child-pipeline

property branch

readonly branch?: string;

The branch name that a downstream pipeline will use

property include

readonly include?: TriggerInclude[];

A list of local files or artifacts from other jobs to define the pipeline

property project

readonly project?: string;

Path to the project, e.g. group/project, or group/sub-group/project.

property strategy

readonly strategy?: Strategy;

You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend

interface TriggerInclude

interface TriggerInclude {}

References a local file or an artifact from another job to define the pipeline configuration.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#triggerinclude

property artifact

readonly artifact?: string;

Relative path to the generated YAML file which is extracted from the artifacts and used as the configuration for triggering the child pipeline.

property file

readonly file?: string;

Relative path from repository root (/) to the pipeline configuration YAML file.

property job

readonly job?: string;

Job name which generates the artifact

property local

readonly local?: string;

Relative path from local repository root (/) to the local YAML file to define the pipeline configuration.

property project

readonly project?: string;

Path to another private project under the same GitLab instance, like group/project or group/sub-group/project.

property ref

readonly ref?: string;

Branch/Tag/Commit hash for the target project.

property template

readonly template?: string;

Name of the template YAML file to use in the pipeline configuration.

interface VariableConfig

interface VariableConfig {}

Explains what the global variable is used for, what the acceptable values are.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#variables

property description

readonly description?: string;

Define a global variable that is prefilled when running a pipeline manually. Must be used with value.

property value

readonly value?: string;

The variable value.

interface VaultConfig

interface VaultConfig {}

Specification for a secret provided by a HashiCorp Vault.
See Also
- https://www.vaultproject.io/

property engine

readonly engine: Engine;

property field

readonly field: string;

property path

readonly path: string;

Path to the secret.

interface Workflow

interface Workflow {}

Used to control pipeline behavior.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#workflow

property name

readonly name?: string;

You can use name to define a name for pipelines.

property rules

readonly rules?: WorkflowRule[];

Used to control whether or not a whole pipeline is created.

interface WorkflowRule

interface WorkflowRule {}

Used to control whether or not a whole pipeline is created.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#workflowrules

property changes

readonly changes?: string[];

property exists

readonly exists?: string[];

property if

readonly if?: string;

property variables

readonly variables?: Record<string, number | string>;

property when

readonly when?: WorkflowWhen;

enum Action

enum Action {
    PREPARE = 'prepare',
    START = 'start',
    STOP = 'stop',
}

Specifies what this job will do. 'start' (default) indicates the job will start the deployment. 'prepare' indicates this will not affect the deployment. 'stop' indicates this will stop the deployment.

member PREPARE

PREPARE = 'prepare'

member START

START = 'start'

member STOP

STOP = 'stop'

enum CachePolicy

enum CachePolicy {
    PULL = 'pull',
    PUSH = 'push',
    PULL_PUSH = 'pull-push',
}

Configure the upload and download behaviour of a cache.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#cachepolicy

member PULL

PULL = 'pull'

Only download the cache when the job starts, but never upload changes when the job finishes.

member PULL_PUSH

PULL_PUSH = 'pull-push'

The job downloads the cache when the job starts, and uploads changes to the cache when the job ends.

member PUSH

PUSH = 'push'

Only upload a cache when the job finishes, but never download the cache when the job starts.

enum CacheWhen

enum CacheWhen {
    ALWAYS = 'always',
    ON_FAILURE = 'on_failure',
    ON_SUCCESS = 'on_success',
}

Configure when artifacts are uploaded depended on job status.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#cachewhen

member ALWAYS

ALWAYS = 'always'

Upload artifacts regardless of job status.

member ON_FAILURE

ON_FAILURE = 'on_failure'

Upload artifacts only when the job fails.

member ON_SUCCESS

ON_SUCCESS = 'on_success'

Upload artifacts only when the job succeeds (this is the default).

enum DefaultElement

enum DefaultElement {
    AFTER_SCRIPT = 'after_script',
    ARTIFACTS = 'artifacts',
    BEFORE_SCRIPT = 'before_script',
    CACHE = 'cache',
    IMAGE = 'image',
    INTERRUPTIBLE = 'interruptible',
    RETRY = 'retry',
    SERVICES = 'services',
    TAGS = 'tags',
    TIMEOUT = 'timeout',
}

member AFTER_SCRIPT

AFTER_SCRIPT = 'after_script'

member ARTIFACTS

ARTIFACTS = 'artifacts'

member BEFORE_SCRIPT

BEFORE_SCRIPT = 'before_script'

member CACHE

CACHE = 'cache'

member IMAGE

IMAGE = 'image'

member INTERRUPTIBLE

INTERRUPTIBLE = 'interruptible'

member RETRY

RETRY = 'retry'

member SERVICES

SERVICES = 'services'

member TAGS

TAGS = 'tags'

member TIMEOUT

TIMEOUT = 'timeout'

enum DeploymentTier

enum DeploymentTier {
    DEVELOPMENT = 'development',
    OTHER = 'other',
    PRODUCTION = 'production',
    STAGING = 'staging',
    TESTING = 'testing',
}

Explicitly specifies the tier of the deployment environment if non-standard environment name is used.

member DEVELOPMENT

DEVELOPMENT = 'development'

member OTHER

OTHER = 'other'

member PRODUCTION

PRODUCTION = 'production'

member STAGING

STAGING = 'staging'

member TESTING

TESTING = 'testing'

enum JobWhen

enum JobWhen {
    ALWAYS = 'always',
    DELAYED = 'delayed',
    MANUAL = 'manual',
    NEVER = 'never',
    ON_FAILURE = 'on_failure',
    ON_SUCCESS = 'on_success',
}

Describes the conditions for when to run the job. Defaults to 'on_success'.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#when

member ALWAYS

ALWAYS = 'always'

member DELAYED

DELAYED = 'delayed'

member MANUAL

MANUAL = 'manual'

member NEVER

NEVER = 'never'

member ON_FAILURE

ON_FAILURE = 'on_failure'

member ON_SUCCESS

ON_SUCCESS = 'on_success'

enum KubernetesEnum

enum KubernetesEnum {
    ACTIVE = 'active',
}

Filter job based on if Kubernetes integration is active.

member ACTIVE

ACTIVE = 'active'

enum LinkType

enum LinkType {
    IMAGE = 'image',
    OTHER = 'other',
    PACKAGE = 'package',
    RUNBOOK = 'runbook',
}

The content kind of what users can download via url.

member IMAGE

IMAGE = 'image'

member OTHER

OTHER = 'other'

member PACKAGE

PACKAGE = 'package'

member RUNBOOK

RUNBOOK = 'runbook'

enum PullPolicy

enum PullPolicy {
    ALWAYS = 'always',
    NEVER = 'never',
    IF_NOT_PRESENT = 'if-not-present',
}

Describes the conditions for when to pull an image.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#servicepull_policy

member ALWAYS

ALWAYS = 'always'

member IF_NOT_PRESENT

IF_NOT_PRESENT = 'if-not-present'

member NEVER

NEVER = 'never'

enum Strategy

enum Strategy {
    DEPEND = 'depend',
}

You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend
See Also
- https://docs.gitlab.com/ee/ci/yaml/#triggerstrategy

member DEPEND

DEPEND = 'depend'

enum WorkflowWhen

enum WorkflowWhen {
    ALWAYS = 'always',
    NEVER = 'never',
}

Describes the conditions for when to run the job. Defaults to 'on_success'. The value can only be 'always' or 'never' when used with workflow.
See Also
- https://docs.gitlab.com/ee/ci/yaml/#workflowrules

member ALWAYS

ALWAYS = 'always'

member NEVER

NEVER = 'never'

namespace java

module 'lib/java/index.d.ts' {}

function generateJavaOptionNames

generateJavaOptionNames: (
    options: ProjectOption[],
    jsiiManifest: any
) => Record<string, string>;

function getJavaImport

getJavaImport: (jsiiType: any, jsiiManifest: any) => string;

constructor

constructor(options: JavaProjectOptions);

property compile

readonly compile: MavenCompile;

Compile component.

property distdir

readonly distdir: string;

Maven artifact output directory.

property junit

readonly junit?: Junit;

JUnit component.

property pom

readonly pom: Pom;

API for managing pom.xml.

property projenrc

readonly projenrc?: ProjenrcJava;

Projenrc component.

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <groupId>/<artifactId>@<semver>

method addPlugin

addPlugin: (spec: string, options?: PluginOptions) => import('..').Dependency;

Adds a build plugin to the pom.
The plug in is also added as a BUILD dep to the project.
Parameter spec
dependency spec (group/artifact@version)
Parameter options
plugin options

method addTestDependency

addTestDependency: (spec: string) => void;

Adds a test dependency.
Parameter spec
Format <groupId>/<artifactId>@<semver>

class Junit

class Junit extends Component {}

Implements JUnit-based testing.

constructor

constructor(project: Project, options: JunitOptions);

class MavenCompile

class MavenCompile extends Component {}

Adds the maven-compiler plugin to a POM file and the compile task.

constructor

constructor(project: Project, pom: Pom, options?: MavenCompileOptions);

class MavenPackaging

class MavenPackaging extends Component {}

Configures a maven project to produce a .jar archive with sources and javadocs.

constructor

constructor(project: Project, pom: Pom, options?: MavenPackagingOptions);

property distdir

readonly distdir: string;

The directory containing the package output, relative to the project outdir

constructor

constructor(project: Project, options: MavenSampleOptions);

class Pom

class Pom extends Component {}

A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project.

constructor

constructor(project: Project, options: PomOptions);

property fileName

readonly fileName: string;

The name of the pom file.

property groupId

readonly groupId: string;

Maven group ID.

property name

readonly name?: string;

Project display name.

property url

readonly url?: string;

Project URL.

property version

readonly version: string;

Project version.

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <groupId>/<artifactId>@<semver>

method addPlugin

addPlugin: (
    spec: string,
    options?: PluginOptions
) => import('../dependencies').Dependency;

Adds a build plugin to the pom.
The plug in is also added as a BUILD dep to the project.
Parameter spec
dependency spec (group/artifact@version)
Parameter options
plugin options

method addPluginRepository

addPluginRepository: (repository: MavenRepository) => void;

method addProperty

addProperty: (key: string, value: string) => void;

Adds a key/value property to the pom.
Parameter key
the key
Parameter value
the value

method addRepository

addRepository: (repository: MavenRepository) => void;

Adds a repository to the pom
Parameter repository
the repository to add

method addTestDependency

addTestDependency: (spec: string) => void;

Adds a test dependency.
Parameter spec
Format <groupId>/<artifactId>@<semver>

class Projenrc

class Projenrc extends ProjenrcFile {}

Allows writing projenrc files in java.
This will install org.projen/projen as a Maven dependency and will add a synth task which will compile & execute main() from src/main/java/projenrc.java.

constructor

constructor(project: Project, pom: Pom, options?: ProjenrcOptions);

property className

readonly className: string;

The name of the java class that includes the projen entrypoint.

property filePath

readonly filePath: string;

The path of the projenrc file.

class UpdatePolicy

class UpdatePolicy {}

property ALWAYS

static readonly ALWAYS: string;

property DAILY

static readonly DAILY: string;

property NEVER

static readonly NEVER: string;

interface JavaProjectCommonOptions

interface JavaProjectCommonOptions extends GitHubProjectOptions, PomOptions {}

Options for JavaProject.

property deps

readonly deps?: string[];

List of runtime dependencies for this project.
Dependencies use the format: <groupId>/<artifactId>@<semver>
Additional dependencies can be added via project.addDependency().
[]

property distdir

readonly distdir?: string;

Final artifact output directory.
"dist/java"

property junit

readonly junit?: boolean;

Include junit tests. true

property projenrcJava

readonly projenrcJava?: boolean;

Use projenrc in java.
This will install projen as a java dependency and will add a synth task which will compile & execute main() from src/main/java/projenrc.java.
true

property projenrcJavaOptions

readonly projenrcJavaOptions?: ProjenrcOptions;

Options related to projenrc in java. - default options

property testDeps

readonly testDeps?: string[];

List of test dependencies for this project.
Dependencies use the format: <groupId>/<artifactId>@<semver>
Additional dependencies can be added via project.addTestDependency().
[]

property sample

readonly sample?: boolean;

Include sample code and test if the relevant directories don't exist. true

property sampleJavaPackage

readonly sampleJavaPackage?: string;

The java package to use for the code sample. "org.acme"

property pom

readonly pom: Pom;

Java pom.

property version

readonly version?: string;

Junit version
"5.7.0"

property source

readonly source?: string;

Source language version.
"1.8"

property target

readonly target?: string;

Target JVM version.
"1.8"

interface MavenPackagingOptions

interface MavenPackagingOptions {}

Options for MavenPackage.

property distdir

readonly distdir?: string;

Where to place the package output? "dist/java"

property javadocs

readonly javadocs?: boolean;

Include javadocs jar in package. true

property sources

readonly sources?: boolean;

Include sources jar in package. true

interface MavenRepository

interface MavenRepository {}

Represents a Maven repository
See Also
- https://maven.apache.org/guides/introduction/introduction-to-repositories.html

property id

readonly id: string;

The identifier for the repository

property layout

readonly layout?: string;

The layout of the repository

property name

readonly name?: string;

The name of the repository

property releases

readonly releases?: MavenRepositoryPolicy;

Repository Policy for Releases

property url

readonly url: string;

The url of the repository

interface MavenRepositoryPolicy

interface MavenRepositoryPolicy {}

Represents a Maven Repository Policy
See Also
- https://maven.apache.org/settings.html#repositories

property checksumPolicy

readonly checksumPolicy?: ChecksumPolicy;

Checksum Policy When Maven deploys files to the repository, it also deploys corresponding checksum files.

property enabled

readonly enabled?: boolean;

property updatePolicy

readonly updatePolicy?: UpdatePolicy;

Update Policy This element specifies how often updates should attempt to occur. Maven will compare the local POM's timestamp (stored in a repository's maven-metadata file) to the remote. UpdatePolicy.DAILY

interface MavenSampleOptions

interface MavenSampleOptions {}

property package

readonly package: string;

Project root java package.

interface ParentPom

interface ParentPom {}

property groupId

readonly groupId?: string;

Parent Pom Group ID

property relativePath

readonly relativePath?: string;

Parent Pom Relative path from the current pom

property version

readonly version?: string;

Parent Pom Version

property goals

readonly goals: string[];

Which Maven goals this plugin should be associated with.

property id

readonly id: string;

The ID.

property phase

readonly phase?: string;

The phase in which the plugin should execute.

property dependencies

readonly dependencies?: string[];

You could configure the dependencies for the plugin.
Dependencies are in <groupId>/<artifactId>@<semver> format.
[]

property artifactId

readonly artifactId: string;

The artifactId is generally the name that the project is known by. Although the groupId is important, people within the group will rarely mention the groupId in discussion (they are often all be the same ID, such as the MojoHaus project groupId: org.codehaus.mojo). It, along with the groupId, creates a key that separates this project from every other project in the world (at least, it should :) ). Along with the groupId, the artifactId fully defines the artifact's living quarters within the repository. In the case of the above project, my-project lives in $M2_REPO/org/codehaus/mojo/my-project. "my-app"

property description

readonly description?: string;

Description of a project is always good. Although this should not replace formal documentation, a quick comment to any readers of the POM is always helpful.
undefined

property groupId

readonly groupId: string;

This is generally unique amongst an organization or a project. For example, all core Maven artifacts do (well, should) live under the groupId org.apache.maven. Group ID's do not necessarily use the dot notation, for example, the junit project. Note that the dot-notated groupId does not have to correspond to the package structure that the project contains. It is, however, a good practice to follow. When stored within a repository, the group acts much like the Java packaging structure does in an operating system. The dots are replaced by OS specific directory separators (such as '/' in Unix) which becomes a relative directory structure from the base repository. In the example given, the org.codehaus.mojo group lives within the directory $M2_REPO/org/codehaus/mojo. "org.acme"

property parentPom

readonly parentPom?: ParentPom;

A Parent Pom can be used to have a child project inherit properties/plugins/ect in order to reduce duplication and keep standards across a large amount of repos
undefined

property url

readonly url?: string;

The URL, like the name, is not required. This is a nice gesture for projects users, however, so that they know where the project lives.
undefined

property version

readonly version: string;

This is the last piece of the naming puzzle. groupId:artifactId denotes a single project but they cannot delineate which incarnation of that project we are talking about. Do we want the junit:junit of 2018 (version 4.12), or of 2007 (version 3.8.2)? In short: code changes, those changes should be versioned, and this element keeps those versions in line. It is also used within an artifact's repository to separate versions from each other. my-project version 1.0 files live in the directory structure $M2_REPO/org/codehaus/mojo/my-project/1.0. "0.1.0"

property className

readonly className?: string;

The name of the Java class which contains the main() method for projen. "projenrc"

property projenVersion

readonly projenVersion?: string;

The projen version to use - current version

property testScope

readonly testScope?: boolean;

Defines projenrc under the test scope instead of the main scope, which is reserved to the app. This means that projenrc will be under src/test/java/projenrc.java and projen will be defined as a test dependency. This enforces that application code does not take a dependency on projen code.
If this is disabled, projenrc should be under src/main/java/projenrc.java.
true

enum ChecksumPolicy

enum ChecksumPolicy {
    IGNORE = 'ignore',
    FAIL = 'fail',
    WARN = 'warn',
}

member FAIL

FAIL = 'fail'

member IGNORE

IGNORE = 'ignore'

member WARN

WARN = 'warn'

namespace javascript

module 'lib/javascript/index.d.ts' {}

function defaultNpmToken

defaultNpmToken: (
    npmToken: string | undefined,
    registry: string | undefined
) => string | undefined;

class Bundler

class Bundler extends Component {}

Adds support for bundling JavaScript applications and dependencies into a single file. In the future, this will also supports bundling websites.

property bundleTask

readonly bundleTask: Task;

Gets or creates the singleton "bundle" task of the project.
If the project doesn't have a "bundle" task, it will be created and spawned during the pre-compile phase.

property esbuildVersion

readonly esbuildVersion: string;

The semantic version requirement for esbuild (if defined).

method addBundle

addBundle: (entrypoint: string, options: AddBundleOptions) => Bundle;

Adds a task to the project which bundles a specific entrypoint and all of its dependencies into a single javascript output file.
Parameter entrypoint
The relative path of the artifact within the project
Parameter options
Bundling options

method of

static of: (project: Project) => Bundler | undefined;

Returns the Bundler instance associated with a project or undefined if there is no Bundler.
Parameter project
The project
Returns
A bundler

constructor

constructor(project: NodeProject, options: EslintOptions);

property config

readonly config: any;

Direct access to the eslint configuration (escape hatch)

property lintPatterns

readonly lintPatterns: string[];

Returns an immutable copy of the lintPatterns being used by this eslint configuration.

property rules

readonly rules: { [rule: string]: any[] };

eslint rules.

method addExtends

addExtends: (...extendList: string[]) => void;

Adds an extends item to the eslint configuration.
Parameter extendList
The list of "extends" to add.

method addLintPattern

addLintPattern: (pattern: string) => void;

Add a file, glob pattern or directory with source files to lint (e.g. [ "src" ])

method addPlugins

addPlugins: (...plugins: string[]) => void;

Adds an eslint plugin
Parameter plugins
The names of plugins to add

method allowDevDeps

allowDevDeps: (pattern: string) => void;

Add a glob file pattern which allows importing dev dependencies.
Parameter pattern
glob pattern.

method of

static of: (project: Project) => Eslint | undefined;

Returns the singleton Eslint component of a project or undefined if there is none.

class Jest

class Jest extends Component {}

Installs the following npm scripts:
- test, intended for testing locally and in CI. Will update snapshots unless updateSnapshot: UpdateSnapshot: NEVER is set. - test:watch, intended for automatically rerunning tests when files change. - test:update, intended for testing locally and updating snapshots to match the latest unit under test. Only available when updateSnapshot: UpdateSnapshot: NEVER.

constructor

constructor(project: NodeProject, options?: JestOptions);

property config

readonly config: any;

Escape hatch.

property file

readonly file?: JsonFile;

Jest config file. undefined if settings are written to package.json

property jestVersion

readonly jestVersion: string;

Jest version, including @ symbol, like @^29

method addIgnorePattern

addIgnorePattern: (pattern: string) => void;

method addModuleNameMappers

addModuleNameMappers: (moduleNameMapperAdditions: {
    [key: string]: string | string[];
}) => void;

Adds one or more moduleNameMapper entries to Jest's configuration. Will overwrite if the same key is used as a pre-existing one.
Parameter moduleNameMapperAdditions
A map from regular expressions to module names or to arrays of module names that allow to stub out resources, like images or styles with a single module.

method addModulePaths

addModulePaths: (...modulePaths: string[]) => void;

Adds one or more modulePaths to Jest's configuration.
Parameter modulePaths
An array of absolute paths to additional locations to search when resolving modules *

method addReporter

addReporter: (reporter: JestReporter) => void;

method addRoots

addRoots: (...roots: string[]) => void;

Adds one or more roots to Jest's configuration.
Parameter roots
A list of paths to directories that Jest should use to search for files in.

method addSetupFile

addSetupFile: (file: string) => void;

Adds a a setup file to Jest's setupFiles configuration.
Parameter file
File path to setup file

method addSetupFileAfterEnv

addSetupFileAfterEnv: (file: string) => void;

Adds a a setup file to Jest's setupFilesAfterEnv configuration.
Parameter file
File path to setup file

method addSnapshotResolver

addSnapshotResolver: (file: string) => void;

method addTestMatch

addTestMatch: (pattern: string) => void;

Adds a test match pattern.
Parameter pattern
glob pattern to match for tests

method addWatchIgnorePattern

addWatchIgnorePattern: (pattern: string) => void;

Adds a watch ignore pattern.
Parameter pattern
The pattern (regular expression).

method discoverTestMatchPatternsForDirs

discoverTestMatchPatternsForDirs: (
    dirs: string[],
    options?: JestDiscoverTestMatchPatternsForDirsOptions
) => void;

Build standard test match patterns for a directory.
Parameter dirs
The directories to add test matches for. Matches any folder if not specified or an empty array.
Parameter options
Options for building test match patterns.

method of

static of: (project: Project) => Jest | undefined;

Returns the singleton Jest component of a project or undefined if there is none.

class JestReporter

class JestReporter {}

constructor

constructor(name: string, options?: { [key: string]: any });

class LicenseChecker

class LicenseChecker extends Component {}

Enforces allowed licenses used by dependencies.

constructor

constructor(scope: Construct, options: LicenseCheckerOptions);

property task

readonly task: Task;

constructor

constructor(project: Project, options?: NodePackageOptions);

property allowLibraryDependencies

readonly allowLibraryDependencies: boolean;

Allow project to take library dependencies.

property bunVersion

readonly bunVersion?: string;

The version of Bun to use if using Bun as a package manager.

property codeArtifactOptions

readonly codeArtifactOptions?: CodeArtifactOptions;

Options for npm packages using AWS CodeArtifact. This is required if publishing packages to, or installing scoped packages from AWS CodeArtifact
- undefined

property entrypoint

readonly entrypoint: string;

The module's entrypoint (e.g. lib/index.js).

property file

readonly file: JsonFile;

The package.json file.

property installAndUpdateLockfileCommand

readonly installAndUpdateLockfileCommand: string;

Renders yarn install or npm install with lockfile update (not frozen)

property installCiTask

readonly installCiTask: Task;

The task for installing project dependencies (frozen)

property installCommand

readonly installCommand: string;

Returns the command to execute in order to install all dependencies (always frozen).

property installTask

readonly installTask: Task;

The task for installing project dependencies (non-frozen)

property license

readonly license?: string;

The SPDX license of this module. undefined if this package is not licensed.

property lockFile

readonly lockFile: string;

The name of the lock file.

property manifest

readonly manifest: any;

Deprecated
use addField(x, y)

property maxNodeVersion

readonly maxNodeVersion?: string;

Maximum node version supported by this package.
The value indicates the package is incompatible with newer versions.

property minNodeVersion

readonly minNodeVersion?: string;

The minimum node version required by this package to function.
This value indicates the package is incompatible with older versions.

property npmProvenance

readonly npmProvenance: boolean;

Should provenance statements be generated when package is published.

property npmRegistry

readonly npmRegistry: string;

The npm registry host (e.g. registry.npmjs.org).

property npmRegistryUrl

readonly npmRegistryUrl: string;

npm registry (e.g. https://registry.npmjs.org). Use npmRegistryHost to get just the host name.

property npmTokenSecret

readonly npmTokenSecret?: string;

GitHub secret which contains the NPM token to use when publishing packages.

property pnpmVersion

readonly pnpmVersion?: string;

The version of PNPM to use if using PNPM as a package manager.

property projenCommand

readonly projenCommand: string;

The command which executes "projen".
Deprecated
use project.projenCommand instead.

property scopedPackagesOptions

readonly scopedPackagesOptions?: ScopedPackagesOptions[];

Options for privately hosted scoped packages
undefined

method addBin

addBin: (bins: Record<string, string>) => void;

method addBundledDeps

addBundledDeps: (...deps: string[]) => void;

Defines bundled dependencies.
Bundled dependencies will be added as normal dependencies as well as to the bundledDependencies section of your package.json.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addDeps

addDeps: (...deps: string[]) => void;

Defines normal dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addDevDeps

addDevDeps: (...deps: string[]) => void;

Defines development/test dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addEngine

addEngine: (engine: string, version: string) => void;

Adds an engines requirement to your package.
Parameter engine
The engine (e.g. node)
Parameter version
The semantic version requirement (e.g. ^10)

method addField

addField: (name: string, value: any) => void;

Directly set fields in package.json.
Parameter name
field name
Parameter value
field value

method addKeywords

addKeywords: (...keywords: string[]) => void;

Adds keywords to package.json (deduplicated)
Parameter keywords
The keywords to add

method addPackageResolutions

addPackageResolutions: (...resolutions: string[]) => void;

Defines resolutions for dependencies to change the normally resolved version of a dependency to something else.
Parameter resolutions
Names resolutions to be added. Specify a version or range with this syntax: module@^7

method addPeerDeps

addPeerDeps: (...deps: string[]) => void;

Defines peer dependencies.
When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addVersion

addVersion: (version: string) => void;

Sets the package version.
Parameter version
Package version.

method hasScript

hasScript: (name: string) => boolean;

Indicates if a script by the given name is defined.
Parameter name
The name of the script
Deprecated
Use project.tasks.tryFind(name)

method of

static of: (project: Project) => NodePackage | undefined;

Returns the NodePackage instance associated with a project or undefined if there is no NodePackage.
Parameter project
The project
Returns
A NodePackage, or undefined

method postSynthesize

postSynthesize: () => void;

method removeScript

removeScript: (name: string) => void;

Removes an npm script (always successful).
Parameter name
The name of the script.

method setScript

setScript: (name: string, command: string) => void;

Add a npm package.json script.
Parameter name
The script name
Parameter command
The command to execute

method synthesize

synthesize: () => void;

method tryResolveDependencyVersion

tryResolveDependencyVersion: (dependencyName: string) => string | undefined;

Attempt to resolve the currently installed version for a given dependency.
Parameter dependencyName
Dependency to resolve for.
Remarks
This method will first look through the current project's dependencies. If found and semantically valid (not '*'), that will be used. Otherwise, it will fall back to locating a package.json manifest for the dependency through node's internal resolution reading the version from there.

constructor

constructor(options: NodeProjectOptions);

property allowLibraryDependencies

readonly allowLibraryDependencies: boolean;

Deprecated
use package.allowLibraryDependencies

property artifactsDirectory

readonly artifactsDirectory: string;

The build output directory. An npm tarball will be created under the js subdirectory. For example, if this is set to dist (the default), the npm tarball will be placed under dist/js/boom-boom-1.2.3.tg.

property artifactsJavascriptDirectory

readonly artifactsJavascriptDirectory: string;

The location of the npm tarball after build (${artifactsDirectory}/js).

property autoMerge

readonly autoMerge?: AutoMerge;

Component that sets up mergify for merging approved pull requests.

property buildWorkflow

readonly buildWorkflow?: BuildWorkflow;

The PR build GitHub workflow. undefined if buildWorkflow is disabled.

property bundler

readonly bundler: Bundler;

property jest

readonly jest?: Jest;

The Jest configuration (if enabled)

property manifest

readonly manifest: any;

Deprecated
use package.addField(x, y)

property maxNodeVersion

readonly maxNodeVersion: string;

Maximum node version supported by this package.
The value indicates the package is incompatible with newer versions.

property minNodeVersion

readonly minNodeVersion: string;

The minimum node version required by this package to function.
This value indicates the package is incompatible with older versions.

property nodeVersion

protected readonly nodeVersion?: string;

property npmrc

readonly npmrc: NpmConfig;

The .npmrc file

property package

readonly package: NodePackage;

API for managing the node package.

property packageManager

readonly packageManager: NodePackageManager;

The package manager to use.
Deprecated
use package.packageManager

property prettier

readonly prettier?: Prettier;

property publisher

readonly publisher?: Publisher;

Package publisher. This will be undefined if the project does not have a release workflow.
Deprecated
use release.publisher.

property release

readonly release?: Release;

Release management.

property runScriptCommand

readonly runScriptCommand: string;

The command to use to run scripts (e.g. yarn run or npm run depends on the package manager).

property workflowBootstrapSteps

protected readonly workflowBootstrapSteps: JobStep[];

property workflowPackageCache

protected readonly workflowPackageCache: boolean;

method addBins

addBins: (bins: Record<string, string>) => void;

method addBundledDeps

addBundledDeps: (...deps: string[]) => void;

Defines bundled dependencies.
Bundled dependencies will be added as normal dependencies as well as to the bundledDependencies section of your package.json.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addCompileCommand

addCompileCommand: (...commands: string[]) => void;

DEPRECATED
Deprecated
use project.compileTask.exec()

method addDeps

addDeps: (...deps: string[]) => void;

Defines normal dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addDevDeps

addDevDeps: (...deps: string[]) => void;

Defines development/test dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addFields

addFields: (fields: { [name: string]: any }) => void;

Directly set fields in package.json.
Parameter fields
The fields to set

method addKeywords

addKeywords: (...keywords: string[]) => void;

Adds keywords to package.json (deduplicated)
Parameter keywords
The keywords to add

method addPackageIgnore

addPackageIgnore: (pattern: string) => void;

Adds patterns to be ignored by npm.
Parameter pattern
The pattern to ignore.
Remarks
If you are having trouble getting an ignore to populate, try using your construct or component's preSynthesize method to properly delay calling this method.

method addPeerDeps

addPeerDeps: (...deps: string[]) => void;

Defines peer dependencies.
When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax: module@^7.

method addScripts

addScripts: (scripts: { [name: string]: string }) => void;

Replaces the contents of multiple npm package.json scripts.
Parameter scripts
The scripts to set

method addTestCommand

addTestCommand: (...commands: string[]) => void;

DEPRECATED
Deprecated
use project.testTask.exec()

method hasScript

hasScript: (name: string) => boolean;

Indicates if a script by the name name is defined.
Parameter name
The name of the script
Deprecated
Use project.tasks.tryFind(name)

method removeScript

removeScript: (name: string) => void;

Removes the npm script (always successful).
Parameter name
The name of the script.

method renderWorkflowSetup

renderWorkflowSetup: (options?: RenderWorkflowSetupOptions) => JobStep[];

Returns the set of workflow steps which should be executed to bootstrap a workflow.
Parameter options
Options.
Returns
Job steps

method runTaskCommand

runTaskCommand: (task: Task) => string;

Returns the shell command to execute in order to run a task. This will typically be npx projen TASK.
Parameter task
The task for which the command is required

method setScript

setScript: (name: string, command: string) => void;

Replaces the contents of an npm package.json script.
Parameter name
The script name
Parameter command
The command to execute

class NpmConfig

class NpmConfig extends Component {}

File representing the local NPM config in .npmrc

constructor

constructor(project: NodeProject, options?: NpmConfigOptions);

method addConfig

addConfig: (name: string, value: string) => void;

configure a generic property
Parameter name
the name of the property
Parameter value
the value of the property

method addRegistry

addRegistry: (url: string, scope?: string) => void;

configure a scoped registry
Parameter url
the URL of the registry to use
Parameter scope
the scope the registry is used for; leave empty for the default registry

constructor

constructor(project: NodeProject, options: PrettierOptions);

property settings

readonly settings: PrettierSettings;

Direct access to the prettier settings

method addIgnorePattern

addIgnorePattern: (pattern: string) => void;

Defines Prettier ignore Patterns these patterns will be added to the file .prettierignore
Parameter pattern
filepatterns so exclude from prettier formatting

method addOverride

addOverride: (override: PrettierOverride) => void;

Add a prettier override
Parameter override
See Also
- https://prettier.io/docs/en/configuration.html#configuration-overrides

method of

static of: (project: Project) => Prettier | undefined;

method preSynthesize

preSynthesize: () => void;

class Projenrc

class Projenrc extends ProjenrcFile {}

A projenrc file written in JavaScript
This component can be instantiated in any type of project and has no expectations around the project's main language.

constructor

constructor(project: Project, options?: ProjenrcOptions);

property filePath

readonly filePath: string;

method preSynthesize

preSynthesize: () => void;

class Transform

class Transform {}

constructor

constructor(name: string, options?: any);

class TypescriptConfig

class TypescriptConfig extends Component {}

constructor

constructor(project: Project, options: TypescriptConfigOptions);

property compilerOptions

readonly compilerOptions?: TypeScriptCompilerOptions;

property exclude

readonly exclude: string[];

property extends

readonly extends: string[];

Array of base tsconfig.json paths. Any absolute paths are resolved relative to this instance, while any relative paths are used as is.

property file

readonly file: JsonFile;

property fileName

readonly fileName: string;

property include

readonly include: string[];

method addExclude

addExclude: (pattern: string) => void;

Add an exclude pattern to the exclude array of the TSConfig.
Parameter pattern
The pattern to add.
See Also
- https://www.typescriptlang.org/tsconfig#exclude

method addExtends

addExtends: (value: TypescriptConfig) => void;

Extend from base TypescriptConfig instance.
Parameter value
Base TypescriptConfig instance.
Remarks
TypeScript 5.0+ is required to extend from more than one base TypescriptConfig.

method addInclude

addInclude: (pattern: string) => void;

Add an include pattern to the include array of the TSConfig.
Parameter pattern
The pattern to add.
See Also
- https://www.typescriptlang.org/tsconfig#include

method preSynthesize

preSynthesize: () => void;

method removeExclude

removeExclude: (pattern: string) => void;

Remove an exclude pattern from the exclude array of the TSConfig.
Parameter pattern
The pattern to remove.
See Also
- https://www.typescriptlang.org/tsconfig#exclude

method removeInclude

removeInclude: (pattern: string) => void;

Remove an include pattern from the include array of the TSConfig.
Parameter pattern
The pattern to remove.
See Also
- https://www.typescriptlang.org/tsconfig#include

method resolveExtendsPath

resolveExtendsPath: (configPath: string) => string;

Resolve valid TypeScript extends paths relative to this config.
Parameter configPath
Path to resolve against.
Remarks
This will only resolve the relative path from this config to another given an absolute path as input. Any non-absolute path or other string will be returned as is. This is to preserve manually specified relative paths as well as npm import paths.

class TypescriptConfigExtends

class TypescriptConfigExtends {}

Container for TypescriptConfig tsconfig.json base configuration(s). Extending from more than one base config file requires TypeScript 5.0+.

method fromPaths

static fromPaths: (paths: string[]) => TypescriptConfigExtends;

Factory for creation from array of file paths.
Parameter paths
Absolute or relative paths to base tsconfig.json files.
Remarks
TypeScript 5.0+ is required to specify more than one value in paths.

method fromTypescriptConfigs

static fromTypescriptConfigs: (
    configs: TypescriptConfig[]
) => TypescriptConfigExtends;

Factory for creation from array of other TypescriptConfig instances.
Parameter configs
Base TypescriptConfig instances.
Remarks
TypeScript 5.0+ is required to specify more than on value in configs.

method toJSON

toJSON: () => string[];

constructor

constructor(project: NodeProject, options?: UpgradeDependenciesOptions);

property containerOptions

containerOptions?: workflows.ContainerOptions;

Container definitions for the upgrade workflow.

property workflows

readonly workflows: GithubWorkflow[];

The workflows that execute the upgrades. One workflow per branch.

method addPostBuildSteps

addPostBuildSteps: (...steps: JobStep[]) => void;

Add steps to execute a successful build.
Parameter steps
workflow steps

class UpgradeDependenciesSchedule

class UpgradeDependenciesSchedule {}

How often to check for new versions and raise pull requests for version upgrades.

property cron

readonly cron: string[];

property DAILY

static readonly DAILY: UpgradeDependenciesSchedule;

At 00:00.

property MONTHLY

static readonly MONTHLY: UpgradeDependenciesSchedule;

At 00:00 on day-of-month 1.

property NEVER

static readonly NEVER: UpgradeDependenciesSchedule;

Disables automatic upgrades.

property WEEKDAY

static readonly WEEKDAY: UpgradeDependenciesSchedule;

At 00:00 on every day-of-week from Monday through Friday.

property WEEKLY

static readonly WEEKLY: UpgradeDependenciesSchedule;

At 00:00 on Monday.

method expressions

static expressions: (cron: string[]) => UpgradeDependenciesSchedule;

Create a schedule from a raw cron expression.

class WatchPlugin

class WatchPlugin {}

constructor

constructor(name: string, options?: any);

class Yarnrc

class Yarnrc extends Component {}

constructor

constructor(project: Project, version: string, options?: YarnrcOptions);

interface AddBundleOptions

interface AddBundleOptions extends BundlingOptions {}

Options for addBundle().

readonly banner?: string;

Use this to insert an arbitrary string at the beginning of generated JavaScript files.
This is similar to footer which inserts at the end instead of the beginning.
This is commonly used to insert comments:
- no comments are passed

property charset

readonly charset?: Charset;

The charset to use for esbuild's output.
By default esbuild's output is ASCII-only. Any non-ASCII characters are escaped using backslash escape sequences. Using escape sequences makes the generated output slightly bigger, and also makes it harder to read. If you would like for esbuild to print the original characters without using escape sequences, use Charset.UTF8.
See Also
- https://esbuild.github.io/api/#charset Charset.ASCII

property define

readonly define?: {
    [key: string]: string;
};

Replace global identifiers with constant expressions.
For example, { 'process.env.DEBUG': 'true' }.
Another example, { 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }.
- no replacements are made

property esbuildArgs

readonly esbuildArgs?: {
    [key: string]: string | boolean;
};

Build arguments to pass into esbuild.

For example, to add the [--log-limit](https://esbuild.github.io/api/#log-limit) flag:

project.bundler.addBundle("./src/hello.ts", {
  platform: "node",
  target: "node18",
  sourcemap: true,
  format: "esm",
  esbuildArgs: {
    "--log-limit": "0",
  },
});

- no additional esbuild arguments are passed

property executable

readonly executable?: boolean;

Mark the output file as executable. false

readonly footer?: string;

Use this to insert an arbitrary string at the end of generated JavaScript files.
This is similar to banner which inserts at the beginning instead of the end.
This is commonly used to insert comments
- no comments are passed

property format

readonly format?: string;

Output format for the generated JavaScript files. There are currently three possible values that can be configured: "iife", "cjs", and "esm".
If not set (undefined), esbuild picks an output format for you based on platform: - "cjs" if platform is "node" - "iife" if platform is "browser" - "esm" if platform is "neutral"
Note: If making a bundle to run under node with ESM, set format to "esm" instead of setting platform to "neutral".
undefined
See Also
- https://esbuild.github.io/api/#format

property inject

readonly inject?: string[];

This option allows you to automatically replace a global variable with an import from another file.
See Also
- https://esbuild.github.io/api/#inject - no code is injected

property keepNames

readonly keepNames?: boolean;

Whether to preserve the original name values even in minified code.
In JavaScript the name property on functions and classes defaults to a nearby identifier in the source code.
However, minification renames symbols to reduce code size and bundling sometimes need to rename symbols to avoid collisions. That changes value of the name property for many of these cases. This is usually fine because the name property is normally only used for debugging. However, some frameworks rely on the name property for registration and binding purposes. If this is the case, you can enable this option to preserve the original name values even in minified code.
false

property loaders

readonly loaders?: {
    [key: string]: string;
};

Map of file extensions (without dot) and loaders to use for this file type. Loaders are appended to the esbuild command by --loader:.extension=loader

property logLevel

readonly logLevel?: BundleLogLevel;

Log level for esbuild. This is also propagated to the package manager and applies to its specific install command.
LogLevel.WARNING

property mainFields

readonly mainFields?: string[];

How to determine the entry point for modules. Try ['module', 'main'] to default to ES module versions.
[]

property metafile

readonly metafile?: boolean;

This option tells esbuild to write out a JSON file relative to output directory with metadata about the build.
The metadata in this JSON file follows this schema (specified using TypeScript syntax):
{ outputs: { [path: string]: { bytes: number inputs: { [path: string]: { bytesInOutput: number } } imports: { path: string }[] exports: string[] } } }
This data can then be analyzed by other tools. For example, bundle buddy can consume esbuild's metadata format and generates a treemap visualization of the modules in your bundle and how much space each one takes up.
See Also
- https://esbuild.github.io/api/#metafile false

property minify

readonly minify?: boolean;

Whether to minify files when bundling.
false

property outfile

readonly outfile?: string;

Bundler output path relative to the asset's output directory. "index.js"

property platform

readonly platform: string;

esbuild platform.
Example 1
"node"

property sourceMapMode

readonly sourceMapMode?: SourceMapMode;

Source map mode to be used when bundling.
See Also
- https://esbuild.github.io/api/#sourcemap
  SourceMapMode.DEFAULT

property sourcesContent

readonly sourcesContent?: boolean;

Whether to include original source code in source maps when bundling.
See Also
- https://esbuild.github.io/api/#sources-content
  true

property target

readonly target: string;

esbuild target.
Example 1
"node12"

property tsconfigPath

readonly tsconfigPath?: string;

The path of the tsconfig.json file to use for bundling "tsconfig.json"

interface BuildWorkflowOptions

interface BuildWorkflowOptions extends BuildWorkflowCommonOptions {}

Build workflow options for NodeProject

property mutableBuild

readonly mutableBuild?: boolean;

Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
true

interface Bundle

interface Bundle {}

property outdir

readonly outdir: string;

Base directory containing the output file (relative to project root).

property outfile

readonly outfile: string;

Location of the output file (relative to project root).

property addToPreCompile

readonly addToPreCompile?: boolean;

Install the bundle command as a pre-compile phase.
true
Deprecated
Use runBundleTask instead.

property assetsDir

readonly assetsDir?: string;

Output directory for all bundles. "assets"

property esbuildVersion

readonly esbuildVersion?: string;

The semantic version requirement for esbuild.
- no specific version (implies latest)

property loaders

readonly loaders?: {
    [key: string]: string;
};

Map of file extensions (without dot) and loaders to use for this file type. Loaders are appended to the esbuild command by --loader:.extension=loader

property runBundleTask

readonly runBundleTask?: RunBundleTask;

Choose which phase (if any) to add the bundle command to.
Note: If using addBundle() with the bundleCompiledResults, this option must be set to RunBundleTask.POST_COMPILE or RunBundleTask.MANUAL.
See Also
- AddBundleOptions.bundleCompiledResults
  RunBundleTask.PRE_COMPILE

property externals

readonly externals?: string[];

You can mark a file or a package as external to exclude it from your build. Instead of being bundled, the import will be preserved (using require for the iife and cjs formats and using import for the esm format) and will be evaluated at run time instead.
This has several uses. First of all, it can be used to trim unnecessary code from your bundle for a code path that you know will never be executed. For example, a package may contain code that only runs in node but you will only be using that package in the browser. It can also be used to import code in node at run time from a package that cannot be bundled. For example, the fsevents package contains a native extension, which esbuild doesn't support.
[]

property sourcemap

readonly sourcemap?: boolean;

Include a source map in the bundle.
false

property watchTask

readonly watchTask?: boolean;

In addition to the bundle:xyz task, creates bundle:xyz:watch task which will invoke the same esbuild command with the --watch flag. This can be used to continusouly watch for changes.
true

interface CodeArtifactOptions

interface CodeArtifactOptions {}

Options for publishing npm packages to AWS CodeArtifact.

property accessKeyIdSecret

readonly accessKeyIdSecret?: string;

GitHub secret which contains the AWS access key ID to use when publishing packages to AWS CodeArtifact. This property must be specified only when publishing to AWS CodeArtifact (npmRegistryUrl contains AWS CodeArtifact URL).
- When the authProvider value is set to CodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR, the default is "AWS_ACCESS_KEY_ID". For CodeArtifactAuthProvider.GITHUB_OIDC, this value must be left undefined.

property authProvider

readonly authProvider?: CodeArtifactAuthProvider;

Provider to use for authorizing requests to AWS CodeArtifact.
CodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR

property roleToAssume

readonly roleToAssume?: string;

ARN of AWS role to be assumed prior to get authorization token from AWS CodeArtifact This property must be specified only when publishing to AWS CodeArtifact (registry contains AWS CodeArtifact URL). When using the CodeArtifactAuthProvider.GITHUB_OIDC auth provider, this value must be defined.
undefined

property secretAccessKeySecret

readonly secretAccessKeySecret?: string;

GitHub secret which contains the AWS secret access key to use when publishing packages to AWS CodeArtifact. This property must be specified only when publishing to AWS CodeArtifact (npmRegistryUrl contains AWS CodeArtifact URL).
- When the authProvider value is set to CodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR, the default is "AWS_SECRET_ACCESS_KEY". For CodeArtifactAuthProvider.GITHUB_OIDC, this value must be left undefined.

interface CoverageThreshold

interface CoverageThreshold {}

property branches

readonly branches?: number;

property functions

readonly functions?: number;

property lines

readonly lines?: number;

property statements

readonly statements?: number;

interface EslintCommandOptions

interface EslintCommandOptions {}

property extraArgs

readonly extraArgs?: string[];

Extra flag arguments to pass to eslint command

property fix

readonly fix?: boolean;

Whether to fix eslint issues when running the eslint task true

interface EslintOptions

interface EslintOptions {}

property aliasExtensions

readonly aliasExtensions?: string[];

Enable import alias for module paths undefined

property aliasMap

readonly aliasMap?: {
    [key: string]: string;
};

Enable import alias for module paths undefined

property commandOptions

readonly commandOptions?: EslintCommandOptions;

Options for eslint command executed by eslint task

property devdirs

readonly devdirs?: string[];

Files or glob patterns or directories with source files that include tests and build tools
These sources are linted but may also import packages from devDependencies. []

property dirs

readonly dirs: string[];

Files or glob patterns or directories with source files to lint (e.g. [ "src" ])

property fileExtensions

readonly fileExtensions?: string[];

File types that should be linted (e.g. [ ".js", ".ts" ]) [".ts"]

property ignorePatterns

readonly ignorePatterns?: string[];

List of file patterns that should not be linted, using the same syntax as .gitignore patterns.
[ '*.js', '*.d.ts', 'node_modules/', '*.generated.ts', 'coverage' ]

property lintProjenRc

readonly lintProjenRc?: boolean;

Should we lint .projenrc.js
true
Deprecated
set to false to remove any automatic rules and add manually

property lintProjenRcFile

readonly lintProjenRcFile?: string;

Projenrc file to lint. Use empty string to disable. "projenrc.js"
Deprecated
provide as devdirs

property prettier

readonly prettier?: boolean;

Enable prettier for code formatting false

property sortExtends

readonly sortExtends?: ICompareString;

The extends array in eslint is order dependent. This option allows to sort the extends array in any way seen fit.
- Use known ESLint best practices to place "prettier" plugins at the end of the array

property tsAlwaysTryTypes

readonly tsAlwaysTryTypes?: boolean;

Always try to resolve types under <root>@types directory even it doesn't contain any source code. This prevents import/no-unresolved eslint errors when importing a @types/* module that would otherwise remain unresolved. true

property tsconfigPath

readonly tsconfigPath?: string;

Path to tsconfig.json which should be used by eslint. "./tsconfig.json"

property yaml

readonly yaml?: boolean;

Write eslint configuration as YAML instead of JSON false

property excludedFiles

readonly excludedFiles?: string[];

Pattern(s) to exclude from this override. If a file matches any of the excluded patterns, the configuration won’t apply.

property extends

readonly extends?: string[];

Config(s) to extend in this override

property files

readonly files: string[];

Files or file patterns on which to apply the override

property parser

readonly parser?: string;

The overridden parser

property plugins

readonly plugins?: string[];

plugins override

property rules

readonly rules?: {
    [rule: string]: any;
};

The overridden rules

interface HasteConfig

interface HasteConfig {}

property computeSha1

readonly computeSha1?: boolean;

property defaultPlatform

readonly defaultPlatform?: string | undefined;

property hasteImplModulePath

readonly hasteImplModulePath?: string;

property platforms

readonly platforms?: Array<string>;

property throwOnModuleCollision

readonly throwOnModuleCollision?: boolean;

interface JestConfigOptions

interface JestConfigOptions {}

property automock

readonly automock?: boolean;

This option tells Jest that all imported modules in your tests should be mocked automatically. All modules used in your tests will have a replacement implementation, keeping the API surface - false

property bail

readonly bail?: boolean | number;

By default, Jest runs all tests and produces all errors into the console upon completion. The bail config option can be used here to have Jest stop running tests after n failures. Setting bail to true is the same as setting bail to 1. - 0

property cacheDirectory

readonly cacheDirectory?: string;

The directory where Jest should store its cached dependency information - "/tmp/"

property clearMocks

readonly clearMocks?: boolean;

Automatically clear mock calls and instances before every test. Equivalent to calling jest.clearAllMocks() before each test. This does not remove any mock implementation that may have been provided true

property collectCoverage

readonly collectCoverage?: boolean;

Indicates whether the coverage information should be collected while executing the test. Because this retrofits all executed files with coverage collection statements, it may significantly slow down your tests true

property collectCoverageFrom

readonly collectCoverageFrom?: string[];

An array of glob patterns indicating a set of files for which coverage information should be collected. - undefined

property coverageDirectory

readonly coverageDirectory?: string;

The directory where Jest should output its coverage files. "coverage"

property coveragePathIgnorePatterns

readonly coveragePathIgnorePatterns?: string[];

An array of regexp pattern strings that are matched against all file paths before executing the test. If the file path matches any of the patterns, coverage information will be skipped "/node_modules/"

property coverageProvider

readonly coverageProvider?: 'babel' | 'v8';

Indicates which provider should be used to instrument code for coverage. Allowed values are v8 (default) or babel - "v8"

property coverageReporters

readonly coverageReporters?: string[];

A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used - ["json", "lcov", "text", "clover", "cobertura"]

property coverageThreshold

readonly coverageThreshold?: CoverageThreshold;

Specify the global coverage thresholds. This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as global, as a glob, and as a directory or file path. If thresholds aren't met, jest will fail. - undefined

property dependencyExtractor

readonly dependencyExtractor?: string;

This option allows the use of a custom dependency extractor. It must be a node module that exports an object with an extract function - undefined

property displayName

readonly displayName?: string | any;

Allows for a label to be printed alongside a test while it is running. - undefined

property errorOnDeprecated

readonly errorOnDeprecated?: boolean;

Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process. - false

property extraGlobals

readonly extraGlobals?: string[];

Test files run inside a vm, which slows calls to global context properties (e.g. Math). With this option you can specify extra properties to be defined inside the vm for faster lookups. - undefined

property forceCoverageMatch

readonly forceCoverageMatch?: string[];

Test files are normally ignored from collecting code coverage. With this option, you can overwrite this behavior and include otherwise ignored files in code coverage. - ['']

property globals

readonly globals?: any;

A set of global variables that need to be available in all test environments. - {}

property globalSetup

readonly globalSetup?: string;

This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites. This function gets Jest's globalConfig object as a parameter. - undefined

property globalTeardown

readonly globalTeardown?: string;

This option allows the use of a custom global teardown module which exports an async function that is triggered once after all test suites. This function gets Jest's globalConfig object as a parameter. - undefined

property haste

readonly haste?: HasteConfig;

This will be used to configure the behavior of jest-haste-map, Jest's internal file crawler/cache system. - {}

property injectGlobals

readonly injectGlobals?: boolean;

Insert Jest's globals (expect, test, describe, beforeEach etc.) into the global environment. If you set this to false, you should import from @jest/globals - true

property maxConcurrency

readonly maxConcurrency?: number;

A number limiting the number of tests that are allowed to run at the same time when using test.concurrent. Any test above this limit will be queued and executed once a slot is released. - 5

property maxWorkers

readonly maxWorkers?: number | string;

Specifies the maximum number of workers the worker-pool will spawn for running tests. In single run mode, this defaults to the number of the cores available on your machine minus one for the main thread In watch mode, this defaults to half of the available cores on your machine. For environments with variable CPUs available, you can use percentage based configuration: "maxWorkers": "50%" - the number of the cores available on your machine minus one for the main thread

property moduleDirectories

readonly moduleDirectories?: string[];

An array of directory names to be searched recursively up from the requiring module's location. Setting this option will override the default, if you wish to still search node_modules for packages include it along with any other options: ["node_modules", "bower_components"] - ["node_modules"]

property moduleFileExtensions

readonly moduleFileExtensions?: string[];

An array of file extensions your modules use. If you require modules without specifying a file extension, these are the extensions Jest will look for, in left-to-right order. - ["js", "json", "jsx", "ts", "tsx", "node"]

property moduleNameMapper

readonly moduleNameMapper?: {
    [key: string]: string | string[];
};

A map from regular expressions to module names or to arrays of module names that allow to stub out resources, like images or styles with a single module. - null

property modulePathIgnorePatterns

readonly modulePathIgnorePatterns?: string[];

An array of regexp pattern strings that are matched against all module paths before those paths are to be considered 'visible' to the module loader. If a given module's path matches any of the patterns, it will not be require()-able in the test environment. - []

property modulePaths

readonly modulePaths?: string[];

An alternative API to setting the NODE_PATH env variable, modulePaths is an array of absolute paths to additional locations to search when resolving modules. Use the string token to include the path to your project's root directory. Example: ["/app/"]. - []

property notify

readonly notify?: boolean;

Activates notifications for test results. - false

property notifyMode

readonly notifyMode?:
    | 'always'
    | 'failure'
    | 'success'
    | 'change'
    | 'success-change'
    | 'failure-change';

Specifies notification mode. Requires notify: true - failure-change

property preset

readonly preset?: string;

A preset that is used as a base for Jest's configuration. A preset should point to an npm module that has a jest-preset.json or jest-preset.js file at the root. - undefined

property prettierPath

readonly prettierPath?: string;

Sets the path to the prettier node module used to update inline snapshots. - "prettier"

property projects

readonly projects?: Array<
    | string
    | {
          [key: string]: any;
      }
>;

When the projects configuration is provided with an array of paths or glob patterns, Jest will run tests in all of the specified projects at the same time. This is great for monorepos or when working on multiple projects at the same time. - undefined

property reporters

readonly reporters?: JestReporter[];

Use this configuration option to add custom reporters to Jest. A custom reporter is a class that implements onRunStart, onTestStart, onTestResult, onRunComplete methods that will be called when any of those events occurs. - undefined

property resetMocks

readonly resetMocks?: boolean;

Automatically reset mock state before every test. Equivalent to calling jest.resetAllMocks() before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation. - false

property resetModules

readonly resetModules?: boolean;

By default, each test file gets its own independent module registry. Enabling resetModules goes a step further and resets the module registry before running each individual test. - false

property resolver

readonly resolver?: string;

This option allows the use of a custom resolver. https://jestjs.io/docs/en/configuration#resolver-string - undefined

property restoreMocks

readonly restoreMocks?: boolean;

Automatically restore mock state before every test. Equivalent to calling jest.restoreAllMocks() before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation. - false

property rootDir

readonly rootDir?: string;

The root directory that Jest should scan for tests and modules within. If you put your Jest config inside your package.json and want the root directory to be the root of your repo, the value for this config param will default to the directory of the package.json. - directory of the package.json

property roots

readonly roots?: string[];

A list of paths to directories that Jest should use to search for files in. - [""]

property runner

readonly runner?: string;

This option allows you to use a custom runner instead of Jest's default test runner. - "jest-runner"

property setupFiles

readonly setupFiles?: string[];

A list of paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. Since every test runs in its own environment, these scripts will be executed in the testing environment immediately before executing the test code itself. - []

property setupFilesAfterEnv

readonly setupFilesAfterEnv?: string[];

A list of paths to modules that run some code to configure or set up the testing framework before each test file in the suite is executed. Since setupFiles executes before the test framework is installed in the environment, this script file presents you the opportunity of running some code immediately after the test framework has been installed in the environment. - []

property slowTestThreshold

readonly slowTestThreshold?: number;

The number of seconds after which a test is considered as slow and reported as such in the results. - 5

property snapshotResolver

readonly snapshotResolver?: string;

The path to a module that can resolve test<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. - undefined

property snapshotSerializers

readonly snapshotSerializers?: string[];

A list of paths to snapshot serializer modules Jest should use for snapshot testing. = []

property testEnvironment

readonly testEnvironment?: string;

The test environment that will be used for testing. The default environment in Jest is a browser-like environment through jsdom. If you are building a node service, you can use the node option to use a node-like environment instead. - "jsdom"

property testEnvironmentOptions

readonly testEnvironmentOptions?: any;

Test environment options that will be passed to the testEnvironment. The relevant options depend on the environment. - {}

property testFailureExitCode

readonly testFailureExitCode?: number;

The exit code Jest returns on test failure. - 1

property testMatch

readonly testMatch?: string[];

The glob patterns Jest uses to detect test files. By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). It will also find files called test.js or spec.js. ['**/__tests__/**/*.[jt]s?(x)', '**/*(*.)@(spec|test).[tj]s?(x)']

property testPathIgnorePatterns

readonly testPathIgnorePatterns?: string[];

An array of regexp pattern strings that are matched against all test paths before executing the test. If the test path matches any of the patterns, it will be skipped. - ["/node_modules/"]

property testRegex

readonly testRegex?: string | string[];

The pattern or patterns Jest uses to detect test files. By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). It will also find files called test.js or spec.js. - (/__tests__/.*|(\.|/)(test|spec))\.[jt]sx?$

property testResultsProcessor

readonly testResultsProcessor?: string;

This option allows the use of a custom results processor. - undefined

property testRunner

readonly testRunner?: string;

This option allows the use of a custom test runner. The default is jasmine2. A custom test runner can be provided by specifying a path to a test runner implementation. - "jasmine2"

property testSequencer

readonly testSequencer?: string;

This option allows you to use a custom sequencer instead of Jest's default. Sort may optionally return a Promise. - "@jest/test-sequencer"

property testTimeout

readonly testTimeout?: number;

Default timeout of a test in milliseconds. - 5000

property testURL

readonly testURL?: string;

This option sets the URL for the jsdom environment. It is reflected in properties such as location.href. - "http://localhost"

property timers

readonly timers?: string;

Setting this value to legacy or fake allows the use of fake timers for functions such as setTimeout. Fake timers are useful when a piece of code sets a long timeout that we don't want to wait for in a test. - "real"

property transform

readonly transform?: {
    [key: string]: Transform;
};

A map from regular expressions to paths to transformers. A transformer is a module that provides a synchronous function for transforming source files. - {"\.[jt]sx?$": "babel-jest"}

property transformIgnorePatterns

readonly transformIgnorePatterns?: string[];

An array of regexp pattern strings that are matched against all source file paths before transformation. If the test path matches any of the patterns, it will not be transformed. - ["/node_modules/", "\.pnp\.[^\/]+$"]

property unmockedModulePathPatterns

readonly unmockedModulePathPatterns?: string[];

An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them. If a module's path matches any of the patterns in this list, it will not be automatically mocked by the module loader. - []

property verbose

readonly verbose?: boolean;

Indicates whether each individual test should be reported during the run. All errors will also still be shown on the bottom after execution. Note that if there is only one test file being run it will default to true. - false

property watchman

readonly watchman?: boolean;

Whether to use watchman for file crawling. - true

property watchPathIgnorePatterns

readonly watchPathIgnorePatterns?: string[];

An array of RegExp patterns that are matched against all source file paths before re-running tests in watch mode. If the file path matches any of the patterns, when it is updated, it will not trigger a re-run of tests. - []

property watchPlugins

readonly watchPlugins?: WatchPlugin[];

index signature

readonly [name: string]: any;

Escape hatch to allow any value (JS/TS only)
Deprecated
use additionalOptions instead.
ignore

interface JestDiscoverTestMatchPatternsForDirsOptions

interface JestDiscoverTestMatchPatternsForDirsOptions {}

Options for discoverTestMatchPatternsForDirs.

property fileExtensionPattern

readonly fileExtensionPattern?: string;

The file extension pattern to use. Defaults to "[jt]s?(x)".

interface JestOptions

interface JestOptions {}

property configFilePath

readonly configFilePath?: string;

Path to JSON config file for Jest
- No separate config file, jest settings are stored in package.json

property coverage

readonly coverage?: boolean;

Collect coverage. Deprecated true
Deprecated
use jestConfig.collectCoverage

property coverageText

readonly coverageText?: boolean;

Include the text coverage reporter, which means that coverage summary is printed at the end of the jest execution.
true

property extraCliOptions

readonly extraCliOptions?: string[];

Additional options to pass to the Jest CLI invocation - no extra options

property ignorePatterns

readonly ignorePatterns?: string[];

Defines testPathIgnorePatterns and coveragePathIgnorePatterns ["/node_modules/"]
Deprecated
use jestConfig.coveragePathIgnorePatterns or jestConfig.testPathIgnorePatterns respectively

property jestConfig

readonly jestConfig?: JestConfigOptions;

Jest configuration. - default jest configuration

property jestVersion

readonly jestVersion?: string;

The version of jest to use.
Note that same version is used as version of @types/jest and ts-jest (if Typescript in use), so given version should work also for those.
- installs the latest jest version

property junitReporting

readonly junitReporting?: boolean;

Result processing with jest-junit.
Output directory is test-reports/.
true

property preserveDefaultReporters

readonly preserveDefaultReporters?: boolean;

Preserve the default Jest reporter when additional reporters are added.
true

property updateSnapshot

readonly updateSnapshot?: UpdateSnapshot;

Whether to update snapshots in task "test" (which is executed in task "build" and build workflows), or create a separate task "test:update" for updating snapshots.
- ALWAYS

interface LicenseCheckerOptions

interface LicenseCheckerOptions {}

Options to configure the license checker

property allow

readonly allow?: string[];

List of SPDX license identifiers that are allowed to be used.
For the license check to pass, all detected licenses MUST be in this list. Only one of allowedLicenses and prohibitedLicenses can be provided and must not be empty. - no licenses are allowed

property deny

readonly deny?: string[];

List of SPDX license identifiers that are prohibited to be used.
For the license check to pass, no detected licenses can be in this list. Only one of allowedLicenses and prohibitedLicenses can be provided and must not be empty. - no licenses are prohibited

property taskName

readonly taskName?: string;

The name of the task that is added to check licenses
"check-licenses"

interface NodePackageOptions

interface NodePackageOptions {}

property allowLibraryDependencies

readonly allowLibraryDependencies?: boolean;

Allow the project to include peerDependencies and bundledDependencies. This is normally only allowed for libraries. For apps, there's no meaning for specifying these.
true

property autoDetectBin

readonly autoDetectBin?: boolean;

Automatically add all executables under the bin directory to your package.json file under the bin section.
true

property bin

readonly bin?: Record<string, string>;

Binary programs vended with your module.
You can use this option to add/customize how binaries are represented in your package.json, but unless autoDetectBin is false, every executable file under bin will automatically be added to this section.

property bugsEmail

readonly bugsEmail?: string;

The email address to which issues should be reported.

property bugsUrl

readonly bugsUrl?: string;

The url to your project's issue tracker.

property bundledDeps

readonly bundledDeps?: string[];

List of dependencies to bundle into this module. These modules will be added both to the dependencies section and bundledDependencies section of your package.json.
The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.

property bunVersion

readonly bunVersion?: string;

The version of Bun to use if using Bun as a package manager.
"latest"

property codeArtifactOptions

readonly codeArtifactOptions?: CodeArtifactOptions;

Options for npm packages using AWS CodeArtifact. This is required if publishing packages to, or installing scoped packages from AWS CodeArtifact
- undefined

property deps

readonly deps?: string[];

Runtime dependencies of this module.
The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.
Example 1
[ 'express', 'lodash', 'foo@^2' ] []

property description

readonly description?: string;

The description is just a string that helps people understand the purpose of the package. It can be used when searching for packages in a package manager as well. See https://classic.yarnpkg.com/en/docs/package-json/#toc-description

property devDeps

readonly devDeps?: string[];

Build dependencies for this module. These dependencies will only be available in your build environment but will not be fetched when this module is consumed.
The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.
Example 1
[ 'typescript', '@types/express' ] []

property entrypoint

readonly entrypoint?: string;

Module entrypoint (main in package.json)
Set to an empty string to not include main in your package.json
"lib/index.js"

property homepage

readonly homepage?: string;

Package's Homepage / Website

property keywords

readonly keywords?: string[];

Keywords to include in package.json.

property license

readonly license?: string;

License's SPDX identifier. See https://github.com/projen/projen/tree/main/license-text for a list of supported licenses. Use the licensed option if you want to no license to be specified.
"Apache-2.0"

property licensed

readonly licensed?: boolean;

Indicates if a license should be added.
true

property maxNodeVersion

readonly maxNodeVersion?: string;

The maximum node version supported by this package. Most projects should not use this option.
The value indicates that the package is incompatible with any newer versions of node. This requirement is enforced via the engines field.
You will normally not need to set this option. Consider this option only if your package is known to not function with newer versions of node.
- no maximum version is enforced

property minNodeVersion

readonly minNodeVersion?: string;

The minimum node version required by this package to function. Most projects should not use this option.
The value indicates that the package is incompatible with any older versions of node. This requirement is enforced via the engines field.
You will normally not need to set this option, even if your package is incompatible with EOL versions of node. Consider this option only if your package depends on a specific feature, that is not available in other LTS versions. Setting this option has very high impact on the consumers of your package, as package managers will actively prevent usage with node versions you have marked as incompatible.
To change the node version of your CI/CD workflows, use workflowNodeVersion.
- no minimum version is enforced

property npmAccess

readonly npmAccess?: NpmAccess;

Access level of the npm package.
- for scoped packages (e.g. foo@bar), the default is NpmAccess.RESTRICTED, for non-scoped packages, the default is NpmAccess.PUBLIC.

property npmProvenance

readonly npmProvenance?: boolean;

Should provenance statements be generated when the package is published.
A supported package manager is required to publish a package with npm provenance statements and you will need to use a supported CI/CD provider.
Note that the projen Release and Publisher components are using publib to publish packages, which is using npm internally and supports provenance statements independently of the package manager used.
See Also
- https://docs.npmjs.com/generating-provenance-statements - true for public packages, false otherwise

property npmRegistry

readonly npmRegistry?: string;

The host name of the npm registry to publish to. Cannot be set together with npmRegistryUrl.
Deprecated
use npmRegistryUrl instead

property npmRegistryUrl

readonly npmRegistryUrl?: string;

The base URL of the npm package registry.
Must be a URL (e.g. start with "https://" or "http://")
"https://registry.npmjs.org"

property npmTokenSecret

readonly npmTokenSecret?: string;

GitHub secret which contains the NPM token to use when publishing packages.
"NPM_TOKEN"

property packageManager

readonly packageManager?: NodePackageManager;

The Node Package Manager used to execute scripts
NodePackageManager.YARN_CLASSIC

property packageName

readonly packageName?: string;

The "name" in package.json - defaults to project name

property peerDependencyOptions

readonly peerDependencyOptions?: PeerDependencyOptions;

Options for peerDeps.

property peerDeps

readonly peerDeps?: string[];

Peer dependencies for this module. Dependencies listed here are required to be installed (and satisfied) by the _consumer_ of this library. Using peer dependencies allows you to ensure that only a single module of a certain library exists in the node_modules tree of your consumers.
Note that prior to npm@7, peer dependencies are _not_ automatically installed, which means that adding peer dependencies to a library will be a breaking change for your customers.
Unless peerDependencyOptions.pinnedDevDependency is disabled (it is enabled by default), projen will automatically add a dev dependency with a pinned version for each peer dependency. This will ensure that you build & test your module against the lowest peer version required.
[]

property pnpmVersion

readonly pnpmVersion?: string;

The version of PNPM to use if using PNPM as a package manager.
"9"

property repository

readonly repository?: string;

The repository is the location where the actual code for your package lives. See https://classic.yarnpkg.com/en/docs/package-json/#toc-repository

property repositoryDirectory

readonly repositoryDirectory?: string;

If the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.

property scopedPackagesOptions

readonly scopedPackagesOptions?: ScopedPackagesOptions[];

Options for privately hosted scoped packages
- fetch all scoped packages from the public npm registry

property scripts

readonly scripts?: {
    [name: string]: string;
};

npm scripts to include. If a script has the same name as a standard script, the standard script will be overwritten. Also adds the script as a task.
{}
Deprecated
use project.addTask() or package.setScript()

property yarnBerryOptions

readonly yarnBerryOptions?: YarnBerryOptions;

Options for Yarn Berry
- Yarn Berry v4 with all default options

interface NodeProjectOptions

interface NodeProjectOptions
    extends GitHubProjectOptions,
        NodePackageOptions,
        ReleaseProjectOptions {}

property artifactsDirectory

readonly artifactsDirectory?: string;

A directory which will contain build artifacts.
"dist"

property autoApproveUpgrades

readonly autoApproveUpgrades?: boolean;

Automatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).
Throw if set to true but autoApproveOptions are not defined.
- true

property buildWorkflow

readonly buildWorkflow?: boolean;

Define a GitHub workflow for building PRs. - true if not a subproject

property buildWorkflowTriggers

readonly buildWorkflowTriggers?: Triggers;

Build workflow triggers "{ pullRequest: {}, workflowDispatch: {} }"
Deprecated
- Use buildWorkflowOptions.workflowTriggers

property checkLicenses

readonly checkLicenses?: LicenseCheckerOptions;

Configure which licenses should be deemed acceptable for use by dependencies
This setting will cause the build to fail, if any prohibited or not allowed licenses ares encountered.
- no license checks are run during the build and all licenses will be accepted

property codeCov

readonly codeCov?: boolean;

Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v4 A secret is required for private repos. Configured with @codeCovTokenSecret false

property codeCovTokenSecret

readonly codeCovTokenSecret?: string;

Define the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories - if this option is not specified, only public repositories are supported

property copyrightOwner

readonly copyrightOwner?: string;

License copyright owner.
- defaults to the value of authorName or "" if authorName is undefined.

property copyrightPeriod

readonly copyrightPeriod?: string;

The copyright years to put in the LICENSE file.
- current year

property defaultReleaseBranch

readonly defaultReleaseBranch: string;

The name of the main release branch.
"main"

property dependabot

readonly dependabot?: boolean;

Use dependabot to handle dependency upgrades. Cannot be used in conjunction with depsUpgrade.
false

property dependabotOptions

readonly dependabotOptions?: DependabotOptions;

Options for dependabot.
- default options

property depsUpgrade

readonly depsUpgrade?: boolean;

Use tasks and github workflows to handle dependency upgrades. Cannot be used in conjunction with dependabot.
true

property depsUpgradeOptions

readonly depsUpgradeOptions?: UpgradeDependenciesOptions;

Options for UpgradeDependencies.
- default options

property jest

readonly jest?: boolean;

Setup jest unit tests true

property mutableBuild

readonly mutableBuild?: boolean;

Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
true
Deprecated
- Use buildWorkflowOptions.mutableBuild

property npmignore

readonly npmignore?: string[];

Additional entries to .npmignore.
Deprecated
- use project.addPackageIgnore

property npmignoreEnabled

readonly npmignoreEnabled?: boolean;

Defines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.
true

property npmIgnoreOptions

readonly npmIgnoreOptions?: IgnoreFileOptions;

Configuration options for .npmignore file

property package

readonly package?: boolean;

Defines a package task that will produce an npm tarball under the artifacts directory (e.g. dist).
true

property prettier

readonly prettier?: boolean;

Setup prettier.
false

property projenDevDependency

readonly projenDevDependency?: boolean;

Indicates of "projen" should be installed as a devDependency.
- true if not a subproject

property projenrcJs

readonly projenrcJs?: boolean;

Generate (once) .projenrc.js (in JavaScript). Set to false in order to disable .projenrc.js generation.
- true if projenrcJson is false

property projenrcJsOptions

readonly projenrcJsOptions?: ProjenrcOptions;

Options for .projenrc.js - default options

property projenVersion

readonly projenVersion?: string;

Version of projen to install.
- Defaults to the latest version.

property pullRequestTemplate

readonly pullRequestTemplate?: boolean;

Include a GitHub pull request template.
true

property pullRequestTemplateContents

readonly pullRequestTemplateContents?: string[];

The contents of the pull request template.
- default content

property release

readonly release?: boolean;

Add release management to this project.
- true (false for subprojects)

property releaseToNpm

readonly releaseToNpm?: boolean;

Automatically release to npm when new versions are introduced. false

property releaseWorkflow

readonly releaseWorkflow?: boolean;

DEPRECATED: renamed to release.
- true if not a subproject
Deprecated
see release.

property workflowBootstrapSteps

readonly workflowBootstrapSteps?: JobStep[];

Workflow steps to use in order to bootstrap this repo.
"yarn install --frozen-lockfile && yarn projen"

property workflowGitIdentity

readonly workflowGitIdentity?: GitIdentity;

The git identity to use in workflows.
- GitHub Actions

property workflowNodeVersion

readonly workflowNodeVersion?: string;

The node version used in GitHub Actions workflows.
Always use this option if your GitHub Actions workflows require a specific to run.
- minNodeVersion if set, otherwise lts/*.

property workflowPackageCache

readonly workflowPackageCache?: boolean;

Enable Node.js package cache in GitHub workflows.
false

interface NpmConfigOptions

interface NpmConfigOptions {}

Options to configure the local NPM config

property registry

readonly registry?: string;

URL of the registry mirror to use
You can change this or add scoped registries using the addRegistry method
- use npmjs default registry

interface PeerDependencyOptions

interface PeerDependencyOptions {}

property pinnedDevDependency

readonly pinnedDevDependency?: boolean;

Automatically add a pinned dev dependency. true

property ignoreFileOptions

readonly ignoreFileOptions?: IgnoreFileOptions;

Configuration options for .prettierignore file

property overrides

readonly overrides?: PrettierOverride[];

Provide a list of patterns to override prettier configuration.
[]
See Also
- https://prettier.io/docs/en/configuration.html#configuration-overrides

property settings

readonly settings?: PrettierSettings;

Prettier settings. - default settings

property yaml

readonly yaml?: boolean;

Write prettier configuration as YAML instead of JSON false

interface PrettierOverride

interface PrettierOverride {}

property files

readonly files: Files;

Include these files in this override.

property options

readonly options: PrettierSettings;

The options to apply for this override.

interface PrettierSettings

interface PrettierSettings {}

Options to set in Prettier directly or through overrides
See Also
- https://prettier.io/docs/en/options.html

property arrowParens

readonly arrowParens?: ArrowParens;

Include parentheses around a sole arrow function parameter.
ArrowParens.ALWAYS

property bracketSameLine

readonly bracketSameLine?: boolean;

Put > of opening tags on the last line instead of on a new line.
false

property cursorOffset

readonly cursorOffset?: number;

Print (to stderr) where a cursor at the given position would move to after formatting. This option cannot be used with --range-start and --range-end.
-1

property embeddedLanguageFormatting

readonly embeddedLanguageFormatting?: EmbeddedLanguageFormatting;

Control how Prettier formats quoted code embedded in the file.
EmbeddedLanguageFormatting.AUTO

property endOfLine

readonly endOfLine?: EndOfLine;

Which end of line characters to apply.
EndOfLine.LF

property filepath

readonly filepath?: string;

Specify the input filepath. This will be used to do parser inference. none

property htmlWhitespaceSensitivity

readonly htmlWhitespaceSensitivity?: HTMLWhitespaceSensitivity;

How to handle whitespaces in HTML.
HTMLWhitespaceSensitivity.CSS

property insertPragma

readonly insertPragma?: boolean;

Insert pragma into file's first docblock comment.
false

property parser

readonly parser?: string;

Which parser to use.
- Prettier automatically infers the parser from the input file path, so you shouldn’t have to change this setting.

property plugins

readonly plugins?: string[];

Add a plugin. Multiple plugins can be passed as separate --plugins.
[]

property pluginSearchDirs

readonly pluginSearchDirs?: string[];

Custom directory that contains prettier plugins in node_modules subdirectory. Overrides default behavior when plugins are searched relatively to the location of Prettier. Multiple values are accepted.
[]

property printWidth

readonly printWidth?: number;

The line length where Prettier will try wrap.
80

property quoteProps

readonly quoteProps?: QuoteProps;

Change when properties in objects are quoted.
QuoteProps.ASNEEDED

property rangeEnd

readonly rangeEnd?: number;

Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. This option cannot be used with --cursor-offset.
null

property rangeStart

readonly rangeStart?: number;

Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. This option cannot be used with --cursor-offset.
0

property requirePragma

readonly requirePragma?: boolean;

Require either '@prettier' or '@format' to be present in the file's first docblock comment in order for it to be formatted.
false

property semi

readonly semi?: boolean;

Print semicolons.
true

property singleQuote

readonly singleQuote?: boolean;

Use single quotes instead of double quotes.
false

property tabWidth

readonly tabWidth?: number;

Number of spaces per indentation level.
2

property trailingComma

readonly trailingComma?: TrailingComma;

Print trailing commas wherever possible when multi-line.
TrailingComma.ES5

property useTabs

readonly useTabs?: boolean;

Indent with tabs instead of spaces.
false

property vueIndentScriptAndStyle

readonly vueIndentScriptAndStyle?: boolean;

Indent script and style tags in Vue files.
false

interface ProjenrcOptions

interface ProjenrcOptions {}

property filename

readonly filename?: string;

The name of the projenrc file. ".projenrc.js"

interface RenderWorkflowSetupOptions

interface RenderWorkflowSetupOptions {}

Options for renderWorkflowSetup().

property installStepConfiguration

readonly installStepConfiguration?: JobStepConfiguration;

Configure the install step in the workflow setup.
- { name: "Install dependencies" }
Example 1
- { workingDirectory: "rootproject-dir" } for subprojects installing from root.
Example 2
- { env: { NPM_TOKEN: "token" }} for installing from private npm registry.

property mutable

readonly mutable?: boolean;

Should the package lockfile be updated? false

interface ScopedPackagesOptions

interface ScopedPackagesOptions {}

Options for scoped packages

property scope

readonly scope: string;

Scope of the packages
Example 1
"@angular"

interface TypeScriptCompilerOptions

interface TypeScriptCompilerOptions {}

property allowArbitraryExtensions

readonly allowArbitraryExtensions?: boolean;

Suppress arbitrary extension import errors with the assumption that a bundler will be handling it.
See Also
- https://www.typescriptlang.org/tsconfig#allowArbitraryExtensions undefined

property allowImportingTsExtensions

readonly allowImportingTsExtensions?: boolean;

Allows TypeScript files to import each other with TypeScript-specific extensions (.ts, .mts, .tsx). Requires noEmit or emitDeclarationOnly.
undefined

property allowJs

readonly allowJs?: boolean;

Allow JavaScript files to be compiled.
false

property allowSyntheticDefaultImports

readonly allowSyntheticDefaultImports?: boolean;

Allow default imports from modules with no default export. This does not affect code emit, just typechecking.

property allowUnreachableCode

readonly allowUnreachableCode?: boolean;

Allow Unreachable Code
When:
- undefined (default) provide suggestions as warnings to editors - true unreachable code is ignored - false raises compiler errors about unreachable code
These warnings are only about code which is provably unreachable due to the use of JavaScript syntax.
See Also
- https://www.typescriptlang.org/tsconfig#allowUnreachableCode

property allowUnusedLabels

readonly allowUnusedLabels?: boolean;

Allow Unused Labels
When:
- undefined (default) provide suggestions as warnings to editors - true unused labels are ignored - false raises compiler errors about unused labels
Labels are very rare in JavaScript and typically indicate an attempt to write an object literal:
function verifyAge(age: number) { // Forgot 'return' statement if (age > 18) { verified: true; // ^^^^^^^^ Unused label. } }
See Also
- https://www.typescriptlang.org/tsconfig#allowUnusedLabels

property alwaysStrict

readonly alwaysStrict?: boolean;

Ensures that your files are parsed in the ECMAScript strict mode, and emit “use strict” for each source file.
true

property baseUrl

readonly baseUrl?: string;

Lets you set a base directory to resolve non-absolute module names.
You can define a root folder where you can do absolute file resolution.

property checkJs

readonly checkJs?: boolean;

Check JS
Works in tandem with [allowJs](https://www.typescriptlang.org/tsconfig#allowJs). When checkJs is enabled then errors are reported in JavaScript files. This is the equivalent of including // @ts-check at the top of all JavaScript files which are included in your project.
See Also
- https://www.typescriptlang.org/tsconfig#checkJs

property customConditions

readonly customConditions?: string[];

List of additional conditions that should succeed when TypeScript resolves from an exports or imports field of a package.json.
See Also
- https://www.typescriptlang.org/tsconfig#customConditions undefined

property declarationDir

readonly declarationDir?: string;

Offers a way to configure the root directory for where declaration files are emitted.

property declarationMap

readonly declarationMap?: boolean;

Generates a source map for .d.ts files which map back to the original .ts source file. This will allow editors such as VS Code to go to the original .ts file when using features like Go to Definition.
See Also
- https://www.typescriptlang.org/tsconfig#declarationMap

property downlevelIteration

readonly downlevelIteration?: boolean;

Downleveling is TypeScript’s term for transpiling to an older version of JavaScript. This flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes.
ECMAScript 6 added several new iteration primitives: the for / of loop (for (el of arr)), Array spread ([a, ...b]), argument spread (fn(...args)), and Symbol.iterator. downlevelIteration allows for these iteration primitives to be used more accurately in ES5 environments if a Symbol.iterator implementation is present.

property emitDeclarationOnly

readonly emitDeclarationOnly?: boolean;

Only emit .d.ts files; do not emit .js files.
false

property emitDecoratorMetadata

readonly emitDecoratorMetadata?: boolean;

Enables experimental support for decorators, which is in stage 2 of the TC39 standardization process. Decorators are a language feature which hasn’t yet been fully ratified into the JavaScript specification. This means that the implementation version in TypeScript may differ from the implementation in JavaScript when it it decided by TC39. You can find out more about decorator support in TypeScript in the handbook.
See Also
- https://www.typescriptlang.org/docs/handbook/decorators.html undefined

property esModuleInterop

readonly esModuleInterop?: boolean;

Emit __importStar and __importDefault helpers for runtime babel ecosystem compatibility and enable --allowSyntheticDefaultImports for typesystem compatibility.
false

property exactOptionalPropertyTypes

readonly exactOptionalPropertyTypes?: boolean;

Specifies that optional property types should be interpreted exactly as written, meaning that | undefined is not added to the type Available with TypeScript 4.4 and newer. false

property experimentalDecorators

readonly experimentalDecorators?: boolean;

Enables experimental support for decorators, which is in stage 2 of the TC39 standardization process.
true

property forceConsistentCasingInFileNames

readonly forceConsistentCasingInFileNames?: boolean;

Disallow inconsistently-cased references to the same file.
false

property importsNotUsedAsValues

readonly importsNotUsedAsValues?: TypeScriptImportsNotUsedAsValues;

This flag works because you can use import type to explicitly create an import statement which should never be emitted into JavaScript.
Remarks
For TypeScript 5.0+ use verbatimModuleSyntax instead. Posed for deprecation upon TypeScript 5.5.
See Also
- https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues "remove"

property incremental

readonly incremental?: boolean;

Tells TypeScript to save information about the project graph from the last compilation to files stored on disk. This creates a series of .tsbuildinfo files in the same folder as your compilation output. They are not used by your JavaScript at runtime and can be safely deleted. You can read more about the flag in the 3.4 release notes.
See Also
- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag
  To control which folders you want to the files to be built to, use the config option tsBuildInfoFile.

property inlineSourceMap

readonly inlineSourceMap?: boolean;

When set, instead of writing out a .js.map file to provide source maps, TypeScript will embed the source map content in the .js files.
true

property inlineSources

readonly inlineSources?: boolean;

When set, TypeScript will include the original content of the .ts file as an embedded string in the source map. This is often useful in the same cases as inlineSourceMap.
true

property isolatedModules

readonly isolatedModules?: boolean;

Perform additional checks to ensure that separate compilation (such as with transpileModule or @babel/plugin-transform-typescript) would be safe.
false

property jsx

readonly jsx?: TypeScriptJsxMode;

Support JSX in .tsx files: "react", "preserve", "react-native" etc.
undefined

property jsxImportSource

readonly jsxImportSource?: string;

Declares the module specifier to be used for importing the jsx and jsxs factory functions when using jsx.
undefined

property lib

readonly lib?: string[];

Reference for type definitions / libraries to use (eg. ES2016, ES5, ES2018).
[ "es2018" ]

property module

readonly module?: string;

Sets the module system for the program. See https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules.
"CommonJS"

property moduleDetection

readonly moduleDetection?: TypeScriptModuleDetection;

This setting controls how TypeScript determines whether a file is a [script or a module](https://www.typescriptlang.org/docs/handbook/modules/theory.html#scripts-and-modules-in-javascript).
"auto"

property moduleResolution

readonly moduleResolution?: TypeScriptModuleResolution;

Determine how modules get resolved. Either "Node" for Node.js/io.js style resolution, or "Classic".
"node"

property noEmit

readonly noEmit?: boolean;

Do not emit outputs.
false

property noEmitOnError

readonly noEmitOnError?: boolean;

Do not emit compiler output files like JavaScript source code, source-maps or declarations if any errors were reported.
true

property noFallthroughCasesInSwitch

readonly noFallthroughCasesInSwitch?: boolean;

Report errors for fallthrough cases in switch statements. Ensures that any non-empty case inside a switch statement includes either break or return. This means you won’t accidentally ship a case fallthrough bug.
true

property noImplicitAny

readonly noImplicitAny?: boolean;

In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type.
true

property noImplicitOverride

readonly noImplicitOverride?: boolean;

Using noImplicitOverride, you can ensure that sub-classes never go out of sync as they are required to explicitly declare that they are overriding a member using the override keyword. This also improves readability of the programmer's intent.
Available with TypeScript 4.3 and newer.
false

property noImplicitReturns

readonly noImplicitReturns?: boolean;

When enabled, TypeScript will check all code paths in a function to ensure they return a value.
true

property noImplicitThis

readonly noImplicitThis?: boolean;

Raise error on ‘this’ expressions with an implied ‘any’ type.
true

property noPropertyAccessFromIndexSignature

readonly noPropertyAccessFromIndexSignature?: boolean;

Raise error on use of the dot syntax to access fields which are not defined.
true

property noUncheckedIndexedAccess

readonly noUncheckedIndexedAccess?: boolean;

Raise error when accessing indexes on objects with unknown keys defined in index signatures.
true

property noUnusedLocals

readonly noUnusedLocals?: boolean;

Report errors on unused local variables.
true

property noUnusedParameters

readonly noUnusedParameters?: boolean;

Report errors on unused parameters in functions.
true

property outDir

readonly outDir?: string;

Output directory for the compiled files.

property paths

readonly paths?: {
    [key: string]: string[];
};

A series of entries which re-map imports to lookup locations relative to the baseUrl, there is a larger coverage of paths in the handbook.
paths lets you declare how TypeScript should resolve an import in your require/imports.

property resolveJsonModule

readonly resolveJsonModule?: boolean;

Allows importing modules with a ‘.json’ extension, which is a common practice in node projects. This includes generating a type for the import based on the static JSON shape.
true

property resolvePackageJsonExports

readonly resolvePackageJsonExports?: boolean;

Forces TypeScript to consult the exports field of package.json files if it ever reads from a package in node_modules.
true

property resolvePackageJsonImports

readonly resolvePackageJsonImports?: boolean;

Forces TypeScript to consult the imports field of package.json when performing a lookup that begins with # from a file that has a package.json as an ancestor.
undefined

property rootDir

readonly rootDir?: string;

Specifies the root directory of input files.
Only use to control the output directory structure with outDir.

property skipLibCheck

readonly skipLibCheck?: boolean;

Skip type checking of all declaration files (*.d.ts).
false

property sourceMap

readonly sourceMap?: boolean;

Enables the generation of sourcemap files.
undefined

property sourceRoot

readonly sourceRoot?: string;

Specify the location where a debugger should locate TypeScript files instead of relative source locations.
undefined

property strict

readonly strict?: boolean;

The strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness. Turning this on is equivalent to enabling all of the strict mode family options, which are outlined below. You can then turn off individual strict mode family checks as needed.
true

property strictNullChecks

readonly strictNullChecks?: boolean;

When strictNullChecks is false, null and undefined are effectively ignored by the language. This can lead to unexpected errors at runtime. When strictNullChecks is true, null and undefined have their own distinct types and you’ll get a type error if you try to use them where a concrete value is expected.
true

property strictPropertyInitialization

readonly strictPropertyInitialization?: boolean;

When set to true, TypeScript will raise an error when a class property was declared but not set in the constructor.
true

property stripInternal

readonly stripInternal?: boolean;

Do not emit declarations for code that has an @internal annotation in it’s JSDoc comment.
true

property target

readonly target?: string;

Modern browsers support all ES6 features, so ES6 is a good choice. You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments.
"ES2018"

property tsBuildInfoFile

readonly tsBuildInfoFile?: string;

This setting lets you specify a file for storing incremental compilation information as a part of composite projects which enables faster building of larger TypeScript codebases. You can read more about composite projects in the handbook.

property typeRoots

readonly typeRoots?: string[];

If typeRoots is specified, only packages under typeRoots will be included
See Also
- https://www.typescriptlang.org/tsconfig/#typeRoots

property types

readonly types?: string[];

If types is specified, only packages listed will be included in the global scope
See Also
- https://www.typescriptlang.org/tsconfig#types

property useUnknownInCatchVariables

readonly useUnknownInCatchVariables?: boolean;

Change the type of the variable in a catch clause from any to unknown Available with TypeScript 4.4 and newer. true

property verbatimModuleSyntax

readonly verbatimModuleSyntax?: boolean;

Simplifies TypeScript's handling of import/export type modifiers.
See Also
- https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax undefined

interface TypescriptConfigOptions

interface TypescriptConfigOptions {}

property compilerOptions

readonly compilerOptions?: TypeScriptCompilerOptions;

Compiler options to use.
Remarks
Must provide either extends or compilerOptions (or both).

property exclude

readonly exclude?: string[];

Filters results from the "include" option.
- node_modules is excluded by default

property extends

readonly extends?: TypescriptConfigExtends;

Base tsconfig.json configuration(s) to inherit from.
Remarks
Must provide either extends or compilerOptions (or both).

property fileName

readonly fileName?: string;

"tsconfig.json"

property include

readonly include?: string[];

Specifies a list of glob patterns that match TypeScript files to be included in compilation.
- all .ts files recursively

interface UpgradeDependenciesOptions

interface UpgradeDependenciesOptions {}

Options for UpgradeDependencies.

property exclude

readonly exclude?: string[];

List of package names to exclude during the upgrade.
- Nothing is excluded.

property include

readonly include?: string[];

List of package names to include during the upgrade.
- Everything is included.

property includeDeprecatedVersions

readonly includeDeprecatedVersions?: boolean;

Include deprecated packages.
By default, deprecated versions will be excluded from upgrades.
See Also
- https://github.com/raineorshine/npm-check-updates?tab=readme-ov-file#options
  false

property pullRequestTitle

readonly pullRequestTitle?: string;

Title of the pull request to use (should be all lower-case).
"upgrade dependencies"

property satisfyPeerDependencies

readonly satisfyPeerDependencies?: boolean;

Check peer dependencies of installed packages and filter updates to compatible versions.
By default, the upgrade workflow will adhere to version constraints from peer dependencies. Sometimes this is not desirable and can be disabled.
See Also
- https://github.com/raineorshine/npm-check-updates#peer
  true

property signoff

readonly signoff?: boolean;

Add Signed-off-by line by the committer at the end of the commit log message.
true

property target

readonly target?: string;

Determines the target version to upgrade dependencies to.
See Also
- https://github.com/raineorshine/npm-check-updates#target
  "minor"

property taskName

readonly taskName?: string;

The name of the task that will be created. This will also be the workflow name.
"upgrade".

property types

readonly types?: DependencyType[];

Specify which dependency types the upgrade should operate on.
- All dependency types.

property workflow

readonly workflow?: boolean;

Include a github workflow for creating PR's that upgrades the required dependencies, either by manual dispatch, or by a schedule.
If this is false, only a local projen task is created, which can be executed manually to upgrade the dependencies.
- true for root projects, false for subprojects.

property workflowOptions

readonly workflowOptions?: UpgradeDependenciesWorkflowOptions;

Options for the github workflow. Only applies if workflow is true.
- default options.

interface UpgradeDependenciesWorkflowOptions

interface UpgradeDependenciesWorkflowOptions {}

Options for UpgradeDependencies.workflowOptions.

property assignees

readonly assignees?: string[];

Assignees to add on the PR.
- no assignees

property branches

readonly branches?: string[];

List of branches to create PR's for.
- All release branches configured for the project.

property gitIdentity

readonly gitIdentity?: GitIdentity;

The git identity to use for commits. "github-actions@github.com"

property labels

readonly labels?: string[];

Labels to apply on the PR.
- no labels.

property permissions

readonly permissions?: JobPermissions;

Permissions granted to the upgrade job To limit job permissions for contents, the desired permissions have to be explicitly set, e.g.: { contents: JobPermission.NONE } { contents: JobPermission.READ }

property projenCredentials

readonly projenCredentials?: GithubCredentials;

Choose a method for authenticating with GitHub for creating the PR.
When using the default github token, PR's created by this workflow will not trigger any subsequent workflows (i.e the build workflow), so projen requires API access to be provided through e.g. a personal access token or other method.
See Also
- https://github.com/peter-evans/create-pull-request/issues/48 - personal access token named PROJEN_GITHUB_TOKEN

property runsOn

readonly runsOn?: string[];

Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property runsOnGroup

readonly runsOnGroup?: GroupRunnerOptions;

Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both runsOn and runsOnGroup are specified

property schedule

readonly schedule?: UpgradeDependenciesSchedule;

Schedule to run on.
UpgradeDependenciesSchedule.DAILY

property version

readonly version?: string;

A fully specified version to use for yarn (e.g., x.x.x)
- 4.0.1

property yarnRcOptions

readonly yarnRcOptions?: YarnrcOptions;

The yarnrc configuration.
- a blank Yarn RC file

property zeroInstalls

readonly zeroInstalls?: boolean;

Should zero-installs be enabled? Learn more at: https://yarnpkg.com/features/caching#zero-installs
false

interface YarnLogFilter

interface YarnLogFilter {}

https://yarnpkg.com/configuration/yarnrc#logFilters

property code

readonly code?: string;

property level

readonly level?: YarnLogFilterLevel;

property pattern

readonly pattern?: string;

property text

readonly text?: string;

interface YarnNetworkSetting

interface YarnNetworkSetting {}

https://yarnpkg.com/configuration/yarnrc#networkSettings

property caFilePath

readonly caFilePath?: string;

Deprecated
- use httpsCaFilePath in Yarn v4 and newer

property enableNetwork

readonly enableNetwork?: boolean;

property httpProxy

readonly httpProxy?: string;

property httpsCaFilePath

readonly httpsCaFilePath?: string;

property httpsCertFilePath

readonly httpsCertFilePath?: string;

property httpsKeyFilePath

readonly httpsKeyFilePath?: string;

property httpsProxy

readonly httpsProxy?: string;

interface YarnNpmRegistry

interface YarnNpmRegistry {}

https://yarnpkg.com/configuration/yarnrc#npmRegistries

property npmAlwaysAuth

readonly npmAlwaysAuth?: boolean;

property npmAuthIdent

readonly npmAuthIdent?: string;

property npmAuthToken

readonly npmAuthToken?: string;

interface YarnNpmScope

interface YarnNpmScope {}

https://yarnpkg.com/configuration/yarnrc#npmScopes

property npmAlwaysAuth

readonly npmAlwaysAuth?: boolean;

property npmAuthIdent

readonly npmAuthIdent?: string;

property npmAuthToken

readonly npmAuthToken?: string;

property npmPublishRegistry

readonly npmPublishRegistry?: string;

property npmRegistryServer

readonly npmRegistryServer?: string;

interface YarnPackageExtension

interface YarnPackageExtension {}

https://yarnpkg.com/configuration/yarnrc#packageExtensions

property dependencies

readonly dependencies?: Record<string, string>;

property peerDependencies

readonly peerDependencies?: Record<string, string>;

property peerDependenciesMeta

readonly peerDependenciesMeta?: Record<
    string,
    Record<string, YarnPeerDependencyMeta>
>;

interface YarnPeerDependencyMeta

interface YarnPeerDependencyMeta {}

https://yarnpkg.com/configuration/yarnrc#packageExtensions

property optional

readonly optional?: boolean;

interface YarnrcOptions

interface YarnrcOptions {}

Configuration for .yarnrc.yml in Yarn Berry v4

property cacheFolder

readonly cacheFolder?: string;

https://yarnpkg.com/configuration/yarnrc#cacheFolder

property cacheMigrationMode

readonly cacheMigrationMode?: YarnCacheMigrationMode;

https://yarnpkg.com/configuration/yarnrc#cacheMigrationMode

property changesetBaseRefs

readonly changesetBaseRefs?: string[];

https://yarnpkg.com/configuration/yarnrc#changesetBaseRefs

property changesetIgnorePatterns

readonly changesetIgnorePatterns?: string[];

https://yarnpkg.com/configuration/yarnrc#changesetIgnorePatterns

property checksumBehavior

readonly checksumBehavior?: YarnChecksumBehavior;

https://yarnpkg.com/configuration/yarnrc#checksumBehavior

property cloneConcurrency

readonly cloneConcurrency?: number;

https://yarnpkg.com/configuration/yarnrc#cloneConcurrency

property compressionLevel

readonly compressionLevel?: number | string;

https://yarnpkg.com/configuration/yarnrc#compressionLevel

property constraintsPath

readonly constraintsPath?: string;

https://yarnpkg.com/configuration/yarnrc#constraintsPath

property defaultLanguageName

readonly defaultLanguageName?: string;

https://yarnpkg.com/configuration/yarnrc#defaultLanguageName

property defaultProtocol

readonly defaultProtocol?: string;

https://yarnpkg.com/configuration/yarnrc#defaultProtocol

property defaultSemverRangePrefix

readonly defaultSemverRangePrefix?: YarnDefaultSemverRangePrefix;

https://yarnpkg.com/configuration/yarnrc#defaultSemverRangePrefix

property deferredVersionFolder

readonly deferredVersionFolder?: string;

https://yarnpkg.com/configuration/yarnrc#deferredVersionFolder

property enableColors

readonly enableColors?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableColors

property enableConstraintsCheck

readonly enableConstraintsCheck?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableConstraintsCheck

property enableGlobalCache

readonly enableGlobalCache?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableGlobalCache

property enableHardenedMode

readonly enableHardenedMode?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableHardenedMode

property enableHyperlinks

readonly enableHyperlinks?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableHyperlinks

property enableImmutableCache

readonly enableImmutableCache?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableImmutableCache

property enableImmutableInstalls

readonly enableImmutableInstalls?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableImmutableInstalls

property enableInlineBuilds

readonly enableInlineBuilds?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableInlineBuilds

property enableInlineHunks

readonly enableInlineHunks?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableInlineHunks

property enableMessageNames

readonly enableMessageNames?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableMessageNames

property enableMirror

readonly enableMirror?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableMirror

property enableNetwork

readonly enableNetwork?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableNetwork

property enableOfflineMode

readonly enableOfflineMode?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableOfflineMode

property enableProgressBars

readonly enableProgressBars?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableProgressBars

property enableScripts

readonly enableScripts?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableScripts

property enableStrictSsl

readonly enableStrictSsl?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableStrictSsl

property enableTelemetry

readonly enableTelemetry?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableTelemetry

property enableTimers

readonly enableTimers?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableTimers

property enableTransparentWorkspaces

readonly enableTransparentWorkspaces?: boolean;

https://yarnpkg.com/configuration/yarnrc#enableTransparentWorkspaces

property globalFolder

readonly globalFolder?: string;

https://yarnpkg.com/configuration/yarnrc#globalFolder

property httpProxy

readonly httpProxy?: string;

https://yarnpkg.com/configuration/yarnrc#httpProxy

property httpRetry

readonly httpRetry?: number;

https://yarnpkg.com/configuration/yarnrc#httpRetry

property httpsCaFilePath

readonly httpsCaFilePath?: string;

https://yarnpkg.com/configuration/yarnrc#httpsCaFilePath

property httpsCertFilePath

readonly httpsCertFilePath?: string;

https://yarnpkg.com/configuration/yarnrc#httpsCertFilePath

property httpsKeyFilePath

readonly httpsKeyFilePath?: string;

https://yarnpkg.com/configuration/yarnrc#httpsKeyFilePath

property httpsProxy

readonly httpsProxy?: string;

https://yarnpkg.com/configuration/yarnrc#httpsProxy

property httpTimeout

readonly httpTimeout?: number;

https://yarnpkg.com/configuration/yarnrc#httpTimeout

property ignoreCwd

readonly ignoreCwd?: boolean;

https://v3.yarnpkg.com/configuration/yarnrc#ignoreCwd
Deprecated
- removed in Yarn v4 and newer

property ignorePath

readonly ignorePath?: boolean;

https://yarnpkg.com/configuration/yarnrc#ignorePath

property immutablePatterns

readonly immutablePatterns?: string[];

https://yarnpkg.com/configuration/yarnrc#immutablePatterns

property initFields

readonly initFields?: Record<string, any>;

https://yarnpkg.com/configuration/yarnrc#initFields

property initScope

readonly initScope?: string;

https://yarnpkg.com/configuration/yarnrc#initScope

property injectEnvironmentFiles

readonly injectEnvironmentFiles?: string[];

https://yarnpkg.com/configuration/yarnrc#injectEnvironmentFiles

property installStatePath

readonly installStatePath?: string;

https://yarnpkg.com/configuration/yarnrc#installStatePath

property lockfileFilename

readonly lockfileFilename?: string;

https://v3.yarnpkg.com/configuration/yarnrc#lockfileFilename
Deprecated
- removed in Yarn v4 and newer

property logFilters

readonly logFilters?: YarnLogFilter[];

https://yarnpkg.com/configuration/yarnrc#logFilters

property networkConcurrency

readonly networkConcurrency?: number;

https://yarnpkg.com/configuration/yarnrc#networkConcurrency

property networkSettings

readonly networkSettings?: Record<string, YarnNetworkSetting>;

https://yarnpkg.com/configuration/yarnrc#networkSettings

property nmHoistingLimits

readonly nmHoistingLimits?: YarnNmHoistingLimit;

https://yarnpkg.com/configuration/yarnrc#nmHoistingLimits

property nmMode

readonly nmMode?: YarnNmMode;

https://yarnpkg.com/configuration/yarnrc#nmMode

property nmSelfReferences

readonly nmSelfReferences?: boolean;

https://yarnpkg.com/configuration/yarnrc#nmSelfReferences

property nodeLinker

readonly nodeLinker?: YarnNodeLinker;

https://yarnpkg.com/configuration/yarnrc#nodeLinker

property npmAlwaysAuth

readonly npmAlwaysAuth?: boolean;

https://yarnpkg.com/configuration/yarnrc#npmAlwaysAuth

property npmAuditExcludePackages

readonly npmAuditExcludePackages?: string[];

https://yarnpkg.com/configuration/yarnrc#npmAuditExcludePackages

property npmAuditIgnoreAdvisories

readonly npmAuditIgnoreAdvisories?: string[];

https://yarnpkg.com/configuration/yarnrc#npmAuditIgnoreAdvisories

property npmAuditRegistry

readonly npmAuditRegistry?: string;

https://yarnpkg.com/configuration/yarnrc#npmAuditRegistry

property npmAuthIdent

readonly npmAuthIdent?: string;

https://yarnpkg.com/configuration/yarnrc#npmAuthIdent

property npmAuthToken

readonly npmAuthToken?: string;

https://yarnpkg.com/configuration/yarnrc#npmAuthToken

property npmPublishAccess

readonly npmPublishAccess?: YarnNpmPublishAccess;

https://yarnpkg.com/configuration/yarnrc#npmPublishAccess

property npmPublishRegistry

readonly npmPublishRegistry?: string;

https://yarnpkg.com/configuration/yarnrc#npmPublishRegistry

property npmRegistries

readonly npmRegistries?: Record<string, YarnNpmRegistry>;

https://yarnpkg.com/configuration/yarnrc#npmRegistries

property npmRegistryServer

readonly npmRegistryServer?: string;

https://yarnpkg.com/configuration/yarnrc#npmRegistryServer

property npmScopes

readonly npmScopes?: Record<string, YarnNpmScope>;

https://yarnpkg.com/configuration/yarnrc#npmScopes

property packageExtensions

readonly packageExtensions?: Record<string, YarnPackageExtension>;

https://yarnpkg.com/configuration/yarnrc#packageExtensions

property patchFolder

readonly patchFolder?: string;

https://yarnpkg.com/configuration/yarnrc#patchFolder

property pnpDataPath

readonly pnpDataPath?: string;

https://v3.yarnpkg.com/configuration/yarnrc#pnpDataPath
Deprecated
- removed in Yarn v4 and newer

property pnpEnableEsmLoader

readonly pnpEnableEsmLoader?: boolean;

https://yarnpkg.com/configuration/yarnrc#pnpEnableEsmLoader

property pnpEnableInlining

readonly pnpEnableInlining?: boolean;

https://yarnpkg.com/configuration/yarnrc#pnpEnableInlining

property pnpFallbackMode

readonly pnpFallbackMode?: YarnPnpFallbackMode;

https://yarnpkg.com/configuration/yarnrc#pnpFallbackMode

property pnpIgnorePatterns

readonly pnpIgnorePatterns?: string[];

https://yarnpkg.com/configuration/yarnrc#pnpIgnorePatterns

property pnpMode

readonly pnpMode?: YarnPnpMode;

https://yarnpkg.com/configuration/yarnrc#pnpMode

property pnpShebang

readonly pnpShebang?: string;

https://yarnpkg.com/configuration/yarnrc#pnpShebang

property pnpUnpluggedFolder

readonly pnpUnpluggedFolder?: string;

https://yarnpkg.com/configuration/yarnrc#pnpUnpluggedFolder

property preferAggregateCacheInfo

readonly preferAggregateCacheInfo?: boolean;

https://v3.yarnpkg.com/configuration/yarnrc#preferAggregateCacheInfo
Deprecated
- removed in Yarn v4 and newer

property preferDeferredVersions

readonly preferDeferredVersions?: boolean;

https://yarnpkg.com/configuration/yarnrc#preferDeferredVersions

property preferInteractive

readonly preferInteractive?: boolean;

https://yarnpkg.com/configuration/yarnrc#preferInteractive

property preferReuse

readonly preferReuse?: boolean;

https://yarnpkg.com/configuration/yarnrc#preferReuse

property preferTruncatedLines

readonly preferTruncatedLines?: boolean;

https://yarnpkg.com/configuration/yarnrc#preferTruncatedLines

property progressBarStyle

readonly progressBarStyle?: YarnProgressBarStyle;

https://yarnpkg.com/configuration/yarnrc#progressBarStyle

property rcFilename

readonly rcFilename?: string;

https://yarnpkg.com/configuration/yarnrc#rcFilename

property supportedArchitectures

readonly supportedArchitectures?: YarnSupportedArchitectures;

https://yarnpkg.com/configuration/yarnrc#supportedArchitectures

property taskPoolConcurrency

readonly taskPoolConcurrency?: string;

https://yarnpkg.com/configuration/yarnrc#taskPoolConcurrency

property telemetryInterval

readonly telemetryInterval?: number;

https://yarnpkg.com/configuration/yarnrc#telemetryInterval

property telemetryUserId

readonly telemetryUserId?: string;

https://yarnpkg.com/configuration/yarnrc#telemetryUserId

property tsEnableAutoTypes

readonly tsEnableAutoTypes?: boolean;

https://yarnpkg.com/configuration/yarnrc#tsEnableAutoTypes

property unsafeHttpWhitelist

readonly unsafeHttpWhitelist?: string[];

https://yarnpkg.com/configuration/yarnrc#unsafeHttpWhitelist

property virtualFolder

readonly virtualFolder?: string;

https://yarnpkg.com/configuration/yarnrc#virtualFolder

property winLinkType

readonly winLinkType?: YarnWinLinkType;

https://yarnpkg.com/configuration/yarnrc#winLinkType

property workerPoolMode

readonly workerPoolMode?: YarnWorkerPoolMode;

https://yarnpkg.com/configuration/yarnrc#workerPoolMode

property yarnPath

readonly yarnPath?: string;

https://yarnpkg.com/configuration/yarnrc#yarnPath

interface YarnSupportedArchitectures

interface YarnSupportedArchitectures {}

https://yarnpkg.com/configuration/yarnrc#supportedArchitectures

property cpu

readonly cpu?: string[];

property libc

readonly libc?: string[];

property os

readonly os?: string[];

enum ArrowParens

enum ArrowParens {
    ALWAYS = 'always',
    AVOID = 'avoid',
}

member ALWAYS

ALWAYS = 'always'

Always include parens. Example: (x) => x

member AVOID

AVOID = 'avoid'

Omit parens when possible. Example: x => x

member DAILY

DAILY = 1

Automatically bump & release a new version on a daily basis.

member EVERY_COMMIT

EVERY_COMMIT = 0

Automatically bump & release a new version for every commit to "main"

enum BundleLogLevel

enum BundleLogLevel {
    VERBOSE = 'verbose',
    DEBUG = 'debug',
    INFO = 'info',
    WARNING = 'warning',
    ERROR = 'error',
    SILENT = 'silent',
}

Log levels for esbuild and package managers' install commands.

member DEBUG

DEBUG = 'debug'

Show everything from info and some additional messages for debugging

member ERROR

ERROR = 'error'

Show errors only

member INFO

INFO = 'info'

Show warnings, errors, and an output file summary

member SILENT

SILENT = 'silent'

Show nothing

member ASCII

ASCII = 'ascii'

ASCII
Any non-ASCII characters are escaped using backslash escape sequences

member UTF8

UTF8 = 'utf8'

UTF-8
Keep original characters without using escape sequences

enum CodeArtifactAuthProvider

enum CodeArtifactAuthProvider {
    ACCESS_AND_SECRET_KEY_PAIR = 'ACCESS_AND_SECRET_KEY_PAIR',
    GITHUB_OIDC = 'GITHUB_OIDC',
}

Options for authorizing requests to a AWS CodeArtifact npm repository.

member ACCESS_AND_SECRET_KEY_PAIR

ACCESS_AND_SECRET_KEY_PAIR = 'ACCESS_AND_SECRET_KEY_PAIR'

Fixed credentials provided via Github secrets.

member GITHUB_OIDC

GITHUB_OIDC = 'GITHUB_OIDC'

Ephemeral credentials provided via Github's OIDC integration with an IAM role. See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services

enum EmbeddedLanguageFormatting

enum EmbeddedLanguageFormatting {
    AUTO = 'auto',
    OFF = 'off',
}

member AUTO

AUTO = 'auto'

Format embedded code if Prettier can automatically identify it.

member OFF

OFF = 'off'

Never automatically format embedded code.

enum EndOfLine

enum EndOfLine {
    AUTO = 'auto',
    CR = 'cr',
    CRLF = 'crlf',
    LF = 'lf',
}

member AUTO

AUTO = 'auto'

Maintain existing (mixed values within one file are normalised by looking at what's used after the first line)

member CR

CR = 'cr'

Carriage Return character only (\r), used very rarely

member CRLF

CRLF = 'crlf'

Carriage Return + Line Feed characters (\r\n), common on Windows

member LF

LF = 'lf'

Line Feed only (\n), common on Linux and macOS as well as inside git repos

enum HTMLWhitespaceSensitivity

enum HTMLWhitespaceSensitivity {
    CSS = 'css',
    IGNORE = 'ignore',
    STRICT = 'strict',
}

member CSS

CSS = 'css'

Respect the default value of CSS display property.

member IGNORE

IGNORE = 'ignore'

Whitespaces are considered insignificant.

member STRICT

STRICT = 'strict'

Whitespaces are considered significant.

member BUN

BUN = 'bun'

Use bun as the package manager

member NPM

NPM = 'npm'

Use npm as the package manager.

member PNPM

PNPM = 'pnpm'

Use pnpm as the package manager.

member YARN

YARN = 'yarn'

Use yarn as the package manager.
Deprecated
For yarn 1.x use YARN_CLASSIC for yarn >= 2 use YARN_BERRY. Currently, NodePackageManager.YARN means YARN_CLASSIC. In the future, we might repurpose it to mean YARN_BERRY.

member YARN_BERRY

YARN_BERRY = 'yarn_berry'

Use yarn versions >= 2 as the package manager.

member YARN2

YARN2 = 'yarn2'

Use yarn versions >= 2 as the package manager.
Deprecated
use YARN_BERRY instead

member PUBLIC

PUBLIC = 'public'

Package is public.

member RESTRICTED

RESTRICTED = 'restricted'

Package can only be accessed with credentials.

enum ProseWrap

enum ProseWrap {
    ALWAYS = 'always',
    NEVER = 'never',
    PRESERVE = 'preserve',
}

member ALWAYS

ALWAYS = 'always'

Wrap prose if it exceeds the print width.

member NEVER

NEVER = 'never'

Do not wrap prose.

enum QuoteProps

enum QuoteProps {
    ASNEEDED = 'as-needed',
    CONSISTENT = 'consistent',
    PRESERVE = 'preserve',
}

member ASNEEDED

ASNEEDED = 'as-needed'

Only add quotes around object properties where required.

member CONSISTENT

CONSISTENT = 'consistent'

If at least one property in an object requires quotes, quote all properties.

member PRESERVE

PRESERVE = 'preserve'

Respect the input use of quotes in object properties.

member MANUAL

MANUAL = 'manual'

Don't bundle automatically as part of the build.

member POST_COMPILE

POST_COMPILE = 'post_compile'

Bundle automatically after compilation. This is useful if you want to bundle the compiled results.

Thus will run compilation tasks (using tsc, etc.) before running file through bundling step.

This is only required unless you are using new experimental features that are not supported by esbuild but are supported by typescript's tsc compiler. One example of such feature is emitDecoratorMetadata.

// In a TypeScript project with output configured
// to go to the "lib" directory:
const project = new TypeScriptProject({
  name: "test",
  defaultReleaseBranch: "main",
  tsconfig: {
    compilerOptions: {
      outDir: "lib",
    },
  },
  bundlerOptions: {
    // ensure we compile with `tsc` before bundling
    runBundleTask: RunBundleTask.POST_COMPILE,
  },
});

// Tell the bundler to bundle the compiled results (from the "lib" directory)
project.bundler.addBundle("./lib/index.js", {
  platform: "node",
  target: "node18",
  sourcemap: false,
  format: "esm",
});

member PRE_COMPILE

PRE_COMPILE = 'pre_compile'

Bundle automatically before compilation.

enum SourceMapMode

enum SourceMapMode {
    DEFAULT = 'default',
    EXTERNAL = 'external',
    INLINE = 'inline',
    BOTH = 'both',
}

SourceMap mode for esbuild
See Also
- https://esbuild.github.io/api/#sourcemap

member BOTH

BOTH = 'both'

Both sourceMap mode - If you want to have the effect of both inline and external simultaneously

member DEFAULT

DEFAULT = 'default'

Default sourceMap mode - will generate a .js.map file alongside any generated .js file and add a special //# sourceMappingURL= comment to the bottom of the .js file pointing to the .js.map file

member EXTERNAL

EXTERNAL = 'external'

External sourceMap mode - If you want to omit the special //# sourceMappingURL= comment from the generated .js file but you still want to generate the .js.map files

member INLINE

INLINE = 'inline'

Inline sourceMap mode - If you want to insert the entire source map into the .js file instead of generating a separate .js.map file

enum TrailingComma

enum TrailingComma {
    ALL = 'all',
    ES5 = 'es5',
    NONE = 'none',
}

member ALL

ALL = 'all'

Trailing commas wherever possible (including function arguments).

member ES5

ES5 = 'es5'

Trailing commas where valid in ES5 (objects, arrays, etc.)

member NONE

NONE = 'none'

No trailing commas.

enum TypeScriptImportsNotUsedAsValues

enum TypeScriptImportsNotUsedAsValues {
    REMOVE = 'remove',
    PRESERVE = 'preserve',
    ERROR = 'error',
}

This flag controls how import works, there are 3 different options.
See Also
- https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues

member ERROR

ERROR = 'error'

This preserves all imports (the same as the preserve option), but will error when a value import is only used as a type. This might be useful if you want to ensure no values are being accidentally imported, but still make side-effect imports explicit.

member PRESERVE

PRESERVE = 'preserve'

Preserves all import statements whose values or types are never used. This can cause imports/side-effects to be preserved.

member REMOVE

REMOVE = 'remove'

The default behavior of dropping import statements which only reference types.

enum TypeScriptJsxMode

enum TypeScriptJsxMode {
    PRESERVE = 'preserve',
    REACT = 'react',
    REACT_NATIVE = 'react-native',
    REACT_JSX = 'react-jsx',
    REACT_JSXDEV = 'react-jsxdev',
}

Determines how JSX should get transformed into valid JavaScript.
See Also
- https://www.typescriptlang.org/docs/handbook/jsx.html

member PRESERVE

PRESERVE = 'preserve'

Keeps the JSX as part of the output to be further consumed by another transform step (e.g. Babel).

member REACT

REACT = 'react'

Converts JSX syntax into React.createElement, does not need to go through a JSX transformation before use, and the output will have a .js file extension.

member REACT_JSX

REACT_JSX = 'react-jsx'

Passes key separately from props and always passes children as props (since React 17).
See Also
- https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#react-17-jsx-factories

member REACT_JSXDEV

REACT_JSXDEV = 'react-jsxdev'

Same as REACT_JSX with additional debug data.

member REACT_NATIVE

REACT_NATIVE = 'react-native'

Keeps all JSX like 'preserve' mode, but output will have a .js extension.

enum TypeScriptModuleDetection

enum TypeScriptModuleDetection {
    AUTO = 'auto',
    LEGACY = 'legacy',
    FORCE = 'force',
}

This setting controls how TypeScript determines whether a file is a script or a module.
See Also
- https://www.typescriptlang.org/docs/handbook/modules/theory.html#scripts-and-modules-in-javascript

member AUTO

AUTO = 'auto'

TypeScript will not only look for import and export statements, but it will also check whether the "type" field in a package.json is set to "module" when running with module: nodenext or node16, and check whether the current file is a JSX file when running under jsx: react-jsx.
See Also
- https://www.typescriptlang.org/tsconfig/#moduleDetection

member FORCE

FORCE = 'force'

Ensures that every non-declaration file is treated as a module.
See Also
- https://www.typescriptlang.org/tsconfig/#moduleDetection

member LEGACY

LEGACY = 'legacy'

The same behavior as 4.6 and prior, usings import and export statements to determine whether a file is a module.
See Also
- https://www.typescriptlang.org/tsconfig/#moduleDetection

enum TypeScriptModuleResolution

enum TypeScriptModuleResolution {
    CLASSIC = 'classic',
    NODE = 'node',
    NODE10 = 'node10',
    NODE16 = 'node16',
    NODE_NEXT = 'nodenext',
    BUNDLER = 'bundler',
}

Determines how modules get resolved.
See Also
- https://www.typescriptlang.org/docs/handbook/module-resolution.html

member BUNDLER

BUNDLER = 'bundler'

Resolution strategy which attempts to mimic resolution patterns of modern bundlers; from TypeScript 5.0 onwards.
See Also
- https://www.typescriptlang.org/tsconfig#moduleResolution

member CLASSIC

CLASSIC = 'classic'

TypeScript's former default resolution strategy.
See Also
- https://www.typescriptlang.org/docs/handbook/module-resolution.html#classic

member NODE

NODE = 'node'

Resolution strategy which attempts to mimic the Node.js module resolution strategy at runtime.
See Also
- https://www.typescriptlang.org/docs/handbook/module-resolution.html#node

member NODE_NEXT

NODE_NEXT = 'nodenext'

Node.js’ ECMAScript Module Support from TypeScript 4.7 onwards
See Also
- https://www.typescriptlang.org/tsconfig#moduleResolution

member NODE10

NODE10 = 'node10'

--moduleResolution node was renamed to node10 (keeping node as an alias for backward compatibility) in TypeScript 5.0. It reflects the CommonJS module resolution algorithm as it existed in Node.js versions earlier than v12. It should no longer be used.
See Also
- https://www.typescriptlang.org/docs/handbook/modules/reference.html#node10-formerly-known-as-node

member NODE16

NODE16 = 'node16'

Node.js’ ECMAScript Module Support from TypeScript 4.7 onwards
See Also
- https://www.typescriptlang.org/tsconfig#moduleResolution

enum UpdateSnapshot

enum UpdateSnapshot {
    ALWAYS = 'always',
    NEVER = 'never',
}

member ALWAYS

ALWAYS = 'always'

Always update snapshots in "test" task.

member NEVER

NEVER = 'never'

Never update snapshots in "test" task and create a separate "test:update" task.

enum YarnCacheMigrationMode

enum YarnCacheMigrationMode {
    REQUIRED_ONLY = 'requied-only',
    MATCH_SPEC = 'match-spec',
    ALWAYS = 'always',
}

https://yarnpkg.com/configuration/yarnrc#cacheMigrationMode

member ALWAYS

ALWAYS = 'always'

member MATCH_SPEC

MATCH_SPEC = 'match-spec'

member REQUIRED_ONLY

REQUIRED_ONLY = 'requied-only'

enum YarnChecksumBehavior

enum YarnChecksumBehavior {
    THROW = 'throw',
    UPDATE = 'update',
    RESET = 'reset',
    IGNORE = 'ignore',
}

https://yarnpkg.com/configuration/yarnrc#checksumBehavior

member IGNORE

IGNORE = 'ignore'

member RESET

RESET = 'reset'

member THROW

THROW = 'throw'

member UPDATE

UPDATE = 'update'

enum YarnDefaultSemverRangePrefix

enum YarnDefaultSemverRangePrefix {
    CARET = '^',
    TILDE = '~',
    EMPTY_STRING = '',
}

https://yarnpkg.com/configuration/yarnrc#defaultSemverRangePrefix

member CARET

CARET = '^'

member EMPTY_STRING

EMPTY_STRING = ''

member TILDE

TILDE = '~'

enum YarnLogFilterLevel

enum YarnLogFilterLevel {
    INFO = 'info',
    WARNING = 'warning',
    ERROR = 'error',
    DISCARD = 'discard',
}

https://v3.yarnpkg.com/configuration/yarnrc#logFilters.0.level

member DISCARD

DISCARD = 'discard'

member ERROR

ERROR = 'error'

member INFO

INFO = 'info'

member WARNING

WARNING = 'warning'

enum YarnNmHoistingLimit

enum YarnNmHoistingLimit {
    DEPENDENCIES = 'dependencies',
    NONE = 'none',
    WORKSPACES = 'workspaces',
}

https://yarnpkg.com/configuration/yarnrc#nmHoistingLimits

member DEPENDENCIES

DEPENDENCIES = 'dependencies'

member NONE

NONE = 'none'

member WORKSPACES

WORKSPACES = 'workspaces'

enum YarnNmMode

enum YarnNmMode {
    CLASSIC = 'classic',
    HARDLINKS_LOCAL = 'hardlinks-local',
    HARDLINKS_GLOBAL = 'hardlinks-global',
}

https://yarnpkg.com/configuration/yarnrc#nmMode

member CLASSIC

CLASSIC = 'classic'

member HARDLINKS_GLOBAL

HARDLINKS_GLOBAL = 'hardlinks-global'

member HARDLINKS_LOCAL

HARDLINKS_LOCAL = 'hardlinks-local'

enum YarnNodeLinker

enum YarnNodeLinker {
    PNP = 'pnp',
    PNPM = 'pnpm',
    NODE_MODULES = 'node-modules',
}

https://yarnpkg.com/configuration/yarnrc#nodeLinker

member NODE_MODULES

NODE_MODULES = 'node-modules'

member PNP

PNP = 'pnp'

member PNPM

PNPM = 'pnpm'

enum YarnNpmPublishAccess

enum YarnNpmPublishAccess {
    PUBLIC = 'public',
    RESTRICTED = 'restricted',
}

https://yarnpkg.com/configuration/yarnrc#npmPublishAccess

member PUBLIC

PUBLIC = 'public'

member RESTRICTED

RESTRICTED = 'restricted'

enum YarnPnpFallbackMode

enum YarnPnpFallbackMode {
    NONE = 'none',
    DEPENDENCIES_ONLY = 'dependencies-only',
    ALL = 'all',
}

https://yarnpkg.com/configuration/yarnrc#pnpFallbackMode

member ALL

ALL = 'all'

member DEPENDENCIES_ONLY

DEPENDENCIES_ONLY = 'dependencies-only'

member NONE

NONE = 'none'

enum YarnPnpMode

enum YarnPnpMode {
    STRICT = 'strict',
    LOOSE = 'loose',
}

https://yarnpkg.com/configuration/yarnrc#pnpMode

member LOOSE

LOOSE = 'loose'

member STRICT

STRICT = 'strict'

enum YarnProgressBarStyle

enum YarnProgressBarStyle {
    PATRICK = 'patrick',
    SIMBA = 'simba',
    JACK = 'jack',
    HOGSFATHER = 'hogsfather',
    DEFAULT = 'default',
}

https://yarnpkg.com/configuration/yarnrc#progressBarStyle

member DEFAULT

DEFAULT = 'default'

member HOGSFATHER

HOGSFATHER = 'hogsfather'

member JACK

JACK = 'jack'

member PATRICK

PATRICK = 'patrick'

member SIMBA

SIMBA = 'simba'

enum YarnWinLinkType

enum YarnWinLinkType {
    JUNCTIONS = 'junctions',
    SYMLINKS = 'symlinks',
}

https://yarnpkg.com/configuration/yarnrc#winLinkType

member JUNCTIONS

JUNCTIONS = 'junctions'

member SYMLINKS

SYMLINKS = 'symlinks'

enum YarnWorkerPoolMode

enum YarnWorkerPoolMode {
    ASYNC = 'async',
    WORKERS = 'workers',
}

member ASYNC

ASYNC = 'async'

member WORKERS

WORKERS = 'workers'

type Files

type Files = string[] | string;

Exclude these files from this override.
Include these files in this override.

namespace python

module 'lib/python/index.d.ts' {}

function resolvePythonImportName

resolvePythonImportName: (jsiiFqn: string, jsiiManifest: any) => string;

class Pip

class Pip extends Component implements IPythonDeps {}

Manages dependencies using a requirements.txt file and the pip CLI tool.

constructor

constructor(project: Project, _options?: PipOptions);

property installCiTask

readonly installCiTask: Task;

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <module>@<semver>

method addDevDependency

addDevDependency: (spec: string) => void;

Adds a dev dependency.
Parameter spec
Format <module>@<semver>

method installDependencies

installDependencies: () => void;

Installs dependencies (called during post-synthesis).

class Poetry

class Poetry
    extends Component
    implements IPythonDeps, IPythonEnv, IPythonPackaging {}

Manage project dependencies, virtual environments, and packaging through the poetry CLI tool.

constructor

constructor(project: Project, options: PoetryOptions);

property installCiTask

readonly installCiTask: Task;

Task for installing dependencies according to the existing lockfile.

property installTask

readonly installTask: Task;

Task for updating the lockfile and installing project dependencies.

property publishTask

readonly publishTask: Task;

Task for publishing the package to a package repository.

property publishTestTask

readonly publishTestTask: Task;

Task for publishing the package to the Test PyPI repository for testing purposes.

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <module>@<semver>

method addDevDependency

addDevDependency: (spec: string) => void;

Adds a dev dependency.
Parameter spec
Format <module>@<semver>

method installDependencies

installDependencies: () => void;

Installs dependencies (called during post-synthesis).

method setupEnvironment

setupEnvironment: () => void;

Initializes the virtual environment if it doesn't exist (called during post-synthesis).

class PoetryPyproject

class PoetryPyproject extends Component {}

Represents configuration of a pyproject.toml file for a Poetry project.
See Also
- https://python-poetry.org/docs/pyproject/

constructor

constructor(project: Project, options: PoetryPyprojectOptions);

property file

readonly file: TomlFile;

class Projenrc

class Projenrc extends ProjenrcFile {}

Allows writing projenrc files in python.
This will install projen as a Python dependency and will add a synth task which will run .projenrc.py.

constructor

constructor(project: Project, options?: ProjenrcOptions);

property filePath

readonly filePath: string;

The name of the projenrc file.

property pythonExec

readonly pythonExec: string;

Path to the python executable to use.

class Pytest

class Pytest extends Component {}

constructor

constructor(project: Project, options?: PytestOptions);

property testdir

readonly testdir: string;

Deprecated
Use sampleTestdir on the project instead.

property testMatch

readonly testMatch: string[];

class PytestSample

class PytestSample extends Component {}

Python test code sample.

constructor

constructor(project: Project, options: PytestSampleOptions);

class PythonProject

class PythonProject extends GitHubProject {}

Python project.
python

constructor

constructor(options: PythonProjectOptions);

property depsManager

readonly depsManager: IPythonDeps;

API for managing dependencies.

property envManager

readonly envManager: IPythonEnv;

API for mangaging the Python runtime environment.

property moduleName

readonly moduleName: string;

Python module name (the project name, with any hyphens or periods replaced with underscores).

property packagingManager

readonly packagingManager?: IPythonPackaging;

API for managing packaging the project as a library. Only applies when the projectType is LIB.

property pytest

pytest?: Pytest;

Pytest component.

property sampleTestdir

readonly sampleTestdir: string;

Directory where sample tests are located. "tests"

property version

readonly version: string;

Version of the package for distribution (should follow semver).

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <module>@<semver>

method addDevDependency

addDevDependency: (spec: string) => void;

Adds a dev dependency.
Parameter spec
Format <module>@<semver>

method postSynthesize

postSynthesize: () => void;

class PythonSample

class PythonSample extends Component {}

Python code sample.

constructor

constructor(project: Project, options: PythonSampleOptions);

class RequirementsFile

class RequirementsFile extends FileBase {}

Specifies a list of packages to be installed using pip.
See Also
- https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format

constructor

constructor(
    project: Project,
    filePath: string,
    options: RequirementsFileOptions
);

method addPackages

addPackages: (...packages: string[]) => void;

Adds the specified packages provided in semver format.
Comment lines (start with #) are ignored.
Parameter packages
Package version in format <module>@<semver>

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

class SetupPy

class SetupPy extends FileBase {}

Python packaging script where package metadata can be placed.

constructor

constructor(project: Project, options: SetupPyOptions);

method synthesizeContent

protected synthesizeContent: (resolver: IResolver) => string | undefined;

class Setuptools

class Setuptools extends Component implements IPythonPackaging {}

Manages packaging through setuptools with a setup.py script.

constructor

constructor(project: Project, options: SetuptoolsOptions);

property publishTask

readonly publishTask: Task;

property publishTestTask

readonly publishTestTask: Task;

A task that uploads the package to the Test PyPI repository.

class Venv

class Venv extends Component implements IPythonEnv {}

Manages a virtual environment through the Python venv module.

constructor

constructor(project: Project, options?: VenvOptions);

method setupEnvironment

setupEnvironment: () => void;

Initializes the virtual environment if it doesn't exist (called during post-synthesis).

interface IPackageProvider

interface IPackageProvider {}

property packages

readonly packages: Dependency[];

An array of packages (may be dynamically generated).

interface IPythonDeps

interface IPythonDeps {}

property installCiTask

readonly installCiTask: Task;

A task that installs and updates dependencies.

method addDependency

addDependency: (spec: string) => void;

Adds a runtime dependency.
Parameter spec
Format <module>@<semver>

method addDevDependency

addDevDependency: (spec: string) => void;

Adds a dev dependency.
Parameter spec
Format <module>@<semver>

method installDependencies

installDependencies: () => void;

Installs dependencies (called during post-synthesis).

interface IPythonEnv

interface IPythonEnv {}

method setupEnvironment

setupEnvironment: () => void;

Initializes the virtual environment if it doesn't exist (called during post-synthesis).

interface IPythonPackaging

interface IPythonPackaging {}

property publishTask

readonly publishTask: Task;

A task that uploads the package to a package repository.

interface PipOptions

interface PipOptions {}

Options for pip

interface PoetryOptions

interface PoetryOptions extends PythonPackagingOptions, PythonExecutableOptions {}

interface PoetryPyprojectOptions

interface PoetryPyprojectOptions extends PoetryPyprojectOptionsWithoutDeps {}

Poetry-specific options.
See Also
- https://python-poetry.org/docs/pyproject/

property dependencies

readonly dependencies?: {
    [key: string]: any;
};

A list of dependencies for the project.
The python version for which your package is compatible is also required.
Example 1
{ requests: "^2.13.0" }

property devDependencies

readonly devDependencies?: {
    [key: string]: any;
};

A list of development dependencies for the project.
Example 1
{ requests: "^2.13.0" }

interface PoetryPyprojectOptionsWithoutDeps

interface PoetryPyprojectOptionsWithoutDeps {}

Poetry-specific options.
See Also
- https://python-poetry.org/docs/pyproject/

property authors

readonly authors?: string[];

The authors of the package. Must be in the form "name "

property classifiers

readonly classifiers?: string[];

A list of PyPI trove classifiers that describe the project.
See Also
- https://pypi.org/classifiers/

property description

readonly description?: string;

A short description of the package (required).

property documentation

readonly documentation?: string;

A URL to the documentation of the project.

property exclude

readonly exclude?: string[];

A list of patterns that will be excluded in the final package.
If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (.gitignore for git for example).

property extras

readonly extras?: {
    [key: string]: string[];
};

Package extras

property homepage

readonly homepage?: string;

A URL to the website of the project.

property include

readonly include?: string[];

A list of patterns that will be included in the final package.

property keywords

readonly keywords?: string[];

A list of keywords (max: 5) that the package is related to.

property license

readonly license?: string;

License of this package as an SPDX identifier.
If the project is proprietary and does not use a specific license, you can set this value as "Proprietary".

property maintainers

readonly maintainers?: string[];

the maintainers of the package. Must be in the form "name "

property name

readonly name?: string;

Name of the package (required).

property packageMode

readonly packageMode?: boolean;

Package mode (optional).
Example 1
false
See Also
- https://python-poetry.org/docs/pyproject/#package-mode true

property packages

readonly packages?: any[];

A list of packages and modules to include in the final distribution.

property plugins

readonly plugins?: any;

Plugins. Must be specified as a table.
See Also
- https://toml.io/en/v1.0.0#table

property readme

readonly readme?: string;

The name of the readme file of the package.

property repository

readonly repository?: string;

A URL to the repository of the project.

property scripts

readonly scripts?: {
    [key: string]: any;
};

The scripts or executables that will be installed when installing the package.

property source

readonly source?: any[];

Source registries from which packages are retrieved.

property urls

readonly urls?: {
    [key: string]: string;
};

Project custom URLs, in addition to homepage, repository and documentation. E.g. "Bug Tracker"

property version

readonly version?: string;

Version of the package (required).

interface ProjenrcOptions

interface ProjenrcOptions {}

Options for Projenrc.

property filename

readonly filename?: string;

The name of the projenrc file. ".projenrc.py"

property projenVersion

readonly projenVersion?: string;

The projen version to use - current version

property pythonExec

readonly pythonExec?: string;

Path to the python executable to use. "python"

interface PytestOptions

interface PytestOptions {}

property maxFailures

readonly maxFailures?: number;

Stop the testing process after the first N failures

property testdir

readonly testdir?: string;

Location of sample tests. Typically the same directory where project tests will be located.
"tests"
Deprecated
Reference sampleTestdir on the project instead; to change the directory where tests are discovered from, use testMatch.

property testMatch

readonly testMatch?: string[];

List of paths to test files or directories. Useful when all project tests are in a known location to speed up test collection and to avoid picking up undesired tests by accident.
Leave empty to discover all test_*.py or *_test.py files, per Pytest default.
The array will be concatenated and passed as a single argument to pytest.
Example 1
["tests/unit", "tests/qa"] []

property version

readonly version?: string;

Pytest version
"7.4.3"

interface PytestSampleOptions

interface PytestSampleOptions {}

Options for python test code sample.

property moduleName

readonly moduleName: string;

Name of the python package as used in imports and filenames.

property testdir

readonly testdir: string;

Test directory

interface PythonExecutableOptions

interface PythonExecutableOptions {}

property pythonExec

readonly pythonExec?: string;

Path to the python executable to use. "python"

interface PythonPackagingOptions

interface PythonPackagingOptions {}

property authorEmail

readonly authorEmail: string;

Author's e-mail
$GIT_USER_EMAIL

property authorName

readonly authorName: string;

Author's name
$GIT_USER_NAME

property classifiers

readonly classifiers?: string[];

A list of PyPI trove classifiers that describe the project.
See Also
- https://pypi.org/classifiers/

property description

readonly description?: string;

A short description of the package.

property homepage

readonly homepage?: string;

A URL to the website of the project.

property license

readonly license?: string;

License of this package as an SPDX identifier.

property packageName

readonly packageName?: string;

Package name.

property poetryOptions

readonly poetryOptions?: PoetryPyprojectOptionsWithoutDeps;

Additional options to set for poetry if using poetry

property setupConfig

readonly setupConfig?: {
    [key: string]: any;
};

Additional fields to pass in the setup() function if using setuptools

property version

readonly version: string;

Version of the package.
"0.1.0"

interface PythonProjectOptions

interface PythonProjectOptions
    extends GitHubProjectOptions,
        PythonPackagingOptions,
        PythonExecutableOptions {}

Options for PythonProject.

property deps

readonly deps?: string[];

List of runtime dependencies for this project.
Dependencies use the format: <module>@<semver>
Additional dependencies can be added via project.addDependency().
[]

property devDeps

readonly devDeps?: string[];

List of dev dependencies for this project.
Dependencies use the format: <module>@<semver>
Additional dependencies can be added via project.addDevDependency().
[]

property moduleName

readonly moduleName: string;

Name of the python package as used in imports and filenames.
Must only consist of alphanumeric characters and underscores.
$PYTHON_MODULE_NAME

property pip

readonly pip?: boolean;

Use pip with a requirements.txt file to track project dependencies.
- true, unless poetry is true, then false

property poetry

readonly poetry?: boolean;

Use poetry to manage your project dependencies, virtual environment, and (optional) packaging/publishing.
This feature is incompatible with pip, setuptools, or venv. If you set this option to true, then pip, setuptools, and venv must be set to false.
false

property projenrcJs

readonly projenrcJs?: boolean;

Use projenrc in javascript.
This will install projen as a JavaScript dependency and add a synth task which will run .projenrc.js.
false

property projenrcJsOptions

readonly projenrcJsOptions?: ProjenrcJsOptions;

Options related to projenrc in JavaScript. - default options

property projenrcPython

readonly projenrcPython?: boolean;

Use projenrc in Python.
This will install projen as a Python dependency and add a synth task which will run .projenrc.py.
true

property projenrcPythonOptions

readonly projenrcPythonOptions?: ProjenrcPythonOptions;

Options related to projenrc in python. - default options

property projenrcTs

readonly projenrcTs?: boolean;

Use projenrc in TypeScript.
This will create a tsconfig file (default: tsconfig.projen.json) and use ts-node in the default task to parse the project source files.
false

property projenrcTsOptions

readonly projenrcTsOptions?: ProjenrcTsOptions;

Options related to projenrc in TypeScript. - default options

property pytest

readonly pytest?: boolean;

Include pytest tests. true

property pytestOptions

readonly pytestOptions?: PytestOptions;

pytest options - defaults

property sample

readonly sample?: boolean;

Include sample code and test if the relevant directories don't exist. true

property sampleTestdir

readonly sampleTestdir?: string;

Location of sample tests. Typically the same directory where project tests will be located. "tests"

property setuptools

readonly setuptools?: boolean;

Use setuptools with a setup.py script for packaging and publishing.
- true, unless poetry is true, then false

property venv

readonly venv?: boolean;

Use venv to manage a virtual environment for installing dependencies inside.
- true, unless poetry is true, then false

property venvOptions

readonly venvOptions?: VenvOptions;

Venv options - defaults

interface PythonSampleOptions

interface PythonSampleOptions {}

Options for python sample code.

property dir

readonly dir: string;

Sample code directory

interface RequirementsFileOptions

interface RequirementsFileOptions {}

property packageProvider

readonly packageProvider?: IPackageProvider;

Provide a list of packages that can be dynamically updated.

interface SetupPyOptions

interface SetupPyOptions {}

Fields to pass in the setup() function of setup.py
See Also
- https://docs.python.org/3/distutils/setupscript.html

property additionalOptions

readonly additionalOptions?: {
    [name: string]: any;
};

Escape hatch to allow any value

property authorEmail

readonly authorEmail?: string;

Author's e-mail

property authorName

readonly authorName?: string;

Author's name

property classifiers

readonly classifiers?: string[];

A list of PyPI trove classifiers that describe the project.
See Also
- https://pypi.org/classifiers/

property description

readonly description?: string;

A short project description

property homepage

readonly homepage?: string;

Package's Homepage / Website

property license

readonly license?: string;

The project license

property name

readonly name?: string;

Name of the package

property packages

readonly packages?: string[];

List of submodules to be packaged

property version

readonly version?: string;

Manually specify package version

index signature

readonly [name: string]: any;

Escape hatch to allow any value (JS/TS only)
Deprecated
Prefer using additionalOptions instead.
ignore

interface SetuptoolsOptions

interface SetuptoolsOptions
    extends PythonPackagingOptions,
        PythonExecutableOptions {}

interface VenvOptions

interface VenvOptions {}

Options for venv.

property envdir

readonly envdir?: string;

Name of directory to store the environment in
".env"

property pythonExec

readonly pythonExec?: string;

Path to the python executable to use. "python"

namespace release

module 'lib/release/index.d.ts' {}

function isAwsCodeArtifactRegistry

isAwsCodeArtifactRegistry: (
    registryUrl: string | undefined
) => boolean | '' | undefined;

Evaluates if the registryUrl is a AWS CodeArtifact registry.
Parameter registryUrl
url of registry
Returns
true for AWS CodeArtifact

class Publisher

class Publisher extends Component {}

Implements GitHub jobs for publishing modules to package managers.
Under the hood, it uses https://github.com/aws/publib

constructor

constructor(project: Project, options: PublisherOptions);

property artifactName

readonly artifactName: string;

property buildJobId

readonly buildJobId: string;

property condition

readonly condition?: string;

property jsiiReleaseVersion

readonly jsiiReleaseVersion: string;

Deprecated
use publibVersion

property publibVersion

readonly publibVersion: string;

property PUBLISH_GIT_TASK_NAME

static readonly PUBLISH_GIT_TASK_NAME: string;

method addGitHubPostPublishingSteps

addGitHubPostPublishingSteps: (...steps: JobStep[]) => void;

Adds post publishing steps for the GitHub release job.
Parameter steps
The steps.

method addGitHubPrePublishingSteps

addGitHubPrePublishingSteps: (...steps: JobStep[]) => void;

Adds pre publishing steps for the GitHub release job.
Parameter steps
The steps.

method publishToGit

publishToGit: (options: GitPublishOptions) => import('..').Task;

Publish to git.
This includes generating a project-level changelog and release tags.
Parameter options
Options

method publishToGitHubReleases

publishToGitHubReleases: (options: GitHubReleasesPublishOptions) => void;

Creates a GitHub Release.
Parameter options
Options

method publishToGo

publishToGo: (options?: GoPublishOptions) => void;

Adds a go publishing job.
Parameter options
Options

method publishToMaven

publishToMaven: (options?: MavenPublishOptions) => void;

Publishes artifacts from java/** to Maven.
Parameter options
Options

method publishToNpm

publishToNpm: (options?: NpmPublishOptions) => void;

Publishes artifacts from js/** to npm.
Parameter options
Options

projen

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Enums

Namespaces

Variables

variable CHANGES_SINCE_LAST_RELEASE

Functions

function filteredRunsOnOptions

function filteredWorkflowRunsOnOptions

Classes

class Component

Parameter project

Parameter id

constructor

property project

method isComponent

method postSynthesize

method preSynthesize

method synthesize

class Dependencies

constructor

Parameter project

property all

property MANIFEST_FILE

method addDependency

Parameter spec

Parameter type

method getDependency

Parameter name

Parameter type

Returns

method isDependencySatisfied

Parameter name

Parameter type

Parameter expectedRange

Returns

method parseDependency

method removeDependency

Parameter name

Parameter type

method tryGetDependency

Parameter name

Parameter type

Returns

class DevEnvironmentDockerImage

property dockerFile

property image

method fromFile

Parameter dockerFile

Example 1

method fromImage

Parameter image

Example 1

class DockerCompose

constructor

property file

method addService

Parameter serviceName

Parameter description

method bindVolume

Parameter sourcePath

Parameter targetPath

method namedVolume

Parameter volumeName

Parameter targetPath

Parameter options

method network

Parameter networkName

Parameter options

method portMapping

Parameter publishedPort

Parameter targetPort

Parameter options

method serviceName