Skip to main content

cdk Submodule

Constructs

AutoDiscoverBase

Base class for auto-discovering and creating project subcomponents.

Initializers

import { cdk } from 'projen'

new cdk.AutoDiscoverBase(project: Project, options: AutoDiscoverBaseOptions)
NameTypeDescription
project
projen.ProjectNo description.
options
AutoDiscoverBaseOptions
No description.

projectRequired
  • Type: projen.Project

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

NameDescription
isConstruct
Checks if x is a construct.
isComponent
Test whether the given construct is a component.

isConstruct
import { cdk } from 'projen'

cdk.AutoDiscoverBase.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.

xRequired
  • Type: any

Any object.


isComponent
import { cdk } from 'projen'

cdk.AutoDiscoverBase.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
entrypoints
string[]Auto-discovered entry points with paths relative to the project directory.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

entrypointsRequired
public readonly entrypoints: string[];
  • Type: string[]

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


ConstructLibrary

A multi-language library for CDK constructs.

Initializers

import { cdk } from 'projen'

new cdk.ConstructLibrary(options: ConstructLibraryOptions)
NameTypeDescription
options
ConstructLibraryOptions
No description.

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
addExcludeFromCleanup
Exclude the matching files from pre-synth cleanup.
addGitIgnore
Adds a .gitignore pattern.
addPackageIgnore
Adds patterns to be ignored by npm.
addTask
Adds a new task to this project.
addTip
Prints a "tip" message during synthesis.
annotateGenerated
Marks the provided file(s) as being 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.
tryFindJsonFile
Finds a json file by name.
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.
addBins
No description.
addBundledDeps
Defines bundled dependencies.
addCompileCommand
DEPRECATED.
addDeps
Defines normal dependencies.
addDevDeps
Defines development/test dependencies.
addFields
Directly set fields in package.json.
addKeywords
Adds keywords to package.json (deduplicated).
addPeerDeps
Defines peer dependencies.
addScripts
Replaces the contents of multiple npm package.json scripts.
addTestCommand
DEPRECATED.
hasScript
Indicates if a script by the name name is defined.
removeScript
Removes the npm script (always successful).
renderWorkflowSetup
Returns the set of workflow steps which should be executed to bootstrap a workflow.
setScript
Replaces the contents of an npm package.json script.

toString
public toString(): string

Returns a string representation of this construct.

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.

globsRequired
  • Type: ...string[]

The glob patterns to match.


addGitIgnore
public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

patternRequired
  • Type: string

The glob pattern to ignore.


addPackageIgnore
public addPackageIgnore(pattern: string): void

Adds patterns to be ignored by npm.

patternRequired
  • Type: string

The pattern to ignore.


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.

nameRequired
  • Type: string

The task name to add.


propsOptional
  • Type: projen.TaskOptions

Task properties.


addTip
public addTip(message: string): void

Prints a "tip" message during synthesis.

messageRequired
  • Type: string

The message.


annotateGenerated
public annotateGenerated(glob: string): void

Marks the provided file(s) as being generated.

This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.

https://github.com/github/linguist/blob/master/docs/overrides.md

globRequired
  • 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.

nameRequired
  • 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.

This will typically be npx projen TASK.

taskRequired
  • Type: projen.Task

The task for which the command is required.


synth
public synth(): void

Synthesize all project files into outdir.

  1. Call "this.preSynthesize()"
  2. Delete all generated files
  3. Synthesize all subprojects
  4. Synthesize all components of this project
  5. Call "postSynthesize()" for all components of this project
  6. Call "this.postSynthesize()"
tryFindFile
public tryFindFile(filePath: string): FileBase

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

filePathRequired
  • Type: string

The file path.

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


tryFindJsonFile
public tryFindJsonFile(filePath: string): JsonFile

Finds a json file by name.

filePathRequired
  • Type: string

The file path.


tryFindObjectFile
public tryFindObjectFile(filePath: string): ObjectFile

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

filePathRequired
  • 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.

filePathRequired
  • Type: string

The file path.

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


addBins
public addBins(bins: {[ key: string ]: string}): void
binsRequired
  • Type: {[ key: string ]: string}

addBundledDeps
public addBundledDeps(deps: ...string[]): void

Defines bundled dependencies.

Bundled dependencies will be added as normal dependencies as well as to the bundledDependencies section of your package.json.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addCompileCommand
public addCompileCommand(commands: ...string[]): void

DEPRECATED.

commandsRequired
  • Type: ...string[]

addDeps
public addDeps(deps: ...string[]): void

Defines normal dependencies.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addDevDeps
public addDevDeps(deps: ...string[]): void

Defines development/test dependencies.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addFields
public addFields(fields: {[ key: string ]: any}): void

Directly set fields in package.json.

fieldsRequired
  • Type: {[ key: string ]: any}

The fields to set.


addKeywords
public addKeywords(keywords: ...string[]): void

Adds keywords to package.json (deduplicated).

keywordsRequired
  • Type: ...string[]

The keywords to add.


addPeerDeps
public addPeerDeps(deps: ...string[]): void

Defines peer dependencies.

When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addScripts
public addScripts(scripts: {[ key: string ]: string}): void

Replaces the contents of multiple npm package.json scripts.

scriptsRequired
  • Type: {[ key: string ]: string}

The scripts to set.


addTestCommand
public addTestCommand(commands: ...string[]): void

DEPRECATED.

commandsRequired
  • Type: ...string[]

hasScript
public hasScript(name: string): boolean

Indicates if a script by the name name is defined.

nameRequired
  • Type: string

The name of the script.


removeScript
public removeScript(name: string): void

Removes the npm script (always successful).

nameRequired
  • Type: string

The name of the script.


renderWorkflowSetup
public renderWorkflowSetup(options?: RenderWorkflowSetupOptions): JobStep[]

Returns the set of workflow steps which should be executed to bootstrap a workflow.

optionsOptional
  • Type: projen.javascript.RenderWorkflowSetupOptions

Options.


setScript
public setScript(name: string, command: string): void

Replaces the contents of an npm package.json script.

nameRequired
  • Type: string

The script name.


commandRequired
  • Type: string

The command to execute.


Static Functions

NameDescription
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 { cdk } from 'projen'

cdk.ConstructLibrary.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.

xRequired
  • Type: any

Any object.


isProject
import { cdk } from 'projen'

cdk.ConstructLibrary.isProject(x: any)

Test whether the given construct is a project.

xRequired
  • Type: any

of
import { cdk } from 'projen'

cdk.ConstructLibrary.of(construct: IConstruct)

Find the closest ancestor project for given construct.

When given a project, this it the project itself.

constructRequired
  • Type: constructs.IConstruct

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
buildTask
projen.TaskNo description.
commitGenerated
booleanWhether to commit the managed files by default.
compileTask
projen.TaskNo description.
components
projen.Component[]Returns all the components within this project.
deps
projen.DependenciesProject dependencies.
ejected
booleanWhether or not the project is being ejected.
files
projen.FileBase[]All files in this project.
gitattributes
projen.GitAttributesFileThe .gitattributes file for this repository.
gitignore
projen.IgnoreFile.gitignore.
logger
projen.LoggerLogging utilities.
name
stringProject name.
outdir
stringAbsolute output directory of this project.
packageTask
projen.TaskNo description.
postCompileTask
projen.TaskNo description.
preCompileTask
projen.TaskNo description.
projectBuild
projen.ProjectBuildManages the build process of the project.
projenCommand
stringThe command to use in order to run the projen CLI.
root
projen.ProjectThe root project.
subprojects
projen.Project[]Returns all the subprojects within this project.
tasks
projen.TasksProject tasks.
testTask
projen.TaskNo description.
defaultTask
projen.TaskThis is the "default" task, the one that executes "projen".
initProject
projen.InitProjectThe options used when this project is bootstrapped via projen new.
parent
projen.ProjectA parent project.
projectType
projen.ProjectTypeNo description.
autoApprove
projen.github.AutoApproveAuto approve set up for this project.
devContainer
projen.vscode.DevContainerAccess for .devcontainer.json (used for GitHub Codespaces).
github
projen.github.GitHubAccess all github components.
gitpod
projen.GitpodAccess for Gitpod.
vscode
projen.vscode.VsCodeAccess all VSCode components.
allowLibraryDependencies
booleanNo description.
artifactsDirectory
stringThe build output directory.
artifactsJavascriptDirectory
stringThe location of the npm tarball after build (${artifactsDirectory}/js).
bundler
projen.javascript.BundlerNo description.
entrypoint
stringNo description.
manifest
anyNo description.
npmrc
projen.javascript.NpmConfigThe .npmrc file.
package
projen.javascript.NodePackageAPI for managing the node package.
packageManager
projen.javascript.NodePackageManagerThe package manager to use.
runScriptCommand
stringThe command to use to run scripts (e.g. yarn run or npm run depends on the package manager).
autoMerge
projen.github.AutoMergeComponent that sets up mergify for merging approved pull requests.
buildWorkflow
projen.build.BuildWorkflowThe PR build GitHub workflow.
buildWorkflowJobId
stringThe job ID of the build workflow.
jest
projen.javascript.JestThe Jest configuration (if enabled).
maxNodeVersion
stringMaximum node version supported by this package.
minNodeVersion
stringThe minimum node version required by this package to function.
npmignore
projen.IgnoreFileThe .npmignore file.
prettier
projen.javascript.PrettierNo description.
publisher
projen.release.PublisherPackage publisher.
release
projen.release.ReleaseRelease management.
upgradeWorkflow
projen.javascript.UpgradeDependenciesThe upgrade workflow.
docsDirectory
stringNo description.
libdir
stringThe directory in which compiled .js files reside.
srcdir
stringThe directory in which the .ts sources reside.
testdir
stringThe directory in which tests reside.
tsconfigDev
projen.javascript.TypescriptConfigA typescript configuration file which covers all files (sources, tests, projen).
watchTask
projen.TaskThe "watch" task.
docgen
booleanNo description.
eslint
projen.javascript.EslintNo description.
tsconfig
projen.javascript.TypescriptConfigNo description.
tsconfigEslint
projen.javascript.TypescriptConfigNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


