Skip to content

Latest commit

 

History

History
4581 lines (2881 loc) · 163 KB

API.md

File metadata and controls

4581 lines (2881 loc) · 163 KB
Raw

cdktf-project

This is a projen project template to manage CDKTF repositories. Please see the API for documentation.

Requirements

CDKTF supports only certain versions of Node (^19.0.0, ^16.3.0, ^18.0.0) and will show unexpected errors in other versions of Node. As such, make sure your local environment is using one of these versions when running projen. 18.0.0 has the farthest EOL at 2025-04-30.

Usage

nvm use 18
npx projen new \
  --from @rlmartin-projen/cdktf-project@~0 \
  --projenrc-ts

Warnings

.github/settings.yml

This template will generate configuration in .github/settings.yml to attempt to manage protected branches and deployment environments. Both of these features are available to only public repositories or public and private repositories on paid plans. If you are using this project template on a free, private repository, you should not expect the protected branch or deployment environment configuration in .github/settings.yml to have any effect.

API Reference

Constructs

CdktfProject

Initializers 

import { CdktfProject } from '@rlmartin-projen/cdktf-project'

new CdktfProject(options: CdktfProjectOptions)
Name Type Description
options CdktfProjectOptions No description.
optionsRequired

Methods

Name Description
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.
addEmbeddedPackage No description.
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.

addEmbeddedPackage 
public addEmbeddedPackage(name: string, config: EmbeddedPackage, majorVersion: number, namespaceOpt?: string): void
nameRequired
  • Type: string
configRequired
majorVersionRequired
  • Type: number
namespaceOptOptional
  • Type: string

Static Functions

Name Description
isConstruct Checks if x is a construct.
isProject Test whether the given construct is a project.
of Find the closest ancestor project for given construct.
isConstruct 
import { CdktfProject } from '@rlmartin-projen/cdktf-project'

CdktfProject.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 { CdktfProject } from '@rlmartin-projen/cdktf-project'

CdktfProject.isProject(x: any)

Test whether the given construct is a project.

xRequired
  • Type: any
of 
import { CdktfProject } from '@rlmartin-projen/cdktf-project'

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

Name Type Description
node constructs.Node The tree node.
buildTask projen.Task No description.
commitGenerated boolean Whether to commit the managed files by default.
compileTask projen.Task No description.
components projen.Component[] Returns all the components within this project.
deps projen.Dependencies Project dependencies.
ejected boolean Whether or not the project is being ejected.
files projen.FileBase[] All files in this project.
gitattributes projen.GitAttributesFile The .gitattributes file for this repository.
gitignore projen.IgnoreFile .gitignore.
logger projen.Logger Logging utilities.
name string Project name.
outdir string Absolute output directory of this project.
packageTask projen.Task No description.
postCompileTask projen.Task No description.
preCompileTask projen.Task No description.
projectBuild projen.ProjectBuild Manages the build process of the project.
projenCommand string The command to use in order to run the projen CLI.
root projen.Project The root project.
subprojects projen.Project[] Returns all the subprojects within this project.
tasks projen.Tasks Project tasks.
testTask projen.Task No description.
defaultTask projen.Task This is the "default" task, the one that executes "projen".
initProject projen.InitProject The options used when this project is bootstrapped via projen new.
parent projen.Project A parent project.
projectType projen.ProjectType No description.
autoApprove projen.github.AutoApprove Auto approve set up for this project.
devContainer projen.vscode.DevContainer Access for .devcontainer.json (used for GitHub Codespaces).
github projen.github.GitHub Access all github components.
gitpod projen.Gitpod Access for Gitpod.
vscode projen.vscode.VsCode Access all VSCode components.
allowLibraryDependencies boolean No description.
artifactsDirectory string The build output directory.
artifactsJavascriptDirectory string The location of the npm tarball after build (${artifactsDirectory}/js).
bundler projen.javascript.Bundler No description.
entrypoint string No description.
manifest any No description.
npmrc projen.javascript.NpmConfig The .npmrc file.
package projen.javascript.NodePackage API for managing the node package.
packageManager projen.javascript.NodePackageManager The package manager to use.
runScriptCommand string The command to use to run scripts (e.g. yarn run or npm run depends on the package manager).
autoMerge projen.github.AutoMerge Component that sets up mergify for merging approved pull requests.
buildWorkflow projen.build.BuildWorkflow The PR build GitHub workflow.
buildWorkflowJobId string The job ID of the build workflow.
jest projen.javascript.Jest The Jest configuration (if enabled).
maxNodeVersion string Maximum node version required by this package.
minNodeVersion string Minimum node.js version required by this package.
npmignore projen.IgnoreFile The .npmignore file.
prettier projen.javascript.Prettier No description.
publisher projen.release.Publisher Package publisher.
release projen.release.Release Release management.
upgradeWorkflow projen.javascript.UpgradeDependencies The upgrade workflow.
docsDirectory string No description.
libdir string The directory in which compiled .js files reside.
srcdir string The directory in which the .ts sources reside.
testdir string The directory in which tests reside.
tsconfigDev projen.javascript.TypescriptConfig A typescript configuration file which covers all files (sources, tests, projen).
watchTask projen.Task The "watch" task.
docgen boolean No description.
eslint projen.javascript.Eslint No description.
tsconfig projen.javascript.TypescriptConfig No description.
tsconfigEslint projen.javascript.TypescriptConfig No 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 required by this package.

