API Reference

Submodules

The following submodules are available:

Constructs

AiInstructions

Generates instruction files for AI coding assistants with projen-specific guidance.

This component creates configuration files that help AI tools like GitHub Copilot, Cursor IDE, Claude Code, and Amazon Q understand that the project is managed by projen and should follow projen conventions.

Example

const project = new TypeScriptProject({
  name: "my-project",
});

// Basic usage - generates files for all supported AI agents
new AiInstructions(project);

// Custom usage - specify which agents and add custom instructions
new AiInstructions(project, {
  agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR],
  agentSpecificInstructions: {
    [AiAgent.GITHUB_COPILOT]: ["Always use descriptive commit messages."],
  },
});

// Add more instructions after instantiation
const ai = new AiInstructions(project);
ai.addInstructions("Use functional programming patterns.");
ai.addInstructions("Always write comprehensive tests.");

Initializers

import { AiInstructions } from 'projen'

new AiInstructions(project: Project, options?: AiInstructionsOptions)

Name	Type	Description
`project`	`Project`	No description.
`options`	`AiInstructionsOptions`	No description.

`project`^Required

Type: Project

`options`^Optional

Type: AiInstructionsOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`addAgentSpecificInstructions`	Add instructions for a specific AI agent.
`addInstructions`	Adds instructions that will be included for all selected AI agents.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

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

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

It does not run on later projen invocations. It only fires for projen new (or Projects.createProject). It is also skipped when post-synthesis steps are disabled, e.g. --no-post or PROJEN_DISABLE_POST. Use it for one-off setup that can be turned off by the user, like running a task to give the user immediate feedback on their new project. Order across components is not guaranteed.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

It does not run on later projen invocations. It only fires for projen new (or Projects.createProject). Use it for deterministic, one-off file generation. Order across components is not guaranteed.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`addAgentSpecificInstructions`

public addAgentSpecificInstructions(agent: AiAgent, instructions: ...string[]): void

Add instructions for a specific AI agent.

This can also be used to add instructions for an AI agent that was previously not enabled.

Example

aiInstructions.addAgentSpecificInstructions(AiAgent.GITHUB_COPILOT, "Use descriptive commit messages.");

`agent`^Required

Type: AiAgent

The AI agent to add instructions for.

`instructions`^Required

Type: ...string[]

The instruction(s) to add.

`addInstructions`

public addInstructions(instructions: ...string[]): void

Adds instructions that will be included for all selected AI agents.

Example

aiInstructions.addInstructions("Always use TypeScript strict mode.");
aiInstructions.addInstructions("Prefer functional programming.", "Avoid mutations.");

`instructions`^Required

Type: ...string[]

The instructions to add.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`bestPractices`	Returns development best practices instructions for AI agents.
`projen`	Returns projen-specific instructions for AI agents.

`isConstruct`

import { AiInstructions } from 'projen'

AiInstructions.isConstruct(x: any)

Checks if x is a construct.

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

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

`x`^Required

Type: any

Any object.

`isComponent`

import { AiInstructions } from 'projen'

AiInstructions.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`bestPractices`

import { AiInstructions } from 'projen'

AiInstructions.bestPractices(project: Project)

Returns development best practices instructions for AI agents.

`project`^Required

Type: Project

`projen`

import { AiInstructions } from 'projen'

AiInstructions.projen(project: Project)

Returns projen-specific instructions for AI agents.

`project`^Required

Type: Project

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

AiInstructionsFile

Initializers

import { AiInstructionsFile } from 'projen'

new AiInstructionsFile(scope: IConstruct, filePath: string, options?: FileBaseOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`FileBaseOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Optional

Type: FileBaseOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addInstructions`	Adds instructions to the instruction file.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addInstructions`

public addInstructions(instructions: ...string[]): void

Adds instructions to the instruction file.

`instructions`^Required

Type: ...string[]

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { AiInstructionsFile } from 'projen'

AiInstructionsFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { AiInstructionsFile } from 'projen'

AiInstructionsFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

Component

Represents a project component.

Initializers

import { Component } from 'projen'

new Component(scope: IConstruct, id?: string)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`id`	`string`	No description.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Component } from 'projen'

Component.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Component } from 'projen'

Component.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

Dependencies

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:

Initializers

import { Dependencies } from 'projen'

new Dependencies(project: Project)

Name	Type	Description
`project`	`Project`	The parent project.

`project`^Required

Type: Project

The parent project.

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`addDependency`	Adds a dependency to this project.
`getDependency`	Returns a dependency by name.
`isDependencySatisfied`	Checks if an existing dependency satisfies a dependency requirement.
`removeDependency`	Removes a dependency.
`requestDependency`	Request a dependency. Unlike `addDependency`, this merges intelligently with existing dependencies of the same name and type:.
`tryGetDependency`	Returns a dependency by name.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`addDependency`

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

Adds a dependency to this project.

`spec`^Required

Type: string

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).

`type`^Required

Type: DependencyType

The type of the dependency.

`metadata`^Optional

Type: {[ key: string ]: any}

`getDependency`

public 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.

`name`^Required

Type: string

The name of the dependency.

`type`^Optional

Type: DependencyType

The dependency type.

If this dependency is defined only for a single type, this argument can be omitted.

`isDependencySatisfied`

public isDependencySatisfied(name: string, type: DependencyType, expectedRange: string): boolean

Checks if an existing dependency satisfies a dependency requirement.

`name`^Required

Type: string

The name of the dependency to check (without the version).

`type`^Required

Type: DependencyType

The dependency type.

`expectedRange`^Required

Type: string

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.

`removeDependency`

public removeDependency(name: string, type?: DependencyType): void

Removes a dependency.

`name`^Required

Type: string

The name of the module to remove (without the version).

`type`^Optional

Type: DependencyType

The dependency type.

This is only required if there the dependency is defined for multiple types.

`requestDependency`

public requestDependency(request: DependencyRequest): Dependency

Request a dependency. Unlike addDependency, this merges intelligently with existing dependencies of the same name and type:.

If the dep exists with a version that already satisfies the request, the version is not changed.

If the dep doesn't exist, it is added with the requested type/version.
If the dep exists but the versions don't intersect, an error is thrown.
If no type is provided, an existing dependency of any type will satisfy the request. If none exists, it is added as BUILD.

`request`^Required

Type: DependencyRequest

The dependency request.

`tryGetDependency`

public tryGetDependency(name: string, type?: DependencyType): Dependency

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.

`name`^Required

Type: string

The name of the dependency.

`type`^Optional

Type: DependencyType

The dependency type.

If this dependency is defined only for a single type, this argument can be omitted.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`parseDependency`	Returns the coordinates of a dependency spec.

`isConstruct`

import { Dependencies } from 'projen'

Dependencies.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Dependencies } from 'projen'

Dependencies.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`parseDependency`

import { Dependencies } from 'projen'

Dependencies.parseDependency(spec: string)

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" }.

`spec`^Required

Type: string

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`all`	`Dependency[]`	A copy of all dependencies recorded for this project.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`all`^Required

public readonly all: Dependency[];

Type: Dependency[]

A copy of all dependencies recorded for this project.

The list is sorted by type->name->version

Constants

Name	Type	Description
`MANIFEST_FILE`	`string`	The project-relative path of the deps manifest file.

`MANIFEST_FILE`^Required

public readonly MANIFEST_FILE: string;

Type: string

The project-relative path of the deps manifest file.

DockerCompose

Create a docker-compose YAML file.

Initializers

import { DockerCompose } from 'projen'

new DockerCompose(project: Project, props?: DockerComposeProps)

Name	Type	Description
`project`	`Project`	No description.
`props`	`DockerComposeProps`	No description.

`project`^Required

Type: Project

`props`^Optional

Type: DockerComposeProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`addService`	Add a service to the docker-compose file.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`addService`

public addService(serviceName: string, description: DockerComposeServiceDescription): DockerComposeService

Add a service to the docker-compose file.

`serviceName`^Required

Type: string

name of the service.

`description`^Required

Type: DockerComposeServiceDescription

a service description.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`bindVolume`	Create a bind volume that binds a host path to the target path in the container.
`namedVolume`	Create a named volume and mount it to the target path.
`network`	Create a named network and mount it to the target path.
`portMapping`	Create a port mapping.
`serviceName`	Depends on a service name.

`isConstruct`

import { DockerCompose } from 'projen'

DockerCompose.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { DockerCompose } from 'projen'

DockerCompose.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`bindVolume`

import { DockerCompose } from 'projen'

DockerCompose.bindVolume(sourcePath: string, targetPath: string)

Create a bind volume that binds a host path to the target path in the container.

`sourcePath`^Required

Type: string

Host path name.

`targetPath`^Required

Type: string

Target path name.

`namedVolume`

import { DockerCompose } from 'projen'

DockerCompose.namedVolume(volumeName: string, targetPath: string, options?: DockerComposeVolumeConfig)

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.

`volumeName`^Required

Type: string

Name of the volume.

`targetPath`^Required

Type: string

Target path.

`options`^Optional

Type: DockerComposeVolumeConfig

volume configuration (default: docker compose defaults).

`network`

import { DockerCompose } from 'projen'

DockerCompose.network(networkName: string, options?: DockerComposeNetworkConfig)

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.

`networkName`^Required

Type: string

Name of the network.

`options`^Optional

Type: DockerComposeNetworkConfig

network configuration.

`portMapping`

import { DockerCompose } from 'projen'

DockerCompose.portMapping(publishedPort: number, targetPort: number, options?: DockerComposePortMappingOptions)

Create a port mapping.

`publishedPort`^Required

Type: number

Published port number.

`targetPort`^Required

Type: number

Container's port number.

`options`^Optional

Type: DockerComposePortMappingOptions

Port mapping options.

`serviceName`

import { DockerCompose } from 'projen'

DockerCompose.serviceName(serviceName: string)

Depends on a service name.

`serviceName`^Required

Type: string

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`file`	`YamlFile`	The Docker Compose file.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`file`^Required

public readonly file: YamlFile;

Type: YamlFile

The Docker Compose file.

FileBase

Initializers

import { FileBase } from 'projen'

new FileBase(scope: IConstruct, filePath: string, options?: FileBaseOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`FileBaseOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Optional

Type: FileBaseOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { FileBase } from 'projen'

FileBase.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { FileBase } from 'projen'

FileBase.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

FutureComponent

A {@link Component} that is created detached from any project and attached to one later via {@link FutureComponent.attach}.

Like a regular component, but constructed without a project. It improves on a naive deferred component in three ways:

Use-before-attach is an error, not a silent footgun. The constructor hands the caller a guard proxy; touching project, node, synthesize() or any subclass feature before attach() throws.
No global shadow-tree leak. Each instance gets its own throwaway shadow root, so detached components never share an id counter and the root becomes garbage once the component is reparented on attach.
attach() returns the unwrapped component, so callers can opt out of the proxy entirely.

The constructor takes no arguments (super()). A subclass that needs options captures them itself, reading the local parameter inside its constructor - NOT this.options, which the guard blocks until attach.

class Worker extends FutureComponent {
  private readonly options: WorkerOptions;
  constructor(options: WorkerOptions = {}) {
    super();
    this.options = options; // set: allowed
  }
  protected init() {
    // this.project is available here
  }
}

const w = new Worker({ retries: 3 });
// w.project;                  // throws: not attached yet
const real = w.attach(project); // reparents, runs init(), returns the bare instance

Initializers

import { FutureComponent } from 'projen'

new FutureComponent()

Name	Type	Description

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`attach`	Attach the component to a scope. Only now does it become usable.
`tryAttach`	Attach the component if it isn't already, without caring where.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`attach`

public attach(scope: IConstruct, id?: string): FutureComponent

Attach the component to a scope. Only now does it become usable.

Returns the real, unwrapped component (not the proxy). A component may be attached exactly once; attaching an already-attached component throws (copy it first to attach a variant elsewhere). Use tryAttach() if you don't care whether it has already been attached.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

`tryAttach`

public tryAttach(scope: IConstruct, id?: string): FutureComponent

Attach the component if it isn't already, without caring where.

Unlike attach(), never throws on an already-attached component: if attached anywhere at all, the existing instance is returned and scope is ignored. Use attach() when attaching to a specific scope is part of your contract and a pre-existing attachment elsewhere would be a bug.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { FutureComponent } from 'projen'

FutureComponent.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { FutureComponent } from 'projen'

FutureComponent.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`attached`	`boolean`	Whether `attach()` has been called.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`attached`^Required

public readonly attached: boolean;

Type: boolean

Whether attach() has been called.

A convenience for tests/introspection; prefer tryAttach() over reading this and branching.

GitAttributesFile

Assign attributes to file names in a git repository.

https://git-scm.com/docs/gitattributes

Initializers

import { GitAttributesFile } from 'projen'

new GitAttributesFile(scope: IConstruct, options?: GitAttributesFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`GitAttributesFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Optional

Type: GitAttributesFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addAttributes`	Maps a set of attributes to a set of files.
`addLfsPattern`	Add attributes necessary to mark these files as stored in LFS.
`removeAttributes`	Removes attributes from a set of files.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addAttributes`

public addAttributes(glob: string, attributes: ...string[]): void

Maps a set of attributes to a set of files.

`glob`^Required

Type: string

Glob pattern to match files in the repo.

`attributes`^Required

Type: ...string[]

Attributes to assign to these files.

`addLfsPattern`

public addLfsPattern(glob: string): void

Add attributes necessary to mark these files as stored in LFS.

`glob`^Required

Type: string

`removeAttributes`

public removeAttributes(glob: string, attributes: ...string[]): void

Removes attributes from a set of files.

If no attributes are provided, the glob pattern will be removed completely.

`glob`^Required

Type: string

Glob pattern to modify.

`attributes`^Required

Type: ...string[]

Attributes to remove from matched files.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { GitAttributesFile } from 'projen'

GitAttributesFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { GitAttributesFile } from 'projen'

GitAttributesFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`endOfLine`	`EndOfLine`	The default end of line character for text files.
`hasLfsPatterns`	`boolean`	Whether the current gitattributes file has any LFS patterns.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`endOfLine`^Required

public readonly endOfLine: EndOfLine;

Type: EndOfLine

The default end of line character for text files.

`hasLfsPatterns`^Required

public readonly hasLfsPatterns: boolean;

Type: boolean

Whether the current gitattributes file has any LFS patterns.

Gitpod

Implements: IDevEnvironment

The Gitpod component which emits .gitpod.yml.

Initializers

import { Gitpod } from 'projen'

new Gitpod(project: Project, options?: GitpodOptions)

Name	Type	Description
`project`	`Project`	No description.
`options`	`GitpodOptions`	No description.

`project`^Required

Type: Project

`options`^Optional

Type: GitpodOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`addCustomTask`	Add a task with more granular options.
`addDockerImage`	Add a custom Docker image or Dockerfile for the container.
`addPorts`	Add ports that should be exposed (forwarded) from the container.
`addPrebuilds`	Add a prebuilds configuration for the Gitpod App.
`addTasks`	Add tasks to run when gitpod starts.
`addVscodeExtensions`	Add a list of VSCode extensions that should be automatically installed in the container.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`addCustomTask`

public 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.

`options`^Required

Type: GitpodTask

The task parameters.

`addDockerImage`

public addDockerImage(image: DevEnvironmentDockerImage): void

Add a custom Docker image or Dockerfile for the container.

`image`^Required

Type: DevEnvironmentDockerImage

The Docker image.

`addPorts`

public addPorts(ports: ...string[]): void

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

`ports`^Required

Type: ...string[]

The new ports.

`addPrebuilds`

public addPrebuilds(config: GitpodPrebuilds): void

Add a prebuilds configuration for the Gitpod App.

`config`^Required

Type: GitpodPrebuilds

The configuration.

`addTasks`

public 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.

`tasks`^Required

Type: ...Task[]

The new tasks.

`addVscodeExtensions`

public addVscodeExtensions(extensions: ...string[]): 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.

https://www.gitpod.io/docs/vscode-extensions/

Example

'scala-lang.scala@0.3.9:O5XmjwY5Gz+0oDZAmqneJw=='

`extensions`^Required

Type: ...string[]

The extension IDs.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Gitpod } from 'projen'

Gitpod.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Gitpod } from 'projen'

Gitpod.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`config`	`any`	Direct access to the gitpod configuration (escape hatch).

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`config`^Required

public readonly config: any;

Type: any

Direct access to the gitpod configuration (escape hatch).

IgnoreFile

Initializers

import { IgnoreFile } from 'projen'

new IgnoreFile(project: Project, filePath: string, options?: IgnoreFileOptions)

Name	Type	Description
`project`	`Project`	The project to tie this file to.
`filePath`	`string`	- the relative path in the project to put the file.
`options`	`IgnoreFileOptions`	No description.

`project`^Required

Type: Project

The project to tie this file to.

`filePath`^Required

Type: string

the relative path in the project to put the file.

`options`^Optional

Type: IgnoreFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addPatterns`	Add ignore patterns.
`exclude`	Ignore the files that match these patterns.
`include`	Always include the specified file patterns.
`removePatterns`	Removes patterns previously added from the ignore file.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addPatterns`

public 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.

`patterns`^Required

Type: ...string[]

Ignore patterns.

`exclude`

public exclude(patterns: ...string[]): void

Ignore the files that match these patterns.

`patterns`^Required

Type: ...string[]

The patterns to match.

`include`

public include(patterns: ...string[]): void

Always include the specified file patterns.

`patterns`^Required

Type: ...string[]

Patterns to include in git commits.

`removePatterns`

public removePatterns(patterns: ...string[]): void

Removes patterns previously added from the ignore file.

If addPattern() is called after this, the pattern will be added again.

`patterns`^Required

Type: ...string[]

patters to remove.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { IgnoreFile } from 'projen'

IgnoreFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { IgnoreFile } from 'projen'

IgnoreFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`filterCommentLines`	`boolean`	No description.
`filterEmptyLines`	`boolean`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`filterCommentLines`^Required

public readonly filterCommentLines: boolean;

Type: boolean

`filterEmptyLines`^Required

public readonly filterEmptyLines: boolean;

Type: boolean

IniFile

Represents an INI file.

Initializers

import { IniFile } from 'projen'

new IniFile(project: Project, filePath: string, options: IniFileOptions)

Name	Type	Description
`project`	`Project`	No description.
`filePath`	`string`	No description.
`options`	`IniFileOptions`	No description.

`project`^Required

Type: Project

`filePath`^Required

Type: string

`options`^Required

Type: IniFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { IniFile } from 'projen'

IniFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { IniFile } from 'projen'

IniFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

JsonFile

Represents a JSON file.

Initializers

import { JsonFile } from 'projen'

new JsonFile(scope: IConstruct, filePath: string, options: JsonFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`JsonFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Required

Type: JsonFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { JsonFile } from 'projen'

JsonFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { JsonFile } from 'projen'

JsonFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.
`supportsComments`	`boolean`	Indicates if the files supports comments.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

`supportsComments`^Required

public readonly supportsComments: boolean;

Type: boolean

Indicates if the files supports comments.

License

Initializers

import { License } from 'projen'

new License(project: Project, options: LicenseOptions)

Name	Type	Description
`project`	`Project`	No description.
`options`	`LicenseOptions`	No description.

`project`^Required

Type: Project

`options`^Required

Type: LicenseOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { License } from 'projen'

License.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { License } from 'projen'

License.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

Logger

Project-level logging utilities.

Initializers

import { Logger } from 'projen'

new Logger(scope: IConstruct, options?: LoggerOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`LoggerOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Optional

Type: LoggerOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`debug`	Log a message to stderr with DEBUG severity.
`error`	Log a message to stderr with ERROR severity.
`info`	Log a message to stderr with INFO severity.
`log`	Log a message to stderr with a given logging level.
`verbose`	Log a message to stderr with VERBOSE severity.
`warn`	Log a message to stderr with WARN severity.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`debug`

public debug(text: ...any[]): void

Log a message to stderr with DEBUG severity.

`text`^Required

Type: ...any[]

strings or objects to print.

`error`

public error(text: ...any[]): void

Log a message to stderr with ERROR severity.

`text`^Required

Type: ...any[]

strings or objects to print.

`info`

public info(text: ...any[]): void

Log a message to stderr with INFO severity.

`text`^Required

Type: ...any[]

strings or objects to print.

`log`

public 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.

`level`^Required

Type: LogLevel

Logging verbosity.

`text`^Required

Type: ...any[]

strings or objects to print.

`verbose`

public verbose(text: ...any[]): void

Log a message to stderr with VERBOSE severity.

`text`^Required

Type: ...any[]

strings or objects to print.

`warn`

public warn(text: ...any[]): void

Log a message to stderr with WARN severity.

`text`^Required

Type: ...any[]

strings or objects to print.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Logger } from 'projen'

Logger.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Logger } from 'projen'

Logger.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

Makefile

Minimal Makefile.

Initializers

import { Makefile } from 'projen'

new Makefile(project: Project, filePath: string, options?: MakefileOptions)

Name	Type	Description
`project`	`Project`	No description.
`filePath`	`string`	No description.
`options`	`MakefileOptions`	No description.

`project`^Required

Type: Project

`filePath`^Required

Type: string

`options`^Optional

Type: MakefileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addAll`	Add a target to all.
`addAlls`	Add multiple targets to all.
`addRule`	Add a rule to the Makefile.
`addRules`	Add multiple rules to the Makefile.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addAll`

public addAll(target: string): Makefile

Add a target to all.

`target`^Required

Type: string

`addAlls`

public addAlls(targets: ...string[]): Makefile

Add multiple targets to all.

`targets`^Required

Type: ...string[]

`addRule`

public addRule(rule: Rule): Makefile

Add a rule to the Makefile.

`rule`^Required

Type: Rule

`addRules`

public addRules(rules: ...Rule[]): Makefile

Add multiple rules to the Makefile.

`rules`^Required

Type: ...Rule[]

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Makefile } from 'projen'

Makefile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Makefile } from 'projen'

Makefile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`rules`	`Rule[]`	List of rule definitions.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`rules`^Required

public readonly rules: Rule[];

Type: Rule[]

List of rule definitions.

ObjectFile

Represents an Object file.

Initializers

import { ObjectFile } from 'projen'

new ObjectFile(scope: IConstruct, filePath: string, options: ObjectFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`ObjectFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Required

Type: ObjectFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { ObjectFile } from 'projen'

ObjectFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ObjectFile } from 'projen'

ObjectFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

Project

Base project.

Initializers

import { Project } from 'projen'

new Project(options: ProjectOptions)

Name	Type	Description
`options`	`ProjectOptions`	No description.

`options`^Required

Type: ProjectOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`addExcludeFromCleanup`	Exclude the matching files from pre-synth cleanup.
`addGitIgnore`	Adds a .gitignore pattern.
`addPackageIgnore`	Exclude these files from the bundled package.
`addTask`	Adds a new task to this project.
`annotateGenerated`	Consider a set of files as "generated".
`postSynthesize`	Called after all components are synthesized.
`preSynthesize`	Called before all components are synthesized.
`removeTask`	Removes a task from a project.
`runTaskCommand`	Returns the shell command to execute in order to run a task.
`synth`	Synthesize all project files into `outdir`.
`tryFindFile`	Finds a file at the specified relative path within this project and all its subprojects.
`tryFindObjectFile`	Finds an object file (like JsonFile, YamlFile, etc.) by name.
`tryRemoveFile`	Finds a file at the specified relative path within this project and removes it.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`addExcludeFromCleanup`

public 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.

`globs`^Required

Type: ...string[]

The glob patterns to match.

`addGitIgnore`

public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

`pattern`^Required

Type: string

The glob pattern to ignore.

`addPackageIgnore`

public 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.

`_pattern`^Required

Type: string

The glob pattern to exclude.

`addTask`

public 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.

`name`^Required

Type: string

The task name to add.

`props`^Optional

Type: TaskOptions

Task properties.

`annotateGenerated`

public 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.

`_glob`^Required

Type: string

the glob pattern to match (could be a file path).

`postSynthesize`

public postSynthesize(): void

Called after all components are synthesized.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before all components are synthesized.

`removeTask`

public removeTask(name: string): Task

Removes a task from a project.

`name`^Required

Type: string

The name of the task to remove.

`runTaskCommand`

public runTaskCommand(task: Task): string

Returns the shell command to execute in order to run a task.

By default, this is npx projen@<version> <task>

`task`^Required

Type: Task

The task for which the command is required.

`synth`

public synth(): void

Synthesize all project files into outdir.

Call "this.preSynthesize()"
Delete all generated files
Synthesize all subprojects
Synthesize all components of this project
Call "projectCreation()" for all components, only if the project is being created for the first time
Call "postSynthesize()" for all components of this project
Call "this.postSynthesize()"
Call "postProjectCreation()" for all components, only if the project is being created for the first time

`tryFindFile`

public tryFindFile(filePath: string): FileBase

Finds a file at the specified relative path within this project and all its subprojects.

`filePath`^Required

Type: string

The file path.

If this path is relative, it will be resolved from the root of this project.

`tryFindObjectFile`

public tryFindObjectFile(filePath: string): ObjectFile

Finds an object file (like JsonFile, YamlFile, etc.) by name.

`filePath`^Required

Type: string

The file path.

`tryRemoveFile`

public tryRemoveFile(filePath: string): FileBase

Finds a file at the specified relative path within this project and removes it.

`filePath`^Required

Type: string

The file path.

If this path is relative, it will be resolved from the root of this project.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isProject`	Test whether the given construct is a project.
`of`	Find the closest ancestor project for given construct.

`isConstruct`

import { Project } from 'projen'

Project.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isProject`

import { Project } from 'projen'

Project.isProject(x: any)

Test whether the given construct is a project.

`x`^Required

Type: any

`of`

import { Project } from 'projen'

Project.of(construct: IConstruct)

Find the closest ancestor project for given construct.

When given a project, this it the project itself.

`construct`^Required

Type: constructs.IConstruct

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`buildTask`	`Task`	No description.
`commitGenerated`	`boolean`	Whether to commit the managed files by default.
`compileTask`	`Task`	No description.
`components`	`Component[]`	Returns all the components within this project.
`deps`	`Dependencies`	Project dependencies.
`ejected`	`boolean`	Whether or not the project is being ejected.
`files`	`FileBase[]`	All files in this project.
`gitattributes`	`GitAttributesFile`	The .gitattributes file for this repository.
`gitignore`	`IgnoreFile`	.gitignore.
`logger`	`Logger`	Logging utilities.
`name`	`string`	Project name.
`outdir`	`string`	Absolute output directory of this project.
`packageTask`	`Task`	No description.
`postCompileTask`	`Task`	No description.
`preCompileTask`	`Task`	No description.
`projectBuild`	`ProjectBuild`	Manages the build process of the project.
`projenCommand`	`string`	The command to use in order to run the projen CLI.
`root`	`Project`	The root project.
`subprojects`	`Project[]`	Returns all the subprojects within this project.
`tasks`	`Tasks`	Project tasks.
`testTask`	`Task`	No description.
`defaultTask`	`Task`	This is the "default" task, the one that executes "projen".
`initProject`	`InitProject`	The options used when this project is bootstrapped via `projen new`.
`parent`	`Project`	A parent project.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`buildTask`^Required

public readonly buildTask: Task;

Type: Task

`commitGenerated`^Required

public readonly commitGenerated: boolean;

Type: boolean

Whether to commit the managed files by default.

`compileTask`^Required

public readonly compileTask: Task;

Type: Task

`components`^Required

public readonly components: Component[];

Type: Component[]

Returns all the components within this project.

`deps`^Required

public readonly deps: Dependencies;

Type: Dependencies

Project dependencies.

`ejected`^Required

public readonly ejected: boolean;

Type: boolean

Whether or not the project is being ejected.

`files`^Required

public readonly files: FileBase[];

Type: FileBase[]

All files in this project.

`gitattributes`^Required

public readonly gitattributes: GitAttributesFile;

Type: GitAttributesFile

The .gitattributes file for this repository.

`gitignore`^Required

public readonly gitignore: IgnoreFile;

Type: IgnoreFile

.gitignore.

`logger`^Required

public readonly logger: Logger;

Type: Logger

Logging utilities.

`name`^Required

public readonly name: string;

Type: string

Project name.

`outdir`^Required

public readonly outdir: string;

Type: string

Absolute output directory of this project.

`packageTask`^Required

public readonly packageTask: Task;

Type: Task

`postCompileTask`^Required

public readonly postCompileTask: Task;

Type: Task

`preCompileTask`^Required

public readonly preCompileTask: Task;

Type: Task

`projectBuild`^Required

public readonly projectBuild: ProjectBuild;

Type: ProjectBuild

Manages the build process of the project.

`projenCommand`^Required

public readonly projenCommand: string;

Type: string

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

`root`^Required

public readonly root: Project;

Type: Project

The root project.

`subprojects`^Required

public readonly subprojects: Project[];

Type: Project[]

Returns all the subprojects within this project.

`tasks`^Required

public readonly tasks: Tasks;

Type: Tasks

Project tasks.

`testTask`^Required

public readonly testTask: Task;

Type: Task

`defaultTask`^Optional

public readonly defaultTask: Task;

Type: Task

This is the "default" task, the one that executes "projen".

Undefined if the project is being ejected.

`initProject`^Optional

Deprecated: use the initProject argument passed to Component.projectCreation() instead.

public readonly initProject: InitProject;

Type: 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.

`parent`^Optional

public readonly parent: Project;

Type: Project

A parent project.

If undefined, this is the root project.

Constants

Name	Type	Description
`DEFAULT_TASK`	`string`	The name of the default task (the task executed when `projen` is run without arguments).

`DEFAULT_TASK`^Required

public readonly DEFAULT_TASK: string;

Type: string

The name of the default task (the task executed when projen is run without arguments).

Normally this task should synthesize the project files.

ProjectBuild

Manages a standard build process for all projects.

Build spawns these tasks in order:

default
pre-compile
compile
post-compile
test
package

Initializers

import { ProjectBuild } from 'projen'

new ProjectBuild(project: Project)

Name	Type	Description
`project`	`Project`	No description.

`project`^Required

Type: Project

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { ProjectBuild } from 'projen'

ProjectBuild.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ProjectBuild } from 'projen'

ProjectBuild.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`buildTask`	`Task`	The task responsible for a full release build.
`compileTask`	`Task`	Compiles the code.
`packageTask`	`Task`	The "package" task.
`postCompileTask`	`Task`	Post-compile task.
`preCompileTask`	`Task`	Pre-compile task.
`testTask`	`Task`	Tests the code.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`buildTask`^Required

public readonly buildTask: Task;

Type: Task

The task responsible for a full release build.

`compileTask`^Required

public readonly compileTask: Task;

Type: Task

Compiles the code.

By default for node.js projects this task is empty.

`packageTask`^Required

public readonly packageTask: Task;

Type: Task

The "package" task.

`postCompileTask`^Required

public readonly postCompileTask: Task;

Type: Task

Post-compile task.

`preCompileTask`^Required

public readonly preCompileTask: Task;

Type: Task

Pre-compile task.

`testTask`^Required

public readonly testTask: Task;

Type: Task

Tests the code.

ProjectTree

Generates a .projen/tree.json file that provides a snapshot of your project's component hierarchy. This file includes metadata about each component such as file paths, types, and the projen version used.

The tree file is helpful for:

Understanding how your project is structured
Debugging component relationships
Verifying which versions synthesized the project

Initializers

import { ProjectTree } from 'projen'

new ProjectTree(project: Project)

Name	Type	Description
`project`	`Project`	No description.

`project`^Required

Type: Project

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { ProjectTree } from 'projen'

ProjectTree.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ProjectTree } from 'projen'