buildTaskRequired
public readonly buildTask: Task;
  • Type: projen.Task

commitGeneratedRequired
public readonly commitGenerated: boolean;
  • Type: boolean

Whether to commit the managed files by default.


compileTaskRequired
public readonly compileTask: Task;
  • Type: projen.Task

componentsRequired
public readonly components: Component[];
  • Type: projen.Component[]

Returns all the components within this project.


depsRequired
public readonly deps: Dependencies;
  • Type: projen.Dependencies

Project dependencies.


ejectedRequired
public readonly ejected: boolean;
  • Type: boolean

Whether or not the project is being ejected.


filesRequired
public readonly files: FileBase[];
  • Type: projen.FileBase[]

All files in this project.


gitattributesRequired
public readonly gitattributes: GitAttributesFile;
  • Type: projen.GitAttributesFile

The .gitattributes file for this repository.


gitignoreRequired
public readonly gitignore: IgnoreFile;
  • Type: projen.IgnoreFile

.gitignore.


loggerRequired
public readonly logger: Logger;
  • Type: projen.Logger

Logging utilities.


nameRequired
public readonly name: string;
  • Type: string

Project name.


outdirRequired
public readonly outdir: string;
  • Type: string

Absolute output directory of this project.


packageTaskRequired
public readonly packageTask: Task;
  • Type: projen.Task

postCompileTaskRequired
public readonly postCompileTask: Task;
  • Type: projen.Task

preCompileTaskRequired
public readonly preCompileTask: Task;
  • Type: projen.Task

projectBuildRequired
public readonly projectBuild: ProjectBuild;
  • Type: projen.ProjectBuild

Manages the build process of the project.


projenCommandRequired
public readonly projenCommand: string;
  • Type: string

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


rootRequired
public readonly root: Project;
  • Type: projen.Project

The root project.


subprojectsRequired
public readonly subprojects: Project[];
  • Type: projen.Project[]

Returns all the subprojects within this project.


tasksRequired
public readonly tasks: Tasks;
  • Type: projen.Tasks

Project tasks.


testTaskRequired
public readonly testTask: Task;
  • Type: projen.Task

defaultTaskOptional
public readonly defaultTask: Task;
  • Type: projen.Task

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

Undefined if the project is being ejected.


initProjectOptional
public readonly initProject: InitProject;
  • Type: projen.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.


parentOptional
public readonly parent: Project;
  • Type: projen.Project

A parent project.

If undefined, this is the root project.


projectTypeRequired
public readonly projectType: ProjectType;
  • Type: projen.ProjectType

autoApproveOptional
public readonly autoApprove: AutoApprove;
  • Type: projen.github.AutoApprove

Auto approve set up for this project.


devContainerOptional
public readonly devContainer: DevContainer;
  • Type: projen.vscode.DevContainer

Access for .devcontainer.json (used for GitHub Codespaces).

This will be undefined if devContainer boolean is false


githubOptional
public readonly github: GitHub;
  • Type: projen.github.GitHub

Access all github components.

This will be undefined for subprojects.


gitpodOptional
public readonly gitpod: Gitpod;
  • Type: projen.Gitpod

Access for Gitpod.

This will be undefined if gitpod boolean is false


vscodeOptional
public readonly vscode: VsCode;
  • Type: projen.vscode.VsCode

Access all VSCode components.

This will be undefined for subprojects.


allowLibraryDependenciesRequired
  • Deprecated: use package.allowLibraryDependencies
public readonly allowLibraryDependencies: boolean;
  • Type: boolean

artifactsDirectoryRequired
public readonly artifactsDirectory: string;
  • Type: string

The build output directory.

An npm tarball will be created under the js subdirectory. For example, if this is set to dist (the default), the npm tarball will be placed under dist/js/boom-boom-1.2.3.tg.


artifactsJavascriptDirectoryRequired
public readonly artifactsJavascriptDirectory: string;
  • Type: string

The location of the npm tarball after build (${artifactsDirectory}/js).


bundlerRequired
public readonly bundler: Bundler;
  • Type: projen.javascript.Bundler

entrypointRequired
  • Deprecated: use package.entrypoint
public readonly entrypoint: string;
  • Type: string

manifestRequired
  • Deprecated: use package.addField(x, y)
public readonly manifest: any;
  • Type: any

npmrcRequired
public readonly npmrc: NpmConfig;
  • Type: projen.javascript.NpmConfig

The .npmrc file.


packageRequired
public readonly package: NodePackage;
  • Type: projen.javascript.NodePackage

API for managing the node package.


packageManagerRequired
  • Deprecated: use package.packageManager
public readonly packageManager: NodePackageManager;
  • Type: projen.javascript.NodePackageManager

The package manager to use.


runScriptCommandRequired
public readonly runScriptCommand: string;
  • Type: string

The command to use to run scripts (e.g. yarn run or npm run depends on the package manager).


autoMergeOptional
public readonly autoMerge: AutoMerge;
  • Type: projen.github.AutoMerge

Component that sets up mergify for merging approved pull requests.


buildWorkflowOptional
public readonly buildWorkflow: BuildWorkflow;
  • Type: projen.build.BuildWorkflow

The PR build GitHub workflow.

undefined if buildWorkflow is disabled.


buildWorkflowJobIdOptional
public readonly buildWorkflowJobId: string;
  • Type: string

The job ID of the build workflow.


jestOptional
public readonly jest: Jest;
  • Type: projen.javascript.Jest

The Jest configuration (if enabled).


maxNodeVersionOptional
public readonly maxNodeVersion: string;
  • Type: string

Maximum node version supported by this package.

The value indicates the package is incompatible with newer versions.


minNodeVersionOptional
public readonly minNodeVersion: string;
  • Type: string

The minimum node version required by this package to function.

This value indicates the package is incompatible with older versions.


npmignoreOptional
public readonly npmignore: IgnoreFile;
  • Type: projen.IgnoreFile

The .npmignore file.


prettierOptional
public readonly prettier: Prettier;
  • Type: projen.javascript.Prettier

publisherOptional
  • Deprecated: use release.publisher.
public readonly publisher: Publisher;
  • Type: projen.release.Publisher

Package publisher.

This will be undefined if the project does not have a release workflow.


releaseOptional
public readonly release: Release;
  • Type: projen.release.Release

Release management.


upgradeWorkflowOptional
public readonly upgradeWorkflow: UpgradeDependencies;
  • Type: projen.javascript.UpgradeDependencies

The upgrade workflow.


docsDirectoryRequired
public readonly docsDirectory: string;
  • Type: string

libdirRequired
public readonly libdir: string;
  • Type: string

The directory in which compiled .js files reside.


srcdirRequired
public readonly srcdir: string;
  • Type: string

The directory in which the .ts sources reside.


testdirRequired
public readonly testdir: string;
  • Type: string

The directory in which tests reside.


tsconfigDevRequired
public readonly tsconfigDev: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

A typescript configuration file which covers all files (sources, tests, projen).


watchTaskRequired
public readonly watchTask: Task;
  • Type: projen.Task

The "watch" task.


docgenOptional
public readonly docgen: boolean;
  • Type: boolean

eslintOptional
public readonly eslint: Eslint;
  • Type: projen.javascript.Eslint

tsconfigOptional
public readonly tsconfig: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

tsconfigEslintOptional
public readonly tsconfigEslint: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

Constants

NameTypeDescription
DEFAULT_TASK
stringThe name of the default task (the task executed when projen is run without arguments).
DEFAULT_TS_JEST_TRANFORM_PATTERN
stringNo description.

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


DEFAULT_TS_JEST_TRANFORM_PATTERNRequired
public readonly DEFAULT_TS_JEST_TRANFORM_PATTERN: string;
  • Type: string

IntegrationTestAutoDiscoverBase

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

Initializers

import { cdk } from 'projen'

new cdk.IntegrationTestAutoDiscoverBase(project: Project, options: IntegrationTestAutoDiscoverBaseOptions)
NameTypeDescription
project
projen.ProjectNo description.
options
IntegrationTestAutoDiscoverBaseOptions
No description.

projectRequired
  • Type: projen.Project

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

NameDescription
isConstruct
Checks if x is a construct.
isComponent
Test whether the given construct is a component.

isConstruct
import { cdk } from 'projen'

cdk.IntegrationTestAutoDiscoverBase.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.

xRequired
  • Type: any

Any object.


isComponent
import { cdk } from 'projen'

cdk.IntegrationTestAutoDiscoverBase.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
entrypoints
string[]Auto-discovered entry points with paths relative to the project directory.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

entrypointsRequired
public readonly entrypoints: string[];
  • Type: string[]

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


IntegrationTestBase

Initializers

import { cdk } from 'projen'

new cdk.IntegrationTestBase(project: Project, options: IntegrationTestBaseOptions)
NameTypeDescription
project
projen.ProjectNo description.
options
IntegrationTestBaseOptions
No description.

projectRequired
  • Type: projen.Project

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

NameDescription
isConstruct
Checks if x is a construct.
isComponent
Test whether the given construct is a component.

isConstruct
import { cdk } from 'projen'

cdk.IntegrationTestBase.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.

xRequired
  • Type: any

Any object.


isComponent
import { cdk } from 'projen'

cdk.IntegrationTestBase.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.
assertTask
projen.TaskSynthesizes the integration test and compares against a local copy (runs during build).
deployTask
projen.TaskDeploy the integration test and update the snapshot upon success.
snapshotTask
projen.TaskJust update snapshot (without deployment).

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

assertTaskRequired
public readonly assertTask: Task;
  • Type: projen.Task

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


deployTaskRequired
public readonly deployTask: Task;
  • Type: projen.Task

Deploy the integration test and update the snapshot upon success.


snapshotTaskRequired
public readonly snapshotTask: Task;
  • Type: projen.Task

Just update snapshot (without deployment).


JsiiDocgen

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

Initializers

import { cdk } from 'projen'

new cdk.JsiiDocgen(scope: IConstruct, options?: JsiiDocgenOptions)
NameTypeDescription
scope
constructs.IConstructNo description.
options
JsiiDocgenOptions
No description.