minNodeVersionOptional 
public readonly minNodeVersion: string;
  • Type: string

Minimum node.js version required by this package.

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

Name Type Description
DEFAULT_TASK string The name of the default task (the task executed when projen is run without arguments).
DEFAULT_TS_JEST_TRANFORM_PATTERN string No 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

CdktfProjectOptions

Initializer 

import { CdktfProjectOptions } from '@rlmartin-projen/cdktf-project'

const cdktfProjectOptions: CdktfProjectOptions = { ... }

Properties

Name Type Description
name string This is the name of your project.
commitGenerated boolean Whether to commit the managed files by default.
gitIgnoreOptions projen.IgnoreFileOptions Configuration options for .gitignore file.
gitOptions projen.GitOptions Configuration options for git.
logging projen.LoggerOptions Configure logging options such as verbosity.
outdir string The root directory of the project.
parent projen.Project The parent project, if this project is part of a bigger project.
projenCommand string The shell command to use in order to run the projen CLI.
projenrcJson boolean Generate (once) .projenrc.json (in JSON). Set to false in order to disable .projenrc.json generation.
projenrcJsonOptions projen.ProjenrcJsonOptions Options for .projenrc.json.
renovatebot boolean Use renovatebot to handle dependency upgrades.
renovatebotOptions projen.RenovatebotOptions Options for renovatebot.
autoApproveOptions projen.github.AutoApproveOptions Enable and configure the 'auto approve' workflow.
autoMerge boolean Enable automatic merging on GitHub.
autoMergeOptions projen.github.AutoMergeOptions Configure options for automatic merging on GitHub.
clobber boolean Add a clobber task which resets the repo to origin.
devContainer boolean Add a VSCode development environment (used for GitHub Codespaces).
github boolean Enable GitHub integration.
githubOptions projen.github.GitHubOptions Options for GitHub integration.
gitpod boolean Add a Gitpod development environment.
mergify boolean Whether mergify should be enabled on this repository or not.
mergifyOptions projen.github.MergifyOptions Options for mergify.
projectType projen.ProjectType Which type of project this is (library/app).
projenCredentials projen.github.GithubCredentials Choose a method of providing GitHub API access for projen workflows.
projenTokenSecret string The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows.
readme projen.SampleReadmeProps The README setup.
stale boolean Auto-close of stale issues and pull request.
staleOptions projen.github.StaleOptions Auto-close stale issues and pull requests.
vscode boolean Enable VSCode integration.
allowLibraryDependencies boolean Allow the project to include peerDependencies and bundledDependencies.
authorEmail string Author's e-mail.
authorName string Author's name.
authorOrganization boolean Is the author an organization.
authorUrl string Author's URL / Website.
autoDetectBin boolean Automatically 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 string The email address to which issues should be reported.
bugsUrl string The url to your project's issue tracker.
bundledDeps string[] List of dependencies to bundle into this module.
codeArtifactOptions projen.javascript.CodeArtifactOptions Options for npm packages using AWS CodeArtifact.
deps string[] Runtime dependencies of this module.
description string The description is just a string that helps people understand the purpose of the package.
devDeps string[] Build dependencies for this module.
entrypoint string Module entrypoint (main in package.json).
homepage string Package's Homepage / Website.
keywords string[] Keywords to include in package.json.
license string License's SPDX identifier.
licensed boolean Indicates if a license should be added.
maxNodeVersion string Minimum node.js version to require via engines (inclusive).
minNodeVersion string Minimum Node.js version to require via package.json engines (inclusive).
npmAccess projen.javascript.NpmAccess Access level of the npm package.
npmProvenance boolean Should provenance statements be generated when the package is published.
npmRegistry string The host name of the npm registry to publish to.
npmRegistryUrl string The base URL of the npm package registry.
npmTokenSecret string GitHub secret which contains the NPM token to use when publishing packages.
packageManager projen.javascript.NodePackageManager The Node Package Manager used to execute scripts.
packageName string The "name" in package.json.
peerDependencyOptions projen.javascript.PeerDependencyOptions Options for peerDeps.
peerDeps string[] Peer dependencies for this module.
pnpmVersion string The version of PNPM to use if using PNPM as a package manager.
repository string The repository is the location where the actual code for your package lives.
repositoryDirectory string If the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.
scopedPackagesOptions projen.javascript.ScopedPackagesOptions[] Options for privately hosted scoped packages.
scripts {[ key: string ]: string} npm scripts to include.
stability string Package's Stability.
yarnBerryOptions projen.javascript.YarnBerryOptions Options for Yarn Berry.
jsiiReleaseVersion string Version requirement of publib which is used to publish modules to npm.
majorVersion number Major version to release from the default branch.
minMajorVersion number Minimal Major version to release.
npmDistTag string The 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 string Bump versions from the default branch as pre-releases (e.g. "beta", "alpha", "pre").
publishDryRun boolean Instead of actually publishing to package managers, just print the publishing command.
publishTasks boolean Define publishing tasks that can be executed manually as well as workflows.
releasableCommits projen.ReleasableCommits Find 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 boolean Automatically release new versions every commit to one of branches in releaseBranches.
releaseFailureIssue boolean Create a github issue on every failed publishing task.
releaseFailureIssueLabel string The label to apply to issues indicating publish failures.
releaseSchedule string CRON schedule to trigger new releases.
releaseTagPrefix string Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.
releaseTrigger projen.release.ReleaseTrigger The release trigger to use.
releaseWorkflowName string The 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 standard-version package.
workflowContainerImage string Container image to use for GitHub workflows.
workflowRunsOn string[] Github Runner selection labels.
workflowRunsOnGroup projen.GroupRunnerOptions Github Runner Group selection options.
defaultReleaseBranch string The name of the main release branch.
artifactsDirectory string A directory which will contain build artifacts.
autoApproveUpgrades boolean Automatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).
buildWorkflow boolean Define a GitHub workflow for building PRs.
buildWorkflowOptions projen.javascript.BuildWorkflowOptions Options for PR build workflow.
buildWorkflowTriggers projen.github.workflows.Triggers Build workflow triggers.
bundlerOptions projen.javascript.BundlerOptions Options for Bundler.
checkLicenses projen.javascript.LicenseCheckerOptions Configure which licenses should be deemed acceptable for use by dependencies.
codeCov boolean Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v4 A secret is required for private repos. Configured with @codeCovTokenSecret.
codeCovTokenSecret string Define the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories.
copyrightOwner string License copyright owner.
copyrightPeriod string The copyright years to put in the LICENSE file.
dependabot boolean Use dependabot to handle dependency upgrades.
dependabotOptions projen.github.DependabotOptions Options for dependabot.
depsUpgrade boolean Use tasks and github workflows to handle dependency upgrades.
depsUpgradeOptions projen.javascript.UpgradeDependenciesOptions Options for UpgradeDependencies.
gitignore string[] Additional entries to .gitignore.
jest boolean Setup jest unit tests.
jestOptions projen.javascript.JestOptions Jest options.
mutableBuild boolean Automatically update files modified during builds to pull-request branches.
npmignore string[] Additional entries to .npmignore.
npmignoreEnabled boolean Defines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.
npmIgnoreOptions projen.IgnoreFileOptions Configuration options for .npmignore file.
package boolean Defines a package task that will produce an npm tarball under the artifacts directory (e.g. dist).
prettier boolean Setup prettier.
prettierOptions projen.javascript.PrettierOptions Prettier options.
projenDevDependency boolean Indicates of "projen" should be installed as a devDependency.
projenrcJs boolean Generate (once) .projenrc.js (in JavaScript). Set to false in order to disable .projenrc.js generation.
projenrcJsOptions projen.javascript.ProjenrcOptions Options for .projenrc.js.
projenVersion string Version of projen to install.
pullRequestTemplate boolean Include a GitHub pull request template.
pullRequestTemplateContents string[] The contents of the pull request template.
release boolean Add release management to this project.
releaseToNpm boolean Automatically release to npm when new versions are introduced.
releaseWorkflow boolean DEPRECATED: renamed to release.
workflowBootstrapSteps projen.github.workflows.JobStep[] Workflow steps to use in order to bootstrap this repo.
workflowGitIdentity projen.github.GitIdentity The git identity to use in workflows.
workflowNodeVersion string The node version to use in GitHub workflows.
workflowPackageCache boolean Enable Node.js package cache in GitHub workflows.
disableTsconfig boolean Do not generate a tsconfig.json file (used by jsii projects since tsconfig.json is generated by the jsii compiler).
disableTsconfigDev boolean Do not generate a tsconfig.dev.json file.
docgen boolean Docgen by Typedoc.
docsDirectory string Docs directory.
entrypointTypes string The .d.ts file that includes the type declarations for this module.
eslint boolean Setup eslint.
eslintOptions projen.javascript.EslintOptions Eslint options.
libdir string Typescript artifacts output directory.
projenrcTs boolean Use TypeScript for your projenrc file (.projenrc.ts).
projenrcTsOptions projen.typescript.ProjenrcOptions Options for .projenrc.ts.
sampleCode boolean Generate one-time sample in src/ and test/ if there are no files there.
srcdir string Typescript sources directory.
testdir string Jest tests directory. Tests files should be named xxx.test.ts.
tsconfig projen.javascript.TypescriptConfigOptions Custom TSConfig.
tsconfigDev projen.javascript.TypescriptConfigOptions Custom tsconfig options for the development tsconfig.json file (used for testing).
tsconfigDevFile string The name of the development tsconfig.json file.
tsJestOptions projen.typescript.TsJestOptions Options for ts-jest.
typescriptVersion string TypeScript version to use.
artifactsFolder string Configurable folder for artifacts to package when transitioning from plan to apply.
deploymentEnvironments {[ key: string ]: DeploymentEnvironment} Add GitHub Wokflows for enabled environments.
embeddedNamespace string Used to scope the embedded packages to avoid naming collisions.
embeddedPackages {[ key: string ]: EmbeddedPackage} Small functions to be deployed with the other resources in the repo.
nodeScripts {[ key: string ]: string} A set of scripts to be added to package.json but not wrapped by projen.
nodeVersion number The Node.js version to use when building.
npmrc string[] Raw lines to drop into the workflow's .npmrc file, to access private package. Empty implies no .npmrc required.
repoAdmins {[ key: string ]: number} The GitHub Team slug (including the org_name/ prefix) or GitHub username for the teams/people who maintain infrastructure.
terraformBackend TerraformBackend Terraform backend configuration.
terraformManualWorkflow boolean Set this to turn on a GitHub workflow that can be used to run manual Terraform commands within the environment.
terraformModules TerraformModuleOptions[] Terraform Modules to add to cdktf.json. These are assumed to be internal to the Medly GitHub org.
terraformModulesSsh boolean Set this to true for local dev when using SSH to connect to GitHub.
terraformProviders string[] Terraform Providers to add to cdktf.json.
terraformVars string[] List of Terraform variables to pull from GitHub secrets and set as TF_VAR_ environment variables during terraform plan.
terraformVersion string The Terraform version to use in the build pipelines.
workflowEnvVars EnvVars Optional list of env vars to load from GitHub Secrets/Variables into workflow-level env variables.
workflowInputs {[ key: string ]: WorkflowInputOptions} Optional inputs (map of name => options) to inject into the workflow_dispatch.
workflowSteps WorkflowSteps Optional steps to include in the GitHub workflow.
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 max