ProjectTree.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`file`	`JsonFile`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`file`^Required

public readonly file: JsonFile;

Type: JsonFile

ProjenrcFile

A component representing the projen runtime configuration.

Initializers

import { ProjenrcFile } from 'projen'

new ProjenrcFile(scope: IConstruct, id?: string)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`id`	`string`	No description.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`of`	Returns the `Projenrc` instance associated with a project or `undefined` if there is no Projenrc.

`isConstruct`

import { ProjenrcFile } from 'projen'

ProjenrcFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ProjenrcFile } from 'projen'

ProjenrcFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`of`

import { ProjenrcFile } from 'projen'

ProjenrcFile.of(project: Project)

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

`project`^Required

Type: Project

The project.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`filePath`	`string`	The path of the projenrc file.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`filePath`^Required

public readonly filePath: string;

Type: string

The path of the projenrc file.

ProjenrcJson

Sets up a project to use JSON for projenrc.

Initializers

import { ProjenrcJson } from 'projen'

new ProjenrcJson(project: Project, options?: ProjenrcJsonOptions)

Name	Type	Description
`project`	`Project`	No description.
`options`	`ProjenrcJsonOptions`	No description.

`project`^Required

Type: Project

`options`^Optional

Type: ProjenrcJsonOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.
`of`	Returns the `Projenrc` instance associated with a project or `undefined` if there is no Projenrc.

`isConstruct`

import { ProjenrcJson } from 'projen'

ProjenrcJson.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ProjenrcJson } from 'projen'

ProjenrcJson.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

`of`

import { ProjenrcJson } from 'projen'

ProjenrcJson.of(project: Project)

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

`project`^Required

Type: Project

The project.

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`filePath`	`string`	The path of the projenrc file.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`filePath`^Required

public readonly filePath: string;

Type: string

The path of the projenrc file.

PropertiesFile

Represents a Java .properties file.

Properties files consist of key=value pairs, one per line, with # used for comments. This file format is commonly used by tools like SonarQube, Gradle, and other JVM-based ecosystem tools.

The object passed as obj can be a nested structure. Nested keys are flattened into dot-separated property keys on synthesis. For example, { sonar: { sources: "src" } } produces sonar.sources=src.

This means addOverride uses dot notation as a path separator, consistent with ObjectFile/JsonPatch semantics.

Example

new PropertiesFile(project, 'sonar-project.properties', {
  obj: {
    sonar: {
      projectKey: 'my-project',
      sources: 'src',
    },
  },
});

// Produces:
// sonar.projectKey=my-project
// sonar.sources=src

Initializers

import { PropertiesFile } from 'projen'