scopeRequired
  • Type: constructs.IConstruct

optionsOptional

Methods

NameDescription
toString
Returns a string representation of this construct.
postSynthesize
Called after synthesis.
preSynthesize
Called before synthesis.
synthesize
Synthesizes files to the project output directory.

toString
public toString(): string

Returns a string representation of this construct.

postSynthesize
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize
public preSynthesize(): void

Called before synthesis.

synthesize
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

NameDescription
isConstruct
Checks if x is a construct.
isComponent
Test whether the given construct is a component.

isConstruct
import { cdk } from 'projen'

cdk.JsiiDocgen.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.

xRequired
  • Type: any

Any object.


isComponent
import { cdk } from 'projen'

cdk.JsiiDocgen.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
project
projen.ProjectNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


projectRequired
public readonly project: Project;
  • Type: projen.Project

JsiiProject

Multi-language jsii library project.

Initializers

import { cdk } from 'projen'

new cdk.JsiiProject(options: JsiiProjectOptions)
NameTypeDescription
options
JsiiProjectOptions
No description.

optionsRequired

Methods

NameDescription
toString
Returns a string representation of this construct.
addExcludeFromCleanup
Exclude the matching files from pre-synth cleanup.
addGitIgnore
Adds a .gitignore pattern.
addPackageIgnore
Adds patterns to be ignored by npm.
addTask
Adds a new task to this project.
addTip
Prints a "tip" message during synthesis.
annotateGenerated
Marks the provided file(s) as being 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.
tryFindJsonFile
Finds a json file by name.
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.
addBins
No description.
addBundledDeps
Defines bundled dependencies.
addCompileCommand
DEPRECATED.
addDeps
Defines normal dependencies.
addDevDeps
Defines development/test dependencies.
addFields
Directly set fields in package.json.
addKeywords
Adds keywords to package.json (deduplicated).
addPeerDeps
Defines peer dependencies.
addScripts
Replaces the contents of multiple npm package.json scripts.
addTestCommand
DEPRECATED.
hasScript
Indicates if a script by the name name is defined.
removeScript
Removes the npm script (always successful).
renderWorkflowSetup
Returns the set of workflow steps which should be executed to bootstrap a workflow.
setScript
Replaces the contents of an npm package.json script.

toString
public toString(): string

Returns a string representation of this construct.

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.

globsRequired
  • Type: ...string[]

The glob patterns to match.


addGitIgnore
public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

patternRequired
  • Type: string

The glob pattern to ignore.


addPackageIgnore
public addPackageIgnore(pattern: string): void

Adds patterns to be ignored by npm.

patternRequired
  • Type: string

The pattern to ignore.


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.

nameRequired
  • Type: string

The task name to add.


propsOptional
  • Type: projen.TaskOptions

Task properties.


addTip
public addTip(message: string): void

Prints a "tip" message during synthesis.

messageRequired
  • Type: string

The message.


annotateGenerated
public annotateGenerated(glob: string): void

Marks the provided file(s) as being generated.

This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.

https://github.com/github/linguist/blob/master/docs/overrides.md

globRequired
  • 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.

nameRequired
  • 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.

This will typically be npx projen TASK.

taskRequired
  • Type: projen.Task

The task for which the command is required.


synth
public synth(): void

Synthesize all project files into outdir.

  1. Call "this.preSynthesize()"
  2. Delete all generated files
  3. Synthesize all subprojects
  4. Synthesize all components of this project
  5. Call "postSynthesize()" for all components of this project
  6. Call "this.postSynthesize()"
tryFindFile
public tryFindFile(filePath: string): FileBase

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

filePathRequired
  • Type: string

The file path.

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


tryFindJsonFile
public tryFindJsonFile(filePath: string): JsonFile

Finds a json file by name.

filePathRequired
  • Type: string

The file path.


tryFindObjectFile
public tryFindObjectFile(filePath: string): ObjectFile

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

filePathRequired
  • 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.

filePathRequired
  • Type: string

The file path.

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


addBins
public addBins(bins: {[ key: string ]: string}): void
binsRequired
  • Type: {[ key: string ]: string}

addBundledDeps
public addBundledDeps(deps: ...string[]): void

Defines bundled dependencies.

Bundled dependencies will be added as normal dependencies as well as to the bundledDependencies section of your package.json.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addCompileCommand
public addCompileCommand(commands: ...string[]): void

DEPRECATED.

commandsRequired
  • Type: ...string[]

addDeps
public addDeps(deps: ...string[]): void

Defines normal dependencies.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addDevDeps
public addDevDeps(deps: ...string[]): void

Defines development/test dependencies.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addFields
public addFields(fields: {[ key: string ]: any}): void

Directly set fields in package.json.

fieldsRequired
  • Type: {[ key: string ]: any}

The fields to set.


addKeywords
public addKeywords(keywords: ...string[]): void

Adds keywords to package.json (deduplicated).

keywordsRequired
  • Type: ...string[]

The keywords to add.


addPeerDeps
public addPeerDeps(deps: ...string[]): void

Defines peer dependencies.

When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.

depsRequired
  • Type: ...string[]

Names modules to install.

By default, the the dependency will be installed in the next npx projen run and the version will be recorded in your package.json file. You can upgrade manually or using yarn add/upgrade. If you wish to specify a version range use this syntax: module@^7.


addScripts
public addScripts(scripts: {[ key: string ]: string}): void

Replaces the contents of multiple npm package.json scripts.

scriptsRequired
  • Type: {[ key: string ]: string}

The scripts to set.


addTestCommand
public addTestCommand(commands: ...string[]): void

DEPRECATED.

commandsRequired
  • Type: ...string[]

hasScript
public hasScript(name: string): boolean

Indicates if a script by the name name is defined.

nameRequired
  • Type: string

The name of the script.


removeScript
public removeScript(name: string): void

Removes the npm script (always successful).

nameRequired
  • Type: string

The name of the script.


renderWorkflowSetup
public renderWorkflowSetup(options?: RenderWorkflowSetupOptions): JobStep[]

Returns the set of workflow steps which should be executed to bootstrap a workflow.

optionsOptional
  • Type: projen.javascript.RenderWorkflowSetupOptions

Options.


setScript
public setScript(name: string, command: string): void

Replaces the contents of an npm package.json script.

nameRequired
  • Type: string

The script name.


commandRequired
  • Type: string

The command to execute.


Static Functions

NameDescription
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 { cdk } from 'projen'

cdk.JsiiProject.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.

xRequired
  • Type: any

Any object.


isProject
import { cdk } from 'projen'

cdk.JsiiProject.isProject(x: any)

Test whether the given construct is a project.

xRequired
  • Type: any

of
import { cdk } from 'projen'

cdk.JsiiProject.of(construct: IConstruct)

Find the closest ancestor project for given construct.

When given a project, this it the project itself.

constructRequired
  • Type: constructs.IConstruct

Properties

NameTypeDescription
node
constructs.NodeThe tree node.
buildTask
projen.TaskNo description.
commitGenerated
booleanWhether to commit the managed files by default.
compileTask
projen.TaskNo description.
components
projen.Component[]Returns all the components within this project.
deps
projen.DependenciesProject dependencies.
ejected
booleanWhether or not the project is being ejected.
files
projen.FileBase[]All files in this project.
gitattributes
projen.GitAttributesFileThe .gitattributes file for this repository.
gitignore
projen.IgnoreFile.gitignore.
logger
projen.LoggerLogging utilities.
name
stringProject name.
outdir
stringAbsolute output directory of this project.
packageTask
projen.TaskNo description.
postCompileTask
projen.TaskNo description.
preCompileTask
projen.TaskNo description.
projectBuild
projen.ProjectBuildManages the build process of the project.
projenCommand
stringThe command to use in order to run the projen CLI.
root
projen.ProjectThe root project.
subprojects
projen.Project[]Returns all the subprojects within this project.
tasks
projen.TasksProject tasks.
testTask
projen.TaskNo description.
defaultTask
projen.TaskThis is the "default" task, the one that executes "projen".
initProject
projen.InitProjectThe options used when this project is bootstrapped via projen new.
parent
projen.ProjectA parent project.
projectType
projen.ProjectTypeNo description.
autoApprove
projen.github.AutoApproveAuto approve set up for this project.
devContainer
projen.vscode.DevContainerAccess for .devcontainer.json (used for GitHub Codespaces).
github
projen.github.GitHubAccess all github components.
gitpod
projen.GitpodAccess for Gitpod.
vscode
projen.vscode.VsCodeAccess all VSCode components.
allowLibraryDependencies
booleanNo description.
artifactsDirectory
stringThe build output directory.
artifactsJavascriptDirectory
stringThe location of the npm tarball after build (${artifactsDirectory}/js).
bundler
projen.javascript.BundlerNo description.
entrypoint
stringNo description.
manifest
anyNo description.
npmrc
projen.javascript.NpmConfigThe .npmrc file.
package
projen.javascript.NodePackageAPI for managing the node package.
packageManager
projen.javascript.NodePackageManagerThe package manager to use.
runScriptCommand
stringThe command to use to run scripts (e.g. yarn run or npm run depends on the package manager).
autoMerge
projen.github.AutoMergeComponent that sets up mergify for merging approved pull requests.
buildWorkflow
projen.build.BuildWorkflowThe PR build GitHub workflow.
buildWorkflowJobId
stringThe job ID of the build workflow.
jest
projen.javascript.JestThe Jest configuration (if enabled).
maxNodeVersion
stringMaximum node version supported by this package.
minNodeVersion
stringThe minimum node version required by this package to function.
npmignore
projen.IgnoreFileThe .npmignore file.
prettier
projen.javascript.PrettierNo description.
publisher
projen.release.PublisherPackage publisher.
release
projen.release.ReleaseRelease management.
upgradeWorkflow
projen.javascript.UpgradeDependenciesThe upgrade workflow.
docsDirectory
stringNo description.
libdir
stringThe directory in which compiled .js files reside.
srcdir
stringThe directory in which the .ts sources reside.
testdir
stringThe directory in which tests reside.
tsconfigDev
projen.javascript.TypescriptConfigA typescript configuration file which covers all files (sources, tests, projen).
watchTask
projen.TaskThe "watch" task.
docgen
booleanNo description.
eslint
projen.javascript.EslintNo description.
tsconfig
projen.javascript.TypescriptConfigNo description.
tsconfigEslint
projen.javascript.TypescriptConfigNo description.