Minimum node.js version to require via engines (inclusive).

minNodeVersionOptional 
public readonly minNodeVersion: string;
  • Type: string
  • Default: no "engines" specified

Minimum Node.js version to require via package.json engines (inclusive).

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.

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.

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 standard-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: same as minNodeVersion

The node version to use in GitHub workflows.

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

artifactsFolderOptional 
public readonly artifactsFolder: string;
  • Type: string
  • Default: 'dist'

Configurable folder for artifacts to package when transitioning from plan to apply.

deploymentEnvironmentsOptional 
public readonly deploymentEnvironments: {[ key: string ]: DeploymentEnvironment};

Add GitHub Wokflows for enabled environments.

embeddedNamespaceOptional 
public readonly embeddedNamespace: string;
  • Type: string
  • Default: top-level project name

Used to scope the embedded packages to avoid naming collisions.

embeddedPackagesOptional 
public readonly embeddedPackages: {[ key: string ]: EmbeddedPackage};

Small functions to be deployed with the other resources in the repo.

Should be viewed more as infrastructure than services. Testing and linting intentionally mirror the overall repo.

nodeScriptsOptional 
public readonly nodeScripts: {[ key: string ]: string};
  • Type: {[ key: string ]: string}
  • Default: {}

A set of scripts to be added to package.json but not wrapped by projen.