new PropertiesFile(scope: IConstruct, filePath: string, options: PropertiesFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`PropertiesFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Required

Type: PropertiesFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { PropertiesFile } from 'projen'

PropertiesFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { PropertiesFile } from 'projen'

PropertiesFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

Renovatebot

Defines renovatebot configuration for projen project.

Ignores the versions controlled by Projen.

Initializers

import { Renovatebot } from 'projen'

new Renovatebot(project: Project, options?: RenovatebotOptions)

Name	Type	Description
`project`	`Project`	No description.
`options`	`RenovatebotOptions`	No description.

`project`^Required

Type: Project

`options`^Optional

Type: RenovatebotOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Renovatebot } from 'projen'

Renovatebot.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Renovatebot } from 'projen'

Renovatebot.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`file`	`JsonFile`	The file holding the renovatebot configuration.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`file`^Required

public readonly file: JsonFile;

Type: JsonFile

The file holding the renovatebot configuration.

SampleDir

Renders the given files into the directory if the directory does not exist.

Use this to create sample code files

Initializers

import { SampleDir } from 'projen'

new SampleDir(project: Project, dir: string, options: SampleDirOptions)

Name	Type	Description
`project`	`Project`	Parent project to add files to.
`dir`	`string`	directory to add files to.
`options`	`SampleDirOptions`	options for which files to create.

`project`^Required

Type: Project

Parent project to add files to.

`dir`^Required

Type: string

directory to add files to.

If directory already exists, nothing is added.

`options`^Required

Type: SampleDirOptions

options for which files to create.

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { SampleDir } from 'projen'

SampleDir.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { SampleDir } from 'projen'

SampleDir.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

SampleFile

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.

Initializers

import { SampleFile } from 'projen'

new SampleFile(project: Project, filePath: string, options: SampleFileOptions)

Name	Type	Description
`project`	`Project`	- the project to tie this file to.
`filePath`	`string`	- the relative path in the project to put the file.
`options`	`SampleFileOptions`	- the options for the file.

`project`^Required

Type: Project

the project to tie this file to.

`filePath`^Required

Type: string

the relative path in the project to put the file.

`options`^Required

Type: SampleFileOptions

the options for the file.

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { SampleFile } from 'projen'

SampleFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { SampleFile } from 'projen'

SampleFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

SampleReadme

Represents a README.md sample file. You are expected to manage this file after creation.

Initializers

import { SampleReadme } from 'projen'

new SampleReadme(project: Project, props?: SampleReadmeProps)

Name	Type	Description
`project`	`Project`	No description.
`props`	`SampleReadmeProps`	No description.

`project`^Required

Type: Project

`props`^Optional

Type: SampleReadmeProps

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { SampleReadme } from 'projen'

SampleReadme.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { SampleReadme } from 'projen'

SampleReadme.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

ScriptRunner

Implements: IScriptRunner

A script runner that executes the entrypoint file directly.

A runner is a {@link FutureComponent}: it can be created standalone (e.g. in .projenrc.ts) and is attached to a project by whoever consumes it.

Initializers

import { ScriptRunner } from 'projen'

new ScriptRunner()

Name	Type	Description

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`attach`	Attach the component to a scope. Only now does it become usable.
`tryAttach`	Attach the component if it isn't already, without caring where.
`configFor`	Produce the configuration to run the given entrypoint.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`attach`

public attach(scope: IConstruct, id?: string): FutureComponent

Attach the component to a scope. Only now does it become usable.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

`tryAttach`

public tryAttach(scope: IConstruct, id?: string): FutureComponent

Attach the component if it isn't already, without caring where.

`scope`^Required

Type: constructs.IConstruct

`id`^Optional

Type: string

`configFor`

public configFor(entrypoint: string): RunScriptConfig

Produce the configuration to run the given entrypoint.

`entrypoint`^Required

Type: string

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { ScriptRunner } from 'projen'

ScriptRunner.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { ScriptRunner } from 'projen'

ScriptRunner.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`attached`	`boolean`	Whether `attach()` has been called.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`attached`^Required

public readonly attached: boolean;

Type: boolean

Whether attach() has been called.

A convenience for tests/introspection; prefer tryAttach() over reading this and branching.

SourceCode

Represents a source file.

Initializers

import { SourceCode } from 'projen'

new SourceCode(project: Project, filePath: string, options?: SourceCodeOptions)

Name	Type	Description
`project`	`Project`	No description.
`filePath`	`string`	No description.
`options`	`SourceCodeOptions`	No description.

`project`^Required

Type: Project

`filePath`^Required

Type: string

`options`^Optional

Type: SourceCodeOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`close`	Decreases the indentation level and closes a code block.
`line`	Emit a line of code.
`open`	Opens a code block and increases the indentation level.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`close`

public close(code?: string): void

Decreases the indentation level and closes a code block.

`code`^Optional

Type: string

The code after the block is closed (e.g. }).

`line`

public line(code?: string): void

Emit a line of code.

`code`^Optional

Type: string

The contents, if not specified, just adds a newline.

`open`

public open(code?: string): void

Opens a code block and increases the indentation level.

`code`^Optional

Type: string

The code before the block starts (e.g. export class {).

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { SourceCode } from 'projen'

SourceCode.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { SourceCode } from 'projen'

SourceCode.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`filePath`	`string`	No description.
`marker`	`string`	No description.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`filePath`^Required

public readonly filePath: string;

Type: string

`marker`^Optional

public readonly marker: string;

Type: string

Tasks

Defines and manages project tasks.

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

Initializers

import { Tasks } from 'projen'

new Tasks(project: Project)

Name	Type	Description
`project`	`Project`	No description.

`project`^Required

Type: Project

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`addEnvironment`	Adds global environment.
`addTask`	Adds a task to a project.
`removeTask`	Removes a task from a project.
`resolveTasksManifest`	No description.
`runTask`	Runs the specified task.
`tryFind`	Finds a task by name.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`addEnvironment`

public addEnvironment(name: string, value: string): void

Adds global environment.

`name`^Required

Type: string

Environment variable name.

`value`^Required

Type: string

Value.

`addTask`

public addTask(name: string, options?: TaskOptions): Task

Adds a task to a project.

`name`^Required

Type: string

The name of the task.

`options`^Optional

Type: TaskOptions

Task options.

`removeTask`

public removeTask(name: string): Task

Removes a task from a project.

`name`^Required

Type: string

The name of the task to remove.

`resolveTasksManifest`

public resolveTasksManifest(resolver: IResolver): TasksManifest

`resolver`^Required

Type: IResolver

`runTask`

public runTask(name: string, args?: (string | number)[]): void

Runs the specified task.

`name`^Required

Type: string

The name of the task to run.

`args`^Optional

Type: string | number[]

Arguments to pass to the task.

`tryFind`

public tryFind(name: string): Task

Finds a task by name.

Returns undefined if the task cannot be found.

`name`^Required

Type: string

The name of the task.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Tasks } from 'projen'

Tasks.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Tasks } from 'projen'

Tasks.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`all`	`Task[]`	All tasks.
`env`	`{[ key: string ]: string}`	Returns a copy of the currently global environment for this project.
`shell`	`TaskShell`	The default shell used to run all task commands, or `undefined` for the built-in cross-platform projen shell.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`all`^Required

public readonly all: Task[];

Type: Task[]

All tasks.

`env`^Required

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

Type: {[ key: string ]: string}

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

`shell`^Optional

public readonly shell: TaskShell;

Type: TaskShell

The default shell used to run all task commands, or undefined for the built-in cross-platform projen shell.

Individual tasks and steps can override this. Sets the default shell used to run all task commands.

[{@link TaskCommonOptions.shell }]({@link TaskCommonOptions.shell })

TextFile

A text file.

Initializers

import { TextFile } from 'projen'

new TextFile(scope: IConstruct, filePath: string, options?: TextFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	File path.
`options`	`TextFileOptions`	Options.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

File path.

`options`^Optional

Type: TextFileOptions

Options.

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addLine`	Adds a line to the text file.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addLine`

public addLine(line: string): void

Adds a line to the text file.

`line`^Required

Type: string

the line to add (can use tokens).

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { TextFile } from 'projen'

TextFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { TextFile } from 'projen'

TextFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

TomlFile

Represents a TOML file.

Initializers

import { TomlFile } from 'projen'

new TomlFile(scope: IConstruct, filePath: string, options: TomlFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`TomlFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Required

Type: TomlFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { TomlFile } from 'projen'

TomlFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { TomlFile } from 'projen'

TomlFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

Version

Initializers

import { Version } from 'projen'

new Version(scope: IConstruct, options: VersionOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`options`	`VersionOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`options`^Required

Type: VersionOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Synthesizes files to the project output directory.
`envForBranch`	Return the environment variables to modify the bump command for release branches.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Synthesizes files to the project output directory.

`envForBranch`

public envForBranch(branchOptions: VersionBranchOptions): {[ key: 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).

`branchOptions`^Required

Type: VersionBranchOptions

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { Version } from 'projen'

Version.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { Version } from 'projen'

Version.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`bumpPackage`	`string`	The package used to bump package versions, as a dependency string.
`bumpTask`	`Task`	No description.
`changelogFileName`	`string`	The name of the changelog file (under `artifactsDirectory`).
`releasableCommitsTask`	`Task`	The task that prints the releasable commits since the latest tag.
`releaseTagFileName`	`string`	The name of the file that contains the release tag (under `artifactsDirectory`).
`unbumpTask`	`Task`	No description.
`versionFileName`	`string`	The name of the file that contains the version (under `artifactsDirectory`).
`nextVersionTask`	`Task`	The task that runs the user's `nextVersionCommand`, if configured.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`bumpPackage`^Required

public readonly bumpPackage: string;

Type: string

The package used to bump package versions, as a dependency string.

This is a commit-and-tag-version compatible package.

`bumpTask`^Required

public readonly bumpTask: Task;

Type: Task

`changelogFileName`^Required

public readonly changelogFileName: string;

Type: string

The name of the changelog file (under artifactsDirectory).

`releasableCommitsTask`^Required

public readonly releasableCommitsTask: Task;

Type: Task

The task that prints the releasable commits since the latest tag.

Spawned by bump; its shell can be overridden via task.shell.

`releaseTagFileName`^Required

public readonly releaseTagFileName: string;

Type: string

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

`unbumpTask`^Required

public readonly unbumpTask: Task;

Type: Task

`versionFileName`^Required

public readonly versionFileName: string;

Type: string

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

`nextVersionTask`^Optional

public readonly nextVersionTask: Task;

Type: Task

The task that runs the user's nextVersionCommand, if configured.

Spawned by bump; its shell can be overridden via task.shell.

XmlFile

Represents an XML file.

Objects passed in will be synthesized using the npm "xml" library.

https://www.npmjs.com/package/xml

Initializers

import { XmlFile } from 'projen'

new XmlFile(project: Project, filePath: string, options?: XmlFileOptions)

Name	Type	Description
`project`	`Project`	No description.
`filePath`	`string`	No description.
`options`	`XmlFileOptions`	No description.

`project`^Required

Type: Project

`filePath`^Required

Type: string

`options`^Optional

Type: XmlFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { XmlFile } from 'projen'

XmlFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { XmlFile } from 'projen'

XmlFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

YamlFile

Represents a YAML file.

Initializers

import { YamlFile } from 'projen'

new YamlFile(scope: IConstruct, filePath: string, options: YamlFileOptions)

Name	Type	Description
`scope`	`constructs.IConstruct`	No description.
`filePath`	`string`	No description.
`options`	`YamlFileOptions`	No description.

`scope`^Required

Type: constructs.IConstruct

`filePath`^Required

Type: string

`options`^Required

Type: YamlFileOptions

Methods

Name	Description
`toString`	Returns a string representation of this construct.
`with`	Applies one or more mixins to this construct.
`postProjectCreation`	Called once, right after `postSynthesize()`, only when the project is created for the first time.
`postSynthesize`	Called after synthesis.
`preSynthesize`	Called before synthesis.
`projectCreation`	Called once, right after `synthesize()`, only when the project is created for the first time.
`synthesize`	Writes the file to the project's output directory.
`diff`	Returns a unified diff of the old and new file contents with context lines and hunk headers.
`addDeletionOverride`	Syntactic sugar for `addOverride(path, undefined)`.
`addOverride`	Adds an override to the synthesized object file.
`addToArray`	Adds to an array in the synthesized object file.
`patch`	Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.

`toString`

public toString(): string

Returns a string representation of this construct.

`with`

public with(mixins: ...IMixin[]): IConstruct

Applies one or more mixins to this construct.

`mixins`^Required

Type: ...constructs.IMixin[]

The mixins to apply.

`postProjectCreation`

public postProjectCreation(initProject: InitProject): void

Called once, right after postSynthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`postSynthesize`

public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

`preSynthesize`

public preSynthesize(): void

Called before synthesis.

`projectCreation`

public projectCreation(initProject: InitProject): void

Called once, right after synthesize(), only when the project is created for the first time.

`initProject`^Required

Type: InitProject

Details about how the project was created, e.g. its type and the original CLI args.

`synthesize`

public synthesize(): void

Writes the file to the project's output directory.

`diff`

public diff(colorize?: boolean, contextLines?: number): string[]

Returns a unified diff of the old and new file contents with context lines and hunk headers.

Only available after synthesis.

This is an expensive operation and should only be used on non time-critical code paths, like debug output.

`colorize`^Optional

Type: boolean

Whether to colorize the diff output.

`contextLines`^Optional

Type: number

Number of context lines around changes.

`addDeletionOverride`

public addDeletionOverride(path: string): void

Syntactic sugar for addOverride(path, undefined).

`path`^Required

Type: string

The path of the value to delete.

`addOverride`

public 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"
  ]
  ...
}
...

`path`^Required

Type: string

The path of the property, you can use dot notation to override values in complex types.

Any intermediate keys will be created as needed.

`value`^Required

Type: any

The value.

Could be primitive or complex.

`addToArray`

public 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"]
  ...
}
...

`path`^Required

Type: string

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.

`values`^Required

Type: ...any[]

The values to add.

Could be primitive or complex.

`patch`

public 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"]
  ...
}
...

`patches`^Required

Type: ...JsonPatch[]

The patch operations to apply.

Static Functions

Name	Description
`isConstruct`	Checks if `x` is a construct.
`isComponent`	Test whether the given construct is a component.

`isConstruct`

import { YamlFile } from 'projen'

YamlFile.isConstruct(x: any)

Checks if x is a construct.

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

`x`^Required

Type: any

Any object.

`isComponent`

import { YamlFile } from 'projen'

YamlFile.isComponent(x: any)

Test whether the given construct is a component.

`x`^Required

Type: any

Properties

Name	Type	Description
`node`	`constructs.Node`	The tree node.
`project`	`Project`	No description.
`absolutePath`	`string`	The absolute path of this file.
`committed`	`boolean`	Indicates if the file will be committed.
`path`	`string`	The file path, relative to the project's outdir.
`changed`	`boolean`	Indicates if the file has been changed during synthesis.
`marker`	`string`	The projen marker, used to identify files as projen-generated.
`executable`	`boolean`	Indicates if the file should be marked as executable.
`readonly`	`boolean`	Indicates if the file should be read-only or read-write.
`omitEmpty`	`boolean`	Indicates if empty objects and arrays are omitted from the output object.
`lineWidth`	`number`	Maximum line width (set to 0 to disable folding).

`node`^Required

public readonly node: Node;

Type: constructs.Node

The tree node.

`project`^Required

public readonly project: Project;

Type: Project

`absolutePath`^Required

public readonly absolutePath: string;

Type: string

The absolute path of this file.

`committed`^Required

public readonly committed: boolean;

Type: boolean

Indicates if the file will be committed.

`path`^Required

public readonly path: string;

Type: string

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

`changed`^Optional

public readonly changed: boolean;

Type: 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.

`marker`^Optional

public readonly marker: string;

Type: string

The projen marker, used to identify files as projen-generated.

Value is undefined if the project is being ejected.

`executable`^Required

public readonly executable: boolean;

Type: boolean

Indicates if the file should be marked as executable.

`readonly`^Required

public readonly readonly: boolean;

Type: boolean

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

`omitEmpty`^Required

public readonly omitEmpty: boolean;

Type: boolean

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

`lineWidth`^Required

public readonly lineWidth: number;

Type: number

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

Structs

AiInstructionsOptions

Options for configuring AI tool instruction files.

Initializer

import { AiInstructionsOptions } from 'projen'

const aiInstructionsOptions: AiInstructionsOptions = { ... }

Properties

Name	Type	Description
`agents`	`AiAgent[]`	Which AI agents to generate instruction files for.
`agentSpecificInstructions`	`{[ key: string ]: string[]}`	Per-agent custom instructions.
`includeDefaultInstructions`	`boolean`	Include default instructions for projen and general best practices.
`instructions`	`string[]`	General instructions applicable to all agents.

`agents`^Optional

public readonly agents: AiAgent[];

Type: AiAgent[]
Default: All agents: [AiAgent.GITHUB_COPILOT, AiAgent.CURSOR, AiAgent.CLAUDE, AiAgent.AMAZON_Q, AiAgent.KIRO, AiAgent.CODEX]

Which AI agents to generate instruction files for.

`agentSpecificInstructions`^Optional

public readonly agentSpecificInstructions: {[ key: string ]: string[]};

Type: {[ key: string ]: string[]}
Default: no agent specific instructions

Per-agent custom instructions.

Allows different instructions for different AI tools.

Example

{
  [AiAgent.GITHUB_COPILOT]: {
    instructions: ["Use descriptive commit messages."]
  },
  [AiAgent.CURSOR]: {
    instructions: ["Prefer functional patterns.", "Always add tests."]
  }
}

`includeDefaultInstructions`^Optional

public readonly includeDefaultInstructions: boolean;

Type: boolean
Default: true

Include default instructions for projen and general best practices.

Default instructions will only be included for agents provided in the agents option. If agents is not provided, default instructions will be included for all agents.

`instructions`^Optional

public readonly instructions: string[];

Type: string[]
Default: no agent specific instructions

General instructions applicable to all agents.

CreateProjectOptions

Initializer

import { CreateProjectOptions } from 'projen'

const createProjectOptions: CreateProjectOptions = { ... }

Properties

Name	Type	Description
`dir`	`string`	Directory that the project will be generated in.
`projectFqn`	`string`	Fully-qualified name of the project type (usually formatted as `projen.module.ProjectType`).
`projectOptions`	`{[ key: string ]: any}`	Project options.
`optionHints`	`InitProjectOptionHints`	Should we render commented-out default options in the projenrc file?
`post`	`boolean`	Should we execute post synthesis hooks?
`synth`	`boolean`	Should we call `project.synth()` or instantiate the project (could still have side-effects) and render the .projenrc file.

`dir`^Required

public readonly dir: string;

Type: string

Directory that the project will be generated in.

`projectFqn`^Required

public readonly projectFqn: string;

Type: string

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

Example

`projen.typescript.TypescriptProject`

`projectOptions`^Required

public readonly projectOptions: {[ key: string ]: any};

Type: {[ key: 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.

`optionHints`^Optional

public readonly optionHints: InitProjectOptionHints;

Type: InitProjectOptionHints
Default: InitProjectOptionHints.FEATURED

Should we render commented-out default options in the projenrc file?

Does not apply to projenrc.json files.

`post`^Optional

public readonly post: boolean;

Type: boolean
Default: true

Should we execute post synthesis hooks?

(usually package manager install).

`synth`^Optional

public readonly synth: boolean;

Type: boolean
Default: true

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

Dependency

Represents a project dependency.

Initializer

import { Dependency } from 'projen'

const dependency: Dependency = { ... }

Properties

Name	Type	Description
`name`	`string`	The package manager name of the dependency (e.g. `leftpad` for npm).
`version`	`string`	Semantic version version requirement.
`type`	`DependencyType`	Which type of dependency this is (runtime, build-time, etc).
`metadata`	`{[ key: string ]: any}`	Additional JSON metadata associated with the dependency (package manager specific).

`name`^Required

public readonly name: string;

Type: 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.

`version`^Optional

public readonly version: string;

Type: string
Default: requirement is managed by the package manager (e.g. npm/yarn).

Semantic version version requirement.

`type`^Required

public readonly type: DependencyType;

Type: DependencyType

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

`metadata`^Optional

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

Type: {[ key: string ]: any}
Default: {}

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

DependencyCoordinates

Coordinates of the dependency (name and version).

Initializer

import { DependencyCoordinates } from 'projen'

const dependencyCoordinates: DependencyCoordinates = { ... }

Properties

Name	Type	Description
`name`	`string`	The package manager name of the dependency (e.g. `leftpad` for npm).
`version`	`string`	Semantic version version requirement.

`name`^Required

public readonly name: string;

Type: 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.

`version`^Optional

public readonly version: string;

Type: string
Default: requirement is managed by the package manager (e.g. npm/yarn).

Semantic version version requirement.

DependencyRequest

A request for a dependency.

Unlike adding a dependency directly, requesting a dependency will intelligently merge with existing dependencies of the same name and type.

Initializer

import { DependencyRequest } from 'projen'

const dependencyRequest: DependencyRequest = { ... }

Properties

Name	Type	Description
`name`	`string`	The package name.
`metadata`	`{[ key: string ]: any}`	Additional metadata.
`type`	`DependencyType`	Dependency type.
`version`	`string`	Semantic version constraint.

`name`^Required

public readonly name: string;

Type: string

The package name.

`metadata`^Optional

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

Type: {[ key: string ]: any}
Default: none

Additional metadata.

`type`^Optional

public readonly type: DependencyType;

Type: DependencyType
Default: any existing type, or DependencyType.BUILD

Dependency type.

If not provided, an existing dependency of any type will satisfy the request. If none exists, it is added as BUILD.

`version`^Optional

public readonly version: string;

Type: string
Default: any version

Semantic version constraint.

DepsManifest

Initializer

import { DepsManifest } from 'projen'

const depsManifest: DepsManifest = { ... }

Properties

Name	Type	Description
`dependencies`	`Dependency[]`	All dependencies of this module.

`dependencies`^Required

public readonly dependencies: Dependency[];

Type: Dependency[]

All dependencies of this module.

DevEnvironmentOptions

Base options for configuring a container-based development environment.

Initializer

import { DevEnvironmentOptions } from 'projen'

const devEnvironmentOptions: DevEnvironmentOptions = { ... }

Properties

Name	Type	Description
`dockerImage`	`DevEnvironmentDockerImage`	A Docker image or Dockerfile for the container.
`ports`	`string[]`	An array of ports that should be exposed from the container.
`tasks`	`Task[]`	An array of tasks that should be run when the container starts.
`vscodeExtensions`	`string[]`	An array of extension IDs that specify the extensions that should be installed inside the container when it is created.

`dockerImage`^Optional

public readonly dockerImage: DevEnvironmentDockerImage;

Type: DevEnvironmentDockerImage

A Docker image or Dockerfile for the container.

`ports`^Optional

public readonly ports: string[];

Type: string[]

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

`tasks`^Optional

public readonly tasks: Task[];

Type: Task[]

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

`vscodeExtensions`^Optional

public readonly vscodeExtensions: string[];

Type: string[]

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

DockerComposeBuild

Build arguments for creating a docker image.

Initializer

import { DockerComposeBuild } from 'projen'

const dockerComposeBuild: DockerComposeBuild = { ... }

Properties

Name	Type	Description
`context`	`string`	Docker build context directory.
`args`	`{[ key: string ]: string}`	Build args.
`dockerfile`	`string`	A dockerfile to build from.

`context`^Required

public readonly context: string;

Type: string

Docker build context directory.

`args`^Optional

public readonly args: {[ key: string ]: string};

Type: {[ key: string ]: string}
Default: none are provided

Build args.

`dockerfile`^Optional

public readonly dockerfile: string;

Type: string
Default: "Dockerfile"

A dockerfile to build from.

DockerComposeNetworkConfig

Network configuration.

Initializer

import { DockerComposeNetworkConfig } from 'projen'

const dockerComposeNetworkConfig: DockerComposeNetworkConfig = { ... }

Properties

Name	Type	Description
`attachable`	`boolean`	Set to true to indicate that standalone containers can attach to this network, in addition to services.
`bridge`	`boolean`	Set to true to indicate that the network is a bridge network.
`driver`	`string`	Driver to use for the network.
`driverOpts`	`object`	Options for the configured driver.
`external`	`boolean`	Set to true to indicate that the network is externally created.
`internal`	`boolean`	Set to true to indicate that you want to create an externally isolated overlay network.
`ipam`	`DockerComposeNetworkIpamConfig`	Specify custom IPAM config.
`labels`	`string[]`	Attach labels to the network.
`name`	`string`	Name of the network for when the network name isn't going to work in YAML.
`overlay`	`boolean`	Set to true to indicate that the network is an overlay network.

`attachable`^Optional

public readonly attachable: boolean;

Type: boolean
Default: unset

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

`bridge`^Optional

public readonly bridge: boolean;

Type: boolean
Default: unset

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

`driver`^Optional

public readonly driver: string;

Type: string
Default: value is not provided

Driver to use for the network.

`driverOpts`^Optional

public readonly driverOpts: object;

Type: object
Default: value is not provided

Options for the configured driver.

Those options are driver-dependent - consult the driver’s documentation for more information

`external`^Optional

public readonly external: boolean;

Type: boolean
Default: unset, indicating that docker-compose creates the network

Set to true to indicate that the network is externally created.

`internal`^Optional

public readonly internal: boolean;

Type: boolean
Default: unset

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

`ipam`^Optional

public readonly ipam: DockerComposeNetworkIpamConfig;

Type: DockerComposeNetworkIpamConfig
Default: unset

Specify custom IPAM config.

`labels`^Optional

public readonly labels: string[];

Type: string[]
Default: unset

Attach labels to the network.

`name`^Optional

public readonly name: string;

Type: string
Default: unset, indicating that docker-compose creates networks as usual

Name of the network for when the network name isn't going to work in YAML.

`overlay`^Optional

public readonly overlay: boolean;

Type: boolean
Default: unset

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

DockerComposeNetworkIpamConfig

IPAM configuration.

Initializer

import { DockerComposeNetworkIpamConfig } from 'projen'

const dockerComposeNetworkIpamConfig: DockerComposeNetworkIpamConfig = { ... }

Properties

Name	Type	Description
`config`	`DockerComposeNetworkIpamSubnetConfig[]`	A list with zero or more config blocks specifying custom IPAM configuration.
`driver`	`string`	Driver to use for custom IPAM config.

`config`^Optional

public readonly config: DockerComposeNetworkIpamSubnetConfig[];

Type: DockerComposeNetworkIpamSubnetConfig[]
Default: value is not provided

A list with zero or more config blocks specifying custom IPAM configuration.

`driver`^Optional

public readonly driver: string;

Type: string
Default: value is not provided

Driver to use for custom IPAM config.

DockerComposeNetworkIpamSubnetConfig

IPAM subnet configuration.

Initializer

import { DockerComposeNetworkIpamSubnetConfig } from 'projen'

const dockerComposeNetworkIpamSubnetConfig: DockerComposeNetworkIpamSubnetConfig = { ... }

Properties

Name	Type	Description
`subnet`	`string`	Subnet in CIDR format that represents a network segment.

`subnet`^Optional

public readonly subnet: string;

Type: string
Default: value is not provided

Subnet in CIDR format that represents a network segment.

DockerComposePortMappingOptions

Options for port mappings.

Initializer

import { DockerComposePortMappingOptions } from 'projen'

const dockerComposePortMappingOptions: DockerComposePortMappingOptions = { ... }

Properties

Name	Type	Description
`protocol`	`DockerComposeProtocol`	Port mapping protocol.

`protocol`^Optional

public readonly protocol: DockerComposeProtocol;

Type: DockerComposeProtocol
Default: DockerComposeProtocol.TCP

Port mapping protocol.

DockerComposeProps

Props for DockerCompose.

Initializer

import { DockerComposeProps } from 'projen'

const dockerComposeProps: DockerComposeProps = { ... }

Properties

Name	Type	Description
`nameSuffix`	`string`	A name to add to the docker-compose.yml filename.
`schemaVersion`	`string`	Docker Compose schema version do be used.
`services`	`{[ key: string ]: DockerComposeServiceDescription}`	Service descriptions.

`nameSuffix`^Optional

public readonly nameSuffix: string;

Type: string
Default: no name is added

A name to add to the docker-compose.yml filename.

Example

'myname' yields 'docker-compose.myname.yml'

`schemaVersion`^Optional

Deprecated: - The top level version field is obsolete per the Compose Specification. {@link https://github.com/compose-spec/compose-spec/blob/master/spec.md#version-and-name-top-level-elements Compose Specification}

public readonly schemaVersion: string;

Type: string
Default: no version is provided

Docker Compose schema version do be used.

`services`^Optional

public readonly services: {[ key: string ]: DockerComposeServiceDescription};

Type: {[ key: string ]: DockerComposeServiceDescription}

Service descriptions.

DockerComposeServiceDescription

Description of a docker-compose.yml service.

Initializer

import { DockerComposeServiceDescription } from 'projen'

const dockerComposeServiceDescription: DockerComposeServiceDescription = { ... }

Properties

Name	Type	Description
`command`	`string[]`	Provide a command to the docker container.
`dependsOn`	`IDockerComposeServiceName[]`	Names of other services this service depends on.
`entrypoint`	`string[]`	Entrypoint to run in the container.
`environment`	`{[ key: string ]: string}`	Add environment variables.
`image`	`string`	Use a docker image.
`imageBuild`	`DockerComposeBuild`	Build a docker image.
`labels`	`{[ key: string ]: string}`	Add labels.
`networks`	`IDockerComposeNetworkBinding[]`	Add some networks to the service.
`platform`	`string`	Add platform.
`ports`	`DockerComposeServicePort[]`	Map some ports.
`privileged`	`boolean`	Run in privileged mode.
`volumes`	`IDockerComposeVolumeBinding[]`	Mount some volumes into the service.

`command`^Optional

public readonly command: string[];

Type: string[]
Default: use the container's default command

Provide a command to the docker container.

`dependsOn`^Optional

public readonly dependsOn: IDockerComposeServiceName[];

Type: IDockerComposeServiceName[]
Default: no dependencies

Names of other services this service depends on.

`entrypoint`^Optional

public readonly entrypoint: string[];

Type: string[]

Entrypoint to run in the container.

`environment`^Optional

public readonly environment: {[ key: string ]: string};

Type: {[ key: string ]: string}
Default: no environment variables are provided

Add environment variables.

`image`^Optional

public readonly image: string;

Type: string

Use a docker image.

Note: You must specify either build or image key.

imageBuild

`imageBuild`^Optional

public readonly imageBuild: DockerComposeBuild;

Type: DockerComposeBuild

Build a docker image.

Note: You must specify either imageBuild or image key.

image

`labels`^Optional

public readonly labels: {[ key: string ]: string};

Type: {[ key: string ]: string}
Default: no labels are provided

Add labels.

`networks`^Optional

public readonly networks: IDockerComposeNetworkBinding[];

Type: IDockerComposeNetworkBinding[]

Add some networks to the service.

[DockerCompose.network () to create & mount a named network](DockerCompose.network () to create & mount a named network)

`platform`^Optional

public readonly platform: string;

Type: string
Default: no platform is provided

Add platform.

`ports`^Optional

public readonly ports: DockerComposeServicePort[];

Type: DockerComposeServicePort[]
Default: no ports are mapped

Map some ports.

`privileged`^Optional

public readonly privileged: boolean;

Type: boolean
Default: no privileged mode flag is provided

Run in privileged mode.

`volumes`^Optional

public readonly volumes: IDockerComposeVolumeBinding[];

Type: IDockerComposeVolumeBinding[]

Mount some volumes into the service.

Use one of the following to create volumes:

[DockerCompose.namedVolume () to create & mount a named volume](DockerCompose.namedVolume () to create & mount a named volume)

DockerComposeServicePort

A service port mapping.

Initializer

import { DockerComposeServicePort } from 'projen'

const dockerComposeServicePort: DockerComposeServicePort = { ... }

Properties

Name	Type	Description
`mode`	`string`	Port mapping mode.
`protocol`	`DockerComposeProtocol`	Network protocol.
`published`	`number`	Published port number.
`target`	`number`	Target port number.

`mode`^Required

public readonly mode: string;

Type: string

Port mapping mode.

`protocol`^Required

public readonly protocol: DockerComposeProtocol;

Type: DockerComposeProtocol

Network protocol.

`published`^Required

public readonly published: number;

Type: number

Published port number.

`target`^Required

public readonly target: number;

Type: number

Target port number.

DockerComposeVolumeConfig

Volume configuration.

Initializer

import { DockerComposeVolumeConfig } from 'projen'

const dockerComposeVolumeConfig: DockerComposeVolumeConfig = { ... }

Properties

Name	Type	Description
`driver`	`string`	Driver to use for the volume.
`driverOpts`	`{[ key: string ]: string}`	Options to provide to the driver.
`external`	`boolean`	Set to true to indicate that the volume is externally created.
`name`	`string`	Name of the volume for when the volume name isn't going to work in YAML.

`driver`^Optional

public readonly driver: string;

Type: string
Default: value is not provided

Driver to use for the volume.

`driverOpts`^Optional

public readonly driverOpts: {[ key: string ]: string};

Type: {[ key: string ]: string}

Options to provide to the driver.

`external`^Optional

public readonly external: boolean;

Type: boolean
Default: unset, indicating that docker-compose creates the volume

Set to true to indicate that the volume is externally created.

`name`^Optional

public readonly name: string;

Type: string
Default: unset, indicating that docker-compose creates volumes as usual

Name of the volume for when the volume name isn't going to work in YAML.

DockerComposeVolumeMount

Service volume mounting information.

Initializer

import { DockerComposeVolumeMount } from 'projen'

const dockerComposeVolumeMount: DockerComposeVolumeMount = { ... }

Properties

Name	Type	Description
`source`	`string`	Volume source.
`target`	`string`	Volume target.
`type`	`string`	Type of volume.

`source`^Required

public readonly source: string;

Type: string

Volume source.

`target`^Required

public readonly target: string;

Type: string

Volume target.

`type`^Required

public readonly type: string;

Type: string

Type of volume.

FileBaseOptions

Initializer

import { FileBaseOptions } from 'projen'

const fileBaseOptions: FileBaseOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

GitAttributesFileOptions

Options for GitAttributesFile.

Initializer

import { GitAttributesFileOptions } from 'projen'

const gitAttributesFileOptions: GitAttributesFileOptions = { ... }

Properties

Name	Type	Description
`endOfLine`	`EndOfLine`	The default end of line character for text files.

`endOfLine`^Optional

public readonly endOfLine: EndOfLine;

Type: EndOfLine
Default: EndOfLine.LF

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 }.

GitOptions

Git configuration options.

Initializer

import { GitOptions } from 'projen'

const gitOptions: GitOptions = { ... }

Properties

Name	Type	Description
`endOfLine`	`EndOfLine`	The default end of line character for text files.
`lfsPatterns`	`string[]`	File patterns to mark as stored in Git LFS.

`endOfLine`^Optional

public readonly endOfLine: EndOfLine;

Type: EndOfLine
Default: EndOfLine.LF

The default end of line character for text files.

`lfsPatterns`^Optional

public readonly lfsPatterns: string[];

Type: string[]
Default: No files stored in LFS

File patterns to mark as stored in Git LFS.

GitpodOptions

Constructor options for the Gitpod component.

By default, Gitpod uses the 'gitpod/workspace-full' docker image.

[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.](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.)

Initializer

import { GitpodOptions } from 'projen'

const gitpodOptions: GitpodOptions = { ... }

Properties

Name	Type	Description
`dockerImage`	`DevEnvironmentDockerImage`	A Docker image or Dockerfile for the container.
`ports`	`string[]`	An array of ports that should be exposed from the container.
`tasks`	`Task[]`	An array of tasks that should be run when the container starts.
`vscodeExtensions`	`string[]`	An array of extension IDs that specify the extensions that should be installed inside the container when it is created.
`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.

`dockerImage`^Optional

public readonly dockerImage: DevEnvironmentDockerImage;

Type: DevEnvironmentDockerImage

A Docker image or Dockerfile for the container.

`ports`^Optional

public readonly ports: string[];

Type: string[]

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

`tasks`^Optional

public readonly tasks: Task[];

Type: Task[]

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

`vscodeExtensions`^Optional

public readonly vscodeExtensions: string[];

Type: string[]

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

`prebuilds`^Optional

public readonly prebuilds: GitpodPrebuilds;

Type: GitpodPrebuilds
Default: undefined

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.

GitpodPort

Options for an exposed port on Gitpod.

Initializer

import { GitpodPort } from 'projen'

const gitpodPort: GitpodPort = { ... }

Properties

Name	Type	Description
`onOpen`	`GitpodOnOpen`	What to do when a service on a port is detected.
`port`	`string`	A port that should be exposed (forwarded) from the container.
`visibility`	`GitpodPortVisibility`	Whether the port visibility should be private or public.

`onOpen`^Optional

public readonly onOpen: GitpodOnOpen;

Type: GitpodOnOpen
Default: GitpodOnOpen.NOTIFY

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

`port`^Optional

public readonly port: string;

Type: string

A port that should be exposed (forwarded) from the container.

Example

"8080"

`visibility`^Optional

public readonly visibility: GitpodPortVisibility;

Type: GitpodPortVisibility
Default: GitpodPortVisibility.PUBLIC

Whether the port visibility should be private or public.

GitpodPrebuilds

Configure the Gitpod App for prebuilds.

Currently only GitHub is supported.

https://www.gitpod.io/docs/prebuilds/

Initializer

import { GitpodPrebuilds } from 'projen'

const gitpodPrebuilds: GitpodPrebuilds = { ... }

Properties

Name	Type	Description
`addBadge`	`boolean`	Add a "Review in Gitpod" button to the pull request's description.
`addCheck`	`boolean`	Add a check to pull requests.
`addComment`	`boolean`	Add a "Review in Gitpod" button as a comment to pull requests.
`addLabel`	`boolean`	Add a label once the prebuild is ready to pull requests.
`branches`	`boolean`	Enable for all branches in this repo.
`master`	`boolean`	Enable for the master/default branch.
`pullRequests`	`boolean`	Enable for pull requests coming from this repo.
`pullRequestsFromForks`	`boolean`	Enable for pull requests coming from forks.

`addBadge`^Optional

public readonly addBadge: boolean;

Type: boolean
Default: false

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

`addCheck`^Optional

public readonly addCheck: boolean;

Type: boolean
Default: true

Add a check to pull requests.

`addComment`^Optional

public readonly addComment: boolean;

Type: boolean
Default: false

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

`addLabel`^Optional

public readonly addLabel: boolean;

Type: boolean
Default: false

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

`branches`^Optional

public readonly branches: boolean;

Type: boolean
Default: false

Enable for all branches in this repo.

`master`^Optional

public readonly master: boolean;

Type: boolean
Default: true

Enable for the master/default branch.

`pullRequests`^Optional

public readonly pullRequests: boolean;

Type: boolean
Default: true

Enable for pull requests coming from this repo.

`pullRequestsFromForks`^Optional

public readonly pullRequestsFromForks: boolean;

Type: boolean
Default: false

Enable for pull requests coming from forks.

GitpodTask

Configure options for a task to be run when opening a Gitpod workspace (e.g. running tests, or starting a dev server).

Initializer

import { GitpodTask } from 'projen'

const gitpodTask: GitpodTask = { ... }

Properties

Name	Type	Description
`command`	`string`	Required.
`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.
`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.
`name`	`string`	A name for this task.
`openIn`	`GitpodOpenIn`	You can configure where in the IDE the terminal should be opened.
`openMode`	`GitpodOpenMode`	You can configure how the terminal should be opened relative to the previous task.
`prebuild`	`string`	The optional prebuild command will be executed during prebuilds.

`command`^Required

public readonly command: string;

Type: string

Required.

The shell command to run

`before`^Optional

public readonly before: string;

Type: 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.

A shell command, chained with the other task commands using &&.

`init`^Optional

public readonly init: string;

Type: 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.

`name`^Optional

public readonly name: string;

Type: string
Default: task names are omitted when blank

A name for this task.

`openIn`^Optional

public readonly openIn: GitpodOpenIn;

Type: GitpodOpenIn
Default: GitpodOpenIn.BOTTOM

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

`openMode`^Optional

public readonly openMode: GitpodOpenMode;

Type: GitpodOpenMode
Default: GitpodOpenMode.TAB_AFTER

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

`prebuild`^Optional

public readonly prebuild: string;

Type: 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.

A shell command, chained with the other task commands using &&.

GroupRunnerOptions

Initializer

import { GroupRunnerOptions } from 'projen'

const groupRunnerOptions: GroupRunnerOptions = { ... }

Properties

Name	Type	Description
`group`	`string`	No description.
`labels`	`string[]`	No description.

`group`^Required

public readonly group: string;

Type: string

`labels`^Optional

public readonly labels: string[];

Type: string[]

IgnoreFileOptions

Initializer

import { IgnoreFileOptions } from 'projen'

const ignoreFileOptions: IgnoreFileOptions = { ... }

Properties

Name	Type	Description
`filterCommentLines`	`boolean`	Filter out comment lines?
`filterEmptyLines`	`boolean`	Filter out blank/empty lines?
`ignorePatterns`	`string[]`	Patterns to add to the ignore file.

`filterCommentLines`^Optional

public readonly filterCommentLines: boolean;

Type: boolean
Default: true

Filter out comment lines?

`filterEmptyLines`^Optional

public readonly filterEmptyLines: boolean;

Type: boolean
Default: true

Filter out blank/empty lines?

`ignorePatterns`^Optional

public readonly ignorePatterns: string[];

Type: string[]
Default: []

Patterns to add to the ignore file.

IniFileOptions

Options for IniFile.

Initializer

import { IniFileOptions } from 'projen'

const iniFileOptions: IniFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

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.

Initializer

import { InitProject } from 'projen'

const initProject: InitProject = { ... }

Properties

Name	Type	Description
`args`	`{[ key: string ]: any}`	Initial arguments passed to `projen new`.
`comments`	`InitProjectOptionHints`	Include commented out options.
`fqn`	`string`	The JSII FQN of the project type.
`post`	`boolean`	Whether `projen new` should run post-synthesis steps (e.g. package manager install).
`synth`	`boolean`	Whether `projen new` should call `project.synth()` after construction.
`type`	`ProjectType`	Project metadata.

`args`^Required

public readonly args: {[ key: string ]: any};

Type: {[ key: string ]: any}

Initial arguments passed to projen new.

`comments`^Required

public readonly comments: InitProjectOptionHints;

Type: InitProjectOptionHints
Default: InitProjectOptionHints.FEATURED

Include commented out options.

Does not apply to projenrc.json files.

`fqn`^Required

public readonly fqn: string;

Type: string

The JSII FQN of the project type.

`post`^Required

public readonly post: boolean;

Type: boolean
Default: true

Whether projen new should run post-synthesis steps (e.g. package manager install).

`synth`^Required

public readonly synth: boolean;

Type: boolean
Default: true

Whether projen new should call project.synth() after construction.

`type`^Required

public readonly type: ProjectType;

Type: ProjectType

Project metadata.

JsonFileOptions

Options for JsonFile.

Initializer

import { JsonFileOptions } from 'projen'

const jsonFileOptions: JsonFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.
`allowComments`	`boolean`	Allow the use of comments in this file.
`newline`	`boolean`	Adds a newline at the end of the file.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

`allowComments`^Optional

public readonly allowComments: boolean;

Type: boolean
Default: false for .json files, true for .json5 and .jsonc files

Allow the use of comments in this file.

`newline`^Optional

public readonly newline: boolean;

Type: boolean
Default: true

Adds a newline at the end of the file.

LicenseOptions

Initializer

import { LicenseOptions } from 'projen'

const licenseOptions: LicenseOptions = { ... }

Properties

Name	Type	Description
`spdx`	`string`	License type (SPDX).
`copyrightOwner`	`string`	Copyright owner.
`copyrightPeriod`	`string`	Period of license (e.g. "1998-2023").

`spdx`^Required

public readonly spdx: string;

Type: string

License type (SPDX).

[https://github.com/projen/projen/tree/main/license-text for list of supported licenses](https://github.com/projen/projen/tree/main/license-text for list of supported licenses)

`copyrightOwner`^Optional

public readonly copyrightOwner: string;

Type: string
Default:

If the license text has $copyright_owner, this option must be specified.

`copyrightPeriod`^Optional

public readonly copyrightPeriod: string;

Type: string
Default: current year (e.g. "2020")

Period of license (e.g. "1998-2023").

The string $copyright_period will be substituted with this string.

LoggerOptions

Options for logging utilities.

Initializer

import { LoggerOptions } from 'projen'

const loggerOptions: LoggerOptions = { ... }

Properties

Name	Type	Description
`level`	`LogLevel`	The logging verbosity.
`usePrefix`	`boolean`	Include a prefix for all logging messages with the project name.

`level`^Optional

public readonly level: LogLevel;

Type: LogLevel
Default: LogLevel.INFO

The logging verbosity.

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

`usePrefix`^Optional

public readonly usePrefix: boolean;

Type: boolean
Default: false

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

MakefileOptions

Options for Makefiles.

Initializer

import { MakefileOptions } from 'projen'

const makefileOptions: MakefileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`all`	`string[]`	List of targets to build when Make is invoked without specifying any targets.
`rules`	`Rule[]`	Rules to include in the Makefile.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`all`^Optional

public readonly all: string[];

Type: string[]
Default: []

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

`rules`^Optional

public readonly rules: Rule[];

Type: Rule[]
Default: []

Rules to include in the Makefile.

ObjectFileOptions

Options for ObjectFile.

Initializer

import { ObjectFileOptions } from 'projen'

const objectFileOptions: ObjectFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

ProjectOption

Initializer

import { ProjectOption } from 'projen'

const projectOption: ProjectOption = { ... }

Properties

Name	Type	Description
`name`	`string`	No description.
`type`	`any`	No description.
`default`	`string`	No description.
`deprecated`	`boolean`	No description.
`docs`	`string`	No description.
`featured`	`boolean`	No description.
`fqn`	`string`	No description.
`initialValue`	`string`	No description.
`optional`	`boolean`	No description.

`name`^Required

public readonly name: string;

Type: string

`type`^Required

public readonly type: any;

Type: any

`default`^Optional

public readonly default: string;

Type: string

`deprecated`^Optional

public readonly deprecated: boolean;

Type: boolean

`docs`^Optional

public readonly docs: string;

Type: string

`featured`^Optional

public readonly featured: boolean;

Type: boolean

`fqn`^Optional

public readonly fqn: string;

Type: string

`initialValue`^Optional

public readonly initialValue: string;

Type: string

`optional`^Optional

public readonly optional: boolean;

Type: boolean

ProjectOptions

Options for Project.

Initializer

import { ProjectOptions } from 'projen'

const projectOptions: ProjectOptions = { ... }

Properties

Name	Type	Description
`name`	`string`	This is the name of your project.
`commitGenerated`	`boolean`	Whether to commit the managed files by default.
`gitIgnoreOptions`	`IgnoreFileOptions`	Configuration options for .gitignore file.
`gitOptions`	`GitOptions`	Configuration options for git.
`logging`	`LoggerOptions`	Configure logging options such as verbosity.
`outdir`	`string`	The root directory of the project.
`parent`	`Project`	The parent project, if this project is part of a bigger project.
`projectTree`	`boolean`	Generate a project tree file (`.projen/tree.json`) that shows all components and their relationships. Useful for understanding your project structure and debugging.
`projenCommand`	`string`	The shell command to use in order to run the projen CLI.
`projenrcJson`	`boolean`	Generate (once) .projenrc.json (in JSON). Set to `false` in order to disable .projenrc.json generation.
`projenrcJsonOptions`	`ProjenrcJsonOptions`	Options for .projenrc.json.
`renovatebot`	`boolean`	Use renovatebot to handle dependency upgrades.
`renovatebotOptions`	`RenovatebotOptions`	Options for renovatebot.

`name`^Required

public readonly name: string;

Type: string
Default: $BASEDIR

This is the name of your project.

`commitGenerated`^Optional

public readonly commitGenerated: boolean;

Type: boolean
Default: true

Whether to commit the managed files by default.

`gitIgnoreOptions`^Optional

public readonly gitIgnoreOptions: IgnoreFileOptions;

Type: IgnoreFileOptions

Configuration options for .gitignore file.

`gitOptions`^Optional

public readonly gitOptions: GitOptions;

Type: GitOptions

Configuration options for git.

`logging`^Optional

public readonly logging: LoggerOptions;

Type: LoggerOptions
Default: {}

Configure logging options such as verbosity.

`outdir`^Optional

public readonly outdir: string;

Type: string
Default: "."

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.

`parent`^Optional

public readonly parent: Project;

Type: Project

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

`projectTree`^Optional

public readonly projectTree: boolean;

Type: boolean
Default: false

Generate a project tree file (.projen/tree.json) that shows all components and their relationships. Useful for understanding your project structure and debugging.

`projenCommand`^Optional

public readonly projenCommand: string;

Type: string
Default: "npx projen"

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

Inserted verbatim into task steps, workflows and IDE configuration, and run by each of their shells - locally, in CI and in dev containers. Keep it a plain unquoted command, since shell syntax in it executes in all of them.

Can be used to customize in special environments.

`projenrcJson`^Optional

public readonly projenrcJson: boolean;

Type: boolean
Default: false

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

`projenrcJsonOptions`^Optional

public readonly projenrcJsonOptions: ProjenrcJsonOptions;

Type: ProjenrcJsonOptions
Default: default options

Options for .projenrc.json.

`renovatebot`^Optional

public readonly renovatebot: boolean;

Type: boolean
Default: false

Use renovatebot to handle dependency upgrades.

`renovatebotOptions`^Optional

public readonly renovatebotOptions: RenovatebotOptions;

Type: RenovatebotOptions
Default: default options

Options for renovatebot.

ProjectType

Initializer

import { ProjectType } from 'projen'

const projectType: ProjectType = { ... }

Properties

Name	Type	Description
`docsurl`	`string`	No description.
`fqn`	`string`	No description.
`moduleName`	`string`	No description.
`options`	`ProjectOption[]`	No description.
`pjid`	`string`	No description.
`typename`	`string`	No description.
`docs`	`string`	No description.

`docsurl`^Required

public readonly docsurl: string;

Type: string

`fqn`^Required

public readonly fqn: string;

Type: string

`moduleName`^Required

public readonly moduleName: string;

Type: string

`options`^Required

public readonly options: ProjectOption[];

Type: ProjectOption[]

`pjid`^Required

public readonly pjid: string;

Type: string

`typename`^Required

public readonly typename: string;

Type: string

`docs`^Optional

public readonly docs: string;

Type: string

ProjenrcJsonOptions

Initializer

import { ProjenrcJsonOptions } from 'projen'

const projenrcJsonOptions: ProjenrcJsonOptions = { ... }

Properties

Name	Type	Description
`filename`	`string`	The name of the projenrc file.

`filename`^Optional

public readonly filename: string;

Type: string
Default: ".projenrc.json"

The name of the projenrc file.

PropertiesFileOptions

Options for PropertiesFile.

Initializer

import { PropertiesFileOptions } from 'projen'

const propertiesFileOptions: PropertiesFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.
`comment`	`string[]`	A comment to include at the top of the file (after the projen marker, if enabled).

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

`comment`^Optional

public readonly comment: string[];

Type: string[]
Default: no additional comment

A comment to include at the top of the file (after the projen marker, if enabled).

Each string in the array becomes a separate comment line.

RenovatebotOptions

Options for Renovatebot.

Initializer

import { RenovatebotOptions } from 'projen'

const renovatebotOptions: RenovatebotOptions = { ... }

Properties

Name	Type	Description
`ignore`	`string[]`	You can use the `ignore` option to customize which dependencies are updated.
`ignoreProjen`	`boolean`	Ignores updates to `projen`.
`labels`	`string[]`	List of labels to apply to the created PR's.
`marker`	`boolean`	No description.
`minimumReleaseAge`	`string`	Minimum release age for packages before Renovate will propose an update.
`minimumReleaseAgeBehaviour`	`RenovatebotMinimumReleaseAgeBehaviour`	Controls whether a release timestamp is required when using `minimumReleaseAge`.
`overrideConfig`	`any`	No description.
`scheduleInterval`	`string[]`	How often to check for new versions and raise pull requests.

`ignore`^Optional

public readonly ignore: string[];

Type: string[]
Default: []

You can use the ignore option to customize which dependencies are updated.

The ignore option supports just package name.

`ignoreProjen`^Optional

public readonly ignoreProjen: boolean;

Type: boolean
Default: true

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.

`labels`^Optional

public readonly labels: string[];

Type: string[]

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

`marker`^Optional

public readonly marker: boolean;

Type: boolean

`minimumReleaseAge`^Optional

public readonly minimumReleaseAge: string;

Type: string
Default: no minimum release age

Minimum release age for packages before Renovate will propose an update.

This is a supply chain security feature to avoid updating to newly published, potentially malicious versions.

https://docs.renovatebot.com/configuration-options/#minimumreleaseage

`minimumReleaseAgeBehaviour`^Optional

public readonly minimumReleaseAgeBehaviour: RenovatebotMinimumReleaseAgeBehaviour;

Type: RenovatebotMinimumReleaseAgeBehaviour
Default: RenovatebotMinimumReleaseAgeBehaviour.TIMESTAMP_REQUIRED

Controls whether a release timestamp is required when using minimumReleaseAge.

https://docs.renovatebot.com/configuration-options/#minimumreleaseagebehaviour

`overrideConfig`^Optional

public readonly overrideConfig: any;

Type: any

`scheduleInterval`^Optional

public readonly scheduleInterval: string[];

Type: string[]
Default: ["at any time"]

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.

https://docs.renovatebot.com/configuration-options/#schedule

ResolveOptions

Resolve options.

Initializer

import { ResolveOptions } from 'projen'

const resolveOptions: ResolveOptions = { ... }

Properties

Name	Type	Description
`args`	`any[]`	Context arguments.
`omitEmpty`	`boolean`	Omits empty arrays and objects.

`args`^Optional

public readonly args: any[];

Type: any[]
Default: []

Context arguments.

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty arrays and objects.

Rule

A Make rule.

Initializer

import { Rule } from 'projen'

const rule: Rule = { ... }

Properties

Name	Type	Description
`targets`	`string[]`	Files to be created or updated by this rule.
`phony`	`boolean`	Marks whether the target is phony.
`prerequisites`	`string[]`	Files that are used as inputs to create a target.
`recipe`	`string[]`	Commands that are run (using prerequisites as inputs) to create a target.

`targets`^Required

public readonly targets: string[];

Type: string[]

Files to be created or updated by this rule.

If the rule is phony then instead this represents the command's name(s).

`phony`^Optional

public readonly phony: boolean;

Type: boolean
Default: false

Marks whether the target is phony.

`prerequisites`^Optional

public readonly prerequisites: string[];

Type: string[]
Default: []

Files that are used as inputs to create a target.

`recipe`^Optional

public readonly recipe: string[];

Type: string[]
Default: []

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

Each entry is a shell command, run by make in its own shell.

RunScriptConfig

The resolved configuration for running a script.

Initializer

import { RunScriptConfig } from 'projen'

const runScriptConfig: RunScriptConfig = { ... }

Properties

Name	Type	Description
`dependencies`	`DependencyRequest[]`	Dependencies required to run the script.
`steps`	`TaskStep[]`	The task steps to execute the script.

`dependencies`^Required

public readonly dependencies: DependencyRequest[];

Type: DependencyRequest[]

Dependencies required to run the script.

`steps`^Required

public readonly steps: TaskStep[];

Type: TaskStep[]

The task steps to execute the script.

RunsOnConfig

Resolved runsOn/runsOnGroup config for a job.

Exactly one of the two fields is set.

Initializer

import { RunsOnConfig } from 'projen'

const runsOnConfig: RunsOnConfig = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`GroupRunnerOptions`	Github Runner Group selection options.

`runsOn`^Optional

public readonly runsOn: string[];

Type: string[]
Default: not set if runsOnGroup is used

Github Runner selection labels.

`runsOnGroup`^Optional

public readonly runsOnGroup: GroupRunnerOptions;

Type: GroupRunnerOptions
Default: not set if runsOn is used

Github Runner Group selection options.

RunsOnOptions

Options for selecting the GitHub Runner that a job runs on.

Initializer

import { RunsOnOptions } from 'projen'

const runsOnOptions: RunsOnOptions = { ... }

Properties

Name	Type	Description
`runsOn`	`string[]`	Github Runner selection labels.
`runsOnGroup`	`GroupRunnerOptions`	Github Runner Group selection options.

`runsOn`^Optional

public readonly runsOn: string[];

Type: string[]
Default: ["ubuntu-latest"]

Github Runner selection labels.

`runsOnGroup`^Optional

public readonly runsOnGroup: GroupRunnerOptions;

Type: GroupRunnerOptions

Github Runner Group selection options.

SampleDirOptions

SampleDir options.

Initializer

import { SampleDirOptions } from 'projen'

const sampleDirOptions: SampleDirOptions = { ... }

Properties

Name	Type	Description
`files`	`{[ key: string ]: string}`	The files to render into the directory.
`sourceDir`	`string`	Absolute path to a directory to copy files from (does not need to be text files).

`files`^Optional

public readonly files: {[ key: string ]: string};

Type: {[ key: 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).

`sourceDir`^Optional

public readonly sourceDir: string;

Type: 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') });

SampleFileOptions

Options for the SampleFile object.

Initializer

import { SampleFileOptions } from 'projen'

const sampleFileOptions: SampleFileOptions = { ... }

Properties

Name	Type	Description
`contents`	`string`	The contents of the file to write.
`sourcePath`	`string`	Absolute path to a file to copy the contents from (does not need to be a text file).

`contents`^Optional

public readonly contents: string;

Type: string

The contents of the file to write.

`sourcePath`^Optional

public readonly sourcePath: string;

Type: 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') });

SampleReadmeProps

SampleReadme Properties.

Initializer

import { SampleReadmeProps } from 'projen'

const sampleReadmeProps: SampleReadmeProps = { ... }

Properties

Name	Type	Description
`contents`	`string`	The contents.
`filename`	`string`	The name of the README.md file.

`contents`^Optional

public readonly contents: string;

Type: string
Default: "# replace this"

The contents.

`filename`^Optional

public readonly filename: string;

Type: string
Default: "README.md"

The name of the README.md file.

Example

"readme.md"

SnapshotOptions

Options for the Snapshot synthesis.

Initializer

import { SnapshotOptions } from 'projen'

const snapshotOptions: SnapshotOptions = { ... }

Properties

Name	Type	Description
`parseJson`	`boolean`	Parse .json files as a JS object for improved inspection. This will fail if the contents are invalid JSON.

`parseJson`^Optional

public readonly parseJson: boolean;

Type: boolean
Default: true parse .json files into an object

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

SourceCodeOptions

Options for SourceCodeFile.

Initializer

import { SourceCodeOptions } from 'projen'

const sourceCodeOptions: SourceCodeOptions = { ... }

Properties

Name	Type	Description
`executable`	`boolean`	Whether the generated file should be marked as executable.
`indent`	`number`	Indentation size.
`readonly`	`boolean`	Whether the generated file should be readonly.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`indent`^Optional

public readonly indent: number;

Type: number
Default: 2

Indentation size.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

TaskCommonOptions

Initializer

import { TaskCommonOptions } from 'projen'

const taskCommonOptions: TaskCommonOptions = { ... }

Properties

Name	Type	Description
`condition`	`string`	A shell command which determines if the this task should be executed.
`cwd`	`string`	The working directory for all steps in this task (unless overridden by the step).
`description`	`string`	The description of this build command.
`env`	`{[ key: string ]: string}`	Defines environment variables for the execution of this task.
`requiredEnv`	`string[]`	A set of environment variables that must be defined in order to execute this task.
`shell`	`TaskShell`	The shell used to run this task's commands, including its `condition` and `$(...)` environment evaluation. Use {@link TaskShell} to pick a built-in or an explicit invocation. Set at project, task or step level; the nearest declared level wins.

`condition`^Optional

public readonly condition: string;

Type: 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.

`cwd`^Optional

public readonly cwd: string;

Type: string
Default: process.cwd()

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

`description`^Optional

public readonly description: string;

Type: string
Default: the task name

The description of this build command.

`env`^Optional

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

Type: {[ key: string ]: string}
Default: {}

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").

`requiredEnv`^Optional

public readonly requiredEnv: string[];

Type: 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.

`shell`^Optional

public readonly shell: TaskShell;

Type: TaskShell
Default: inherited from the task/project, otherwise the built-in projen shell

The shell used to run this task's commands, including its condition and $(...) environment evaluation. Use {@link TaskShell} to pick a built-in or an explicit invocation. Set at project, task or step level; the nearest declared level wins.

TaskOptions

Initializer

import { TaskOptions } from 'projen'

const taskOptions: TaskOptions = { ... }

Properties

Name	Type	Description
`condition`	`string`	A shell command which determines if the this task should be executed.
`cwd`	`string`	The working directory for all steps in this task (unless overridden by the step).
`description`	`string`	The description of this build command.
`env`	`{[ key: string ]: string}`	Defines environment variables for the execution of this task.
`requiredEnv`	`string[]`	A set of environment variables that must be defined in order to execute this task.
`shell`	`TaskShell`	The shell used to run this task's commands, including its `condition` and `$(...)` environment evaluation. Use {@link TaskShell} to pick a built-in or an explicit invocation. Set at project, task or step level; the nearest declared level wins.
`args`	`string[]`	Should the provided `exec` shell command receive fixed args.
`exec`	`string`	Shell command to execute as the first command of the task.
`execArgs`	`string[]`	Shell command to execute as the first command of the task, provided as a list of the program followed by its arguments (an "argv").
`receiveArgs`	`boolean`	Should the provided `exec` shell command receive args passed to the task.
`steps`	`TaskStep[]`	List of task steps to run.

`condition`^Optional

public readonly condition: string;

Type: 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.

`cwd`^Optional

public readonly cwd: string;

Type: string
Default: process.cwd()

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

`description`^Optional

public readonly description: string;

Type: string
Default: the task name

The description of this build command.

`env`^Optional

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

Type: {[ key: string ]: string}
Default: {}

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").

`requiredEnv`^Optional

public readonly requiredEnv: string[];

Type: 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.

`shell`^Optional

public readonly shell: TaskShell;

Type: TaskShell
Default: inherited from the task/project, otherwise the built-in projen shell

`args`^Optional

public readonly args: string[];

Type: string[]
Default: no arguments are passed to the step

Should the provided exec shell command receive fixed args.

[{@link TaskStepOptions.args }]({@link TaskStepOptions.args })

`exec`^Optional

public readonly exec: string;

Type: string
Default: add steps using task.exec(command) or task.spawn(subtask)

Shell command to execute as the first command of the task.

A single shell string, so only pass trusted input: an interpolated value is interpreted by the shell too. Use execArgs for arguments you did not write literally.

Mutually exclusive with execArgs.

`execArgs`^Optional

public readonly execArgs: string[];

Type: string[]
Default: add steps using task.execArgs(args), task.exec(command) or task.spawn(subtask)

Shell command to execute as the first command of the task, provided as a list of the program followed by its arguments (an "argv").

A convenient alternative to exec: arguments with spaces or special characters are passed through as-is, with no quoting needed. The elements are not run through a shell, so environment variables ($FOO) are not expanded and other shell features are unavailable.

[TaskStep.execArgs * Mutually exclusive with exec.](TaskStep.execArgs * Mutually exclusive with exec.)

`receiveArgs`^Optional

public readonly receiveArgs: boolean;

Type: boolean
Default: false

Should the provided exec shell command receive args passed to the task.

[{@link TaskStepOptions.receiveArgs }]({@link TaskStepOptions.receiveArgs })

`steps`^Optional

public readonly steps: TaskStep[];

Type: TaskStep[]

List of task steps to run.

TasksManifest

Schema for tasks.json.

Initializer

import { TasksManifest } from 'projen'

const tasksManifest: TasksManifest = { ... }

Properties

Name	Type	Description
`env`	`{[ key: string ]: string}`	Environment for all tasks.
`manifestVersion`	`number`	The version of the tasks manifest schema.
`shell`	`string \| string[]`	The default task shell, in `tasks.json` form: a keyword (`"projen"` or `"system"`) or an invocation argument list. See {@link TaskCommonOptions.shell}.
`tasks`	`{[ key: string ]: TaskSpec}`	All tasks available for this project.

`env`^Optional

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

Type: {[ key: string ]: string}

Environment for all tasks.

`manifestVersion`^Optional

public readonly manifestVersion: number;

Type: number
Default: the manifest is treated as a legacy (unversioned) manifest

The version of the tasks manifest schema.

Used by the task runtime to detect manifests produced by a newer version of projen. Manifests generated by older versions of projen omit this field and are treated as "legacy" for backwards compatibility.

`shell`^Optional

public readonly shell: string | string[];

Type: string | string[]

The default task shell, in tasks.json form: a keyword ("projen" or "system") or an invocation argument list. See {@link TaskCommonOptions.shell}.

`tasks`^Optional

public readonly tasks: {[ key: string ]: TaskSpec};

Type: {[ key: string ]: TaskSpec}

All tasks available for this project.

TaskSpec

Specification of a single task.

The tasks.json (manifest) form of a task. {@link TaskCommonOptions} is the form used to define one; they differ only in the rendered shell field.

Initializer

import { TaskSpec } from 'projen'

const taskSpec: TaskSpec = { ... }

Properties

Name	Type	Description
`name`	`string`	Task name.
`condition`	`string`	A shell command which determines if the this task should be executed.
`cwd`	`string`	The working directory for all steps in this task (unless overridden by the step).
`description`	`string`	The description of this build command.
`env`	`{[ key: string ]: string}`	Defines environment variables for the execution of this task.
`requiredEnv`	`string[]`	A set of environment variables that must be defined in order to execute this task.
`shell`	`string \| string[]`	The task shell in `tasks.json` form: a keyword (`"projen"` or `"system"`) or an invocation argument list.
`steps`	`TaskStep[]`	Task steps.

`name`^Required

public readonly name: string;

Type: string

Task name.

`condition`^Optional

public readonly condition: string;

Type: 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.

`cwd`^Optional

public readonly cwd: string;

Type: string
Default: process.cwd()

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

`description`^Optional

public readonly description: string;

Type: string
Default: the task name

The description of this build command.

`env`^Optional

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

Type: {[ key: string ]: string}
Default: {}

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").

`requiredEnv`^Optional

public readonly requiredEnv: string[];

Type: 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.

`shell`^Optional

public readonly shell: string | string[];

Type: string | string[]
Default: the built-in projen shell

The task shell in tasks.json form: a keyword ("projen" or "system") or an invocation argument list.

`steps`^Optional

public readonly steps: TaskStep[];

Type: TaskStep[]

Task steps.

TaskStep

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.

The tasks.json (manifest) form of a step. {@link TaskStepOptions} is the form used to define steps (via task.exec() etc.); they differ only in the rendered shell field.

Initializer

import { TaskStep } from 'projen'

const taskStep: TaskStep = { ... }

Properties

Name	Type	Description
`args`	`string[]`	A list of fixed arguments always passed to the step.
`builtin`	`string`	The name of a built-in task to execute.
`condition`	`string`	A shell command which determines if the this step should be executed.
`cwd`	`string`	The working directory for this step.
`env`	`{[ key: string ]: string}`	Defines environment variables for the execution of this step (`exec` and `builtin` only).
`exec`	`string`	Shell command to execute.
`execArgs`	`string[]`	Shell command to execute, provided as a list of the program followed by its arguments (an "argv").
`name`	`string`	Step name.
`outputEnv`	`string`	Capture this step's standard output and expose it to later steps as an environment variable with this name.
`receiveArgs`	`boolean`	Should this step receive args passed to the task.
`say`	`string`	Print a message.
`shell`	`string \| string[]`	The step shell in `tasks.json` form: a keyword (`"projen"` or `"system"`) or an invocation argument list.
`spawn`	`string`	Subtask to execute.

`args`^Optional

public readonly args: string[];

Type: string[]
Default: no arguments are passed to the step

A list of fixed arguments always passed to the step.

[{@link TaskStepOptions.args }]({@link TaskStepOptions.args })

`builtin`^Optional

public readonly builtin: string;

Type: string
Default: do not execute a builtin task

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.

`condition`^Optional

public readonly condition: string;

Type: 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).

`cwd`^Optional

public readonly cwd: string;

Type: string
Default: determined by the task

The working directory for this step.

`env`^Optional

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

Type: {[ key: string ]: string}
Default: no environment variables defined in step

Defines environment variables for the execution of this step (exec and builtin only).

[{@link TaskStepOptions.env }]({@link TaskStepOptions.env })

`exec`^Optional

public readonly exec: string;

Type: string
Default: don't execute a shell command

Shell command to execute.

A single shell string, so only pass trusted input: an interpolated value is interpreted by the shell too. Use execArgs for arguments you did not write literally.

`execArgs`^Optional

public readonly execArgs: string[];

Type: string[]
Default: don't execute a shell command

Shell command to execute, provided as a list of the program followed by its arguments (an "argv").

Often more convenient than exec: each element is passed to the program as-is, so arguments with spaces or special characters don't need quoting. Fixed (args) or received (receiveArgs) arguments are inserted wherever a $@ element appears, or appended at the end if there is none.

The elements are not run through a shell, so environment variables ($FOO) are not expanded and other shell features are unavailable. Use exec if you need them.

Mutually exclusive with exec.

Example

{ execArgs: ["echo", "hello world"] }

`name`^Optional

public readonly name: string;

Type: string
Default: no name

Step name.

`outputEnv`^Optional

public readonly outputEnv: string;

Type: string
Default: stdout is not captured

Capture this step's standard output and expose it to later steps as an environment variable with this name.

[{@link TaskStepOptions.outputEnv }]({@link TaskStepOptions.outputEnv })

`receiveArgs`^Optional

public readonly receiveArgs: boolean;

Type: boolean
Default: false

Should this step receive args passed to the task.

[{@link TaskStepOptions.receiveArgs }]({@link TaskStepOptions.receiveArgs })

`say`^Optional

public readonly say: string;

Type: string
Default: don't say anything

Print a message.

`shell`^Optional

public readonly shell: string | string[];

Type: string | string[]
Default: the task's (or project's) shell

The step shell in tasks.json form: a keyword ("projen" or "system") or an invocation argument list.

`spawn`^Optional

public readonly spawn: string;

Type: string
Default: don't spawn a subtask

Subtask to execute.

TaskStepOptions

Options for task steps.

Initializer

import { TaskStepOptions } from 'projen'

const taskStepOptions: TaskStepOptions = { ... }

Properties

Name	Type	Description
`args`	`string[]`	A list of fixed arguments always passed to the step.
`condition`	`string`	A shell command which determines if the this step should be executed.
`cwd`	`string`	The working directory for this step.
`env`	`{[ key: string ]: string}`	Defines environment variables for the execution of this step (`exec` and `builtin` only).
`name`	`string`	Step name.
`outputEnv`	`string`	Capture this step's (trimmed) stdout into an environment variable of this name, visible to all later steps of the task run.
`receiveArgs`	`boolean`	Should this step receive args passed to the task.
`shell`	`TaskShell`	The shell used to run this step, overriding the task/project shell.

`args`^Optional

public readonly args: string[];

Type: string[]
Default: no arguments are passed to the step

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

task.spawn("deploy", { args: ["--force"] });

`condition`^Optional

public readonly condition: string;

Type: 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).

`cwd`^Optional

public readonly cwd: string;

Type: string
Default: determined by the task

The working directory for this step.

`env`^Optional

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

Type: {[ key: string ]: string}
Default: no environment variables defined in step

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

{ "foo": "bar", "boo": "$(echo baz)" }

`name`^Optional

public readonly name: string;

Type: string
Default: no name

Step name.

`outputEnv`^Optional

public readonly outputEnv: string;

Type: string
Default: stdout is not captured

Capture this step's (trimmed) stdout into an environment variable of this name, visible to all later steps of the task run.

For spawn steps the spawned subtask's combined stdout is captured.

Set only when the step runs (a skipped step leaves it unset) and always overwrites. The step's output still streams live.

`receiveArgs`^Optional

public readonly receiveArgs: boolean;

Type: boolean
Default: false

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 double 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

task.exec("echo Hello $@ World!", { receiveArgs: true });

`shell`^Optional

public readonly shell: TaskShell;

Type: TaskShell
Default: the task's (or project's) shell