nodeRequired
public readonly node: Node;
  • Type: constructs.Node

The tree node.


buildTaskRequired
public readonly buildTask: Task;
  • Type: projen.Task

commitGeneratedRequired
public readonly commitGenerated: boolean;
  • Type: boolean

Whether to commit the managed files by default.


compileTaskRequired
public readonly compileTask: Task;
  • Type: projen.Task

componentsRequired
public readonly components: Component[];
  • Type: projen.Component[]

Returns all the components within this project.


depsRequired
public readonly deps: Dependencies;
  • Type: projen.Dependencies

Project dependencies.


ejectedRequired
public readonly ejected: boolean;
  • Type: boolean

Whether or not the project is being ejected.


filesRequired
public readonly files: FileBase[];
  • Type: projen.FileBase[]

All files in this project.


gitattributesRequired
public readonly gitattributes: GitAttributesFile;
  • Type: projen.GitAttributesFile

The .gitattributes file for this repository.


gitignoreRequired
public readonly gitignore: IgnoreFile;
  • Type: projen.IgnoreFile

.gitignore.


loggerRequired
public readonly logger: Logger;
  • Type: projen.Logger

Logging utilities.


nameRequired
public readonly name: string;
  • Type: string

Project name.


outdirRequired
public readonly outdir: string;
  • Type: string

Absolute output directory of this project.


packageTaskRequired
public readonly packageTask: Task;
  • Type: projen.Task

postCompileTaskRequired
public readonly postCompileTask: Task;
  • Type: projen.Task

preCompileTaskRequired
public readonly preCompileTask: Task;
  • Type: projen.Task

projectBuildRequired
public readonly projectBuild: ProjectBuild;
  • Type: projen.ProjectBuild

Manages the build process of the project.


projenCommandRequired
public readonly projenCommand: string;
  • Type: string

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


rootRequired
public readonly root: Project;
  • Type: projen.Project

The root project.


subprojectsRequired
public readonly subprojects: Project[];
  • Type: projen.Project[]

Returns all the subprojects within this project.


tasksRequired
public readonly tasks: Tasks;
  • Type: projen.Tasks

Project tasks.


testTaskRequired
public readonly testTask: Task;
  • Type: projen.Task

defaultTaskOptional
public readonly defaultTask: Task;
  • Type: projen.Task

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

Undefined if the project is being ejected.


initProjectOptional
public readonly initProject: InitProject;
  • Type: projen.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.


parentOptional
public readonly parent: Project;
  • Type: projen.Project

A parent project.

If undefined, this is the root project.


projectTypeRequired
public readonly projectType: ProjectType;
  • Type: projen.ProjectType

autoApproveOptional
public readonly autoApprove: AutoApprove;
  • Type: projen.github.AutoApprove

Auto approve set up for this project.


devContainerOptional
public readonly devContainer: DevContainer;
  • Type: projen.vscode.DevContainer

Access for .devcontainer.json (used for GitHub Codespaces).

This will be undefined if devContainer boolean is false


githubOptional
public readonly github: GitHub;
  • Type: projen.github.GitHub

Access all github components.

This will be undefined for subprojects.


gitpodOptional
public readonly gitpod: Gitpod;
  • Type: projen.Gitpod

Access for Gitpod.

This will be undefined if gitpod boolean is false


vscodeOptional
public readonly vscode: VsCode;
  • Type: projen.vscode.VsCode

Access all VSCode components.

This will be undefined for subprojects.


allowLibraryDependenciesRequired
  • Deprecated: use package.allowLibraryDependencies
public readonly allowLibraryDependencies: boolean;
  • Type: boolean

artifactsDirectoryRequired
public readonly artifactsDirectory: string;
  • Type: string

The build output directory.

An npm tarball will be created under the js subdirectory. For example, if this is set to dist (the default), the npm tarball will be placed under dist/js/boom-boom-1.2.3.tg.


artifactsJavascriptDirectoryRequired
public readonly artifactsJavascriptDirectory: string;
  • Type: string

The location of the npm tarball after build (${artifactsDirectory}/js).


bundlerRequired
public readonly bundler: Bundler;
  • Type: projen.javascript.Bundler

entrypointRequired
  • Deprecated: use package.entrypoint
public readonly entrypoint: string;
  • Type: string

manifestRequired
  • Deprecated: use package.addField(x, y)
public readonly manifest: any;
  • Type: any

npmrcRequired
public readonly npmrc: NpmConfig;
  • Type: projen.javascript.NpmConfig

The .npmrc file.


packageRequired
public readonly package: NodePackage;
  • Type: projen.javascript.NodePackage

API for managing the node package.


packageManagerRequired
  • Deprecated: use package.packageManager
public readonly packageManager: NodePackageManager;
  • Type: projen.javascript.NodePackageManager

The package manager to use.


runScriptCommandRequired
public readonly runScriptCommand: string;
  • Type: string

The command to use to run scripts (e.g. yarn run or npm run depends on the package manager).


autoMergeOptional
public readonly autoMerge: AutoMerge;
  • Type: projen.github.AutoMerge

Component that sets up mergify for merging approved pull requests.


buildWorkflowOptional
public readonly buildWorkflow: BuildWorkflow;
  • Type: projen.build.BuildWorkflow

The PR build GitHub workflow.

undefined if buildWorkflow is disabled.


buildWorkflowJobIdOptional
public readonly buildWorkflowJobId: string;
  • Type: string

The job ID of the build workflow.


jestOptional
public readonly jest: Jest;
  • Type: projen.javascript.Jest

The Jest configuration (if enabled).


maxNodeVersionOptional
public readonly maxNodeVersion: string;
  • Type: string

Maximum node version supported by this package.

The value indicates the package is incompatible with newer versions.


minNodeVersionOptional
public readonly minNodeVersion: string;
  • Type: string

The minimum node version required by this package to function.

This value indicates the package is incompatible with older versions.


npmignoreOptional
public readonly npmignore: IgnoreFile;
  • Type: projen.IgnoreFile

The .npmignore file.


prettierOptional
public readonly prettier: Prettier;
  • Type: projen.javascript.Prettier

publisherOptional
  • Deprecated: use release.publisher.
public readonly publisher: Publisher;
  • Type: projen.release.Publisher

Package publisher.

This will be undefined if the project does not have a release workflow.


releaseOptional
public readonly release: Release;
  • Type: projen.release.Release

Release management.


upgradeWorkflowOptional
public readonly upgradeWorkflow: UpgradeDependencies;
  • Type: projen.javascript.UpgradeDependencies

The upgrade workflow.


docsDirectoryRequired
public readonly docsDirectory: string;
  • Type: string

libdirRequired
public readonly libdir: string;
  • Type: string

The directory in which compiled .js files reside.


srcdirRequired
public readonly srcdir: string;
  • Type: string

The directory in which the .ts sources reside.


testdirRequired
public readonly testdir: string;
  • Type: string

The directory in which tests reside.


tsconfigDevRequired
public readonly tsconfigDev: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

A typescript configuration file which covers all files (sources, tests, projen).


watchTaskRequired
public readonly watchTask: Task;
  • Type: projen.Task

The "watch" task.


docgenOptional
public readonly docgen: boolean;
  • Type: boolean

eslintOptional
public readonly eslint: Eslint;
  • Type: projen.javascript.Eslint

tsconfigOptional
public readonly tsconfig: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

tsconfigEslintOptional
public readonly tsconfigEslint: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig

Constants

NameTypeDescription
DEFAULT_TASK
stringThe name of the default task (the task executed when projen is run without arguments).
DEFAULT_TS_JEST_TRANFORM_PATTERN
stringNo description.

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


DEFAULT_TS_JEST_TRANFORM_PATTERNRequired
public readonly DEFAULT_TS_JEST_TRANFORM_PATTERN: string;
  • Type: string

Structs

AutoDiscoverBaseOptions

Options for AutoDiscoverBase.

Initializer

import { cdk } from 'projen'

const autoDiscoverBaseOptions: cdk.AutoDiscoverBaseOptions = { ... }

Properties

NameTypeDescription
extension
stringLocate files with the given extension.
projectdir
stringLocate entrypoints in the given project directory.

extensionRequired
public readonly extension: string;
  • Type: string

Locate files with the given extension.


Example

".integ.ts"
projectdirRequired
public readonly projectdir: string;
  • Type: string

Locate entrypoints in the given project directory.


Example

"test"

Catalog

Initializer

import { cdk } from 'projen'

const catalog: cdk.Catalog = { ... }

Properties

NameTypeDescription
announce
booleanShould we announce new versions?
twitter
stringTwitter account to.

announceOptional
public readonly announce: boolean;
  • Type: boolean
  • Default: true

Should we announce new versions?


twitterOptional
public readonly twitter: string;
  • Type: string

Twitter account to.


ConstructLibraryOptions

Initializer

import { cdk } from 'projen'

const constructLibraryOptions: cdk.ConstructLibraryOptions = { ... }

Properties