nodeVersionOptional 
public readonly nodeVersion: number;
  • Type: number
  • Default: 20

The Node.js version to use when building.

npmrcOptional 
public readonly npmrc: string[];
  • Type: string[]
  • Default: []

Raw lines to drop into the workflow's .npmrc file, to access private package. Empty implies no .npmrc required.

repoAdminsOptional 
public readonly repoAdmins: {[ key: string ]: number};
  • Type: {[ key: string ]: number}
  • Default: {}

The GitHub Team slug (including the org_name/ prefix) or GitHub username for the teams/people who maintain infrastructure.

As a hack, and to avoid async fetching from the GitHub API to lookup ids, this is a map of username => GitHub id (which will need to be looked up manually). In the future it would be nice to make this a simple string[] (list of usernames) and automatically lookup the ids.

terraformBackendOptional 
public readonly terraformBackend: TerraformBackend;

Terraform backend configuration.

terraformManualWorkflowOptional 
public readonly terraformManualWorkflow: boolean;
  • Type: boolean

Set this to turn on a GitHub workflow that can be used to run manual Terraform commands within the environment.

This is helpful for debugging and managing complicated state changes.

terraformModulesOptional 
public readonly terraformModules: TerraformModuleOptions[];

Terraform Modules to add to cdktf.json. These are assumed to be internal to the Medly GitHub org.