The shell used to run this step, overriding the task/project shell.

[{@link TaskCommonOptions.shell }]({@link TaskCommonOptions.shell })

TextFileOptions

Options for TextFile.

Initializer

import { TextFileOptions } from 'projen'

const textFileOptions: TextFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`lines`	`string[]`	The contents of the text file.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`lines`^Optional

public readonly lines: string[];

Type: string[]
Default: [] empty file

The contents of the text file.

You can use addLine() to append lines.

TomlFileOptions

Options for TomlFile.

Initializer

import { TomlFileOptions } from 'projen'

const tomlFileOptions: TomlFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

VersionBranchOptions

Options to pass to modifyBranchEnvironment.

Initializer

import { VersionBranchOptions } from 'projen'

const versionBranchOptions: VersionBranchOptions = { ... }

Properties

Name	Type	Description
`majorVersion`	`number`	The major versions released from this branch.
`minMajorVersion`	`number`	The minimum major version to release.
`minorVersion`	`number`	The minor versions released from this branch.
`prerelease`	`string`	Bump the version as a pre-release tag.
`tagPrefix`	`string`	Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.

`majorVersion`^Optional

public readonly majorVersion: number;

Type: number

The major versions released from this branch.

`minMajorVersion`^Optional

public readonly minMajorVersion: number;