NameTypeDescription
name
stringThis is the name of your project.
commitGenerated
booleanWhether to commit the managed files by default.
gitIgnoreOptions
projen.IgnoreFileOptionsConfiguration options for .gitignore file.
gitOptions
projen.GitOptionsConfiguration options for git.
logging
projen.LoggerOptionsConfigure logging options such as verbosity.
outdir
stringThe root directory of the project.
parent
projen.ProjectThe parent project, if this project is part of a bigger project.
projenCommand
stringThe shell command to use in order to run the projen CLI.
projenrcJson
booleanGenerate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation.
projenrcJsonOptions
projen.ProjenrcJsonOptionsOptions for .projenrc.json.
renovatebot
booleanUse renovatebot to handle dependency upgrades.
renovatebotOptions
projen.RenovatebotOptionsOptions for renovatebot.
autoApproveOptions
projen.github.AutoApproveOptionsEnable and configure the 'auto approve' workflow.
autoMerge
booleanEnable automatic merging on GitHub.
autoMergeOptions
projen.github.AutoMergeOptionsConfigure options for automatic merging on GitHub.
clobber
booleanAdd a clobber task which resets the repo to origin.
devContainer
booleanAdd a VSCode development environment (used for GitHub Codespaces).
github
booleanEnable GitHub integration.
githubOptions
projen.github.GitHubOptionsOptions for GitHub integration.
gitpod
booleanAdd a Gitpod development environment.
mergify
booleanWhether mergify should be enabled on this repository or not.
mergifyOptions
projen.github.MergifyOptionsOptions for mergify.
projectType
projen.ProjectTypeWhich type of project this is (library/app).
projenCredentials
projen.github.GithubCredentialsChoose a method of providing GitHub API access for projen workflows.
projenTokenSecret
stringThe name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.
readme
projen.SampleReadmePropsThe README setup.
stale
booleanAuto-close of stale issues and pull request.
staleOptions
projen.github.StaleOptionsAuto-close stale issues and pull requests.
vscode
booleanEnable VSCode integration.
allowLibraryDependencies
booleanAllow the project to include peerDependencies and bundledDependencies.
authorEmail
stringAuthor's e-mail.
authorName
stringAuthor's name.
authorOrganization
booleanIs the author an organization.
authorUrl
stringAuthor's URL / Website.
autoDetectBin
booleanAutomatically add all executables under the bin directory to your package.json file under the bin section.
bin
{[ key: string ]: string}Binary programs vended with your module.
bugsEmail
stringThe email address to which issues should be reported.
bugsUrl
stringThe url to your project's issue tracker.
bundledDeps
string[]List of dependencies to bundle into this module.
codeArtifactOptions
projen.javascript.CodeArtifactOptionsOptions for npm packages using AWS CodeArtifact.
deps
string[]Runtime dependencies of this module.
description
stringThe description is just a string that helps people understand the purpose of the package.
devDeps
string[]Build dependencies for this module.
entrypoint
stringModule entrypoint (main in package.json).
homepage
stringPackage's Homepage / Website.
keywords
string[]Keywords to include in package.json.
license
stringLicense's SPDX identifier.
licensed
booleanIndicates if a license should be added.
maxNodeVersion
stringThe maximum node version supported by this package. Most projects should not use this option.
minNodeVersion
stringThe minimum node version required by this package to function. Most projects should not use this option.
npmAccess
projen.javascript.NpmAccessAccess level of the npm package.
npmProvenance
booleanShould provenance statements be generated when the package is published.
npmRegistry
stringThe host name of the npm registry to publish to.
npmRegistryUrl
stringThe base URL of the npm package registry.
npmTokenSecret
stringGitHub secret which contains the NPM token to use when publishing packages.
packageManager
projen.javascript.NodePackageManagerThe Node Package Manager used to execute scripts.
packageName
stringThe "name" in package.json.
peerDependencyOptions
projen.javascript.PeerDependencyOptionsOptions for peerDeps.
peerDeps
string[]Peer dependencies for this module.
pnpmVersion
stringThe version of PNPM to use if using PNPM as a package manager.
repository
stringThe repository is the location where the actual code for your package lives.
repositoryDirectory
stringIf the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.
scopedPackagesOptions
projen.javascript.ScopedPackagesOptions[]Options for privately hosted scoped packages.
scripts
{[ key: string ]: string}npm scripts to include.
stability
stringPackage's Stability.
yarnBerryOptions
projen.javascript.YarnBerryOptionsOptions for Yarn Berry.
bumpPackage
stringThe commit-and-tag-version compatible package used to bump the package version, as a dependency string.
jsiiReleaseVersion
stringVersion requirement of publib which is used to publish modules to npm.
majorVersion
numberMajor version to release from the default branch.
minMajorVersion
numberMinimal Major version to release.
nextVersionCommand
stringA shell command to control the next version to release.
npmDistTag
stringThe npmDistTag to use when publishing from the default branch.
postBuildSteps
projen.github.workflows.JobStep[]Steps to execute after build as part of the release workflow.
prerelease
stringBump versions from the default branch as pre-releases (e.g. "beta", "alpha", "pre").
publishDryRun
booleanInstead of actually publishing to package managers, just print the publishing command.
publishTasks
booleanDefine publishing tasks that can be executed manually as well as workflows.
releasableCommits
projen.ReleasableCommitsFind commits that should be considered releasable Used to decide if a release is required.
releaseBranches
{[ key: string ]: projen.release.BranchOptions}Defines additional release branches.
releaseEveryCommit
booleanAutomatically release new versions every commit to one of branches in releaseBranches.
releaseFailureIssue
booleanCreate a github issue on every failed publishing task.
releaseFailureIssueLabel
stringThe label to apply to issues indicating publish failures.
releaseSchedule
stringCRON schedule to trigger new releases.
releaseTagPrefix
stringAutomatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.
releaseTrigger
projen.release.ReleaseTriggerThe release trigger to use.
releaseWorkflowName
stringThe name of the default release workflow.
releaseWorkflowSetupSteps
projen.github.workflows.JobStep[]A set of workflow steps to execute in order to setup the workflow container.
versionrcOptions
{[ key: string ]: any}Custom configuration used when creating changelog with commit-and-tag-version package.
workflowContainerImage
stringContainer image to use for GitHub workflows.
workflowRunsOn
string[]Github Runner selection labels.
workflowRunsOnGroup
projen.GroupRunnerOptionsGithub Runner Group selection options.
defaultReleaseBranch
stringThe name of the main release branch.
artifactsDirectory
stringA directory which will contain build artifacts.
autoApproveUpgrades
booleanAutomatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).
buildWorkflow
booleanDefine a GitHub workflow for building PRs.
buildWorkflowOptions
projen.javascript.BuildWorkflowOptionsOptions for PR build workflow.
buildWorkflowTriggers
projen.github.workflows.TriggersBuild workflow triggers.
bundlerOptions
projen.javascript.BundlerOptionsOptions for Bundler.
checkLicenses
projen.javascript.LicenseCheckerOptionsConfigure which licenses should be deemed acceptable for use by dependencies.
codeCov
booleanDefine a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v4 A secret is required for private repos. Configured with @codeCovTokenSecret.
codeCovTokenSecret
stringDefine the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories.
copyrightOwner
stringLicense copyright owner.
copyrightPeriod
stringThe copyright years to put in the LICENSE file.
dependabot
booleanUse dependabot to handle dependency upgrades.
dependabotOptions
projen.github.DependabotOptionsOptions for dependabot.
depsUpgrade
booleanUse tasks and github workflows to handle dependency upgrades.
depsUpgradeOptions
projen.javascript.UpgradeDependenciesOptionsOptions for UpgradeDependencies.
gitignore
string[]Additional entries to .gitignore.
jest
booleanSetup jest unit tests.
jestOptions
projen.javascript.JestOptionsJest options.
mutableBuild
booleanAutomatically update files modified during builds to pull-request branches.
npmignore
string[]Additional entries to .npmignore.
npmignoreEnabled
booleanDefines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.
npmIgnoreOptions
projen.IgnoreFileOptionsConfiguration options for .npmignore file.
package
booleanDefines a package task that will produce an npm tarball under the artifacts directory (e.g. dist).
prettier
booleanSetup prettier.
prettierOptions
projen.javascript.PrettierOptionsPrettier options.
projenDevDependency
booleanIndicates of "projen" should be installed as a devDependency.
projenrcJs
booleanGenerate (once) .projenrc.js (in JavaScript). Set to false in order to disable .projenrc.js generation.
projenrcJsOptions
projen.javascript.ProjenrcOptionsOptions for .projenrc.js.
projenVersion
stringVersion of projen to install.
pullRequestTemplate
booleanInclude a GitHub pull request template.
pullRequestTemplateContents
string[]The contents of the pull request template.
release
booleanAdd release management to this project.
releaseToNpm
booleanAutomatically release to npm when new versions are introduced.
releaseWorkflow
booleanDEPRECATED: renamed to release.
workflowBootstrapSteps
projen.github.workflows.JobStep[]Workflow steps to use in order to bootstrap this repo.
workflowGitIdentity
projen.github.GitIdentityThe git identity to use in workflows.
workflowNodeVersion
stringThe node version used in GitHub Actions workflows.
workflowPackageCache
booleanEnable Node.js package cache in GitHub workflows.
disableTsconfig
booleanDo not generate a tsconfig.json file (used by jsii projects since tsconfig.json is generated by the jsii compiler).
disableTsconfigDev
booleanDo not generate a tsconfig.dev.json file.
docgen
booleanDocgen by Typedoc.
docsDirectory
stringDocs directory.
entrypointTypes
stringThe .d.ts file that includes the type declarations for this module.
eslint
booleanSetup eslint.
eslintOptions
projen.javascript.EslintOptionsEslint options.
libdir
stringTypescript artifacts output directory.
projenrcTs
booleanUse TypeScript for your projenrc file (.projenrc.ts).
projenrcTsOptions
projen.typescript.ProjenrcOptionsOptions for .projenrc.ts.
sampleCode
booleanGenerate one-time sample in src/ and test/ if there are no files there.
srcdir
stringTypescript sources directory.
testdir
stringJest tests directory. Tests files should be named xxx.test.ts.
tsconfig
projen.javascript.TypescriptConfigOptionsCustom TSConfig.
tsconfigDev
projen.javascript.TypescriptConfigOptionsCustom tsconfig options for the development tsconfig.json file (used for testing).
tsconfigDevFile
stringThe name of the development tsconfig.json file.
tsJestOptions
projen.typescript.TsJestOptionsOptions for ts-jest.
typescriptVersion
stringTypeScript version to use.
author
stringThe name of the library author.
authorAddress
stringEmail or URL of the library author.
repositoryUrl
stringGit repository URL.
compat
booleanAutomatically run API compatibility test against the latest version published to npm after compilation.
compatIgnore
stringName of the ignore file for API compatibility tests.
compressAssembly
booleanEmit a compressed version of the assembly.
docgenFilePath
stringFile path for generated docs.
dotnet
JsiiDotNetTarget
No description.
excludeTypescript
string[]Accepts a list of glob patterns.
jsiiVersion
stringVersion of the jsii compiler to use.
publishToGo
JsiiGoTarget
Publish Go bindings to a git repository.
publishToMaven
JsiiJavaTarget
Publish to maven.
publishToNuget
JsiiDotNetTarget
Publish to NuGet.
publishToPypi
JsiiPythonTarget
Publish to pypi.
python
JsiiPythonTarget
No description.
rootdir
stringNo description.
catalog
Catalog
Libraries will be picked up by the construct catalog when they are published to npm as jsii modules and will be published under:.