terraformModulesSshOptional 
public readonly terraformModulesSsh: boolean;
  • Type: boolean
  • Default: false

Set this to true for local dev when using SSH to connect to GitHub.

terraformProvidersOptional 
public readonly terraformProviders: string[];
  • Type: string[]
  • Default: []

Terraform Providers to add to cdktf.json.

terraformVarsOptional 
public readonly terraformVars: string[];
  • Type: string[]
  • Default: []

List of Terraform variables to pull from GitHub secrets and set as TF_VAR_ environment variables during terraform plan.

The secrets will need to be set manually, on one of org/repo/environment. The name of the var is expected to not include the TF_VAR_ prefix.

terraformVersionOptional 
public readonly terraformVersion: string;
  • Type: string
  • Default: latest

The Terraform version to use in the build pipelines.

workflowEnvVarsOptional 
public readonly workflowEnvVars: EnvVars;

Optional list of env vars to load from GitHub Secrets/Variables into workflow-level env variables.

workflowInputsOptional 
public readonly workflowInputs: {[ key: string ]: WorkflowInputOptions};

Optional inputs (map of name => options) to inject into the workflow_dispatch.

workflowStepsOptional 
public readonly workflowSteps: WorkflowSteps;

Optional steps to include in the GitHub workflow.

DeploymentEnvironment