Type: number

The minimum major version to release.

`minorVersion`^Optional

public readonly minorVersion: number;

Type: number

The minor versions released from this branch.

`prerelease`^Optional

public readonly prerelease: string;

Type: string
Default: normal releases

Bump the version as a pre-release tag.

`tagPrefix`^Optional

public readonly tagPrefix: string;

Type: string
Default: no prefix

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.

VersionOptions

Options for Version.

Initializer

import { VersionOptions } from 'projen'

const versionOptions: VersionOptions = { ... }

Properties

Name	Type	Description
`artifactsDirectory`	`string`	The name of the directory into which `changelog.md` and `version.txt` files are emitted.
`versionInputFile`	`string`	A name of a .json file to set the `version` field in after a bump.
`bumpPackage`	`string`	The `commit-and-tag-version` compatible package used to bump the package version, as a dependency string.
`nextVersionCommand`	`string`	A shell command to control the next version to release.
`releasableCommits`	`ReleasableCommits`	Find commits that should be considered releasable Used to decide if a release is required.
`tagPrefix`	`string`	The tag prefix corresponding to this version.
`versionrcOptions`	`{[ key: string ]: any}`	Custom configuration for versionrc file used by standard-release.

`artifactsDirectory`^Required

public readonly artifactsDirectory: string;