nameRequired
public readonly name: string;
  • Type: string
  • Default: $BASEDIR

This is the name of your project.


commitGeneratedOptional
public readonly commitGenerated: boolean;
  • Type: boolean
  • Default: true

Whether to commit the managed files by default.


gitIgnoreOptionsOptional
public readonly gitIgnoreOptions: IgnoreFileOptions;
  • Type: projen.IgnoreFileOptions

Configuration options for .gitignore file.


gitOptionsOptional
public readonly gitOptions: GitOptions;
  • Type: projen.GitOptions

Configuration options for git.


loggingOptional
public readonly logging: LoggerOptions;
  • Type: projen.LoggerOptions
  • Default: {}

Configure logging options such as verbosity.


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


parentOptional
public readonly parent: Project;
  • Type: projen.Project

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


projenCommandOptional
public readonly projenCommand: string;
  • Type: string
  • Default: "npx projen"

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

Can be used to customize in special environments.


projenrcJsonOptional
public readonly projenrcJson: boolean;
  • Type: boolean
  • Default: false

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


projenrcJsonOptionsOptional
public readonly projenrcJsonOptions: ProjenrcJsonOptions;
  • Type: projen.ProjenrcJsonOptions
  • Default: default options

Options for .projenrc.json.


renovatebotOptional
public readonly renovatebot: boolean;
  • Type: boolean
  • Default: false

Use renovatebot to handle dependency upgrades.


renovatebotOptionsOptional
public readonly renovatebotOptions: RenovatebotOptions;
  • Type: projen.RenovatebotOptions
  • Default: default options

Options for renovatebot.


autoApproveOptionsOptional
public readonly autoApproveOptions: AutoApproveOptions;
  • Type: projen.github.AutoApproveOptions
  • Default: auto approve is disabled

Enable and configure the 'auto approve' workflow.


autoMergeOptional
public readonly autoMerge: boolean;
  • Type: boolean
  • Default: true

Enable automatic merging on GitHub.

Has no effect if github.mergify is set to false.


autoMergeOptionsOptional
public readonly autoMergeOptions: AutoMergeOptions;
  • Type: projen.github.AutoMergeOptions
  • Default: see defaults in AutoMergeOptions

Configure options for automatic merging on GitHub.

Has no effect if github.mergify or autoMerge is set to false.


clobberOptional
public readonly clobber: boolean;
  • Type: boolean
  • Default: true, but false for subprojects

Add a clobber task which resets the repo to origin.


devContainerOptional
public readonly devContainer: boolean;
  • Type: boolean
  • Default: false

Add a VSCode development environment (used for GitHub Codespaces).


githubOptional
public readonly github: boolean;
  • Type: boolean
  • Default: true

Enable GitHub integration.

Enabled by default for root projects. Disabled for non-root projects.


githubOptionsOptional
public readonly githubOptions: GitHubOptions;
  • Type: projen.github.GitHubOptions
  • Default: see GitHubOptions

Options for GitHub integration.


gitpodOptional
public readonly gitpod: boolean;
  • Type: boolean
  • Default: false

Add a Gitpod development environment.


mergifyOptional
  • Deprecated: use githubOptions.mergify instead
public readonly mergify: boolean;
  • Type: boolean
  • Default: true

Whether mergify should be enabled on this repository or not.


mergifyOptionsOptional
  • Deprecated: use githubOptions.mergifyOptions instead
public readonly mergifyOptions: MergifyOptions;
  • Type: projen.github.MergifyOptions
  • Default: default options

Options for mergify.


projectTypeOptional
  • Deprecated: no longer supported at the base project level
public readonly projectType: ProjectType;
  • Type: projen.ProjectType
  • Default: ProjectType.UNKNOWN

Which type of project this is (library/app).


projenCredentialsOptional
public readonly projenCredentials: GithubCredentials;
  • Type: projen.github.GithubCredentials
  • Default: use a personal access token named PROJEN_GITHUB_TOKEN

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


projenTokenSecretOptional
  • Deprecated: use projenCredentials
public readonly projenTokenSecret: string;
  • Type: string
  • Default: "PROJEN_GITHUB_TOKEN"

The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.

This token needs to have the repo, workflows and packages scope.


readmeOptional
public readonly readme: SampleReadmeProps;
  • Type: projen.SampleReadmeProps
  • Default: { filename: 'README.md', contents: '# replace this' }

The README setup.


Example

"{ filename: 'readme.md', contents: '# title' }"
staleOptional
public readonly stale: boolean;
  • Type: boolean
  • Default: false

Auto-close of stale issues and pull request.

See staleOptions for options.


staleOptionsOptional
public readonly staleOptions: StaleOptions;
  • Type: projen.github.StaleOptions
  • Default: see defaults in StaleOptions

Auto-close stale issues and pull requests.

To disable set stale to false.


vscodeOptional
public readonly vscode: boolean;
  • Type: boolean
  • Default: true

Enable VSCode integration.

Enabled by default for root projects. Disabled for non-root projects.


allowLibraryDependenciesOptional
public readonly allowLibraryDependencies: boolean;
  • Type: boolean
  • Default: true

Allow the project to include peerDependencies and bundledDependencies.

This is normally only allowed for libraries. For apps, there's no meaning for specifying these.


authorEmailOptional
public readonly authorEmail: string;
  • Type: string

Author's e-mail.


authorNameOptional
public readonly authorName: string;
  • Type: string

Author's name.


authorOrganizationOptional
public readonly authorOrganization: boolean;
  • Type: boolean

Is the author an organization.


authorUrlOptional
public readonly authorUrl: string;
  • Type: string

Author's URL / Website.


autoDetectBinOptional
public readonly autoDetectBin: boolean;
  • Type: boolean
  • Default: true

Automatically add all executables under the bin directory to your package.json file under the bin section.


binOptional
public readonly bin: {[ key: string ]: string};
  • Type: {[ key: string ]: string}

Binary programs vended with your module.

You can use this option to add/customize how binaries are represented in your package.json, but unless autoDetectBin is false, every executable file under bin will automatically be added to this section.


bugsEmailOptional
public readonly bugsEmail: string;
  • Type: string

The email address to which issues should be reported.


bugsUrlOptional
public readonly bugsUrl: string;
  • Type: string

The url to your project's issue tracker.


bundledDepsOptional
public readonly bundledDeps: string[];
  • Type: string[]

List of dependencies to bundle into this module.

These modules will be added both to the dependencies section and bundledDependencies section of your package.json.

The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.


codeArtifactOptionsOptional
public readonly codeArtifactOptions: CodeArtifactOptions;
  • Type: projen.javascript.CodeArtifactOptions
  • Default: undefined

Options for npm packages using AWS CodeArtifact.

This is required if publishing packages to, or installing scoped packages from AWS CodeArtifact


depsOptional
public readonly deps: string[];
  • Type: string[]
  • Default: []

Runtime dependencies of this module.

The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.


Example

[ 'express', 'lodash', 'foo@^2' ]
descriptionOptional
public readonly description: string;
  • Type: string

The description is just a string that helps people understand the purpose of the package.

It can be used when searching for packages in a package manager as well. See https://classic.yarnpkg.com/en/docs/package-json/#toc-description


devDepsOptional
public readonly devDeps: string[];
  • Type: string[]
  • Default: []

Build dependencies for this module.

These dependencies will only be available in your build environment but will not be fetched when this module is consumed.

The recommendation is to only specify the module name here (e.g. express). This will behave similar to yarn add or npm install in the sense that it will add the module as a dependency to your package.json file with the latest version (^). You can specify semver requirements in the same syntax passed to npm i or yarn add (e.g. express@^2) and this will be what you package.json will eventually include.


Example

[ 'typescript', '@types/express' ]
entrypointOptional
public readonly entrypoint: string;
  • Type: string
  • Default: "lib/index.js"

Module entrypoint (main in package.json).

Set to an empty string to not include main in your package.json


homepageOptional
public readonly homepage: string;
  • Type: string

Package's Homepage / Website.


keywordsOptional
public readonly keywords: string[];
  • Type: string[]

Keywords to include in package.json.


licenseOptional
public readonly license: string;
  • Type: string
  • Default: "Apache-2.0"

License's SPDX identifier.

See https://github.com/projen/projen/tree/main/license-text for a list of supported licenses. Use the licensed option if you want to no license to be specified.


licensedOptional
public readonly licensed: boolean;
  • Type: boolean
  • Default: true

Indicates if a license should be added.


maxNodeVersionOptional
public readonly maxNodeVersion: string;
  • Type: string
  • Default: no maximum version is enforced

The maximum node version supported by this package. Most projects should not use this option.

The value indicates that the package is incompatible with any newer versions of node. This requirement is enforced via the engines field.

You will normally not need to set this option. Consider this option only if your package is known to not function with newer versions of node.


minNodeVersionOptional
public readonly minNodeVersion: string;
  • Type: string
  • Default: no minimum version is enforced

The minimum node version required by this package to function. Most projects should not use this option.

The value indicates that the package is incompatible with any older versions of node. This requirement is enforced via the engines field.