Initializer 

import { DeploymentEnvironment } from '@rlmartin-projen/cdktf-project'

const deploymentEnvironment: DeploymentEnvironment = { ... }

Properties

Name Type Description
branchFilters string[] Branch matchers from which code can be deployed for this environment.
onlyProtectedBranches boolean Instead of filtering branches, use branches protected in the repo settings.
region string The AWS region to deploy to.
requireApproval boolean Whether the environment requires approval before applying;
useOidc boolean Whether this deployment uses a GitHub OIDC connection to deploy.
branchFiltersOptional 
public readonly branchFilters: string[];
  • Type: string[]
  • Default: []

Branch matchers from which code can be deployed for this environment.

Empty implies "all". Mutually-exclusive from onlyProtectedBranches.

onlyProtectedBranchesOptional 
public readonly onlyProtectedBranches: boolean;
  • Type: boolean
  • Default: false

Instead of filtering branches, use branches protected in the repo settings.

Mutually-exclusive from branchFilters

regionOptional 
public readonly region: string;
  • Type: string
  • Default: us-east-1

The AWS region to deploy to.

requireApprovalOptional 
public readonly requireApproval: boolean;
  • Type: boolean
  • Default: false

Whether the environment requires approval before applying;

plans always run

useOidcOptional 
public readonly useOidc: boolean;
  • Type: boolean
  • Default: false

Whether this deployment uses a GitHub OIDC connection to deploy.

See https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services

EmbeddedPackage

Initializer 

import { EmbeddedPackage } from '@rlmartin-projen/cdktf-project'

const embeddedPackage: EmbeddedPackage = { ... }

Properties

Name Type Description
type string Determined whether the embedded package is a function or a library.
deps string[] Any dependencies specific to the embedded function.
devDeps string[] Any dev dependencies specific to the embedded function.
localDeps string[] Local dependencies on other embedded packages.
typeRequired 
public readonly type: string;
  • Type: string

Determined whether the embedded package is a function or a library.

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

Any dependencies specific to the embedded function.

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

Any dev dependencies specific to the embedded function.

localDepsOptional 
public readonly localDeps: string[];
  • Type: string[]
  • Default: []

Local dependencies on other embedded packages.

EnvVars

Initializer 

import { EnvVars } from '@rlmartin-projen/cdktf-project'

const envVars: EnvVars = { ... }

Properties

Name Type Description
secrets string[] | {[ key: string ]: string} No description.
vars string[] | {[ key: string ]: string} No description.
secretsOptional 
public readonly secrets: string[] | {[ key: string ]: string};
  • Type: string[] | {[ key: string ]: string}