Type: string

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

`versionInputFile`^Required

public readonly versionInputFile: string;

Type: string

A name of a .json file to set the version field in after a bump.

Example

"package.json"

`bumpPackage`^Optional

public readonly bumpPackage: string;

Type: string
Default: "commit-and-tag-version@13"

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.

`nextVersionCommand`^Optional

public readonly nextVersionCommand: string;

Type: string
Default: The next version will be determined based on the commit history and project settings.

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.

`releasableCommits`^Optional

public readonly releasableCommits: ReleasableCommits;

Type: ReleasableCommits
Default: ReleasableCommits.everyCommit()

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

`tagPrefix`^Optional

public readonly tagPrefix: string;

Type: string

The tag prefix corresponding to this version.

`versionrcOptions`^Optional

public readonly versionrcOptions: {[ key: string ]: any};

Type: {[ key: string ]: any}

Custom configuration for versionrc file used by standard-release.

XmlFileOptions

Options for XmlFile.

Initializer

import { XmlFileOptions } from 'projen'

const xmlFileOptions: XmlFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

YamlFileOptions

Options for JsonFile.

Initializer

import { YamlFileOptions } from 'projen'

const yamlFileOptions: YamlFileOptions = { ... }

Properties

Name	Type	Description
`committed`	`boolean`	Indicates whether this file should be committed to git or ignored.
`editGitignore`	`boolean`	Update the project's .gitignore file.
`executable`	`boolean`	Whether the generated file should be marked as executable.
`marker`	`boolean`	Adds the projen marker to the file.
`readonly`	`boolean`	Whether the generated file should be readonly.
`obj`	`any`	The object that will be serialized. You can modify the object's contents before synthesis.
`omitEmpty`	`boolean`	Omits empty objects and arrays.
`lineWidth`	`number`	Maximum line width (set to 0 to disable folding).