You will normally not need to set this option, even if your package is incompatible with EOL versions of node. Consider this option only if your package depends on a specific feature, that is not available in other LTS versions. Setting this option has very high impact on the consumers of your package, as package managers will actively prevent usage with node versions you have marked as incompatible.

To change the node version of your CI/CD workflows, use workflowNodeVersion.


npmAccessOptional
public readonly npmAccess: NpmAccess;
  • Type: projen.javascript.NpmAccess
  • Default: for scoped packages (e.g. foo@bar), the default is NpmAccess.RESTRICTED, for non-scoped packages, the default is NpmAccess.PUBLIC.

Access level of the npm package.


npmProvenanceOptional
public readonly npmProvenance: boolean;
  • Type: boolean
  • Default: true for public packages, false otherwise

Should provenance statements be generated when the package is published.

A supported package manager is required to publish a package with npm provenance statements and you will need to use a supported CI/CD provider.

Note that the projen Release and Publisher components are using publib to publish packages, which is using npm internally and supports provenance statements independently of the package manager used.

https://docs.npmjs.com/generating-provenance-statements


npmRegistryOptional
  • Deprecated: use npmRegistryUrl instead
public readonly npmRegistry: string;
  • Type: string

The host name of the npm registry to publish to.

Cannot be set together with npmRegistryUrl.


npmRegistryUrlOptional
public readonly npmRegistryUrl: string;

The base URL of the npm package registry.

Must be a URL (e.g. start with "https://" or "http://")


npmTokenSecretOptional
public readonly npmTokenSecret: string;
  • Type: string
  • Default: "NPM_TOKEN"

GitHub secret which contains the NPM token to use when publishing packages.


packageManagerOptional
public readonly packageManager: NodePackageManager;
  • Type: projen.javascript.NodePackageManager
  • Default: NodePackageManager.YARN_CLASSIC

The Node Package Manager used to execute scripts.


packageNameOptional
public readonly packageName: string;
  • Type: string
  • Default: defaults to project name

The "name" in package.json.


peerDependencyOptionsOptional
public readonly peerDependencyOptions: PeerDependencyOptions;
  • Type: projen.javascript.PeerDependencyOptions

Options for peerDeps.


peerDepsOptional
public readonly peerDeps: string[];
  • Type: string[]
  • Default: []

Peer dependencies for this module.

Dependencies listed here are required to be installed (and satisfied) by the consumer of this library. Using peer dependencies allows you to ensure that only a single module of a certain library exists in the node_modules tree of your consumers.

Note that prior to npm@7, peer dependencies are not automatically installed, which means that adding peer dependencies to a library will be a breaking change for your customers.

Unless peerDependencyOptions.pinnedDevDependency is disabled (it is enabled by default), projen will automatically add a dev dependency with a pinned version for each peer dependency. This will ensure that you build & test your module against the lowest peer version required.


pnpmVersionOptional
public readonly pnpmVersion: string;
  • Type: string
  • Default: "7"

The version of PNPM to use if using PNPM as a package manager.


repositoryOptional
public readonly repository: string;
  • Type: string

The repository is the location where the actual code for your package lives.

See https://classic.yarnpkg.com/en/docs/package-json/#toc-repository


repositoryDirectoryOptional
public readonly repositoryDirectory: string;
  • Type: string

If the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.


scopedPackagesOptionsOptional
public readonly scopedPackagesOptions: ScopedPackagesOptions[];
  • Type: projen.javascript.ScopedPackagesOptions[]
  • Default: fetch all scoped packages from the public npm registry

Options for privately hosted scoped packages.


scriptsOptional
  • Deprecated: use project.addTask() or package.setScript()
public readonly scripts: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: {}

npm scripts to include.

If a script has the same name as a standard script, the standard script will be overwritten. Also adds the script as a task.


stabilityOptional
public readonly stability: string;
  • Type: string

Package's Stability.


yarnBerryOptionsOptional
public readonly yarnBerryOptions: YarnBerryOptions;
  • Type: projen.javascript.YarnBerryOptions
  • Default: Yarn Berry v4 with all default options

Options for Yarn Berry.


bumpPackageOptional
public readonly bumpPackage: string;
  • Type: string
  • Default: A recent version of "commit-and-tag-version"

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.


jsiiReleaseVersionOptional
public readonly jsiiReleaseVersion: string;
  • Type: string
  • Default: "latest"

Version requirement of publib which is used to publish modules to npm.


majorVersionOptional
public readonly majorVersion: number;
  • Type: number
  • Default: Major version is not enforced.

Major version to release from the default branch.

If this is specified, we bump the latest version of this major version line. If not specified, we bump the global latest version.


minMajorVersionOptional
public readonly minMajorVersion: number;
  • Type: number
  • Default: No minimum version is being enforced

Minimal Major version to release.

This can be useful to set to 1, as breaking changes before the 1.x major release are not incrementing the major version number.

Can not be set together with majorVersion.


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

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.

This setting cannot be specified together with minMajorVersion; the invoked script can be used to achieve the effects of minMajorVersion.


npmDistTagOptional
public readonly npmDistTag: string;
  • Type: string
  • Default: "latest"

The npmDistTag to use when publishing from the default branch.

To set the npm dist-tag for release branches, set the npmDistTag property for each branch.


postBuildStepsOptional
public readonly postBuildSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]
  • Default: []

Steps to execute after build as part of the release workflow.


prereleaseOptional
public readonly prerelease: string;
  • Type: string
  • Default: normal semantic versions

Bump versions from the default branch as pre-releases (e.g. "beta", "alpha", "pre").


publishDryRunOptional
public readonly publishDryRun: boolean;
  • Type: boolean
  • Default: false

Instead of actually publishing to package managers, just print the publishing command.


publishTasksOptional
public readonly publishTasks: boolean;
  • Type: boolean
  • Default: false

Define publishing tasks that can be executed manually as well as workflows.

Normally, publishing only happens within automated workflows. Enable this in order to create a publishing task for each publishing activity.


releasableCommitsOptional
public readonly releasableCommits: ReleasableCommits;
  • Type: projen.ReleasableCommits
  • Default: ReleasableCommits.everyCommit()

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


releaseBranchesOptional
public readonly releaseBranches: {[ key: string ]: BranchOptions};
  • Type: {[ key: string ]: projen.release.BranchOptions}
  • Default: no additional branches are used for release. you can use addBranch() to add additional branches.

Defines additional release branches.

A workflow will be created for each release branch which will publish releases from commits in this branch. Each release branch must be assigned a major version number which is used to enforce that versions published from that branch always use that major version. If multiple branches are used, the majorVersion field must also be provided for the default branch.


releaseEveryCommitOptional
  • Deprecated: Use releaseTrigger: ReleaseTrigger.continuous() instead
public readonly releaseEveryCommit: boolean;
  • Type: boolean
  • Default: true

Automatically release new versions every commit to one of branches in releaseBranches.


releaseFailureIssueOptional
public readonly releaseFailureIssue: boolean;
  • Type: boolean
  • Default: false

Create a github issue on every failed publishing task.


releaseFailureIssueLabelOptional
public readonly releaseFailureIssueLabel: string;
  • Type: string
  • Default: "failed-release"

The label to apply to issues indicating publish failures.

Only applies if releaseFailureIssue is true.


releaseScheduleOptional
  • Deprecated: Use releaseTrigger: ReleaseTrigger.scheduled() instead
public readonly releaseSchedule: string;
  • Type: string
  • Default: no scheduled releases

CRON schedule to trigger new releases.


releaseTagPrefixOptional
public readonly releaseTagPrefix: string;
  • Type: string
  • Default: "v"

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.


releaseTriggerOptional
public readonly releaseTrigger: ReleaseTrigger;
  • Type: projen.release.ReleaseTrigger
  • Default: Continuous releases (ReleaseTrigger.continuous())

The release trigger to use.


releaseWorkflowNameOptional
public readonly releaseWorkflowName: string;
  • Type: string
  • Default: "release"

The name of the default release workflow.


releaseWorkflowSetupStepsOptional
public readonly releaseWorkflowSetupSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]

A set of workflow steps to execute in order to setup the workflow container.


versionrcOptionsOptional
public readonly versionrcOptions: {[ key: string ]: any};
  • Type: {[ key: string ]: any}
  • Default: standard configuration applicable for GitHub repositories

Custom configuration used when creating changelog with commit-and-tag-version package.

Given values either append to default configuration or overwrite values in it.


workflowContainerImageOptional
public readonly workflowContainerImage: string;
  • Type: string
  • Default: default image

Container image to use for GitHub workflows.


workflowRunsOnOptional
public readonly workflowRunsOn: string[];
  • Type: string[]
  • Default: ["ubuntu-latest"]

Github Runner selection labels.


workflowRunsOnGroupOptional
public readonly workflowRunsOnGroup: GroupRunnerOptions;
  • Type: projen.GroupRunnerOptions

Github Runner Group selection options.


defaultReleaseBranchRequired
public readonly defaultReleaseBranch: string;
  • Type: string
  • Default: "main"

The name of the main release branch.


artifactsDirectoryOptional
public readonly artifactsDirectory: string;
  • Type: string
  • Default: "dist"

A directory which will contain build artifacts.


autoApproveUpgradesOptional
public readonly autoApproveUpgrades: boolean;
  • Type: boolean
  • Default: true

Automatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).

Throw if set to true but autoApproveOptions are not defined.


buildWorkflowOptional
public readonly buildWorkflow: boolean;
  • Type: boolean
  • Default: true if not a subproject

Define a GitHub workflow for building PRs.


buildWorkflowOptionsOptional
public readonly buildWorkflowOptions: BuildWorkflowOptions;
  • Type: projen.javascript.BuildWorkflowOptions

Options for PR build workflow.


buildWorkflowTriggersOptional
  • Deprecated: - Use buildWorkflowOptions.workflowTriggers
public readonly buildWorkflowTriggers: Triggers;
  • Type: projen.github.workflows.Triggers
  • Default: "{ pullRequest: {}, workflowDispatch: {} }"

Build workflow triggers.


bundlerOptionsOptional
public readonly bundlerOptions: BundlerOptions;
  • Type: projen.javascript.BundlerOptions