varsOptional 
public readonly vars: string[] | {[ key: string ]: string};
  • Type: string[] | {[ key: string ]: string}

S3Backend

Initializer 

import { S3Backend } from '@rlmartin-projen/cdktf-project'

const s3Backend: S3Backend = { ... }

Properties

Name Type Description
accountId string The AWS accountId where the S3 bucket and DynamoDB locks table exist.
prefix string Prefix to use when naming backend resources.
region string AWS region where the S3 bucket and DynamoDB locks table exist.
accountIdRequired 
public readonly accountId: string;
  • Type: string

The AWS accountId where the S3 bucket and DynamoDB locks table exist.

prefixRequired 
public readonly prefix: string;
  • Type: string

Prefix to use when naming backend resources.

regionOptional 
public readonly region: string;
  • Type: string
  • Default: 'us-east-1'

AWS region where the S3 bucket and DynamoDB locks table exist.

TerraformBackend

Initializer 

import { TerraformBackend } from '@rlmartin-projen/cdktf-project'

const terraformBackend: TerraformBackend = { ... }

Properties

Name Type Description
aws S3Backend No description.
awsRequired 
public readonly aws: S3Backend;

TerraformModuleOptions

Initializer 

import { TerraformModuleOptions } from '@rlmartin-projen/cdktf-project'

const terraformModuleOptions: TerraformModuleOptions = { ... }

Properties

Name Type Description
githubOrgName string No description.
name string No description.
version string No description.
nameOverride string No description.
submodule TerraformSubmoduleOptions No description.
githubOrgNameRequired 
public readonly githubOrgName: string;
  • Type: string
nameRequired 
public readonly name: string;
  • Type: string
versionRequired 
public readonly version: string;
  • Type: string
nameOverrideOptional 
public readonly nameOverride: string;
  • Type: string
submoduleOptional 
public readonly submodule: TerraformSubmoduleOptions;

TerraformSubmoduleOptions

Initializer 

import { TerraformSubmoduleOptions } from '@rlmartin-projen/cdktf-project'

const terraformSubmoduleOptions: TerraformSubmoduleOptions = { ... }

Properties

Name Type Description
name string No description.
rootPath string The directory where the module can be found.
nameRequired 
public readonly name: string;
  • Type: string
rootPathOptional 
public readonly rootPath: string;
  • Type: string
  • Default: modules

The directory where the module can be found.

Should not include 'name'.

WorkflowInputOptions

Initializer 

import { WorkflowInputOptions } from '@rlmartin-projen/cdktf-project'

const workflowInputOptions: WorkflowInputOptions = { ... }

Properties

Name Type Description
default string No description.
description string No description.
options string[] No description.
required boolean No description.
type string No description.
defaultOptional 
public readonly default: string;
  • Type: string
descriptionOptional 
public readonly description: string;
  • Type: string
optionsOptional 
public readonly options: string[];
  • Type: string[]
requiredOptional 
public readonly required: boolean;
  • Type: boolean
typeOptional 
public readonly type: string;
  • Type: string

WorkflowSteps

Initializer 

import { WorkflowSteps } from '@rlmartin-projen/cdktf-project'

const workflowSteps: WorkflowSteps = { ... }

Properties

Name Type Description
postBuild projen.github.workflows.JobStep[] No description.
postDeploy projen.github.workflows.JobStep[] No description.
preBuild projen.github.workflows.JobStep[] No description.
preDeploy projen.github.workflows.JobStep[] No description.
postBuildOptional 
public readonly postBuild: JobStep[];
  • Type: projen.github.workflows.JobStep[]
postDeployOptional 
public readonly postDeploy: JobStep[];
  • Type: projen.github.workflows.JobStep[]
preBuildOptional 
public readonly preBuild: JobStep[];
  • Type: projen.github.workflows.JobStep[]
preDeployOptional 
public readonly preDeploy: JobStep[];
  • Type: projen.github.workflows.JobStep[]