`committed`^Optional

public readonly committed: boolean;

Type: boolean
Default: true

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.

`editGitignore`^Optional

public readonly editGitignore: boolean;

Type: boolean
Default: true

Update the project's .gitignore file.

`executable`^Optional

public readonly executable: boolean;

Type: boolean
Default: false

Whether the generated file should be marked as executable.

`marker`^Optional

public readonly marker: boolean;

Type: boolean
Default: marker will be included as long as the project is not ejected

Adds the projen marker to the file.

`readonly`^Optional

public readonly readonly: boolean;

Type: boolean
Default: true

Whether the generated file should be readonly.

`obj`^Optional

public readonly obj: any;

Type: any
Default: {} an empty object (use file.obj to mutate).

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

`omitEmpty`^Optional

public readonly omitEmpty: boolean;

Type: boolean
Default: false

Omits empty objects and arrays.

`lineWidth`^Optional

public readonly lineWidth: number;

Type: number
Default: 0

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

Classes

DevEnvironmentDockerImage

Options for specifying the Docker image of the container.

Static Functions

Name	Description
`fromFile`	The relative path of a Dockerfile that defines the container contents.
`fromImage`	A publicly available Docker image.

`fromFile`

import { DevEnvironmentDockerImage } from 'projen'

DevEnvironmentDockerImage.fromFile(dockerFile: string)

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

Example

'.gitpod.Docker'

`dockerFile`^Required

Type: string

a relative path.

`fromImage`

import { DevEnvironmentDockerImage } from 'projen'

DevEnvironmentDockerImage.fromImage(image: string)

A publicly available Docker image.

Example

'ubuntu:latest'

`image`^Required

Type: string

a Docker image.

Properties

Name	Type	Description
`dockerFile`	`string`	The relative path of a Dockerfile that defines the container contents.
`image`	`string`	A publicly available Docker image.

`dockerFile`^Optional

public readonly dockerFile: string;

Type: string

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

`image`^Optional

public readonly image: string;

Type: string

A publicly available Docker image.

DockerComposeService

Implements: IDockerComposeServiceName

A docker-compose service.

Initializers

import { DockerComposeService } from 'projen'

new DockerComposeService(serviceName: string, serviceDescription: DockerComposeServiceDescription)

Name	Type	Description
`serviceName`	`string`	The name of the docker compose service.
`serviceDescription`	`DockerComposeServiceDescription`	No description.

`serviceName`^Required

Type: string

The name of the docker compose service.

`serviceDescription`^Required

Type: DockerComposeServiceDescription

Methods

Name	Description
`addDependsOn`	Make the service depend on another service.
`addEnvironment`	Add an environment variable.
`addLabel`	Add a label.
`addNetwork`	Add a network to the service.
`addPort`	Add a port mapping.
`addVolume`	Add a volume to the service.

`addDependsOn`

public addDependsOn(serviceName: IDockerComposeServiceName): void

Make the service depend on another service.

`serviceName`^Required

Type: IDockerComposeServiceName

`addEnvironment`

public addEnvironment(name: string, value: string): void

Add an environment variable.

`name`^Required

Type: string

environment variable name.

`value`^Required

Type: string

value of the environment variable.

`addLabel`

public addLabel(name: string, value: string): void

Add a label.

`name`^Required

Type: string

environment variable name.

`value`^Required

Type: string

value of the environment variable.

`addNetwork`

public addNetwork(network: IDockerComposeNetworkBinding): void

Add a network to the service.

`network`^Required

Type: IDockerComposeNetworkBinding

`addPort`

public addPort(publishedPort: number, targetPort: number, options?: DockerComposePortMappingOptions): void

Add a port mapping.

`publishedPort`^Required

Type: number

Published port number.

`targetPort`^Required

Type: number

Container's port number.

`options`^Optional

Type: DockerComposePortMappingOptions

Port mapping options.

`addVolume`

public addVolume(volume: IDockerComposeVolumeBinding): void

Add a volume to the service.

`volume`^Required

Type: IDockerComposeVolumeBinding

Properties

Name	Type	Description
`dependsOn`	`IDockerComposeServiceName[]`	Other services that this service depends on.
`environment`	`{[ key: string ]: string}`	Environment variables.
`labels`	`{[ key: string ]: string}`	Attached labels.
`networks`	`IDockerComposeNetworkBinding[]`	Networks mounted in the container.
`ports`	`DockerComposeServicePort[]`	Published ports.
`serviceName`	`string`	Name of the service.
`volumes`	`IDockerComposeVolumeBinding[]`	Volumes mounted in the container.
`command`	`string[]`	Command to run in the container.
`entrypoint`	`string[]`	Entrypoint to run in the container.
`image`	`string`	Docker image.
`imageBuild`	`DockerComposeBuild`	Docker image build instructions.
`platform`	`string`	Target platform.
`privileged`	`boolean`	Run in privileged mode.

`dependsOn`^Required

public readonly dependsOn: IDockerComposeServiceName[];

Type: IDockerComposeServiceName[]

Other services that this service depends on.

`environment`^Required

public readonly environment: {[ key: string ]: string};

Type: {[ key: string ]: string}

Environment variables.

`labels`^Required

public readonly labels: {[ key: string ]: string};

Type: {[ key: string ]: string}

Attached labels.

`networks`^Required

public readonly networks: IDockerComposeNetworkBinding[];

Type: IDockerComposeNetworkBinding[]

Networks mounted in the container.

`ports`^Required

public readonly ports: DockerComposeServicePort[];

Type: DockerComposeServicePort[]

Published ports.

`serviceName`^Required

public readonly serviceName: string;

Type: string

Name of the service.

`volumes`^Required

public readonly volumes: IDockerComposeVolumeBinding[];

Type: IDockerComposeVolumeBinding[]

Volumes mounted in the container.

`command`^Optional

public readonly command: string[];

Type: string[]

Command to run in the container.

`entrypoint`^Optional

public readonly entrypoint: string[];

Type: string[]

Entrypoint to run in the container.

`image`^Optional

public readonly image: string;

Type: string

Docker image.

`imageBuild`^Optional

public readonly imageBuild: DockerComposeBuild;

Type: DockerComposeBuild

Docker image build instructions.

`platform`^Optional

public readonly platform: string;

Type: string

Target platform.

`privileged`^Optional

public readonly privileged: boolean;

Type: boolean

Run in privileged mode.

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

const output = JsonPatch.apply(input,
 JsonPatch.replace('/world/hi/there', 'goodbye'),
 JsonPatch.add('/world/foo/', 'boom'),
 JsonPatch.remove('/hello'));

Static Functions

Name	Description
`add`	Adds a value to an object or inserts it into an array.
`apply`	Applies a set of JSON-Patch (RFC-6902) operations to `document` and returns the result.
`copy`	Copies a value from one location to another within the JSON document.
`escapePath`	Escapes a json pointer path.
`move`	Moves a value from one location to the other.
`remove`	Removes a value from an object or array.
`replace`	Replaces a value.
`test`	Tests that the specified value is set in the document.

`add`

import { JsonPatch } from 'projen'

JsonPatch.add(path: string, value: any)

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

JsonPatch.add('/biscuits/1', { "name": "Ginger Nut" })

`path`^Required

Type: string

`value`^Required

Type: any

`apply`

import { JsonPatch } from 'projen'

JsonPatch.apply(document: any, ops: ...JsonPatch[])

Applies a set of JSON-Patch (RFC-6902) operations to document and returns the result.

`document`^Required

Type: any

The document to patch.

`ops`^Required

Type: ...JsonPatch[]

The operations to apply.

`copy`

import { JsonPatch } from 'projen'

JsonPatch.copy(from: string, path: string)

Copies a value from one location to another within the JSON document.

Both from and path are JSON Pointers.

Example

JsonPatch.copy('/biscuits/0', '/best_biscuit')

`from`^Required

Type: string

`path`^Required

Type: string

`escapePath`

import { JsonPatch } from 'projen'

JsonPatch.escapePath(path: string)

Escapes a json pointer path.

`path`^Required

Type: string

The raw pointer.

`move`

import { JsonPatch } from 'projen'

JsonPatch.move(from: string, path: string)

Moves a value from one location to the other.

Both from and path are JSON Pointers.

Example

JsonPatch.move('/biscuits', '/cookies')

`from`^Required

Type: string

`path`^Required

Type: string

`remove`

import { JsonPatch } from 'projen'

JsonPatch.remove(path: string)

Removes a value from an object or array.

Example

JsonPatch.remove('/biscuits/0')

`path`^Required

Type: string

`replace`

import { JsonPatch } from 'projen'

JsonPatch.replace(path: string, value: any)

Replaces a value.

Equivalent to a “remove” followed by an “add”.

Example

JsonPatch.replace('/biscuits/0/name', 'Chocolate Digestive')

`path`^Required

Type: string

`value`^Required

Type: any

`test`

import { JsonPatch } from 'projen'

JsonPatch.test(path: string, value: any, failureBehavior?: TestFailureBehavior)

Tests that the specified value is set in the document.

If the test fails, then the patch as a whole should not apply.

Example

JsonPatch.test('/best_biscuit/name', 'Choco Leibniz')

`path`^Required

Type: string

`value`^Required

Type: any

`failureBehavior`^Optional

Type: TestFailureBehavior

Projects

Programmatic API for projen.

Static Functions

Name	Description
`createProject`	Creates a new project with defaults.

`createProject`

import { Projects } from 'projen'

Projects.createProject(options: CreateProjectOptions)

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)

`options`^Required

Type: CreateProjectOptions

ReleasableCommits

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

This setting only controls whether a release is triggered, yes or no. The paths used here are independent of the code that controls what commits are inspected to determine the version number.

Static Functions

Name	Description
`everyCommit`	Release every commit.
`exec`	Use an arbitrary shell command to find releasable commits since the latest tag.
`featuresAndFixes`	Release only features and fixes.
`ofType`	Limit commits by their conventional commit type.

`everyCommit`

import { ReleasableCommits } from 'projen'

ReleasableCommits.everyCommit(path?: string)

Release every commit.

This will only not release if the most recent commit is tagged with the latest matching tag.

`path`^Optional

Type: string

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 ".".

`exec`

import { ReleasableCommits } from 'projen'

ReleasableCommits.exec(cmd: string)

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 is available as an environment variable (set to the actual latest tag for the given prefix).

Example

"git log --oneline $LATEST_TAG..HEAD -- ."

`cmd`^Required

Type: string

`featuresAndFixes`

import { ReleasableCommits } from 'projen'

ReleasableCommits.featuresAndFixes(path?: string)

Release only features and fixes.

Shorthand for ReleasableCommits.onlyOfType(['feat', 'fix']).

`path`^Optional

Type: string

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 ".".

`ofType`

import { ReleasableCommits } from 'projen'

ReleasableCommits.ofType(types: string[], path?: string)

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.

`types`^Required

Type: string[]

List of conventional commit types that should be released.

`path`^Optional

Type: string

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 ".".

Properties

Name	Type	Description
`cmd`	`string`	No description.

`cmd`^Required

public readonly cmd: string;

Type: string

Task

A task that can be performed on the project.

Modeled as a series of shell commands and subtasks.

Initializers

import { Task } from 'projen'

new Task(name: string, props?: TaskOptions)

Name	Type	Description
`name`	`string`	No description.
`props`	`TaskOptions`	No description.

`name`^Required

Type: string

`props`^Optional

Type: TaskOptions

Methods

Name	Description
`addCondition`	Add a command to execute which determines if the task should be skipped.
`addSteps`	Adds steps to this task.
`builtin`	Execute a builtin task.
`env`	Adds an environment variable to this task.
`exec`	Executes a shell command.
`execArgs`	Executes a command provided as a list of the program followed by its arguments (an "argv").
`insertStep`	Insert one or more steps at a given index.
`lock`	Forbid additional changes to this task.
`prependExec`	Adds a command at the beginning of the task.
`prependSay`	Says something at the beginning of the task.
`prependSpawn`	Adds a spawn instruction at the beginning of the task.
`prependSteps`	Adds steps at the beginning of this task.
`removeStep`	No description.
`reset`	Reset the task so it no longer has any commands.
`say`	Say something.
`spawn`	Spawns a sub-task.
`updateStep`	No description.

`addCondition`

public 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.

[{@link Task.condition }]({@link Task.condition })

`condition`^Required

Type: ...string[]

The command to execute.

`addSteps`

public addSteps(steps: ...TaskStep[]): void

Adds steps to this task.

This is a generic method that accepts any task step (exec, spawn, say, builtin).

`steps`^Required

Type: ...TaskStep[]

The steps to add.

`builtin`

public 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.

`name`^Required

Type: string

The name of the builtin task to execute (e.g. release/resolve-version).

`env`

public env(name: string, value: string): void

Adds an environment variable to this task.

`name`^Required

Type: string

The name of the variable.

`value`^Required

Type: string

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.

`exec`

public exec(command: string, options?: TaskStepOptions): void

Executes a shell command.

`command`^Required

Type: string

Shell command.

`options`^Optional

Type: TaskStepOptions

Options.

`execArgs`

public execArgs(command: string[], options?: TaskStepOptions): void

Executes a command provided as a list of the program followed by its arguments (an "argv").

A convenient alternative to Task.exec: arguments with spaces or special characters are passed through as-is, with no quoting needed. The elements are not run through a shell, so environment variables ($FOO) are not expanded and other shell features are unavailable.

Example

task.execArgs(["echo", "hello world"]);

`command`^Required

Type: string[]

The program followed by its arguments.

`options`^Optional

Type: TaskStepOptions

Options.

`insertStep`

public insertStep(index: number, steps: ...TaskStep[]): void

Insert one or more steps at a given index.

`index`^Required

Type: number

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.

`steps`^Required

Type: ...TaskStep[]

The steps to insert.

`lock`

public lock(): void

Forbid additional changes to this task.

`prependExec`

public prependExec(command: string, options?: TaskStepOptions): void

Adds a command at the beginning of the task.

`command`^Required

Type: string

The command to add.

`options`^Optional

Type: TaskStepOptions

`prependSay`

public prependSay(message: string, options?: TaskStepOptions): void

Says something at the beginning of the task.

`message`^Required

Type: string

Your message.

`options`^Optional

Type: TaskStepOptions

`prependSpawn`

public prependSpawn(subtask: Task, options?: TaskStepOptions): void

Adds a spawn instruction at the beginning of the task.

`subtask`^Required

Type: Task

The subtask to execute.

`options`^Optional

Type: TaskStepOptions

`prependSteps`

public prependSteps(steps: ...TaskStep[]): void

Adds steps at the beginning of this task.

`steps`^Required

Type: ...TaskStep[]

The steps to add.

`removeStep`

public removeStep(index: number): void

`index`^Required

Type: number

The index of the step to remove.

`reset`

public reset(command?: string, options?: TaskStepOptions): void

Reset the task so it no longer has any commands.

`command`^Optional

Type: string

the first command to add to the task after it was cleared.

`options`^Optional

Type: TaskStepOptions

`say`

public say(message: string, options?: TaskStepOptions): void

Say something.

`message`^Required

Type: string

Your message.

`options`^Optional

Type: TaskStepOptions

Options.

`spawn`

public spawn(subtask: Task, options?: TaskStepOptions): void

Spawns a sub-task.

`subtask`^Required

Type: Task

The subtask to execute.

`options`^Optional

Type: TaskStepOptions

`updateStep`

public updateStep(index: number, step: TaskStep): void

`index`^Required

Type: number

The index of the step to edit.

`step`^Required

Type: TaskStep

The new step to replace the old one entirely, it is not merged with the old step.