Options for Bundler.


checkLicensesOptional
public readonly checkLicenses: LicenseCheckerOptions;
  • Type: projen.javascript.LicenseCheckerOptions
  • Default: no license checks are run during the build and all licenses will be accepted

Configure which licenses should be deemed acceptable for use by dependencies.

This setting will cause the build to fail, if any prohibited or not allowed licenses ares encountered.


codeCovOptional
public readonly codeCov: boolean;
  • Type: boolean
  • Default: false

Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v4 A secret is required for private repos. Configured with @codeCovTokenSecret.


codeCovTokenSecretOptional
public readonly codeCovTokenSecret: string;
  • Type: string
  • Default: if this option is not specified, only public repositories are supported

Define the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories.


copyrightOwnerOptional
public readonly copyrightOwner: string;
  • Type: string
  • Default: defaults to the value of authorName or "" if authorName is undefined.

License copyright owner.


copyrightPeriodOptional
public readonly copyrightPeriod: string;
  • Type: string
  • Default: current year

The copyright years to put in the LICENSE file.


dependabotOptional
public readonly dependabot: boolean;
  • Type: boolean
  • Default: false

Use dependabot to handle dependency upgrades.

Cannot be used in conjunction with depsUpgrade.


dependabotOptionsOptional
public readonly dependabotOptions: DependabotOptions;
  • Type: projen.github.DependabotOptions
  • Default: default options

Options for dependabot.


depsUpgradeOptional
public readonly depsUpgrade: boolean;
  • Type: boolean
  • Default: true

Use tasks and github workflows to handle dependency upgrades.

Cannot be used in conjunction with dependabot.


depsUpgradeOptionsOptional
public readonly depsUpgradeOptions: UpgradeDependenciesOptions;
  • Type: projen.javascript.UpgradeDependenciesOptions
  • Default: default options

Options for UpgradeDependencies.


gitignoreOptional
public readonly gitignore: string[];
  • Type: string[]

Additional entries to .gitignore.


jestOptional
public readonly jest: boolean;
  • Type: boolean
  • Default: true

Setup jest unit tests.


jestOptionsOptional
public readonly jestOptions: JestOptions;
  • Type: projen.javascript.JestOptions
  • Default: default options

Jest options.


mutableBuildOptional
  • Deprecated: - Use buildWorkflowOptions.mutableBuild
public readonly mutableBuild: boolean;
  • Type: boolean
  • Default: true

Automatically update files modified during builds to pull-request branches.

This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.

Implies that PR builds do not have anti-tamper checks.


npmignoreOptional
  • Deprecated: - use project.addPackageIgnore
public readonly npmignore: string[];
  • Type: string[]

Additional entries to .npmignore.


npmignoreEnabledOptional
public readonly npmignoreEnabled: boolean;
  • Type: boolean
  • Default: true

Defines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.


npmIgnoreOptionsOptional
public readonly npmIgnoreOptions: IgnoreFileOptions;
  • Type: projen.IgnoreFileOptions

Configuration options for .npmignore file.


packageOptional
public readonly package: boolean;
  • Type: boolean
  • Default: true

Defines a package task that will produce an npm tarball under the artifacts directory (e.g. dist).


prettierOptional
public readonly prettier: boolean;
  • Type: boolean
  • Default: false

Setup prettier.


prettierOptionsOptional
public readonly prettierOptions: PrettierOptions;
  • Type: projen.javascript.PrettierOptions
  • Default: default options

Prettier options.


projenDevDependencyOptional
public readonly projenDevDependency: boolean;
  • Type: boolean
  • Default: true if not a subproject

Indicates of "projen" should be installed as a devDependency.


projenrcJsOptional
public readonly projenrcJs: boolean;
  • Type: boolean
  • Default: true if projenrcJson is false

Generate (once) .projenrc.js (in JavaScript). Set to false in order to disable .projenrc.js generation.


projenrcJsOptionsOptional
public readonly projenrcJsOptions: ProjenrcOptions;
  • Type: projen.javascript.ProjenrcOptions
  • Default: default options

Options for .projenrc.js.


projenVersionOptional
public readonly projenVersion: string;
  • Type: string
  • Default: Defaults to the latest version.

Version of projen to install.


pullRequestTemplateOptional
public readonly pullRequestTemplate: boolean;
  • Type: boolean
  • Default: true

Include a GitHub pull request template.


pullRequestTemplateContentsOptional
public readonly pullRequestTemplateContents: string[];
  • Type: string[]
  • Default: default content

The contents of the pull request template.


releaseOptional
public readonly release: boolean;
  • Type: boolean
  • Default: true (false for subprojects)

Add release management to this project.


releaseToNpmOptional
public readonly releaseToNpm: boolean;
  • Type: boolean
  • Default: false

Automatically release to npm when new versions are introduced.


releaseWorkflowOptional
  • Deprecated: see release.
public readonly releaseWorkflow: boolean;
  • Type: boolean
  • Default: true if not a subproject

DEPRECATED: renamed to release.


workflowBootstrapStepsOptional
public readonly workflowBootstrapSteps: JobStep[];
  • Type: projen.github.workflows.JobStep[]
  • Default: "yarn install --frozen-lockfile && yarn projen"

Workflow steps to use in order to bootstrap this repo.


workflowGitIdentityOptional
public readonly workflowGitIdentity: GitIdentity;
  • Type: projen.github.GitIdentity
  • Default: GitHub Actions

The git identity to use in workflows.


workflowNodeVersionOptional
public readonly workflowNodeVersion: string;
  • Type: string
  • Default: minNodeVersion if set, otherwise lts/*.

The node version used in GitHub Actions workflows.

Always use this option if your GitHub Actions workflows require a specific to run.


workflowPackageCacheOptional
public readonly workflowPackageCache: boolean;
  • Type: boolean
  • Default: false

Enable Node.js package cache in GitHub workflows.


disableTsconfigOptional
public readonly disableTsconfig: boolean;
  • Type: boolean
  • Default: false

Do not generate a tsconfig.json file (used by jsii projects since tsconfig.json is generated by the jsii compiler).


disableTsconfigDevOptional
public readonly disableTsconfigDev: boolean;
  • Type: boolean
  • Default: false

Do not generate a tsconfig.dev.json file.


docgenOptional
public readonly docgen: boolean;
  • Type: boolean
  • Default: false

Docgen by Typedoc.


docsDirectoryOptional
public readonly docsDirectory: string;
  • Type: string
  • Default: "docs"

Docs directory.


entrypointTypesOptional
public readonly entrypointTypes: string;
  • Type: string
  • Default: .d.ts file derived from the project's entrypoint (usually lib/index.d.ts)

The .d.ts file that includes the type declarations for this module.


eslintOptional
public readonly eslint: boolean;
  • Type: boolean
  • Default: true

Setup eslint.


eslintOptionsOptional
public readonly eslintOptions: EslintOptions;
  • Type: projen.javascript.EslintOptions
  • Default: opinionated default options

Eslint options.


libdirOptional
public readonly libdir: string;
  • Type: string
  • Default: "lib"

Typescript artifacts output directory.


projenrcTsOptional
public readonly projenrcTs: boolean;
  • Type: boolean
  • Default: false

Use TypeScript for your projenrc file (.projenrc.ts).


projenrcTsOptionsOptional
public readonly projenrcTsOptions: ProjenrcOptions;
  • Type: projen.typescript.ProjenrcOptions

Options for .projenrc.ts.


sampleCodeOptional
public readonly sampleCode: boolean;
  • Type: boolean
  • Default: true

Generate one-time sample in src/ and test/ if there are no files there.


srcdirOptional
public readonly srcdir: string;
  • Type: string
  • Default: "src"

Typescript sources directory.


testdirOptional
public readonly testdir: string;
  • Type: string
  • Default: "test"

Jest tests directory. Tests files should be named xxx.test.ts.

If this directory is under srcdir (e.g. src/test, src/__tests__), then tests are going to be compiled into lib/ and executed as javascript. If the test directory is outside of src, then we configure jest to compile the code in-memory.


tsconfigOptional
public readonly tsconfig: TypescriptConfigOptions;
  • Type: projen.javascript.TypescriptConfigOptions
  • Default: default options

Custom TSConfig.


tsconfigDevOptional
public readonly tsconfigDev: TypescriptConfigOptions;
  • Type: projen.javascript.TypescriptConfigOptions
  • Default: use the production tsconfig options

Custom tsconfig options for the development tsconfig.json file (used for testing).


tsconfigDevFileOptional
public readonly tsconfigDevFile: string;
  • Type: string
  • Default: "tsconfig.dev.json"

The name of the development tsconfig.json file.


tsJestOptionsOptional
public readonly tsJestOptions: TsJestOptions;
  • Type: projen.typescript.TsJestOptions

Options for ts-jest.


typescriptVersionOptional
public readonly typescriptVersion: string;
  • Type: string
  • Default: "latest"

TypeScript version to use.

NOTE: Typescript is not semantically versioned and should remain on the same minor, so we recommend using a ~ dependency (e.g. ~1.2.3).


authorRequired
public readonly author: string;
  • Type: string
  • Default: $GIT_USER_NAME

The name of the library author.


authorAddressRequired
public readonly authorAddress: string;
  • Type: string
  • Default: $GIT_USER_EMAIL

Email or URL of the library author.


repositoryUrlRequired
public readonly repositoryUrl: string;
  • Type: string
  • Default: $GIT_REMOTE

Git repository URL.


compatOptional
public readonly compat: boolean;
  • Type: boolean
  • Default: false

Automatically run API compatibility test against the latest version published to npm after compilation.

You can manually run compatibility tests using yarn compat if this feature is disabled.

  • You can ignore compatibility failures by adding lines to a ".compatignore" file.

compatIgnoreOptional
public readonly compatIgnore: string;
  • Type: string
  • Default: ".compatignore"

Name of the ignore file for API compatibility tests.


compressAssemblyOptional
public readonly compressAssembly: boolean;
  • Type: boolean
  • Default: false

Emit a compressed version of the assembly.


docgenFilePathOptional