Properties

Name	Type	Description
`envVars`	`{[ key: string ]: string}`	Returns all environment variables in the task level.
`name`	`string`	Task name.
`steps`	`TaskStep[]`	Returns an immutable copy of all the step specifications of the task.
`condition`	`string`	A command to execute which determines if the task should be skipped.
`cwd`	`string`	Returns the working directory for this task.
`description`	`string`	Returns the description of this task.
`shell`	`TaskShell`	The shell used to run this task's commands, or `undefined` when inheriting the built-in default shell.

`envVars`^Required

public readonly envVars: {[ key: string ]: string};

Type: {[ key: string ]: string}

Returns all environment variables in the task level.

`name`^Required

public readonly name: string;

Type: string

Task name.

`steps`^Required

public readonly steps: TaskStep[];

Type: TaskStep[]

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

`condition`^Optional

public readonly condition: string;

Type: 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.

`cwd`^Optional

public readonly cwd: string;

Type: string

Returns the working directory for this task.

Sets the working directory for this task.

`description`^Optional

public readonly description: string;

Type: string

Returns the description of this task.

Sets the description of this task.

`shell`^Optional

public readonly shell: TaskShell;

Type: TaskShell

The shell used to run this task's commands, or undefined when inheriting the built-in default shell.

Sets the shell used to run this task's commands.

[{@link TaskCommonOptions.shell }]({@link TaskCommonOptions.shell })

TaskShell

The shell used to run a task's commands - including its condition and any $(...) environment-variable evaluation.

Choose one of the built-in shells, or provide an explicit shell invocation:

{@link TaskShell.projen} (the default) - the built-in cross-platform shell.
{@link TaskShell.system} - the operating system's native shell.
{@link TaskShell.bash} / {@link TaskShell.sh} - common POSIX shells.
{@link TaskShell.command} - an arbitrary shell invocation given as an explicit argument list, e.g. TaskShell.command(["npx", "-c"]).

A shell can be set at the project (tasks), task and step level, and the nearest declared level wins (it is a scalar override, not merged).

Static Functions

Name	Description
`bash`	Runs commands through `bash -c`.
`command`	An arbitrary shell invocation, given as an explicit argument list.
`projen`	The built-in cross-platform shell (the default).
`sh`	Runs commands through `sh -c`.
`system`	The operating system's native shell (`/bin/sh` on POSIX, `cmd.exe` on Windows).

`bash`

import { TaskShell } from 'projen'

TaskShell.bash()

Runs commands through bash -c.

`command`

import { TaskShell } from 'projen'

TaskShell.command(command: string[])

An arbitrary shell invocation, given as an explicit argument list.

The task command is appended as the final argument, so the invocation must accept the command as its last argument (e.g. bash -c, sh -c, npx -c, yarn exec).

Example

TaskShell.command(["npx", "-c"]);

`command`^Required

Type: string[]

The shell program followed by its arguments.

Must not be empty.

`projen`

import { TaskShell } from 'projen'

TaskShell.projen()

The built-in cross-platform shell (the default).

It interprets POSIX-style task syntax (mkdir -p, &&, $VAR, ...) identically on every platform, including Windows.

`sh`

import { TaskShell } from 'projen'

TaskShell.sh()

Runs commands through sh -c.

`system`

import { TaskShell } from 'projen'

TaskShell.system()

The operating system's native shell (/bin/sh on POSIX, cmd.exe on Windows).

Use this to opt out of the cross-platform shell and run commands through whatever shell the host provides.

Steps given as an argv (execArgs) are spawned without a shell, so on Windows they cannot run .cmd/.bat shims such as npm-installed CLIs.

Testing

A Testing static class with a .synth helper for getting a snapshots of construct outputs. Useful for snapshot testing with Jest.

Example

`expect(Testing.synth(someProject)).toMatchSnapshot()`

Static Functions

Name	Description
`synth`	Produces a simple JS object that represents the contents of the projects with field names being file paths.

`synth`

import { Testing } from 'projen'

Testing.synth(project: Project, options?: SnapshotOptions)

Produces a simple JS object that represents the contents of the projects with field names being file paths.

`project`^Required

Type: Project

the project to produce a snapshot for.

`options`^Optional

Type: SnapshotOptions

Protocols

ICompareString

Implemented By: ICompareString

Methods

Name	Description
`compare`	No description.

`compare`

public compare(a: string, b: string): number

`a`^Required

Type: string

The first string.

`b`^Required

Type: string

The second string.

IDevEnvironment

Implemented By: projen.vscode.DevContainer, Gitpod, projen.vscode.IDevContainerEnvironment, IDevEnvironment

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

Methods

Name	Description
`addDockerImage`	Add a custom Docker image or Dockerfile for the container.
`addPorts`	Adds ports that should be exposed (forwarded) from the container.
`addTasks`	Adds tasks to run when the container starts.
`addVscodeExtensions`	Adds a list of VSCode extensions that should be automatically installed in the container.

`addDockerImage`

public addDockerImage(image: DevEnvironmentDockerImage): void

Add a custom Docker image or Dockerfile for the container.

`image`^Required

Type: DevEnvironmentDockerImage

The Docker image.

`addPorts`

public addPorts(ports: ...string[]): void

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

`ports`^Required

Type: ...string[]

The new ports.

`addTasks`

public addTasks(tasks: ...Task[]): void

Adds tasks to run when the container starts.

`tasks`^Required

Type: ...Task[]

The new tasks.

`addVscodeExtensions`

public addVscodeExtensions(extensions: ...string[]): void

Adds a list of VSCode extensions that should be automatically installed in the container.

`extensions`^Required

Type: ...string[]

The extension IDs.

IDockerComposeNetworkBinding

Implemented By: IDockerComposeNetworkBinding

Network binding information.

Methods

Name	Description
`bind`	Binds the requested network to the docker-compose network configuration and provide mounting instructions for synthesis.

`bind`

public bind(networkConfig: IDockerComposeNetworkConfig): string

Binds the requested network to the docker-compose network configuration and provide mounting instructions for synthesis.

`networkConfig`^Required

Type: IDockerComposeNetworkConfig

the network configuration.

IDockerComposeNetworkConfig

Implemented By: IDockerComposeNetworkConfig

Storage for network configuration.

Methods

Name	Description
`addNetworkConfiguration`	Add network configuration to the repository.

`addNetworkConfiguration`

public addNetworkConfiguration(networkName: string, configuration: DockerComposeNetworkConfig): void

Add network configuration to the repository.

`networkName`^Required

Type: string

`configuration`^Required

Type: DockerComposeNetworkConfig

IDockerComposeServiceName

Implemented By: DockerComposeService, IDockerComposeServiceName

An interface providing the name of a docker compose service.

Properties

Name	Type	Description
`serviceName`	`string`	The name of the docker compose service.

`serviceName`^Required

public readonly serviceName: string;

Type: string

The name of the docker compose service.

IDockerComposeVolumeBinding

Implemented By: IDockerComposeVolumeBinding

Volume binding information.

Methods

Name	Description
`bind`	Binds the requested volume to the docker-compose volume configuration and provide mounting instructions for synthesis.

`bind`

public bind(volumeConfig: IDockerComposeVolumeConfig): DockerComposeVolumeMount

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

`volumeConfig`^Required

Type: IDockerComposeVolumeConfig

the volume configuration.

IDockerComposeVolumeConfig

Implemented By: IDockerComposeVolumeConfig

Storage for volume configuration.

Methods

Name	Description
`addVolumeConfiguration`	Add volume configuration to the repository.

`addVolumeConfiguration`

public addVolumeConfiguration(volumeName: string, configuration: DockerComposeVolumeConfig): void

Add volume configuration to the repository.

`volumeName`^Required

Type: string

`configuration`^Required

Type: DockerComposeVolumeConfig

IResolvable

Implemented By: IResolvable

Methods

Name	Description
`toJSON`	Resolves and returns content.

`toJSON`

public toJSON(): any

Resolves and returns content.

IResolver

Implemented By: IResolver

API for resolving tokens when synthesizing file content.

Methods

Name	Description
`resolve`	Given a value (object/string/array/whatever, looks up any functions inside the object and returns an object where all functions are called.

`resolve`

public 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.

`value`^Required

Type: any

The value to resolve.

`options`^Optional

Type: ResolveOptions

IScriptRunner

Implemented By: projen.typescript.TypeScriptRunner, ScriptRunner, IScriptRunner

A script runner that can produce the configuration to execute a file of a particular type.

Methods

Name	Description
`configFor`	Produce the configuration to run the given entrypoint.

`configFor`

public configFor(entrypoint: string): RunScriptConfig

Produce the configuration to run the given entrypoint.

`entrypoint`^Required

Type: string

Enums

AiAgent

Supported AI coding assistants and their instruction file locations.

Members

Name	Description
`GITHUB_COPILOT`	GitHub Copilot - .github/copilot-instructions.md.
`CURSOR`	Cursor IDE - .cursor/rules/project.md.
`CLAUDE`	Claude Code - CLAUDE.md.
`AMAZON_Q`	Amazon Q - .amazonq/rules/project.md.
`KIRO`	Kiro - .kiro/steering/project.md.
`CODEX`	OpenAI Codex - AGENTS.md.

`GITHUB_COPILOT`

GitHub Copilot - .github/copilot-instructions.md.

`CURSOR`

Cursor IDE - .cursor/rules/project.md.

`CLAUDE`

Claude Code - CLAUDE.md.

`AMAZON_Q`

Amazon Q - .amazonq/rules/project.md.

`KIRO`

Kiro - .kiro/steering/project.md.

`CODEX`

OpenAI Codex - AGENTS.md.

DependencyType

Type of dependency.

Members

Name	Description
`RUNTIME`	The dependency is required for the program/library during runtime.
`PEER`	The dependency is required at runtime but expected to be installed by the consumer.
`BUNDLED`	The dependency is bundled and shipped with the module, so consumers are not required to install it.
`BUILD`	The dependency is required to run the `build` task.
`TEST`	The dependency is required to run the `test` task.
`DEVENV`	The dependency is required for development (e.g. IDE plugins).
`OVERRIDE`	Transient dependency that needs to be overwritten.
`OPTIONAL`	An optional dependency that may be used at runtime if available, but is not required.

`RUNTIME`

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

`PEER`

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

`BUNDLED`

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

`BUILD`

The dependency is required to run the build task.

`TEST`

The dependency is required to run the test task.

`DEVENV`

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

`OVERRIDE`

Transient dependency that needs to be overwritten.

Available for Node packages

`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.

DockerComposeProtocol

Network protocol for port mapping.

Members

Name	Description
`TCP`	TCP protocol.
`UDP`	UDP protocol.

`TCP`

TCP protocol.

`UDP`

UDP protocol.

EndOfLine

The end of line characters supported by git.

Members

Name	Description
`AUTO`	Maintain existing (mixed values within one file are normalised by looking at what's used after the first line).
`CRLF`	Carriage Return + Line Feed characters (\r\n), common on Windows.
`LF`	Line Feed only (\n), common on Linux and macOS as well as inside git repos.
`NONE`	Disable and do not configure the end of line character.

`AUTO`

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

`CRLF`

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

`LF`

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

`NONE`

Disable and do not configure the end of line character.

GitpodOnOpen

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

Members

Name	Description
`OPEN_BROWSER`	Open a new browser tab.
`OPEN_PREVIEW`	Open a preview on the right side of the IDE.
`NOTIFY`	Show a notification asking the user what to do (default).
`IGNORE`	Do nothing.

`OPEN_BROWSER`

Open a new browser tab.

`OPEN_PREVIEW`

Open a preview on the right side of the IDE.

`NOTIFY`

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

`IGNORE`

Do nothing.

GitpodOpenIn

Configure where in the IDE the terminal should be opened.

Members

Name	Description
`BOTTOM`	the bottom panel (default).
`LEFT`	the left panel.
`RIGHT`	the right panel.
`MAIN`	the main editor area.

`BOTTOM`

the bottom panel (default).

`LEFT`

the left panel.

`RIGHT`

the right panel.

`MAIN`

the main editor area.

GitpodOpenMode

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

Members

Name	Description
`TAB_AFTER`	Opens in the same tab group right after the previous tab.
`TAB_BEFORE`	Opens in the same tab group left before the previous tab.
`SPLIT_RIGHT`	Splits and adds the terminal to the right.
`SPLIT_LEFT`	Splits and adds the terminal to the left.
`SPLIT_TOP`	Splits and adds the terminal to the top.
`SPLIT_BOTTOM`	Splits and adds the terminal to the bottom.

`TAB_AFTER`

Opens in the same tab group right after the previous tab.

`TAB_BEFORE`

Opens in the same tab group left before the previous tab.

`SPLIT_RIGHT`

Splits and adds the terminal to the right.

`SPLIT_LEFT`

Splits and adds the terminal to the left.

`SPLIT_TOP`

Splits and adds the terminal to the top.

`SPLIT_BOTTOM`

Splits and adds the terminal to the bottom.

GitpodPortVisibility

Whether the port visibility should be private or public.

Members

Name	Description
`PUBLIC`	Allows everyone with the port URL to access the port (default).
`PRIVATE`	Only allows users with workspace access to access the port.

`PUBLIC`

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

`PRIVATE`

Only allows users with workspace access to access the port.

InitProjectOptionHints

Choices for how to display commented out options in projenrc files.

Does not apply to projenrc.json files.

Members

Name	Description
`ALL`	Display all possible options (grouped by which interface they belong to).
`FEATURED`	Display only featured options, in alphabetical order.
`NONE`	Display no extra options.

`ALL`

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

`FEATURED`

Display only featured options, in alphabetical order.

`NONE`

Display no extra options.

LogLevel

Logging verbosity.

Members

Name	Description
`OFF`	No description.
`ERROR`	No description.
`WARN`	No description.
`INFO`	No description.
`DEBUG`	No description.
`VERBOSE`	No description.

`OFF`

`ERROR`

`WARN`

`INFO`

`DEBUG`

`VERBOSE`

RenovatebotMinimumReleaseAgeBehaviour

Behaviour when a release timestamp is missing for minimumReleaseAge.

https://docs.renovatebot.com/configuration-options/#minimumreleaseagebehaviour

Members

Name	Description
`TIMESTAMP_REQUIRED`	A release without a timestamp is not treated as stable.
`TIMESTAMP_OPTIONAL`	A release without a timestamp is treated as stable.

`TIMESTAMP_REQUIRED`

A release without a timestamp is not treated as stable.

`TIMESTAMP_OPTIONAL`

A release without a timestamp is treated as stable.

RenovatebotScheduleInterval

How often to check for new versions and raise pull requests for version updates.

https://docs.renovatebot.com/presets-schedule/

Members

Name	Description
`ANY_TIME`	Run at any time.
`EARLY_MONDAYS`	Weekly schedule on early monday mornings.
`DAILY`	Schedule daily.
`MONTHLY`	Schedule monthly.
`QUARTERLY`	Schedule quarterly.
`WEEKENDS`	Schedule for weekends.
`WEEKDAYS`	Schedule for weekdays.

`ANY_TIME`

Run at any time.

`EARLY_MONDAYS`

Weekly schedule on early monday mornings.

`DAILY`

Schedule daily.

`MONTHLY`

Schedule monthly.

`QUARTERLY`

Schedule quarterly.

`WEEKENDS`

Schedule for weekends.

`WEEKDAYS`

Schedule for weekdays.

TestFailureBehavior

Members

Name	Description
`SKIP`	Skip the current patch operation and continue with the next operation.
`FAIL_SYNTHESIS`	Fail the whole file synthesis.

`SKIP`

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

`FAIL_SYNTHESIS`

Fail the whole file synthesis.

Submodules ​

Constructs ​

AiInstructions ​

Initializers ​

projectRequired ​

optionsOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

postSynthesize ​

preSynthesize ​

projectCreation ​

initProjectRequired ​

synthesize ​

addAgentSpecificInstructions ​

agentRequired ​

instructionsRequired ​

addInstructions ​

instructionsRequired ​

Static Functions ​

isConstruct ​

xRequired ​

isComponent ​

xRequired ​

bestPractices ​

projectRequired ​

projen ​

projectRequired ​

Properties ​

nodeRequired ​

projectRequired ​

AiInstructionsFile ​

Initializers ​

scopeRequired ​

filePathRequired ​

optionsOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

postSynthesize ​

preSynthesize ​

projectCreation ​

initProjectRequired ​

synthesize ​

diff ​

colorizeOptional ​

contextLinesOptional ​

addInstructions ​

instructionsRequired ​

Static Functions ​

isConstruct ​

xRequired ​

isComponent ​

xRequired ​

Properties ​

nodeRequired ​

projectRequired ​

absolutePathRequired ​

committedRequired ​

pathRequired ​

changedOptional ​

markerOptional ​

executableRequired ​

readonlyRequired ​

Component ​

Initializers ​

scopeRequired ​

idOptional ​

Methods ​

toString ​

with ​

mixinsRequired ​

postProjectCreation ​

initProjectRequired ​

Submodules

Constructs

AiInstructions

Initializers

`project`^Required

`options`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required

`postSynthesize`

`preSynthesize`

`projectCreation`

`initProject`^Required

`synthesize`

`addAgentSpecificInstructions`

`agent`^Required

`instructions`^Required

`addInstructions`

`instructions`^Required

Static Functions

`isConstruct`

`x`^Required

`isComponent`

`x`^Required

`bestPractices`

`project`^Required

`projen`

`project`^Required

Properties

`node`^Required

`project`^Required

AiInstructionsFile

Initializers

`scope`^Required

`filePath`^Required

`options`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required

`postSynthesize`

`preSynthesize`

`projectCreation`

`initProject`^Required

`synthesize`

`diff`

`colorize`^Optional

`contextLines`^Optional

`addInstructions`

`instructions`^Required

Static Functions

`isConstruct`

`x`^Required

`isComponent`

`x`^Required

Properties

`node`^Required

`project`^Required

`absolutePath`^Required

`committed`^Required

`path`^Required

`changed`^Optional

`marker`^Optional

`executable`^Required

`readonly`^Required

Component

Initializers

`scope`^Required

`id`^Optional

Methods

`toString`

`with`

`mixins`^Required

`postProjectCreation`

`initProject`^Required