projen
- Version 0.91.26
- Published
- 12.9 MB
- 14 dependencies
- Apache-2.0 license
Install
npm i projen
yarn add projen
pnpm add projen
Overview
CDK for software projects
Index
Variables
Functions
Classes
Project
- addExcludeFromCleanup()
- addGitIgnore()
- addPackageIgnore()
- addTask()
- addTip()
- annotateGenerated()
- buildTask
- commitGenerated
- compileTask
- components
- DEFAULT_TASK
- defaultTask
- deps
- ejected
- files
- gitattributes
- gitignore
- initProject
- isProject()
- logger
- name
- of()
- outdir
- packageTask
- parent
- postCompileTask
- postSynthesize()
- preCompileTask
- preSynthesize()
- projectBuild
- projenCommand
- removeTask()
- root
- runTaskCommand()
- subprojects
- synth()
- tasks
- testTask
- tryFindFile()
- tryFindJsonFile()
- tryFindObjectFile()
- tryRemoveFile()
Interfaces
Enums
Namespaces
awscdk
- ApprovalLevel
- AutoDiscover
- AutoDiscoverCommonOptions
- AutoDiscoverOptions
- AwsCdkConstructLibrary
- AwsCdkConstructLibraryOptions
- AwsCdkDeps
- AwsCdkDepsCommonOptions
- AwsCdkDepsJava
- AwsCdkDepsJs
- AwsCdkDepsOptions
- AwsCdkDepsPy
- AwsCdkJavaApp
- AwsCdkJavaAppOptions
- AwsCdkPackageNames
- AwsCdkPythonApp
- AwsCdkPythonAppOptions
- AwsCdkTypeScriptApp
- AwsCdkTypeScriptAppOptions
- CdkConfig
- CdkConfigCommonOptions
- CdkConfigOptions
- CdkTasks
- ConstructLibraryAws
- ConstructLibraryAwsOptions
- EdgeLambdaAutoDiscover
- EdgeLambdaAutoDiscoverOptions
- IntegrationTest
- IntegrationTestAutoDiscover
- IntegrationTestAutoDiscoverOptions
- IntegrationTestCommonOptions
- IntegrationTestOptions
- LambdaAutoDiscover
- LambdaAutoDiscoverOptions
- LambdaExtension
- LambdaExtensionAutoDiscover
- LambdaExtensionAutoDiscoverOptions
- LambdaExtensionCommonOptions
- LambdaExtensionOptions
- LambdaFunction
- LambdaFunctionCommonOptions
- LambdaFunctionOptions
- LambdaRuntime
- LambdaRuntimeOptions
cdk
- AutoDiscoverBase
- AutoDiscoverBaseOptions
- Catalog
- ConstructLibrary
- ConstructLibraryOptions
- IntegrationTestAutoDiscoverBase
- IntegrationTestAutoDiscoverBaseOptions
- IntegrationTestBase
- IntegrationTestBaseOptions
- JsiiDocgen
- JsiiDocgenOptions
- JsiiDotNetTarget
- JsiiGoTarget
- JsiiJavaTarget
- JsiiProject
- JsiiProjectOptions
- JsiiPythonTarget
- Stability
cdk8s
- AutoDiscover
- AutoDiscoverOptions
- Cdk8sDeps
- Cdk8sDepsCommonOptions
- Cdk8sDepsOptions
- Cdk8sDepsPy
- Cdk8sPackageNames
- Cdk8sPythonApp
- Cdk8sPythonOptions
- Cdk8sTypeScriptApp
- Cdk8sTypeScriptAppOptions
- ConstructLibraryCdk8s
- ConstructLibraryCdk8sOptions
- IntegrationTest
- IntegrationTestAutoDiscover
- IntegrationTestAutoDiscoverOptions
- IntegrationTestOptions
github
- AutoApprove
- AutoApproveOptions
- AutoMerge
- AutoMergeOptions
- AutoQueue
- AutoQueueOptions
- CheckoutOptions
- CheckoutWith
- CheckoutWithPatchOptions
- ConcurrencyOptions
- ContributorStatementOptions
- CreatePullRequestOptions
- Dependabot
- DependabotAllow
- DependabotGroup
- DependabotIgnore
- DependabotOptions
- DependabotRegistry
- DependabotRegistryType
- DependabotScheduleInterval
- DownloadArtifactOptions
- DownloadArtifactWith
- GitHub
- GitHubActionsProvider
- GithubCredentials
- GithubCredentialsAppOptions
- GithubCredentialsPersonalAccessTokenOptions
- GitHubOptions
- GitHubProject
- GitHubProjectOptions
- GithubWorkflow
- GithubWorkflowOptions
- GitIdentity
- IAddConditionsLater
- MergeMethod
- MergeQueue
- MergeQueueOptions
- Mergify
- MergifyCondition
- MergifyConditionalOperator
- MergifyOptions
- MergifyQueue
- MergifyRule
- PullRequestBackport
- PullRequestBackportOptions
- PullRequestFromPatchOptions
- PullRequestLint
- PullRequestLintOptions
- PullRequestPatchSource
- PullRequestTemplate
- PullRequestTemplateOptions
- SemanticTitleOptions
- SetupGitIdentityOptions
- Stale
- StaleBehavior
- StaleOptions
- TaskWorkflow
- TaskWorkflowJob
- TaskWorkflowJobOptions
- TaskWorkflowOptions
- UploadArtifactOptions
- UploadArtifactWith
- UploadGitPatchOptions
- VersioningStrategy
- WorkflowActions
- WorkflowJobs
- WorkflowSteps
workflows
- AppPermission
- AppPermissions
- BranchProtectionRuleOptions
- CheckRunOptions
- CheckSuiteOptions
- CommonJobDefinition
- ContainerCredentials
- ContainerOptions
- CreateOptions
- CronScheduleOptions
- DeleteOptions
- DeploymentOptions
- DeploymentStatusOptions
- DiscussionCommentOptions
- DiscussionOptions
- ForkOptions
- GollumOptions
- IssueCommentOptions
- IssuesOptions
- Job
- JobCallingReusableWorkflow
- JobDefaults
- JobMatrix
- JobPermission
- JobPermissions
- JobStep
- JobStepConfiguration
- JobStepOutput
- JobStrategy
- LabelOptions
- MergeGroupOptions
- MilestoneOptions
- PageBuildOptions
- ProjectCardOptions
- ProjectColumnOptions
- ProjectOptions
- PublicOptions
- PullRequestOptions
- PullRequestReviewCommentOptions
- PullRequestReviewOptions
- PullRequestTargetOptions
- PushOptions
- RegistryPackageOptions
- ReleaseOptions
- RepositoryDispatchOptions
- RunSettings
- StatusOptions
- Step
- StepConfiguration
- ToolRequirement
- Tools
- Triggers
- WatchOptions
- WorkflowCallOptions
- WorkflowDispatchOptions
- WorkflowRunOptions
gitlab
- Action
- AllowFailure
- Artifacts
- Assets
- Cache
- CacheKeyFiles
- CachePolicy
- CacheWhen
- CiConfiguration
- CiConfigurationOptions
- CoverageReport
- Default
- DefaultElement
- DeploymentTier
- Engine
- Environment
- Filter
- GitlabConfiguration
- IDToken
- Image
- Include
- IncludeRule
- Inherit
- Job
- JobWhen
- KubernetesConfig
- KubernetesEnum
- Link
- LinkType
- Need
- NestedConfiguration
- Parallel
- PullPolicy
- Release
- Reports
- Retry
- Secret
- Service
- Strategy
- Trigger
- TriggerInclude
- VariableConfig
- VaultConfig
- Workflow
- WorkflowRule
- WorkflowWhen
java
- ChecksumPolicy
- generateJavaOptionNames()
- getJavaImport()
- JavaProject
- JavaProjectCommonOptions
- JavaProjectOptions
- Junit
- JunitOptions
- MavenCompile
- MavenCompileOptions
- MavenPackaging
- MavenPackagingOptions
- MavenRepository
- MavenRepositoryPolicy
- MavenSample
- MavenSampleOptions
- ParentPom
- PluginExecution
- PluginOptions
- Pom
- PomOptions
- Projenrc
- ProjenrcOptions
- UpdatePolicy
javascript
- AddBundleOptions
- ArrowParens
- AutoRelease
- BuildWorkflowOptions
- Bundle
- BundleLogLevel
- Bundler
- BundlerOptions
- BundlingOptions
- Charset
- CodeArtifactAuthProvider
- CodeArtifactOptions
- CoverageThreshold
- defaultNpmToken()
- EmbeddedLanguageFormatting
- EndOfLine
- Eslint
- EslintCommandOptions
- EslintOptions
- EslintOverride
- Files
- HasteConfig
- HTMLWhitespaceSensitivity
- Jest
- JestConfigOptions
- JestDiscoverTestMatchPatternsForDirsOptions
- JestOptions
- JestReporter
- LicenseChecker
- LicenseCheckerOptions
- NodePackage
- NodePackageManager
- NodePackageOptions
- NodeProject
- NodeProjectOptions
- NpmAccess
- NpmConfig
- NpmConfigOptions
- PeerDependencyOptions
- Prettier
- PrettierOptions
- PrettierOverride
- PrettierSettings
- Projenrc
- ProjenrcOptions
- ProseWrap
- QuoteProps
- RenderWorkflowSetupOptions
- RunBundleTask
- ScopedPackagesOptions
- SourceMapMode
- TrailingComma
- Transform
- TypeScriptCompilerOptions
- TypescriptConfig
- TypescriptConfigExtends
- TypescriptConfigOptions
- TypeScriptImportsNotUsedAsValues
- TypeScriptJsxMode
- TypeScriptModuleDetection
- TypeScriptModuleResolution
- UpdateSnapshot
- UpgradeDependencies
- UpgradeDependenciesOptions
- UpgradeDependenciesSchedule
- UpgradeDependenciesWorkflowOptions
- WatchPlugin
- YarnBerryOptions
- YarnCacheMigrationMode
- YarnChecksumBehavior
- YarnDefaultSemverRangePrefix
- YarnLogFilter
- YarnLogFilterLevel
- YarnNetworkSetting
- YarnNmHoistingLimit
- YarnNmMode
- YarnNodeLinker
- YarnNpmPublishAccess
- YarnNpmRegistry
- YarnNpmScope
- YarnPackageExtension
- YarnPeerDependencyMeta
- YarnPnpFallbackMode
- YarnPnpMode
- YarnProgressBarStyle
- Yarnrc
- YarnrcOptions
- YarnSupportedArchitectures
- YarnWinLinkType
- YarnWorkerPoolMode
python
- IPackageProvider
- IPythonDeps
- IPythonEnv
- IPythonPackaging
- Pip
- PipOptions
- Poetry
- PoetryOptions
- PoetryPyproject
- PoetryPyprojectOptions
- PoetryPyprojectOptionsWithoutDeps
- Projenrc
- ProjenrcOptions
- Pytest
- PytestOptions
- PytestSample
- PytestSampleOptions
- PythonExecutableOptions
- PythonPackagingOptions
- PythonProject
- PythonProjectOptions
- PythonSample
- PythonSampleOptions
- RequirementsFile
- RequirementsFileOptions
- resolvePythonImportName()
- SetupPy
- SetupPyOptions
- Setuptools
- SetuptoolsOptions
- Venv
- VenvOptions
release
- BranchOptions
- CodeArtifactAuthProvider
- CodeArtifactOptions
- CommonPublishOptions
- ContinuousReleaseOptions
- GitHubReleasesPublishOptions
- GitPublishOptions
- GoPublishOptions
- isAwsCodeArtifactRegistry()
- JsiiReleaseGo
- JsiiReleaseMaven
- JsiiReleaseNpm
- JsiiReleaseNuget
- JsiiReleasePyPi
- ManualReleaseOptions
- MavenPublishOptions
- NpmPublishOptions
- NugetPublishOptions
- Publisher
- PublisherOptions
- PyPiPublishOptions
- Release
- ReleaseOptions
- ReleaseProjectOptions
- ReleaseTrigger
- ScheduledReleaseOptions
vscode
- Console
- DevContainer
- DevContainerFeature
- DevContainerOptions
- IDevContainerEnvironment
- InternalConsoleOptions
- Presentation
- ServerReadyAction
- VsCode
- VsCodeLaunchCommandInputEntry
- VsCodeLaunchConfig
- VsCodeLaunchConfigurationEntry
- VsCodeLaunchInputEntry
- VsCodeLaunchPickStringInputEntry
- VsCodeLaunchPromptStringInputEntry
- VsCodeRecommendedExtensions
- VsCodeSettings
web
- NextComponent
- NextComponentOptions
- NextJsCommonProjectOptions
- NextJsProject
- NextJsProjectOptions
- NextJsTypeScriptProject
- NextJsTypeScriptProjectOptions
- PostCss
- PostCssOptions
- ReactComponent
- ReactComponentOptions
- ReactProject
- ReactProjectOptions
- ReactRewireOptions
- ReactTypeDef
- ReactTypeDefOptions
- ReactTypeScriptProject
- ReactTypeScriptProjectOptions
- TailwindConfig
- TailwindConfigOptions
Variables
variable CHANGES_SINCE_LAST_RELEASE
const CHANGES_SINCE_LAST_RELEASE: string;
This command determines if there were any changes since the last release in a cross-platform compatible way. It is used as a condition for both the
bump
and therelease
tasks.Explanation: - log commits | git log - limit log output to a single line per commit | --oneline - looks only at the most recent commit | -1 - silent grep output | grep -q - exits with code 0 if a match is found | grep -q "chore(release):" - exits with code 1 if a match is found (reverse-match) | grep -qv "chore(release):"
Functions
function filteredRunsOnOptions
filteredRunsOnOptions: ( runsOn?: string[], runsOnGroup?: GroupRunnerOptions) => { runsOnGroup: GroupRunnerOptions } | { runsOn: string[] };
function filteredWorkflowRunsOnOptions
filteredWorkflowRunsOnOptions: ( workflowRunsOn?: string[], workflowRunsOnGroup?: GroupRunnerOptions) => | { workflowRunsOnGroup: GroupRunnerOptions } | { workflowRunsOn: string[] } | string[];
Classes
class Component
class Component extends Construct {}
Represents a project component.
Parameter project
Parameter id
Unique id of the component. If not provided, an unstable AutoId is generated.
constructor
constructor(scope: IConstruct, id?: string);
property project
readonly project: Project;
method isComponent
static isComponent: (x: any) => x is Component;
Test whether the given construct is a component.
method postSynthesize
postSynthesize: () => void;
Called after synthesis. Order is *not* guaranteed.
method preSynthesize
preSynthesize: () => void;
Called before synthesis.
method synthesize
synthesize: () => void;
Synthesizes files to the project output directory.
class Dependencies
class Dependencies extends Component {}
The
Dependencies
component is responsible to track the list of dependencies a project has, and then used by project types as the model for rendering project-specific dependency manifests such as the dependencies sectionpackage.json
files.To add a dependency you can use a project-type specific API such as
nodeProject.addDeps()
or use the generic API ofproject.deps
:
constructor
constructor(project: Project);
Adds a dependencies component to the project.
Parameter project
The parent project
property all
readonly all: Dependency[];
A copy of all dependencies recorded for this project.
The list is sorted by type->name->version
property MANIFEST_FILE
static readonly MANIFEST_FILE: string;
The project-relative path of the deps manifest file.
method addDependency
addDependency: ( spec: string, type: DependencyType, metadata?: { [key: string]: any }) => Dependency;
Adds a dependency to this project.
Parameter spec
The dependency spec in the format
MODULE[@VERSION]
whereMODULE
is the package-manager-specific module name andVERSION
is an optional semantic version requirement (e.g.^3.4.0
).Parameter type
The type of the dependency.
method getDependency
getDependency: (name: string, type?: DependencyType) => Dependency;
Returns a dependency by name.
Fails if there is no dependency defined by that name or if
type
is not provided and there is more then one dependency type for this dependency.Parameter name
The name of the dependency
Parameter type
The dependency type. If this dependency is defined only for a single type, this argument can be omitted.
Returns
a copy (cannot be modified)
method isDependencySatisfied
isDependencySatisfied: ( name: string, type: DependencyType, expectedRange: string) => boolean;
Checks if an existing dependency satisfies a dependency requirement.
Parameter name
The name of the dependency to check (without the version).
Parameter type
The dependency type.
Parameter expectedRange
The version constraint to check (e.g.
^3.4.0
). The constraint of the dependency must be a subset of the expected range to satisfy the requirements.Returns
true
if the dependency exists and its version satisfies the provided constraint.false
otherwise. Notably returnsfalse
if a dependency exists, but has no version.
method parseDependency
static parseDependency: (spec: string) => DependencyCoordinates;
Returns the coordinates of a dependency spec.
Given
foo@^3.4.0
returns{ name: "foo", version: "^3.4.0" }
. Givenbar@npm:@bar/legacy
returns{ name: "bar", version: "npm:@bar/legacy" }
.
method removeDependency
removeDependency: (name: string, type?: DependencyType) => void;
Removes a dependency.
Parameter name
The name of the module to remove (without the version)
Parameter type
The dependency type. This is only required if there the dependency is defined for multiple types.
method tryGetDependency
tryGetDependency: ( name: string, type?: DependencyType) => Dependency | undefined;
Returns a dependency by name.
Returns
undefined
if there is no dependency defined by that name or iftype
is not provided and there is more then one dependency type for this dependency.Parameter name
The name of the dependency
Parameter type
The dependency type. If this dependency is defined only for a single type, this argument can be omitted.
Returns
a copy (cannot be modified) or undefined if there is no match
class DevEnvironmentDockerImage
class DevEnvironmentDockerImage {}
Options for specifying the Docker image of the container.
property dockerFile
readonly dockerFile?: string;
The relative path of a Dockerfile that defines the container contents.
property image
readonly image?: string;
A publicly available Docker image.
method fromFile
static fromFile: (dockerFile: string) => DevEnvironmentDockerImage;
The relative path of a Dockerfile that defines the container contents.
Parameter dockerFile
a relative path
Example 1
'.gitpod.Docker'
method fromImage
static fromImage: (image: string) => DevEnvironmentDockerImage;
A publicly available Docker image.
Parameter image
a Docker image
Example 1
'ubuntu:latest'
class DockerCompose
class DockerCompose extends Component {}
Create a docker-compose YAML file.
constructor
constructor(project: Project, props?: DockerComposeProps);
property file
readonly file: YamlFile;
The Docker Compose file
method addService
addService: ( serviceName: string, description: DockerComposeServiceDescription) => DockerComposeService;
Add a service to the docker-compose file.
Parameter serviceName
name of the service
Parameter description
a service description
method bindVolume
static bindVolume: ( sourcePath: string, targetPath: string) => IDockerComposeVolumeBinding;
Create a bind volume that binds a host path to the target path in the container.
Parameter sourcePath
Host path name
Parameter targetPath
Target path name
method namedVolume
static namedVolume: ( volumeName: string, targetPath: string, options?: DockerComposeVolumeConfig) => IDockerComposeVolumeBinding;
Create a named volume and mount it to the target path. If you use this named volume in several services, the volume will be shared. In this case, the volume configuration of the first-provided options are used.
Parameter volumeName
Name of the volume
Parameter targetPath
Target path
Parameter options
volume configuration (default: docker compose defaults)
method network
static network: ( networkName: string, options?: DockerComposeNetworkConfig) => IDockerComposeNetworkBinding;
Create a named network and mount it to the target path. If you use this named network in several services, the network will be shared. In this case, the network configuration of the first-provided options are used.
Parameter networkName
Name of the network
Parameter options
network configuration
method portMapping
static portMapping: ( publishedPort: number, targetPort: number, options?: DockerComposePortMappingOptions) => DockerComposeServicePort;
Create a port mapping.
Parameter publishedPort
Published port number
Parameter targetPort
Container's port number
Parameter options
Port mapping options
method serviceName
static serviceName: (serviceName: string) => IDockerComposeServiceName;
Depends on a service name.
class DockerComposeService
class DockerComposeService implements IDockerComposeServiceName {}
A docker-compose service.
constructor
constructor( serviceName: string, serviceDescription: DockerComposeServiceDescription);
property command
readonly command?: string[];
Command to run in the container.
property dependsOn
readonly dependsOn: IDockerComposeServiceName[];
Other services that this service depends on.
property entrypoint
readonly entrypoint?: string[];
Entrypoint to run in the container.
property environment
readonly environment: Record<string, string>;
Environment variables.
property image
readonly image?: string;
Docker image.
property imageBuild
readonly imageBuild?: DockerComposeBuild;
Docker image build instructions.
property labels
readonly labels: Record<string, string>;
Attached labels.
property networks
readonly networks: IDockerComposeNetworkBinding[];
Networks mounted in the container.
property platform
readonly platform?: string;
Target platform
property ports
readonly ports: DockerComposeServicePort[];
Published ports.
property privileged
readonly privileged?: boolean;
Run in privileged mode
property serviceName
readonly serviceName: string;
Name of the service.
property volumes
readonly volumes: IDockerComposeVolumeBinding[];
Volumes mounted in the container.
method addDependsOn
addDependsOn: (serviceName: IDockerComposeServiceName) => void;
Make the service depend on another service.
Parameter serviceName
method addEnvironment
addEnvironment: (name: string, value: string) => void;
Add an environment variable
Parameter name
environment variable name
Parameter value
value of the environment variable
method addLabel
addLabel: (name: string, value: string) => void;
Add a label
Parameter name
environment variable name
Parameter value
value of the environment variable
method addNetwork
addNetwork: (network: IDockerComposeNetworkBinding) => void;
Add a network to the service.
Parameter network
method addPort
addPort: ( publishedPort: number, targetPort: number, options?: DockerComposePortMappingOptions) => void;
Add a port mapping
Parameter publishedPort
Published port number
Parameter targetPort
Container's port number
Parameter options
Port mapping options
method addVolume
addVolume: (volume: IDockerComposeVolumeBinding) => void;
Add a volume to the service.
Parameter volume
class FileBase
abstract class FileBase extends Component {}
constructor
constructor(scope: IConstruct, filePath: string, options?: FileBaseOptions);
property absolutePath
readonly absolutePath: string;
The absolute path of this file.
property changed
readonly changed: boolean;
Indicates if the file has been changed during synthesis. This property is only available in
postSynthesize()
hooks. If this isundefined
, the file has not been synthesized yet.
property executable
executable: boolean;
Indicates if the file should be marked as executable
property marker
readonly marker: string;
The projen marker, used to identify files as projen-generated.
Value is undefined if the project is being ejected.
property path
readonly path: string;
The file path, relative to the project's outdir.
property readonly
readonly: boolean;
Indicates if the file should be read-only or read-write.
method synthesize
synthesize: () => void;
Writes the file to the project's output directory
method synthesizeContent
protected abstract synthesizeContent: ( resolver: IResolver) => string | undefined;
Implemented by derived classes and returns the contents of the file to emit.
Parameter resolver
Call
resolver.resolve(obj)
on any objects in order to resolve token functions.Returns
the content to synthesize or undefined to skip the file
class GitAttributesFile
class GitAttributesFile extends FileBase {}
Assign attributes to file names in a git repository.
See Also
https://git-scm.com/docs/gitattributes
constructor
constructor(scope: IConstruct, options?: GitAttributesFileOptions);
property endOfLine
readonly endOfLine: EndOfLine;
The default end of line character for text files.
property hasLfsPatterns
readonly hasLfsPatterns: boolean;
Whether the current gitattributes file has any LFS patterns
method addAttributes
addAttributes: (glob: string, ...attributes: string[]) => void;
Maps a set of attributes to a set of files.
Parameter glob
Glob pattern to match files in the repo
Parameter attributes
Attributes to assign to these files.
method addLfsPattern
addLfsPattern: (glob: string) => void;
Add attributes necessary to mark these files as stored in LFS
method preSynthesize
preSynthesize: () => void;
method synthesizeContent
protected synthesizeContent: (_: IResolver) => string | undefined;
class Gitpod
class Gitpod extends Component implements IDevEnvironment {}
The Gitpod component which emits .gitpod.yml
constructor
constructor(project: Project, options?: GitpodOptions);
property config
readonly config: any;
Direct access to the gitpod configuration (escape hatch)
method addCustomTask
addCustomTask: (options: GitpodTask) => void;
Add a task with more granular options.
By default, all tasks will be run in parallel. To run tasks in sequence, create a new
Task
and set the other tasks as subtasks.Parameter options
The task parameters
method addDockerImage
addDockerImage: (image: DevEnvironmentDockerImage) => void;
Add a custom Docker image or Dockerfile for the container.
Parameter image
The Docker image
method addPorts
addPorts: (...ports: string[]) => void;
Add ports that should be exposed (forwarded) from the container.
Parameter ports
The new ports
method addPrebuilds
addPrebuilds: (config: GitpodPrebuilds) => void;
Add a prebuilds configuration for the Gitpod App
Parameter config
The configuration
method addTasks
addTasks: (...tasks: Task[]) => void;
Add tasks to run when gitpod starts.
By default, all tasks will be run in parallel. To run tasks in sequence, create a new
Task
and specify the other tasks as subtasks.Parameter tasks
The new tasks
method addVscodeExtensions
addVscodeExtensions: (...extensions: GitpodCodeExtensionId[]) => void;
Add a list of VSCode extensions that should be automatically installed in the container.
These must be in the format defined in the Open VSX registry.
Parameter extensions
The extension IDs
Example 1
'scala-lang.scala@0.3.9:O5XmjwY5Gz+0oDZAmqneJw=='
See Also
https://www.gitpod.io/docs/vscode-extensions/
class IgnoreFile
class IgnoreFile extends FileBase {}
constructor
constructor(project: Project, filePath: string, options?: IgnoreFileOptions);
Parameter project
The project to tie this file to.
Parameter filePath
the relative path in the project to put the file
Parameter minify
whether comments/blank lines should be filtered
property filterCommentLines
readonly filterCommentLines: boolean;
property filterEmptyLines
readonly filterEmptyLines: boolean;
method addPatterns
addPatterns: (...patterns: string[]) => void;
Add ignore patterns. Files that match this pattern will be ignored. If the pattern starts with a negation mark
!
, files that match will _not_ be ignored.Comment lines (start with
#
) and blank lines ("") are filtered by default but can be included using options specified when instantiating the component.Parameter patterns
Ignore patterns.
method exclude
exclude: (...patterns: string[]) => void;
Ignore the files that match these patterns.
Parameter patterns
The patterns to match.
method include
include: (...patterns: string[]) => void;
Always include the specified file patterns.
Parameter patterns
Patterns to include in git commits.
method removePatterns
removePatterns: (...patterns: string[]) => void;
Removes patterns previously added from the ignore file.
If
addPattern()
is called after this, the pattern will be added again.Parameter patterns
patters to remove.
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class IniFile
class IniFile extends ObjectFile {}
Represents an INI file.
constructor
constructor(project: Project, filePath: string, options: IniFileOptions);
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class JsonFile
class JsonFile extends ObjectFile {}
Represents a JSON file.
constructor
constructor(scope: IConstruct, filePath: string, options: JsonFileOptions);
property supportsComments
readonly supportsComments: boolean;
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class JsonPatch
class JsonPatch {}
Utility for applying RFC-6902 JSON-Patch to a document.
Use the the
JsonPatch.apply(doc, ...ops)
function to apply a set of operations to a JSON document and return the result.Operations can be created using the factory methods
JsonPatch.add()
,JsonPatch.remove()
, etc.Example 1
const output = JsonPatch.apply(input, JsonPatch.replace('/world/hi/there', 'goodbye'), JsonPatch.add('/world/foo/', 'boom'), JsonPatch.remove('/hello'));
method add
static add: (path: string, value: any) => JsonPatch;
Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.
Example 1
JsonPatch.add('/biscuits/1', { "name": "Ginger Nut" })
method apply
static apply: (document: any, ...ops: JsonPatch[]) => any;
Applies a set of JSON-Patch (RFC-6902) operations to
document
and returns the result.Parameter document
The document to patch
Parameter ops
The operations to apply
Returns
The result document
method copy
static copy: (from: string, path: string) => JsonPatch;
Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers.
Example 1
JsonPatch.copy('/biscuits/0', '/best_biscuit')
method escapePath
static escapePath: (path: string) => string;
Escapes a json pointer path
Parameter path
The raw pointer the Escaped path
method move
static move: (from: string, path: string) => JsonPatch;
Moves a value from one location to the other. Both from and path are JSON Pointers.
Example 1
JsonPatch.move('/biscuits', '/cookies')
method remove
static remove: (path: string) => JsonPatch;
Removes a value from an object or array.
Example 1
JsonPatch.remove('/biscuits')
Example 2
JsonPatch.remove('/biscuits/0')
method replace
static replace: (path: string, value: any) => JsonPatch;
Replaces a value. Equivalent to a “remove” followed by an “add”.
Example 1
JsonPatch.replace('/biscuits/0/name', 'Chocolate Digestive')
method test
static test: ( path: string, value: any, failureBehavior?: TestFailureBehavior) => JsonPatch;
Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.
Example 1
JsonPatch.test('/best_biscuit/name', 'Choco Leibniz')
class License
class License extends FileBase {}
constructor
constructor(project: Project, options: LicenseOptions);
method synthesizeContent
protected synthesizeContent: (_: IResolver) => string | undefined;
class Logger
class Logger extends Component {}
Project-level logging utilities.
constructor
constructor(scope: IConstruct, options?: LoggerOptions);
method debug
debug: (...text: any[]) => void;
Log a message to stderr with DEBUG severity
Parameter text
strings or objects to print
method error
error: (...text: any[]) => void;
Log a message to stderr with ERROR severity
Parameter text
strings or objects to print
method info
info: (...text: any[]) => void;
Log a message to stderr with INFO severity
Parameter text
strings or objects to print
method log
log: (level: LogLevel, ...text: any[]) => void;
Log a message to stderr with a given logging level. The message will be printed as long as
logger.level
is set to the message's severity or higher.Parameter level
Logging verbosity
Parameter text
strings or objects to print
method verbose
verbose: (...text: any[]) => void;
Log a message to stderr with VERBOSE severity
Parameter text
strings or objects to print
method warn
warn: (...text: any[]) => void;
Log a message to stderr with WARN severity
Parameter text
strings or objects to print
class Makefile
class Makefile extends FileBase {}
Minimal Makefile.
constructor
constructor(project: Project, filePath: string, options?: MakefileOptions);
property rules
readonly rules: Rule[];
List of rule definitions.
method addAll
addAll: (target: string) => Makefile;
Add a target to all
method addAlls
addAlls: (...targets: string[]) => Makefile;
Add multiple targets to all
method addRule
addRule: (rule: Rule) => Makefile;
Add a rule to the Makefile.
method addRules
addRules: (...rules: Rule[]) => Makefile;
Add multiple rules to the Makefile.
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class ObjectFile
abstract class ObjectFile extends FileBase {}
Represents an Object file.
constructor
constructor(scope: IConstruct, filePath: string, options: ObjectFileOptions);
property omitEmpty
readonly omitEmpty: boolean;
Indicates if empty objects and arrays are omitted from the output object.
method addDeletionOverride
addDeletionOverride: (path: string) => void;
Syntactic sugar for
addOverride(path, undefined)
.Parameter path
The path of the value to delete
method addOverride
addOverride: (path: string, value: any) => void;
Adds an override to the synthesized object file.
If the override is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.
To include a literal
.
in the property name, prefix with a\
. In most programming languages you will need to write this as"\\."
because the\
itself will need to be escaped.For example,
project.tsconfig.file.addOverride('compilerOptions.alwaysStrict', true);project.tsconfig.file.addOverride('compilerOptions.lib', ['dom', 'dom.iterable', 'esnext']);would add the overrides
"compilerOptions": {"alwaysStrict": true,"lib": ["dom","dom.iterable","esnext"]...}...Parameter path
The path of the property, you can use dot notation to override values in complex types. Any intermediate keys will be created as needed.
Parameter value
The value. Could be primitive or complex.
method addToArray
addToArray: (path: string, ...values: any) => void;
Adds to an array in the synthesized object file.
If the array is nested, separate each nested level using a dot (.) in the path parameter. If there is an array as part of the nesting, specify the index in the path.
To include a literal
.
in the property name, prefix with a\
. In most programming languages you will need to write this as"\\."
because the\
itself will need to be escaped.For example, with the following object file
"compilerOptions": {"exclude": ["node_modules"],"lib": ["es2020"]...}...project.tsconfig.file.addToArray('compilerOptions.exclude', 'coverage');project.tsconfig.file.addToArray('compilerOptions.lib', 'dom', 'dom.iterable', 'esnext');would result in the following object file
"compilerOptions": {"exclude": ["node_modules", "coverage"],"lib": ["es2020", "dom", "dom.iterable", "esnext"]...}...Parameter path
The path of the property, you can use dot notation to att to arrays in complex types. Any intermediate keys will be created as needed.
Parameter values
The values to add. Could be primitive or complex.
method patch
patch: (...patches: JsonPatch[]) => void;
Applies an RFC 6902 JSON-patch to the synthesized object file. See https://datatracker.ietf.org/doc/html/rfc6902 for more information.
For example, with the following object file
"compilerOptions": {"exclude": ["node_modules"],"lib": ["es2020"]...}...project.tsconfig.file.patch(JsonPatch.add("/compilerOptions/exclude/-", "coverage"));project.tsconfig.file.patch(JsonPatch.replace("/compilerOptions/lib", ["dom", "dom.iterable", "esnext"]));would result in the following object file
"compilerOptions": {"exclude": ["node_modules", "coverage"],"lib": ["dom", "dom.iterable", "esnext"]...}...Parameter patches
The patch operations to apply
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class Project
class Project extends Construct {}
Base project
constructor
constructor(options: ProjectOptions);
property buildTask
readonly buildTask: Task;
property commitGenerated
readonly commitGenerated: boolean;
Whether to commit the managed files by default.
property compileTask
readonly compileTask: Task;
property components
readonly components: Component[];
Returns all the components within this project.
property DEFAULT_TASK
static readonly DEFAULT_TASK: string;
The name of the default task (the task executed when
projen
is run without arguments). Normally this task should synthesize the project files.
property defaultTask
readonly defaultTask?: Task;
This is the "default" task, the one that executes "projen". Undefined if the project is being ejected.
property deps
readonly deps: Dependencies;
Project dependencies.
property ejected
readonly ejected: boolean;
Whether or not the project is being ejected.
property files
readonly files: FileBase[];
All files in this project.
property gitattributes
readonly gitattributes: GitAttributesFile;
The .gitattributes file for this repository.
property gitignore
readonly gitignore: IgnoreFile;
.gitignore
property initProject
readonly initProject?: InitProject;
The options used when this project is bootstrapped via
projen new
. It includes the original set of options passed to the CLI and also the JSII FQN of the project type.
property logger
readonly logger: Logger;
Logging utilities.
property name
readonly name: string;
Project name.
property outdir
readonly outdir: string;
Absolute output directory of this project.
property packageTask
readonly packageTask: Task;
property parent
readonly parent?: Project;
A parent project. If undefined, this is the root project.
property postCompileTask
readonly postCompileTask: Task;
property preCompileTask
readonly preCompileTask: Task;
property projectBuild
readonly projectBuild: ProjectBuild;
Manages the build process of the project.
property projenCommand
readonly projenCommand: string;
The command to use in order to run the projen CLI.
property root
readonly root: Project;
The root project.
property subprojects
readonly subprojects: Project[];
Returns all the subprojects within this project.
property tasks
readonly tasks: Tasks;
Project tasks.
property testTask
readonly testTask: Task;
method addExcludeFromCleanup
addExcludeFromCleanup: (...globs: string[]) => void;
Exclude the matching files from pre-synth cleanup. Can be used when, for example, some source files include the projen marker and we don't want them to be erased during synth.
Parameter globs
The glob patterns to match
method addGitIgnore
addGitIgnore: (pattern: string) => void;
Adds a .gitignore pattern.
Parameter pattern
The glob pattern to ignore.
method addPackageIgnore
addPackageIgnore: (_pattern: string) => void;
Exclude these files from the bundled package. Implemented by project types based on the packaging mechanism. For example,
NodeProject
delegates this to.npmignore
.Parameter _pattern
The glob pattern to exclude
method addTask
addTask: (name: string, props?: TaskOptions) => Task;
Adds a new task to this project. This will fail if the project already has a task with this name.
Parameter name
The task name to add
Parameter props
Task properties
method addTip
addTip: (message: string) => void;
Prints a "tip" message during synthesis.
Parameter message
The message
Deprecated
- use
project.logger.info(message)
to show messages during synthesis
method annotateGenerated
annotateGenerated: (_glob: string) => void;
Consider a set of files as "generated". This method is implemented by derived classes and used for example, to add git attributes to tell GitHub that certain files are generated.
Parameter _glob
the glob pattern to match (could be a file path).
method isProject
static isProject: (x: any) => x is Project;
Test whether the given construct is a project.
method of
static of: (construct: IConstruct) => Project;
Find the closest ancestor project for given construct. When given a project, this it the project itself.
Throws
when no project is found in the path to the root
method postSynthesize
postSynthesize: () => void;
Called after all components are synthesized. Order is *not* guaranteed.
method preSynthesize
preSynthesize: () => void;
Called before all components are synthesized.
method removeTask
removeTask: (name: string) => Task | undefined;
Removes a task from a project.
Parameter name
The name of the task to remove.
Returns
The
Task
that was removed, otherwiseundefined
.
method runTaskCommand
runTaskCommand: (task: Task) => string;
Returns the shell command to execute in order to run a task.
By default, this is
npx projen@<version> <task>
Parameter task
The task for which the command is required
method synth
synth: () => void;
Synthesize all project files into
outdir
.1. Call "this.preSynthesize()" 2. Delete all generated files 3. Synthesize all subprojects 4. Synthesize all components of this project 5. Call "postSynthesize()" for all components of this project 6. Call "this.postSynthesize()"
method tryFindFile
tryFindFile: (filePath: string) => FileBase | undefined;
Finds a file at the specified relative path within this project and all its subprojects.
Parameter filePath
The file path. If this path is relative, it will be resolved from the root of _this_ project.
Returns
a
FileBase
or undefined if there is no file in that path
method tryFindJsonFile
tryFindJsonFile: (filePath: string) => JsonFile | undefined;
Finds a json file by name.
Parameter filePath
The file path.
Deprecated
use
tryFindObjectFile
method tryFindObjectFile
tryFindObjectFile: (filePath: string) => ObjectFile | undefined;
Finds an object file (like JsonFile, YamlFile, etc.) by name.
Parameter filePath
The file path.
method tryRemoveFile
tryRemoveFile: (filePath: string) => FileBase | undefined;
Finds a file at the specified relative path within this project and removes it.
Parameter filePath
The file path. If this path is relative, it will be resolved from the root of _this_ project.
Returns
a
FileBase
if the file was found and removed, or undefined if the file was not found.
class ProjectBuild
class ProjectBuild extends Component {}
Manages a standard build process for all projects.
Build spawns these tasks in order: 1. default 2. pre-compile 3. compile 4. post-compile 5. test 6. package
constructor
constructor(project: Project);
property buildTask
readonly buildTask: Task;
The task responsible for a full release build.
property compileTask
readonly compileTask: Task;
Compiles the code. By default for node.js projects this task is empty.
property packageTask
readonly packageTask: Task;
The "package" task.
property postCompileTask
readonly postCompileTask: Task;
Post-compile task.
property preCompileTask
readonly preCompileTask: Task;
Pre-compile task.
property testTask
readonly testTask: Task;
Tests the code.
class Projects
class Projects {}
Programmatic API for projen.
method createProject
static createProject: (options: CreateProjectOptions) => void;
Creates a new project with defaults.
This function creates the project type in-process (with in VM) and calls
.synth()
on it (ifoptions.synth
is notfalse
).At the moment, it also generates a
.projenrc.js
file with the same code that was just executed. In the future, this will also be done by the project type, so we can easily support multiple languages of projenrc.An environment variable (PROJEN_CREATE_PROJECT=true) is set within the VM so that custom project types can detect whether the current synthesis is the result of a new project creation (and take additional steps accordingly)
class ProjectTree
class ProjectTree extends Component {}
constructor
constructor(project: Project);
property file
file: JsonFile;
class Projenrc
class Projenrc extends ProjenrcJson {}
Deprecated
use
ProjenrcJson
class ProjenrcFile
abstract class ProjenrcFile extends Component {}
A component representing the projen runtime configuration
property filePath
abstract readonly filePath: string;
The path of the projenrc file.
method of
static of: (project: Project) => ProjenrcFile | undefined;
Returns the
Projenrc
instance associated with a project orundefined
if there is no Projenrc.Parameter project
The project
Returns
A Projenrc
method preSynthesize
preSynthesize: () => void;
class ProjenrcJson
class ProjenrcJson extends ProjenrcFile {}
Sets up a project to use JSON for projenrc.
constructor
constructor(project: Project, options?: ProjenrcJsonOptions);
property filePath
readonly filePath: string;
class ReleasableCommits
class ReleasableCommits {}
Find commits that should be considered releasable to decide if a release is required.
property cmd
cmd: string;
method everyCommit
static everyCommit: (path?: string) => ReleasableCommits;
Release every commit
This will only not release if the most recent commit is tagged with the latest matching tag.
Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the
bump
task, i.e. to only consider commits of a subproject use"."
.
method exec
static exec: (cmd: string) => ReleasableCommits;
Use an arbitrary shell command to find releasable commits since the latest tag.
A new release will be initiated, if the number of returned commits is greater than zero. Must return a newline separate list of commits that should considered releasable.
$LATEST_TAG
will be replaced with the actual latest tag for the given prefix.*Example 1
"git log --oneline $LATEST_TAG..HEAD -- ."
method featuresAndFixes
static featuresAndFixes: (path?: string) => ReleasableCommits;
Release only features and fixes
Shorthand for
ReleasableCommits.onlyOfType(['feat', 'fix'])
.Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the
bump
task, i.e. to only consider commits of a subproject use"."
.
method ofType
static ofType: (types: string[], path?: string) => ReleasableCommits;
Limit commits by their conventional commit type
This will only release commit that match one of the provided types. Commits are required to follow the conventional commit spec and will be ignored otherwise.
Parameter types
List of conventional commit types that should be released
Parameter path
Consider only commits that are enough to explain how the files that match the specified paths came to be. This path is relative to the current working dir of the
bump
task, i.e. to only consider commits of a subproject use"."
.
class Renovatebot
class Renovatebot extends Component {}
Defines renovatebot configuration for projen project.
Ignores the versions controlled by Projen.
constructor
constructor(project: Project, options?: RenovatebotOptions);
property file
readonly file: JsonFile;
The file holding the renovatebot configuration
class SampleDir
class SampleDir extends Component {}
Renders the given files into the directory if the directory does not exist. Use this to create sample code files
constructor
constructor(project: Project, dir: string, options: SampleDirOptions);
Create sample files in the given directory if the given directory does not exist
Parameter project
Parent project to add files to.
Parameter dir
directory to add files to. If directory already exists, nothing is added.
Parameter options
options for which files to create.
method synthesize
synthesize: () => void;
class SampleFile
class SampleFile extends Component {}
Produces a file with the given contents but only once, if the file doesn't already exist. Use this for creating example code files or other resources.
constructor
constructor(project: Project, filePath: string, options: SampleFileOptions);
Creates a new SampleFile object
Parameter project
the project to tie this file to.
Parameter filePath
the relative path in the project to put the file
Parameter options
the options for the file.
method synthesize
synthesize: () => void;
class SampleReadme
class SampleReadme extends SampleFile {}
Represents a README.md sample file. You are expected to manage this file after creation.
Parameter text
The initial contents of the README.md file. Defaults to '# replace this'
constructor
constructor(project: Project, props?: SampleReadmeProps);
class Semver
class Semver {}
Deprecated
This class will be removed in upcoming releases. if you wish to specify semver requirements in
deps
,devDeps
, etc, specify them like soexpress@^2.1
.
property mode
readonly mode?: string;
property spec
readonly spec: string;
property version
readonly version: string;
method caret
static caret: (version: string) => Semver;
Accept any minor version.
>= version < next major version
method latest
static latest: () => Semver;
Latest version.
method of
static of: (spec: string) => Semver;
method pinned
static pinned: (version: string) => Semver;
Accept only an exact version
method tilde
static tilde: (version: string) => Semver;
Accept patches.
>= version < next minor version
class SourceCode
class SourceCode extends Component {}
Represents a source file.
constructor
constructor(project: Project, filePath: string, options?: SourceCodeOptions);
property filePath
readonly filePath: string;
property marker
readonly marker: string;
method close
close: (code?: string) => void;
Decreases the indentation level and closes a code block.
Parameter code
The code after the block is closed (e.g.
}
).
method line
line: (code?: string) => void;
Emit a line of code.
Parameter code
The contents, if not specified, just adds a newline
method open
open: (code?: string) => void;
Opens a code block and increases the indentation level.
Parameter code
The code before the block starts (e.g.
export class {
).
class Task
class Task {}
A task that can be performed on the project. Modeled as a series of shell commands and subtasks.
constructor
constructor(name: string, props?: TaskOptions);
property condition
readonly condition: string;
A command to execute which determines if the task should be skipped. If it returns a zero exit code, the task will not be executed.
property cwd
cwd: string;
Returns the working directory for this task.
property description
description: string;
Returns the description of this task.
property envVars
readonly envVars: Readonly<{ [name: string]: string }>;
Returns all environment variables in the task level
property name
readonly name: string;
Task name.
property steps
readonly steps: TaskStep[];
Returns an immutable copy of all the step specifications of the task.
method addCondition
addCondition: (...condition: string[]) => void;
Add a command to execute which determines if the task should be skipped.
If a condition already exists, the new condition will be appended with
&&
delimiter.Parameter condition
The command to execute.
See Also
method builtin
builtin: (name: string) => void;
Execute a builtin task.
Builtin tasks are programs bundled as part of projen itself and used as helpers for various components.
In the future we should support built-in tasks from external modules.
Parameter name
The name of the builtin task to execute (e.g.
release/resolve-version
).
method env
env: (name: string, value: string) => void;
Adds an environment variable to this task.
Parameter name
The name of the variable
Parameter value
The value. If the value is surrounded by
$()
, we will evaluate it within a subshell and use the result as the value of the environment variable.
method exec
exec: (command: string, options?: TaskStepOptions) => void;
Executes a shell command
Parameter command
Shell command
Parameter options
Options
method insertStep
insertStep: (index: number, ...steps: TaskStep[]) => void;
Insert one or more steps at a given index
Parameter index
Steps will be inserted before this index. May be negative to count backwards from the end, or may be
== steps().length
to insert at the end.Parameter steps
The steps to insert
method lock
lock: () => void;
Forbid additional changes to this task.
method prepend
prepend: (shell: string, options?: TaskStepOptions) => void;
Adds a command at the beginning of the task.
Parameter shell
The command to add.
Deprecated
use
prependExec()
method prependExec
prependExec: (shell: string, options?: TaskStepOptions) => void;
Adds a command at the beginning of the task.
Parameter shell
The command to add.
method prependSay
prependSay: (message: string, options?: TaskStepOptions) => void;
Says something at the beginning of the task.
Parameter message
Your message
method prependSpawn
prependSpawn: (subtask: Task, options?: TaskStepOptions) => void;
Adds a spawn instruction at the beginning of the task.
Parameter subtask
The subtask to execute.
method removeStep
removeStep: (index: number) => void;
Parameter index
The index of the step to remove
method reset
reset: (command?: string, options?: TaskStepOptions) => void;
Reset the task so it no longer has any commands.
Parameter command
the first command to add to the task after it was cleared.
method say
say: (message: string, options?: TaskStepOptions) => void;
Say something.
Parameter message
Your message
Parameter options
Options
method spawn
spawn: (subtask: Task, options?: TaskStepOptions) => void;
Spawns a sub-task.
Parameter subtask
The subtask to execute.
method updateStep
updateStep: (index: number, step: TaskStep) => void;
Parameter index
The index of the step to edit
Parameter step
The new step to replace the old one entirely, it is not merged with the old step
class TaskRuntime
class TaskRuntime {}
The runtime component of the tasks engine.
constructor
constructor(workdir: string);
property manifest
readonly manifest: TasksManifest;
The contents of tasks.json
property MANIFEST_FILE
static readonly MANIFEST_FILE: string;
The project-relative path of the tasks manifest file.
property tasks
readonly tasks: TaskSpec[];
The tasks in this project.
property workdir
readonly workdir: string;
The root directory of the project and the cwd for executing tasks.
method runTask
runTask: ( name: string, parents?: string[], args?: Array<string | number>, env?: { [name: string]: string }) => void;
Runs the task.
Parameter name
The task name.
method tryFindTask
tryFindTask: (name: string) => TaskSpec | undefined;
Find a task by name, or
undefined
if not found.
class Tasks
class Tasks extends Component {}
Defines project tasks.
Tasks extend the projen CLI by adding subcommands to it. Task definitions are synthesized into
.projen/tasks.json
.
constructor
constructor(project: Project);
property all
readonly all: Task[];
All tasks.
property env
readonly env: { [key: string]: string };
Returns a copy of the currently global environment for this project.
method addEnvironment
addEnvironment: (name: string, value: string) => void;
Adds global environment.
Parameter name
Environment variable name
Parameter value
Value
method addTask
addTask: (name: string, options?: TaskOptions) => Task;
Adds a task to a project.
Parameter name
The name of the task
Parameter options
Task options.
method removeTask
removeTask: (name: string) => undefined | Task;
Removes a task from a project.
Parameter name
The name of the task to remove.
Returns
The
Task
that was removed, otherwiseundefined
.
method synthesize
synthesize: () => void;
method tryFind
tryFind: (name: string) => undefined | Task;
Finds a task by name. Returns
undefined
if the task cannot be found.Parameter name
The name of the task
class Testing
class Testing {}
A Testing static class with a .synth helper for getting a snapshots of construct outputs. Useful for snapshot testing with Jest.
Example 1
expect(Testing.synth(someProject)).toMatchSnapshot()
method synth
static synth: ( project: Project, options?: SnapshotOptions) => Record<string, any>;
Produces a simple JS object that represents the contents of the projects with field names being file paths.
Parameter project
the project to produce a snapshot for { [filename:string]: any }
class TextFile
class TextFile extends FileBase {}
A text file.
constructor
constructor(scope: IConstruct, filePath: string, options?: TextFileOptions);
Defines a text file.
Parameter project
The project
Parameter filePath
File path
Parameter options
Options
method addLine
addLine: (line: string) => void;
Adds a line to the text file.
Parameter line
the line to add (can use tokens)
method synthesizeContent
protected synthesizeContent: (_: IResolver) => string | undefined;
class TomlFile
class TomlFile extends ObjectFile {}
Represents a TOML file.
constructor
constructor(project: Project, filePath: string, options: TomlFileOptions);
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class Version
class Version extends Component {}
constructor
constructor(scope: IConstruct, options: VersionOptions);
property bumpPackage
readonly bumpPackage: string;
The package used to bump package versions, as a dependency string. This is a
commit-and-tag-version
compatible package.
property bumpTask
readonly bumpTask: Task;
property changelogFileName
readonly changelogFileName: string;
The name of the changelog file (under
artifactsDirectory
).
property releaseTagFileName
readonly releaseTagFileName: string;
The name of the file that contains the release tag (under
artifactsDirectory
).
property STANDARD_VERSION
static readonly STANDARD_VERSION: string;
Deprecated
use
version.bumpPackage
on the component instance instead
property unbumpTask
readonly unbumpTask: Task;
property versionFileName
readonly versionFileName: string;
The name of the file that contains the version (under
artifactsDirectory
).
method envForBranch
envForBranch: (branchOptions: VersionBranchOptions) => Record<string, string>;
Return the environment variables to modify the bump command for release branches.
These options are used to modify the behavior of the version bumping script for additional branches, by setting environment variables.
No settings are inherited from the base
Version
object (but any parameters that control versions do conflict with the use of anextVersionCommand
).
class XmlFile
class XmlFile extends ObjectFile {}
Represents an XML file.
Objects passed in will be synthesized using the npm "xml" library.
See Also
https://www.npmjs.com/package/xml
constructor
constructor(project: Project, filePath: string, options?: XmlFileOptions);
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class YamlFile
class YamlFile extends ObjectFile {}
Represents a YAML file.
constructor
constructor(scope: IConstruct, filePath: string, options: YamlFileOptions);
property lineWidth
lineWidth: number;
Maximum line width (set to 0 to disable folding).
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
Interfaces
interface CreateProjectOptions
interface CreateProjectOptions {}
property dir
readonly dir: string;
Directory that the project will be generated in.
property optionHints
readonly optionHints?: InitProjectOptionHints;
Should we render commented-out default options in the projenrc file? Does not apply to projenrc.json files.
InitProjectOptionHints.FEATURED
property post
readonly post?: boolean;
Should we execute post synthesis hooks? (usually package manager install).
true
property projectFqn
readonly projectFqn: string;
Fully-qualified name of the project type (usually formatted as
projen.module.ProjectType
).Example 1
projen.typescript.TypescriptProject
property projectOptions
readonly projectOptions: Record<string, any>;
Project options. Only JSON-like values can be passed in (strings, booleans, numbers, enums, arrays, and objects that are not derived from classes).
Consult the API reference of the project type you are generating for information about what fields and types are available.
property synth
readonly synth?: boolean;
Should we call
project.synth()
or instantiate the project (could still have side-effects) and render the .projenrc file.true
interface Dependency
interface Dependency extends DependencyCoordinates {}
Represents a project dependency.
interface DependencyCoordinates
interface DependencyCoordinates {}
Coordinates of the dependency (name and version).
property name
readonly name: string;
The package manager name of the dependency (e.g.
leftpad
for npm).NOTE: For package managers that use complex coordinates (like Maven), we will codify it into a string somehow.
property version
readonly version?: string;
Semantic version version requirement.
- requirement is managed by the package manager (e.g. npm/yarn).
interface DepsManifest
interface DepsManifest {}
property dependencies
readonly dependencies: Dependency[];
All dependencies of this module.
interface DevEnvironmentOptions
interface DevEnvironmentOptions {}
Base options for configuring a container-based development environment.
property dockerImage
readonly dockerImage?: DevEnvironmentDockerImage;
A Docker image or Dockerfile for the container.
property ports
readonly ports?: string[];
An array of ports that should be exposed from the container.
property tasks
readonly tasks?: Task[];
An array of tasks that should be run when the container starts.
property vscodeExtensions
readonly vscodeExtensions?: string[];
An array of extension IDs that specify the extensions that should be installed inside the container when it is created.
interface DockerComposeBuild
interface DockerComposeBuild {}
Build arguments for creating a docker image.
property args
readonly args?: Record<string, string>;
Build args. - none are provided
property context
readonly context: string;
Docker build context directory.
property dockerfile
readonly dockerfile?: string;
A dockerfile to build from. "Dockerfile"
interface DockerComposeNetworkConfig
interface DockerComposeNetworkConfig {}
Network configuration
property attachable
readonly attachable?: boolean;
Set to true to indicate that standalone containers can attach to this network, in addition to services. - unset
property bridge
readonly bridge?: boolean;
Set to true to indicate that the network is a bridge network. - unset
property driver
readonly driver?: string;
Driver to use for the network - value is not provided
property driverOpts
readonly driverOpts?: object;
Options for the configured driver. Those options are driver-dependent - consult the driver’s documentation for more information - value is not provided
property external
readonly external?: boolean;
Set to true to indicate that the network is externally created. - unset, indicating that docker-compose creates the network
property internal
readonly internal?: boolean;
Set to true to indicate that you want to create an externally isolated overlay network - unset
property ipam
readonly ipam?: DockerComposeNetworkIpamConfig;
Specify custom IPAM config. - unset
property labels
readonly labels?: string[];
Attach labels to the network - unset
property name
readonly name?: string;
Name of the network for when the network name isn't going to work in YAML. - unset, indicating that docker-compose creates networks as usual
property overlay
readonly overlay?: boolean;
Set to true to indicate that the network is an overlay network. - unset
interface DockerComposeNetworkIpamConfig
interface DockerComposeNetworkIpamConfig {}
IPAM configuration
interface DockerComposeNetworkIpamSubnetConfig
interface DockerComposeNetworkIpamSubnetConfig {}
IPAM subnet configuration
property subnet
readonly subnet?: string;
Subnet in CIDR format that represents a network segment - value is not provided
interface DockerComposePortMappingOptions
interface DockerComposePortMappingOptions {}
Options for port mappings.
property protocol
readonly protocol?: DockerComposeProtocol;
Port mapping protocol. DockerComposeProtocol.TCP
interface DockerComposeProps
interface DockerComposeProps {}
Props for DockerCompose.
property nameSuffix
readonly nameSuffix?: string;
A name to add to the docker-compose.yml filename.
Example 1
'myname' yields 'docker-compose.myname.yml' - no name is added
property schemaVersion
readonly schemaVersion?: string;
Docker Compose schema version do be used - no version is provided
Deprecated
- The top level
version
field is obsolete per the Compose Specification.
property services
readonly services?: Record<string, DockerComposeServiceDescription>;
Service descriptions.
interface DockerComposeServiceDescription
interface DockerComposeServiceDescription {}
Description of a docker-compose.yml service.
property command
readonly command?: string[];
Provide a command to the docker container. - use the container's default command
property dependsOn
readonly dependsOn?: IDockerComposeServiceName[];
Names of other services this service depends on. - no dependencies
property entrypoint
readonly entrypoint?: string[];
Entrypoint to run in the container.
property environment
readonly environment?: Record<string, string>;
Add environment variables. - no environment variables are provided
property image
readonly image?: string;
Use a docker image. Note: You must specify either
build
orimage
key.See Also
imageBuild
property imageBuild
readonly imageBuild?: DockerComposeBuild;
Build a docker image. Note: You must specify either
imageBuild
orimage
key.See Also
image
property labels
readonly labels?: Record<string, string>;
Add labels. - no labels are provided
property networks
readonly networks?: IDockerComposeNetworkBinding[];
Add some networks to the service.
See Also
DockerCompose.network() to create & mount a named network
property platform
readonly platform?: string;
Add platform - no platform is provided
property ports
readonly ports?: DockerComposeServicePort[];
Map some ports. - no ports are mapped
property privileged
readonly privileged?: boolean;
Run in privileged mode - no privileged mode flag is provided
property volumes
readonly volumes?: IDockerComposeVolumeBinding[];
Mount some volumes into the service. Use one of the following to create volumes:
See Also
DockerCompose.bindVolume() to mount a host path
DockerCompose.namedVolume() to create & mount a named volume
interface DockerComposeServicePort
interface DockerComposeServicePort {}
A service port mapping
interface DockerComposeVolumeConfig
interface DockerComposeVolumeConfig {}
Volume configuration
property driver
readonly driver?: string;
Driver to use for the volume - value is not provided
property driverOpts
readonly driverOpts?: Record<string, string>;
Options to provide to the driver.
property external
readonly external?: boolean;
Set to true to indicate that the volume is externally created. - unset, indicating that docker-compose creates the volume
property name
readonly name?: string;
Name of the volume for when the volume name isn't going to work in YAML. - unset, indicating that docker-compose creates volumes as usual
interface DockerComposeVolumeMount
interface DockerComposeVolumeMount {}
Service volume mounting information.
interface FileBaseOptions
interface FileBaseOptions {}
property committed
readonly committed?: boolean;
Indicates whether this file should be committed to git or ignored. By default, all generated files are committed and anti-tamper is used to protect against manual modifications.
true
property editGitignore
readonly editGitignore?: boolean;
Update the project's .gitignore file true
property executable
readonly executable?: boolean;
Whether the generated file should be marked as executable.
false
property marker
readonly marker?: boolean;
Adds the projen marker to the file.
- marker will be included as long as the project is not ejected
property readonly
readonly readonly?: boolean;
Whether the generated file should be readonly.
true
interface GitAttributesFileOptions
interface GitAttributesFileOptions {}
Options for
GitAttributesFile
.
property endOfLine
readonly endOfLine?: EndOfLine;
The default end of line character for text files.
endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting explicitly:
{ endOfLine: EndOfLine.NONE }
.EndOfLine.LF
interface GitOptions
interface GitOptions {}
Git configuration options
property endOfLine
readonly endOfLine?: EndOfLine;
The default end of line character for text files.
endOfLine it's useful to keep the same end of line between Windows and Unix operative systems for git checking/checkout operations. Hence, it can avoid simple repository mutations consisting only of changes in the end of line characters. It will be set in the first line of the .gitattributes file to make it the first match with high priority but it can be overriden in a later line. Can be disabled by setting:
endOfLine: EndOfLine.NONE
.EndOfLine.LF
property lfsPatterns
readonly lfsPatterns?: string[];
File patterns to mark as stored in Git LFS
- No files stored in LFS
interface GitpodOptions
interface GitpodOptions extends DevEnvironmentOptions {}
Constructor options for the Gitpod component.
By default, Gitpod uses the 'gitpod/workspace-full' docker image.
See Also
https://github.com/gitpod-io/workspace-images/blob/master/full/Dockerfile
By default, all tasks will be run in parallel. To run the tasks in sequence, create a new task and specify the other tasks as subtasks.
property prebuilds
readonly prebuilds?: GitpodPrebuilds;
Optional Gitpod's Github App integration for prebuilds If this is not set and Gitpod's Github App is installed, then Gitpod will apply these defaults: https://www.gitpod.io/docs/prebuilds/#configure-the-github-app undefined
interface GitpodPort
interface GitpodPort {}
Options for an exposed port on Gitpod
property onOpen
readonly onOpen?: GitpodOnOpen;
What to do when a service on a port is detected.
GitpodOnOpen.NOTIFY
property port
readonly port?: string;
A port that should be exposed (forwarded) from the container.
Example 1
"8080"
property visibility
readonly visibility?: GitpodPortVisibility;
Whether the port visibility should be private or public.
GitpodPortVisibility.PUBLIC
interface GitpodPrebuilds
interface GitpodPrebuilds {}
Configure the Gitpod App for prebuilds. Currently only GitHub is supported.
See Also
https://www.gitpod.io/docs/prebuilds/
property addBadge
readonly addBadge?: boolean;
Add a "Review in Gitpod" button to the pull request's description false
property addCheck
readonly addCheck?: boolean;
Add a check to pull requests true
property addComment
readonly addComment?: boolean;
Add a "Review in Gitpod" button as a comment to pull requests false
property addLabel
readonly addLabel?: boolean;
Add a label once the prebuild is ready to pull requests false
property branches
readonly branches?: boolean;
Enable for all branches in this repo false
property master
readonly master?: boolean;
Enable for the master/default branch true
property pullRequests
readonly pullRequests?: boolean;
Enable for pull requests coming from this repo true
property pullRequestsFromForks
readonly pullRequestsFromForks?: boolean;
Enable for pull requests coming from forks false
interface GitpodTask
interface GitpodTask {}
Configure options for a task to be run when opening a Gitpod workspace (e.g. running tests, or starting a dev server).
Start Mode | Execution Fresh Workspace | before && init && command Restart Workspace | before && command Snapshot | before && command Prebuild | before && init && prebuild
property before
readonly before?: string;
In case you need to run something even before init, that is a requirement for both init and command, you can use the before property.
property command
readonly command: string;
Required. The shell command to run
property init
readonly init?: string;
The init property can be used to specify shell commands that should only be executed after a workspace was freshly cloned and needs to be initialized somehow. Such tasks are usually builds or downloading dependencies. Anything you only want to do once but not when you restart a workspace or start a snapshot.
property name
readonly name?: string;
A name for this task. - task names are omitted when blank
property openIn
readonly openIn?: GitpodOpenIn;
You can configure where in the IDE the terminal should be opened GitpodOpenIn.BOTTOM
property openMode
readonly openMode?: GitpodOpenMode;
You can configure how the terminal should be opened relative to the previous task. GitpodOpenMode.TAB_AFTER
property prebuild
readonly prebuild?: string;
The optional prebuild command will be executed during prebuilds. It is meant to run additional long running processes that could be useful, e.g. running test suites.
interface GroupRunnerOptions
interface GroupRunnerOptions {}
interface ICompareString
interface ICompareString {}
method compare
compare: (a: string, b: string) => number;
Parameter a
The first string
Parameter b
The second string
Returns
It is expected to return a negative value if the first argument is less than the second argument, zero if they're equal, and a positive value otherwise.
interface IDevEnvironment
interface IDevEnvironment {}
Abstract interface for container-based development environments, such as Gitpod and GitHub Codespaces.
method addDockerImage
addDockerImage: (image: DevEnvironmentDockerImage) => void;
Add a custom Docker image or Dockerfile for the container.
Parameter image
The Docker image
method addPorts
addPorts: (...ports: string[]) => void;
Adds ports that should be exposed (forwarded) from the container.
Parameter ports
The new ports
method addTasks
addTasks: (...tasks: Task[]) => void;
Adds tasks to run when the container starts.
Parameter tasks
The new tasks
method addVscodeExtensions
addVscodeExtensions: (...extensions: string[]) => void;
Adds a list of VSCode extensions that should be automatically installed in the container.
Parameter extensions
The extension IDs
interface IDockerComposeNetworkBinding
interface IDockerComposeNetworkBinding {}
Network binding information.
method bind
bind: (networkConfig: IDockerComposeNetworkConfig) => string;
Binds the requested network to the docker-compose network configuration and provide mounting instructions for synthesis.
Parameter networkConfig
the network configuration
Returns
the service name
interface IDockerComposeNetworkConfig
interface IDockerComposeNetworkConfig {}
Storage for network configuration.
method addNetworkConfiguration
addNetworkConfiguration: ( networkName: string, configuration: DockerComposeNetworkConfig) => void;
Add network configuration to the repository.
Parameter networkName
Parameter configuration
interface IDockerComposeServiceName
interface IDockerComposeServiceName {}
An interface providing the name of a docker compose service.
property serviceName
readonly serviceName: string;
The name of the docker compose service.
interface IDockerComposeVolumeBinding
interface IDockerComposeVolumeBinding {}
Volume binding information.
method bind
bind: (volumeConfig: IDockerComposeVolumeConfig) => DockerComposeVolumeMount;
Binds the requested volume to the docker-compose volume configuration and provide mounting instructions for synthesis.
Parameter volumeConfig
the volume configuration
Returns
mounting instructions for the service.
interface IDockerComposeVolumeConfig
interface IDockerComposeVolumeConfig {}
Storage for volume configuration.
method addVolumeConfiguration
addVolumeConfiguration: ( volumeName: string, configuration: DockerComposeVolumeConfig) => void;
Add volume configuration to the repository.
Parameter volumeName
Parameter configuration
interface IgnoreFileOptions
interface IgnoreFileOptions {}
property filterCommentLines
readonly filterCommentLines?: boolean;
Filter out comment lines?
true
property filterEmptyLines
readonly filterEmptyLines?: boolean;
Filter out blank/empty lines?
true
property ignorePatterns
readonly ignorePatterns?: string[];
Patterns to add to the ignore file
[]
interface IniFileOptions
interface IniFileOptions extends ObjectFileOptions {}
Options for
IniFile
.
interface InitProject
interface InitProject {}
Information passed from
projen new
to the project object when the project is first created. It is used to generate projenrc files in various languages.
property args
readonly args: Record<string, any>;
Initial arguments passed to
projen new
.
property comments
readonly comments: InitProjectOptionHints;
Include commented out options. Does not apply to projenrc.json files. InitProjectOptionHints.FEATURED
property fqn
readonly fqn: string;
The JSII FQN of the project type.
property type
readonly type: inventory.ProjectType;
Project metadata.
interface IResolvable
interface IResolvable {}
method toJSON
toJSON: () => any;
Resolves and returns content.
interface IResolver
interface IResolver {}
API for resolving tokens when synthesizing file content.
method resolve
resolve: (value: any, options?: ResolveOptions) => any;
Given a value (object/string/array/whatever, looks up any functions inside the object and returns an object where all functions are called.
Parameter value
The value to resolve options Resolve options
interface JsonFileOptions
interface JsonFileOptions extends ObjectFileOptions {}
Options for
JsonFile
.
property allowComments
readonly allowComments?: boolean;
Allow the use of comments in this file. - false for .json files, true for .json5 and .jsonc files
property newline
readonly newline?: boolean;
Adds a newline at the end of the file. true
interface LicenseOptions
interface LicenseOptions {}
property copyrightOwner
readonly copyrightOwner?: string;
Copyright owner.
If the license text has $copyright_owner, this option must be specified.
-
property copyrightPeriod
readonly copyrightPeriod?: string;
Period of license (e.g. "1998-2023")
The string
$copyright_period
will be substituted with this string.- current year (e.g. "2020")
property spdx
readonly spdx: string;
License type (SPDX).
See Also
https://github.com/projen/projen/tree/main/license-text for list of supported licenses
interface LoggerOptions
interface LoggerOptions {}
Options for logging utilities.
interface MakefileOptions
interface MakefileOptions extends FileBaseOptions {}
Options for Makefiles.
interface ObjectFileOptions
interface ObjectFileOptions extends FileBaseOptions {}
Options for
ObjectFile
.
property obj
readonly obj?: any;
The object that will be serialized. You can modify the object's contents before synthesis.
Serialization of the object is similar to JSON.stringify with few enhancements: - values that are functions will be called during synthesis and the result will be serialized - this allow to have lazy values. -
Set
will be converted to array -Map
will be converted to a plain object ({ key: value, ... }}) -RegExp
without flags will be converted to string representation of the source{} an empty object (use
file.obj
to mutate).
property omitEmpty
readonly omitEmpty?: boolean;
Omits empty objects and arrays. false
interface ProjectOptions
interface ProjectOptions {}
Options for
Project
.
property commitGenerated
readonly commitGenerated?: boolean;
Whether to commit the managed files by default.
true
property gitIgnoreOptions
readonly gitIgnoreOptions?: IgnoreFileOptions;
Configuration options for .gitignore file
property gitOptions
readonly gitOptions?: GitOptions;
Configuration options for git
property logging
readonly logging?: LoggerOptions;
Configure logging options such as verbosity. {}
property name
readonly name: string;
This is the name of your project.
$BASEDIR
property outdir
readonly outdir?: string;
The root directory of the project.
Relative to this directory, all files are synthesized.
If this project has a parent, this directory is relative to the parent directory and it cannot be the same as the parent or any of it's other subprojects.
"."
property parent
readonly parent?: Project;
The parent project, if this project is part of a bigger project.
property projenCommand
readonly projenCommand?: string;
The shell command to use in order to run the projen CLI.
Can be used to customize in special environments.
"npx projen"
property projenrcJson
readonly projenrcJson?: boolean;
Generate (once) .projenrc.json (in JSON). Set to
false
in order to disable .projenrc.json generation.false
property projenrcJsonOptions
readonly projenrcJsonOptions?: ProjenrcJsonOptions;
Options for .projenrc.json - default options
property renovatebot
readonly renovatebot?: boolean;
Use renovatebot to handle dependency upgrades.
false
property renovatebotOptions
readonly renovatebotOptions?: RenovatebotOptions;
Options for renovatebot.
- default options
interface ProjenrcJsonOptions
interface ProjenrcJsonOptions {}
property filename
readonly filename?: string;
The name of the projenrc file. ".projenrc.json"
interface ProjenrcOptions
interface ProjenrcOptions extends ProjenrcJsonOptions {}
Deprecated
use
ProjenrcJsonOptions
interface RenovatebotOptions
interface RenovatebotOptions {}
Options for Renovatebot
property ignore
readonly ignore?: string[];
You can use the
ignore
option to customize which dependencies are updated. The ignore option supports just package name. []
property ignoreProjen
readonly ignoreProjen?: boolean;
Ignores updates to
projen
.This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.
Projen upgrades are covered through the
ProjenUpgrade
class.true
property labels
readonly labels?: string[];
List of labels to apply to the created PR's.
property marker
readonly marker?: boolean;
property overrideConfig
readonly overrideConfig?: any;
property scheduleInterval
readonly scheduleInterval?: string[];
How often to check for new versions and raise pull requests.
Can be given in CRON or LATER format, and use multiple schedules (e.g. different for weekdays and weekends). Multiple rules are handles as OR.
Some normal scheduling values defined in enum
RenovatebotScheduleInterval
.See Also
https://docs.renovatebot.com/configuration-options/#schedule ["at any time"]
interface ResolveOptions
interface ResolveOptions {}
Resolve options.
interface Rule
interface Rule {}
A Make rule.
property phony
readonly phony?: boolean;
Marks whether the target is phony.
false
property prerequisites
readonly prerequisites?: string[];
Files that are used as inputs to create a target.
[]
property recipe
readonly recipe?: string[];
Commands that are run (using prerequisites as inputs) to create a target.
[]
property targets
readonly targets: string[];
Files to be created or updated by this rule.
If the rule is phony then instead this represents the command's name(s).
interface SampleDirOptions
interface SampleDirOptions {}
SampleDir options
property files
readonly files?: { [fileName: string]: string;};
The files to render into the directory. These files get added after any files from
source
if that option is specified (replacing if names overlap).
property sourceDir
readonly sourceDir?: string;
Absolute path to a directory to copy files from (does not need to be text files).
If your project is typescript-based and has configured
testdir
to be a subdirectory ofsrc
, sample files should outside of thesrc
directory otherwise they may not be copied. For example:new SampleDir(this, 'public', { source: path.join(__dirname, '..', 'sample-assets') });
interface SampleFileOptions
interface SampleFileOptions {}
Options for the SampleFile object.
property contents
readonly contents?: string;
The contents of the file to write.
property sourcePath
readonly sourcePath?: string;
Absolute path to a file to copy the contents from (does not need to be a text file).
If your project is Typescript-based and has configured
testdir
to be a subdirectory ofsrc
, sample files should outside of thesrc
directory, otherwise they may not be copied. For example:new SampleFile(this, 'assets/icon.png', { sourcePath: path.join(__dirname, '..', 'sample-assets', 'icon.png') });
interface SampleReadmeProps
interface SampleReadmeProps {}
SampleReadme Properties
interface SnapshotOptions
interface SnapshotOptions {}
Options for the Snapshot synthesis
property parseJson
readonly parseJson?: boolean;
Parse .json files as a JS object for improved inspection. This will fail if the contents are invalid JSON.
true parse .json files into an object
interface SourceCodeOptions
interface SourceCodeOptions {}
Options for
SourceCodeFile
.
interface TaskCommonOptions
interface TaskCommonOptions {}
property condition
readonly condition?: string;
A shell command which determines if the this task should be executed. If the program exits with a zero exit code, steps will be executed. A non-zero code means that task will be skipped.
property cwd
readonly cwd?: string;
The working directory for all steps in this task (unless overridden by the step).
- process.cwd()
property description
readonly description?: string;
The description of this build command. - the task name
property env
readonly env?: { [name: string]: string;};
Defines environment variables for the execution of this task. Values in this map will be evaluated in a shell, so you can do stuff like
$(echo "foo")
. {}
property requiredEnv
readonly requiredEnv?: string[];
A set of environment variables that must be defined in order to execute this task. Task execution will fail if one of these is not defined.
interface TaskOptions
interface TaskOptions extends TaskCommonOptions {}
property args
readonly args?: string[];
Should the provided
exec
shell command receive fixed args.See Also
- no arguments are passed to the step
property exec
readonly exec?: string;
Shell command to execute as the first command of the task. - add steps using
task.exec(command)
ortask.spawn(subtask)
property receiveArgs
readonly receiveArgs?: boolean;
Should the provided
exec
shell command receive args passed to the task.See Also
property steps
readonly steps?: TaskStep[];
List of task steps to run.
interface TasksManifest
interface TasksManifest {}
Schema for
tasks.json
.
interface TaskSpec
interface TaskSpec extends TaskCommonOptions {}
Specification of a single task.
interface TaskStep
interface TaskStep extends TaskStepOptions {}
A single step within a task. The step could either be the execution of a shell command or execution of a sub-task, by name.
property builtin
readonly builtin?: string;
The name of a built-in task to execute.
Built-in tasks are node.js programs baked into the projen module and as component runtime helpers.
The name is a path relative to the projen lib/ directory (without the .task.js extension). For example, if your built in builtin task is under
src/release/resolve-version.task.ts
, then this would berelease/resolve-version
.- do not execute a builtin task
property exec
readonly exec?: string;
Shell command to execute
- don't execute a shell command
property say
readonly say?: string;
Print a message. - don't say anything
property spawn
readonly spawn?: string;
Subtask to execute
- don't spawn a subtask
interface TaskStepOptions
interface TaskStepOptions {}
Options for task steps.
property args
readonly args?: string[];
A list of fixed arguments always passed to the step.
Useful to re-use existing tasks without having to re-define the whole task.\ Fixed args are always passed to the step, even if
receiveArgs
isfalse
and are always passed before any args the task is called with.If the step executes a shell commands, args are passed through at the end of the
exec
shell command.\ The position of the args can be changed by including the marker$@
inside the command string.If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect.
If the step calls a builtin script, args are passed to the script. It is up to the script to use or discard the arguments.
Example 1
task.spawn("deploy", { args: ["--force"] });
- no arguments are passed to the step
property condition
readonly condition?: string;
A shell command which determines if the this step should be executed. If the program exits with a zero exit code, the step will be executed. A non-zero code means the step will be skipped (subsequent task steps will still be evaluated/executed).
property cwd
readonly cwd?: string;
The working directory for this step.
- determined by the task
property env
readonly env?: { [name: string]: string;};
Defines environment variables for the execution of this step (
exec
andbuiltin
only). Values in this map can be simple, literal values or shell expressions that will be evaluated at runtime e.g.$(echo "foo")
.Example 1
{ "foo": "bar", "boo": "$(echo baz)" }
- no environment variables defined in step
property name
readonly name?: string;
Step name
- no name
property receiveArgs
readonly receiveArgs?: boolean;
Should this step receive args passed to the task.
If
true
, args are passed through at the end of theexec
shell command.\ The position of the args can be changed by including the marker$@
inside the command string.If the marker is explicitly double-quoted ("$@") arguments will be wrapped in single quotes, approximating the whitespace preserving behavior of bash variable expansion.
If the step spawns a subtask, args are passed to the subtask. The subtask must define steps receiving args for this to have any effect.
Example 1
task.exec("echo Hello $@ World!", { receiveArgs: true });
false
interface TextFileOptions
interface TextFileOptions extends FileBaseOptions {}
Options for
TextFile
.
property lines
readonly lines?: string[];
The contents of the text file. You can use
addLine()
to append lines.[] empty file
interface TomlFileOptions
interface TomlFileOptions extends ObjectFileOptions {}
Options for
TomlFile
.
interface VersionBranchOptions
interface VersionBranchOptions {}
Options to pass to
modifyBranchEnvironment
property majorVersion
readonly majorVersion?: number;
The major versions released from this branch.
property minMajorVersion
readonly minMajorVersion?: number;
The minimum major version to release.
property minorVersion
readonly minorVersion?: number;
The minor versions released from this branch.
property prerelease
readonly prerelease?: string;
Bump the version as a pre-release tag.
- normal releases
property tagPrefix
readonly tagPrefix?: string;
Automatically add the given prefix to release tags. Useful if you are releasing on multiple branches with overlapping version numbers.
Note: this prefix is used to detect the latest tagged version when bumping, so if you change this on a project with an existing version history, you may need to manually tag your latest release with the new prefix.
- no prefix
interface VersionOptions
interface VersionOptions {}
Options for
Version
.
property artifactsDirectory
readonly artifactsDirectory: string;
The name of the directory into which
changelog.md
andversion.txt
files are emitted.
property bumpPackage
readonly bumpPackage?: string;
The
commit-and-tag-version
compatible package used to bump the package version, as a dependency string.This can be any compatible package version, including the deprecated
standard-version@9
."commit-and-tag-version@12"
property nextVersionCommand
readonly nextVersionCommand?: string;
A shell command to control the next version to release.
If present, this shell command will be run before the bump is executed, and it determines what version to release. It will be executed in the following environment:
- Working directory: the project directory. -
$VERSION
: the current version. Looks like1.2.3
. -$LATEST_TAG
: the most recent tag. Looks likeprefix-v1.2.3
, or may be unset. -$SUGGESTED_BUMP
: the suggested bump action based on commits. One ofmajor|minor|patch|none
.The command should print one of the following to
stdout
:- Nothing: the next version number will be determined based on commit history. -
x.y.z
: the next version number will bex.y.z
. -major|minor|patch
: the next version number will be the current version number with the indicated component bumped.- The next version will be determined based on the commit history and project settings.
property releasableCommits
readonly releasableCommits?: ReleasableCommits;
Find commits that should be considered releasable Used to decide if a release is required.
ReleasableCommits.everyCommit()
property tagPrefix
readonly tagPrefix?: string;
The tag prefix corresponding to this version.
property versionInputFile
readonly versionInputFile: string;
A name of a .json file to set the
version
field in after a bump.Example 1
"package.json"
property versionrcOptions
readonly versionrcOptions?: Record<string, any>;
Custom configuration for versionrc file used by standard-release
interface XmlFileOptions
interface XmlFileOptions extends ObjectFileOptions {}
Options for
XmlFile
.
interface YamlFileOptions
interface YamlFileOptions extends ObjectFileOptions {}
Options for
JsonFile
.
property lineWidth
readonly lineWidth?: number;
Maximum line width (set to 0 to disable folding).
- 0
Enums
enum DependencyType
enum DependencyType { RUNTIME = 'runtime', PEER = 'peer', BUNDLED = 'bundled', BUILD = 'build', TEST = 'test', DEVENV = 'devenv', OVERRIDE = 'override', OPTIONAL = 'optional',}
Type of dependency.
member BUILD
BUILD = 'build'
The dependency is required to run the
build
task.
member BUNDLED
BUNDLED = 'bundled'
The dependency is bundled and shipped with the module, so consumers are not required to install it.
member DEVENV
DEVENV = 'devenv'
The dependency is required for development (e.g. IDE plugins).
member OPTIONAL
OPTIONAL = 'optional'
An optional dependency that may be used at runtime if available, but is not required. It is expected to be installed by the consumer.
member OVERRIDE
OVERRIDE = 'override'
Transient dependency that needs to be overwritten.
Available for Node packages
member PEER
PEER = 'peer'
The dependency is required at runtime but expected to be installed by the consumer.
member RUNTIME
RUNTIME = 'runtime'
The dependency is required for the program/library during runtime.
member TEST
TEST = 'test'
The dependency is required to run the
test
task.
enum DockerComposeProtocol
enum DockerComposeProtocol { TCP = 'tcp', UDP = 'udp',}
Network protocol for port mapping
enum EndOfLine
enum EndOfLine { AUTO = 'auto', CRLF = 'crlf', LF = 'lf', NONE = 'none',}
The end of line characters supported by git.
member AUTO
AUTO = 'auto'
Maintain existing (mixed values within one file are normalised by looking at what's used after the first line)
member CRLF
CRLF = 'crlf'
Carriage Return + Line Feed characters (\r\n), common on Windows
member LF
LF = 'lf'
Line Feed only (\n), common on Linux and macOS as well as inside git repos
member NONE
NONE = 'none'
Disable and do not configure the end of line character
enum GitpodOnOpen
enum GitpodOnOpen { OPEN_BROWSER = 'open-browser', OPEN_PREVIEW = 'open-preview', NOTIFY = 'notify', IGNORE = 'ignore',}
What to do when a service on a port is detected.
member IGNORE
IGNORE = 'ignore'
Do nothing.
member NOTIFY
NOTIFY = 'notify'
Show a notification asking the user what to do (default)
member OPEN_BROWSER
OPEN_BROWSER = 'open-browser'
Open a new browser tab
member OPEN_PREVIEW
OPEN_PREVIEW = 'open-preview'
Open a preview on the right side of the IDE
enum GitpodOpenIn
enum GitpodOpenIn { BOTTOM = 'bottom', LEFT = 'left', RIGHT = 'right', MAIN = 'main',}
Configure where in the IDE the terminal should be opened.
enum GitpodOpenMode
enum GitpodOpenMode { TAB_AFTER = 'tab-after', TAB_BEFORE = 'tab-before', SPLIT_RIGHT = 'split-right', SPLIT_LEFT = 'split-left', SPLIT_TOP = 'split-top', SPLIT_BOTTOM = 'split-bottom',}
Configure how the terminal should be opened relative to the previous task.
member SPLIT_BOTTOM
SPLIT_BOTTOM = 'split-bottom'
Splits and adds the terminal to the bottom
member SPLIT_LEFT
SPLIT_LEFT = 'split-left'
Splits and adds the terminal to the left
member SPLIT_RIGHT
SPLIT_RIGHT = 'split-right'
Splits and adds the terminal to the right
member SPLIT_TOP
SPLIT_TOP = 'split-top'
Splits and adds the terminal to the top
member TAB_AFTER
TAB_AFTER = 'tab-after'
Opens in the same tab group right after the previous tab
member TAB_BEFORE
TAB_BEFORE = 'tab-before'
Opens in the same tab group left before the previous tab
enum GitpodPortVisibility
enum GitpodPortVisibility { PUBLIC = 'public', PRIVATE = 'private',}
Whether the port visibility should be private or public
enum InitProjectOptionHints
enum InitProjectOptionHints { ALL = 'all', FEATURED = 'featured', NONE = 'none',}
Choices for how to display commented out options in projenrc files. Does not apply to projenrc.json files.
enum LogLevel
enum LogLevel { OFF = '00.off', ERROR = '10.error', WARN = '20.warn', INFO = '30.info', DEBUG = '40.debug', VERBOSE = '50.verbose',}
Logging verbosity.
enum ProjectType
enum ProjectType { UNKNOWN = 'unknown', LIB = 'lib', APP = 'app',}
Which type of project this is.
Deprecated
no longer supported at the base project level
member APP
APP = 'app'
This is an app (service, tool, website, etc). Its artifacts are intended to be deployed or published for end-user consumption.
member LIB
LIB = 'lib'
This is a library, intended to be published to a package manager and consumed by other projects.
member UNKNOWN
UNKNOWN = 'unknown'
This module may be a either a library or an app.
enum RenovatebotScheduleInterval
enum RenovatebotScheduleInterval { ANY_TIME = 'at any time', EARLY_MONDAYS = 'before 3am on Monday', DAILY = 'before 2am', WEEKLY = 'before 3am on Monday', MONTHLY = 'before 3am on the first day of the month', QUARTERLY = 'every 3 months on the first day of the month', WEEKENDS = 'every weekend', WEEKDAYS = 'every weekday',}
How often to check for new versions and raise pull requests for version updates.
See Also
https://docs.renovatebot.com/presets-schedule/
member ANY_TIME
ANY_TIME = 'at any time'
Run at any time
member DAILY
DAILY = 'before 2am'
Schedule daily
member EARLY_MONDAYS
EARLY_MONDAYS = 'before 3am on Monday'
Weekly schedule on early monday mornings
member MONTHLY
MONTHLY = 'before 3am on the first day of the month'
Schedule monthly
member QUARTERLY
QUARTERLY = 'every 3 months on the first day of the month'
Schedule quarterly
member WEEKDAYS
WEEKDAYS = 'every weekday'
Schedule for weekdays
member WEEKENDS
WEEKENDS = 'every weekend'
Schedule for weekends
member WEEKLY
WEEKLY = 'before 3am on Monday'
Schedule weekly
enum TestFailureBehavior
enum TestFailureBehavior { SKIP = 'skip', FAIL_SYNTHESIS = 'fail',}
member FAIL_SYNTHESIS
FAIL_SYNTHESIS = 'fail'
Fail the whole file synthesis.
member SKIP
SKIP = 'skip'
Skip the current patch operation and continue with the next operation.
Namespaces
namespace awscdk
module 'lib/awscdk/index.d.ts' {}
class AutoDiscover
class AutoDiscover extends Component {}
Discovers and creates integration tests and lambdas from code in the project's source and test trees.
constructor
constructor(project: Project, options: AutoDiscoverOptions);
class AwsCdkConstructLibrary
class AwsCdkConstructLibrary extends ConstructLibrary {}
AWS CDK construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the AWS CDK with a friendly workflow and automatic publishing to the construct catalog.
awscdk-construct
constructor
constructor(options: AwsCdkConstructLibraryOptions);
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
property cdkVersion
readonly cdkVersion: string;
The target CDK version for this library.
property version
readonly version: string;
Deprecated
use
cdkVersion
method addCdkDependencies
addCdkDependencies: (...deps: string[]) => void;
Adds dependencies to AWS CDK modules.
Since this is a library project, dependencies will be added as peer dependencies.
Parameter deps
names of cdk modules (e.g.
@aws-cdk/aws-lambda
).Deprecated
Not supported in v2. For v1, use
project.cdkDeps.addV1Dependencies()
method addCdkTestDependencies
addCdkTestDependencies: (...deps: string[]) => void;
Adds AWS CDK modules as dev dependencies.
Parameter deps
names of cdk modules (e.g.
@aws-cdk/aws-lambda
).Deprecated
Not supported in v2. For v1, use
project.cdkDeps.addV1DevDependencies()
class AwsCdkDeps
abstract class AwsCdkDeps extends Component {}
Manages dependencies on the AWS CDK.
constructor
constructor(project: Project, options: AwsCdkDepsOptions);
property cdkCliVersion
readonly cdkCliVersion: string;
The dependency requirement for the CDK CLI (e.g. '^2.3.4').
Will return
^2
if the version was unspecified by the user.
property cdkDependenciesAsDeps
readonly cdkDependenciesAsDeps: boolean;
Whether CDK dependencies are added as normal dependencies (and peer dependencies).
Deprecated
Not used for CDK 2.x
property cdkMajorVersion
readonly cdkMajorVersion: number;
The major version of the AWS CDK (e.g. 1, 2, ...)
property cdkMinimumVersion
readonly cdkMinimumVersion: string;
The minimum version of the AWS CDK (e.g.
2.0.0
).
property cdkVersion
readonly cdkVersion: string;
The dependency requirement for AWS CDK (e.g.
^2.0.0
).
method addV1Dependencies
addV1Dependencies: (...deps: string[]) => void;
Adds dependencies to AWS CDK modules.
The type of dependency is determined by the
dependencyType
option.This method is not supported in CDK v2. Use
project.addPeerDeps()
orproject.addDeps()
as appropriate.Parameter deps
names of cdk modules (e.g.
@aws-cdk/aws-lambda
).
method addV1DevDependencies
addV1DevDependencies: (...deps: string[]) => void;
Adds AWS CDK modules as dev dependencies.
This method is not supported in CDK v2. Use
project.addPeerDeps()
orproject.addDeps()
as appropriate.Parameter deps
fully qualified names of cdk modules (e.g.
@aws-cdk/aws-lambda
).
method packageNames
protected abstract packageNames: () => AwsCdkPackageNames;
Return a configuration object with information about package naming in various languages
method preSynthesize
preSynthesize: () => void;
class AwsCdkDepsJava
class AwsCdkDepsJava extends AwsCdkDeps {}
Manages dependencies on the AWS CDK for Java projects.
method packageNames
protected packageNames: () => AwsCdkPackageNames;
class AwsCdkDepsJs
class AwsCdkDepsJs extends AwsCdkDeps {}
Manages dependencies on the AWS CDK for Node.js projects.
method packageNames
protected packageNames: () => AwsCdkPackageNames;
class AwsCdkDepsPy
class AwsCdkDepsPy extends AwsCdkDeps {}
Manages dependencies on the AWS CDK for Python projects.
method packageNames
protected packageNames: () => AwsCdkPackageNames;
class AwsCdkJavaApp
class AwsCdkJavaApp extends JavaProject {}
AWS CDK app in Java.
awscdk-app-java
constructor
constructor(options: AwsCdkJavaAppOptions);
property cdkConfig
readonly cdkConfig: CdkConfig;
The
cdk.json
file.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
CDK dependency management helper class
property cdkTasks
readonly cdkTasks: CdkTasks;
CDK tasks.
property mainClass
readonly mainClass: string;
The full name of the main class of the java app (package.Class).
property mainClassName
readonly mainClassName: string;
The name of the Java class with the static
main()
method.
property mainPackage
readonly mainPackage: string;
The name of the Java package that includes the main class.
method addCdkDependency
addCdkDependency: (...modules: string[]) => void;
Adds an AWS CDK module dependencies
Parameter modules
The list of modules to depend on (e.g. "software.amazon.awscdk/aws-lambda", "software.amazon.awscdk/aws-iam", etc)
Deprecated
In CDK 2.x all modules are available by default. Alpha modules should be added using the standard 'deps'
class AwsCdkPythonApp
class AwsCdkPythonApp extends PythonProject {}
AWS CDK app in Python
awscdk-app-py
constructor
constructor(options: AwsCdkPythonAppOptions);
property appEntrypoint
readonly appEntrypoint: string;
The CDK app entrypoint
property cdkConfig
readonly cdkConfig: CdkConfig;
cdk.json configuration.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
property cdkTasks
readonly cdkTasks: CdkTasks;
Common CDK tasks.
property cdkVersion
readonly cdkVersion: string;
The CDK version this app is using.
property sampleTestdir
readonly sampleTestdir: string;
The directory in which the python sample tests reside.
property testdir
readonly testdir: string;
The directory in which the python tests reside.
Deprecated
Use
sampleTestdir
instead.
class AwsCdkTypeScriptApp
class AwsCdkTypeScriptApp extends TypeScriptAppProject {}
AWS CDK app in TypeScript
awscdk-app-ts
constructor
constructor(options: AwsCdkTypeScriptAppOptions);
property appEntrypoint
readonly appEntrypoint: string;
The CDK app entrypoint
property cdkConfig
readonly cdkConfig: CdkConfig;
cdk.json configuration.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
property cdkTasks
readonly cdkTasks: CdkTasks;
Common CDK tasks.
property cdkVersion
readonly cdkVersion: string;
The CDK version this app is using.
method addCdkDependency
addCdkDependency: (...modules: string[]) => void;
Adds an AWS CDK module dependencies
Parameter modules
The list of modules to depend on
class CdkConfig
class CdkConfig extends Component {}
Represents cdk.json file.
constructor
constructor(project: Project, options: CdkConfigOptions);
property cdkout
readonly cdkout: string;
Name of the cdk.out directory.
property exclude
readonly exclude: string[];
List of glob patterns to be excluded by CDK.
property include
readonly include: string[];
List of glob patterns to be included by CDK.
property json
readonly json: JsonFile;
Represents the JSON file.
method addExcludes
addExcludes: (...patterns: string[]) => void;
Add excludes to
cdk.json
.Parameter patterns
The excludes to add.
method addIncludes
addIncludes: (...patterns: string[]) => void;
Add includes to
cdk.json
.Parameter patterns
The includes to add.
class CdkTasks
class CdkTasks extends Component {}
Adds standard AWS CDK tasks to your project.
constructor
constructor(project: Project);
property deploy
readonly deploy: Task;
Deploys your app.
property destroy
readonly destroy: Task;
Destroys all the stacks.
property diff
readonly diff: Task;
Diff against production.
property synth
readonly synth: Task;
Synthesizes your app.
property synthSilent
readonly synthSilent: Task;
Synthesizes your app and suppresses stdout.
property watch
readonly watch: Task;
Watch task.
class ConstructLibraryAws
class ConstructLibraryAws extends AwsCdkConstructLibrary {}
Deprecated
use
AwsCdkConstructLibrary
class EdgeLambdaAutoDiscover
class EdgeLambdaAutoDiscover extends AutoDiscoverBase {}
Creates edge lambdas from entry points discovered in the project's source tree.
constructor
constructor(project: Project, options: EdgeLambdaAutoDiscoverOptions);
class IntegrationTest
class IntegrationTest extends IntegrationTestBase {}
Cloud integration tests.
constructor
constructor(project: Project, options: IntegrationTestOptions);
property destroyTask
readonly destroyTask: Task;
Destroy the integration test resources
property watchTask
readonly watchTask: Task;
The watch task.
class IntegrationTestAutoDiscover
class IntegrationTestAutoDiscover extends IntegrationTestAutoDiscoverBase {}
Creates integration tests from entry points discovered in the test tree.
constructor
constructor(project: Project, options: IntegrationTestAutoDiscoverOptions);
class LambdaAutoDiscover
class LambdaAutoDiscover extends AutoDiscoverBase {}
Creates lambdas from entry points discovered in the project's source tree.
constructor
constructor(project: Project, options: LambdaAutoDiscoverOptions);
class LambdaExtension
class LambdaExtension extends Component {}
Create a Lambda Extension
constructor
constructor(project: Project, options: LambdaExtensionOptions);
class LambdaExtensionAutoDiscover
class LambdaExtensionAutoDiscover extends AutoDiscoverBase {}
Creates Lambda Extensions from entrypoints discovered in the project's source tree.
constructor
constructor(project: Project, options: LambdaExtensionAutoDiscoverOptions);
class LambdaFunction
class LambdaFunction extends Component {}
Generates a pre-bundled AWS Lambda function construct from handler code.
To use this, create an AWS Lambda handler file under your source tree with the
.lambda.ts
extension and add aLambdaFunction
component to your typescript project pointing to this entrypoint.This will add a task to your "compile" step which will use
esbuild
to bundle the handler code into the build directory. It will also generate a filesrc/foo-function.ts
with a custom AWS construct calledFooFunction
which extends@aws-cdk/aws-lambda.Function
which is bound to the bundled handle through an asset.Example 1
new LambdaFunction(myProject, { srcdir: myProject.srcdir, entrypoint: 'src/foo.lambda.ts', });
constructor
constructor(project: Project, options: LambdaFunctionOptions);
Defines a pre-bundled AWS Lambda function construct from handler code.
Parameter project
The project to use
Parameter options
Options
class LambdaRuntime
class LambdaRuntime {}
The runtime for the AWS Lambda function.
constructor
constructor( functionRuntime: string, esbuildTarget: string, options?: LambdaRuntimeOptions);
property defaultExternals
readonly defaultExternals: string[];
property esbuildPlatform
readonly esbuildPlatform: string;
property esbuildTarget
readonly esbuildTarget: string;
The esbuild setting to use.
property functionRuntime
readonly functionRuntime: string;
The Node.js runtime to use
property NODEJS_10_X
static readonly NODEJS_10_X: LambdaRuntime;
Node.js 10.x
Deprecated
Node.js 10 runtime has been deprecated on Jul 30, 2021
property NODEJS_12_X
static readonly NODEJS_12_X: LambdaRuntime;
Node.js 12.x
Deprecated
Node.js 12 runtime has been deprecated on Mar 31, 2023
property NODEJS_14_X
static readonly NODEJS_14_X: LambdaRuntime;
Node.js 14.x
Deprecated
Node.js 14 runtime has been deprecated on Dec 4, 2023
property NODEJS_16_X
static readonly NODEJS_16_X: LambdaRuntime;
Node.js 16.x
Deprecated
Node.js 16 runtime has been deprecated on Jun 12, 2024
property NODEJS_18_X
static readonly NODEJS_18_X: LambdaRuntime;
Node.js 18.x
Advanced notice: Node.js 18 runtime will be deprecated on Jul 31, 2025
property NODEJS_20_X
static readonly NODEJS_20_X: LambdaRuntime;
Node.js 20.x
property NODEJS_22_X
static readonly NODEJS_22_X: LambdaRuntime;
Node.js 22.x
interface AutoDiscoverCommonOptions
interface AutoDiscoverCommonOptions {}
Common options for auto discovering project subcomponents.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
AWS CDK dependency manager.
property tsconfigPath
readonly tsconfigPath: string;
Path to the tsconfig file to use for integration tests.
interface AutoDiscoverOptions
interface AutoDiscoverOptions extends LambdaAutoDiscoverOptions, LambdaExtensionAutoDiscoverOptions, IntegrationTestAutoDiscoverOptions {}
Options for
AutoDiscover
property edgeLambdaAutoDiscover
readonly edgeLambdaAutoDiscover?: boolean;
Auto-discover edge lambda functions.
true
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Auto-discover integration tests.
true
property lambdaAutoDiscover
readonly lambdaAutoDiscover?: boolean;
Auto-discover lambda functions.
true
property lambdaExtensionAutoDiscover
readonly lambdaExtensionAutoDiscover?: boolean;
Auto-discover lambda extensions.
true
interface AwsCdkConstructLibraryOptions
interface AwsCdkConstructLibraryOptions extends ConstructLibraryOptions, AwsCdkDepsCommonOptions {}
Options for
AwsCdkConstructLibrary
.
property edgeLambdaAutoDiscover
readonly edgeLambdaAutoDiscover?: boolean;
Automatically adds an
cloudfront.experimental.EdgeFunction
for each.edge-lambda.ts
handler in your source tree. If this is disabled, you can manually add anawscdk.AutoDiscover
component to your project.true
property experimentalIntegRunner
readonly experimentalIntegRunner?: boolean;
Enable experimental support for the AWS CDK integ-runner.
false
Modifiers
@experimental
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Automatically discovers and creates integration tests for each
.integ.ts
file under your test directory.true
property lambdaAutoDiscover
readonly lambdaAutoDiscover?: boolean;
Automatically adds an
aws_lambda.Function
for each.lambda.ts
handler in your source tree. If this is disabled, you either need to explicitly callaws_lambda.Function.autoDiscover()
or define a `new aws_lambda.Function()` for each handler.true
property lambdaExtensionAutoDiscover
readonly lambdaExtensionAutoDiscover?: boolean;
Automatically adds an
awscdk.LambdaExtension
for each.lambda-extension.ts
entrypoint in your source tree. If this is disabled, you can manually add anawscdk.AutoDiscover
component to your projecttrue
property lambdaOptions
readonly lambdaOptions?: LambdaFunctionCommonOptions;
Common options for all AWS Lambda functions.
- default options
interface AwsCdkDepsCommonOptions
interface AwsCdkDepsCommonOptions {}
Options for
AwsCdkDeps
property cdkAssert
readonly cdkAssert?: boolean;
Warning: NodeJS only. Install the @aws-cdk/assert library?
- will be included by default for AWS CDK >= 1.0.0 < 2.0.0
Deprecated
The @aws-cdk/assert library is deprecated in favor of @aws-cdk/assertions (in V1) and included in
aws-cdk-lib
for V2.
property cdkAssertions
readonly cdkAssertions?: boolean;
Install the assertions library?
Only needed for CDK 1.x. If using CDK 2.x then assertions is already included in 'aws-cdk-lib'
- will be included by default for AWS CDK >= 1.111.0 < 2.0.0
property cdkCliVersion
readonly cdkCliVersion?: string;
Version range of the AWS CDK CLI to depend on.
Can be either a specific version, or an NPM version range.
By default, the latest 2.x version will be installed; you can use this option to restrict it to a specific version or version range.
"^2"
property cdkDependencies
readonly cdkDependencies?: string[];
Which AWS CDKv1 modules this project requires
Deprecated
For CDK 2.x use "deps" instead. (or "peerDeps" if you're building a library)
property cdkDependenciesAsDeps
readonly cdkDependenciesAsDeps?: boolean;
If this is enabled (default), all modules declared in
cdkDependencies
will be also added as normaldependencies
(as well aspeerDependencies
).This is to ensure that downstream consumers actually have your CDK dependencies installed when using npm < 7 or yarn, where peer dependencies are not automatically installed. If this is disabled,
cdkDependencies
will be added todevDependencies
to ensure they are present during development.Note: this setting only applies to construct library projects
true
Deprecated
Not supported in CDK v2.
property cdkTestDependencies
readonly cdkTestDependencies?: string[];
AWS CDK modules required for testing.
Deprecated
For CDK 2.x use 'devDeps' (in node.js projects) or 'testDeps' (in java projects) instead
property cdkVersion
readonly cdkVersion: string;
Minimum version of the AWS CDK to depend on.
"2.1.0"
property cdkVersionPinning
readonly cdkVersionPinning?: boolean;
Use pinned version instead of caret version for CDK.
You can use this to prevent mixed versions for your CDK dependencies and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
property constructsVersion
readonly constructsVersion?: string;
Minimum version of the
constructs
library to depend on.- for CDK 1.x the default is "3.2.27", for CDK 2.x the default is "10.0.5".
interface AwsCdkDepsOptions
interface AwsCdkDepsOptions extends AwsCdkDepsCommonOptions {}
property dependencyType
readonly dependencyType: DependencyType;
The type of dependency to use for runtime AWS CDK and
constructs
modules.For libraries, use peer dependencies and for apps use runtime dependencies.
interface AwsCdkJavaAppOptions
interface AwsCdkJavaAppOptions extends JavaProjectOptions, CdkConfigCommonOptions, AwsCdkDepsCommonOptions {}
property mainClass
readonly mainClass: string;
The name of the Java class with the static
main()
method. This method should callapp.synth()
on the CDK app."org.acme.MyApp"
interface AwsCdkPackageNames
interface AwsCdkPackageNames {}
Language-specific AWS CDK package names.
property assert
readonly assert?: string;
Fully qualified name of the assert library package Can be empty as it's only really available for javascript projects
property assertions
readonly assertions: string;
Fully qualified name of the assertions library package
property constructs
readonly constructs: string;
Fully qualified name of the constructs library package
property coreV1
readonly coreV1: string;
Fully qualified name of the core framework package for CDKv1
property coreV2
readonly coreV2: string;
Fully qualified name of the core framework package for CDKv2
interface AwsCdkPythonAppOptions
interface AwsCdkPythonAppOptions extends PythonProjectOptions, CdkConfigCommonOptions, AwsCdkDepsCommonOptions {}
Options for
AwsCdkPythonApp
property appEntrypoint
readonly appEntrypoint?: string;
The CDK app's entrypoint (relative to the source directory, which is "src" by default).
"app.py"
property testdir
readonly testdir?: string;
Python sources directory.
"tests"
Deprecated
Use
sampleTestdir
instead.
interface AwsCdkTypeScriptAppOptions
interface AwsCdkTypeScriptAppOptions extends TypeScriptProjectOptions, CdkConfigCommonOptions, AwsCdkDepsCommonOptions {}
property app
readonly app?: string;
The command line to execute in order to synthesize the CDK application (language specific).
property appEntrypoint
readonly appEntrypoint?: string;
The CDK app's entrypoint (relative to the source directory, which is "src" by default).
"main.ts"
property edgeLambdaAutoDiscover
readonly edgeLambdaAutoDiscover?: boolean;
Automatically adds an
cloudfront.experimental.EdgeFunction
for each.edge-lambda.ts
handler in your source tree. If this is disabled, you can manually add anawscdk.AutoDiscover
component to your project.true
property experimentalIntegRunner
readonly experimentalIntegRunner?: boolean;
Enable experimental support for the AWS CDK integ-runner.
false
Modifiers
@experimental
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Automatically discovers and creates integration tests for each
.integ.ts
file in under your test directory.true
property lambdaAutoDiscover
readonly lambdaAutoDiscover?: boolean;
Automatically adds an
awscdk.LambdaFunction
for each.lambda.ts
handler in your source tree. If this is disabled, you can manually add anawscdk.AutoDiscover
component to your project.true
property lambdaExtensionAutoDiscover
readonly lambdaExtensionAutoDiscover?: boolean;
Automatically adds an
awscdk.LambdaExtension
for each.lambda-extension.ts
entrypoint in your source tree. If this is disabled, you can manually add anawscdk.AutoDiscover
component to your projecttrue
property lambdaOptions
readonly lambdaOptions?: LambdaFunctionCommonOptions;
Common options for all AWS Lambda functions.
- default options
interface CdkConfigCommonOptions
interface CdkConfigCommonOptions {}
Common options for
cdk.json
.
property buildCommand
readonly buildCommand?: string;
A command to execute before synthesis. This command will be called when running
cdk synth
or whencdk watch
identifies a change in your source code before redeployment.- no build command
property cdkout
readonly cdkout?: string;
cdk.out directory.
"cdk.out"
property context
readonly context?: { [key: string]: any;};
Additional context to include in
cdk.json
.- no additional context
property featureFlags
readonly featureFlags?: boolean;
Include all feature flags in cdk.json
true
property requireApproval
readonly requireApproval?: ApprovalLevel;
To protect you against unintended changes that affect your security posture, the AWS CDK Toolkit prompts you to approve security-related changes before deploying them.
ApprovalLevel.BROADENING
property watchExcludes
readonly watchExcludes?: string[];
Glob patterns to exclude from
cdk watch
.[]
property watchIncludes
readonly watchIncludes?: string[];
Glob patterns to include in
cdk watch
.[]
interface CdkConfigOptions
interface CdkConfigOptions extends CdkConfigCommonOptions {}
Options for
CdkJson
.
property app
readonly app: string;
The command line to execute in order to synthesize the CDK application (language specific).
interface ConstructLibraryAwsOptions
interface ConstructLibraryAwsOptions extends AwsCdkConstructLibraryOptions {}
Deprecated
use
AwsCdkConstructLibraryOptions
interface EdgeLambdaAutoDiscoverOptions
interface EdgeLambdaAutoDiscoverOptions extends AutoDiscoverCommonOptions {}
Options for
EdgeLambdaAutoDiscover
property lambdaOptions
readonly lambdaOptions?: LambdaFunctionCommonOptions;
Options for AWS Lambda functions.
property srcdir
readonly srcdir: string;
Project source tree (relative to project output directory).
interface IntegrationTestAutoDiscoverOptions
interface IntegrationTestAutoDiscoverOptions extends AutoDiscoverCommonOptions, IntegrationTestAutoDiscoverBaseOptions {}
Options for
IntegrationTestAutoDiscover
property integrationTestOptions
readonly integrationTestOptions?: IntegrationTestCommonOptions;
Options for integration tests.
interface IntegrationTestCommonOptions
interface IntegrationTestCommonOptions {}
property destroyAfterDeploy
readonly destroyAfterDeploy?: boolean;
Destroy the test app after a successful deployment. If disabled, leaves the app deployed in the dev account. true
property pathMetadata
readonly pathMetadata?: boolean;
Enables path metadata, adding
aws:cdk:path
, with the defining construct's path, to the CloudFormation metadata for each synthesized resource. false
interface IntegrationTestOptions
interface IntegrationTestOptions extends IntegrationTestCommonOptions, IntegrationTestBaseOptions {}
Options for
IntegrationTest
.
interface LambdaAutoDiscoverOptions
interface LambdaAutoDiscoverOptions extends AutoDiscoverCommonOptions {}
Options for
LambdaAutoDiscover
property lambdaOptions
readonly lambdaOptions?: LambdaFunctionCommonOptions;
Options for AWS Lambda functions.
property srcdir
readonly srcdir: string;
Project source tree (relative to project output directory).
interface LambdaExtensionAutoDiscoverOptions
interface LambdaExtensionAutoDiscoverOptions extends AutoDiscoverCommonOptions {}
Options for
LambdaExtensionAutoDiscover
property lambdaExtensionOptions
readonly lambdaExtensionOptions?: LambdaExtensionCommonOptions;
Options for lambda extensions.
property srcdir
readonly srcdir: string;
Project source tree (relative to project output directory).
interface LambdaExtensionCommonOptions
interface LambdaExtensionCommonOptions {}
Common options for creating lambda extensions.
property bundlingOptions
readonly bundlingOptions?: BundlingOptions;
Bundling options for this AWS Lambda extension.
If not specified the default bundling options specified for the project
Bundler
instance will be used.- defaults
property compatibleRuntimes
readonly compatibleRuntimes?: LambdaRuntime[];
The extension's compatible runtimes.
interface LambdaExtensionOptions
interface LambdaExtensionOptions extends LambdaExtensionCommonOptions {}
Options for creating lambda extensions.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
AWS CDK dependency manager.
property constructFile
readonly constructFile?: string;
The name of the generated TypeScript source file. This file should also be under the source tree.
- The name of the entrypoint file, with the
-layer-version.ts
suffix instead of.lambda-extension.ts
.
property constructName
readonly constructName?: string;
The name of the generated
lambda.LayerVersion
subclass.- A pascal cased version of the name of the entrypoint file, with the extension
LayerVersion
(e.g.AppConfigLayerVersion
).
property entrypoint
readonly entrypoint: string;
A path from the project root directory to a TypeScript file which contains the AWS Lambda extension entrypoint (stand-alone script).
This is relative to the root directory of the project.
Example 1
"src/subdir/foo.lambda-extension.ts"
property name
readonly name?: string;
Name of the extension
- Derived from the entrypoint filename.
interface LambdaFunctionCommonOptions
interface LambdaFunctionCommonOptions {}
Common options for
LambdaFunction
. Applies to all functions in auto-discovery.
property awsSdkConnectionReuse
readonly awsSdkConnectionReuse?: boolean;
Whether to automatically reuse TCP connections when working with the AWS SDK for JavaScript.
This sets the
AWS_NODEJS_CONNECTION_REUSE_ENABLED
environment variable to1
.Not applicable when
edgeLambda
is set totrue
because environment variables are not supported in Lambda@Edge.See Also
https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html
true
property bundlingOptions
readonly bundlingOptions?: BundlingOptions;
Bundling options for this AWS Lambda function.
If not specified the default bundling options specified for the project
Bundler
instance will be used.- defaults
property edgeLambda
readonly edgeLambda?: boolean;
Whether to create a
cloudfront.experimental.EdgeFunction
instead of alambda.Function
.false
property runtime
readonly runtime?: LambdaRuntime;
The node.js version to target.
Runtime.NODEJS_18_X
interface LambdaFunctionOptions
interface LambdaFunctionOptions extends LambdaFunctionCommonOptions {}
Options for
Function
.
property cdkDeps
readonly cdkDeps: AwsCdkDeps;
AWS CDK dependency manager.
property constructFile
readonly constructFile?: string;
The name of the generated TypeScript source file. This file should also be under the source tree.
- The name of the entrypoint file, with the
-function.ts
suffix instead of.lambda.ts
.
property constructName
readonly constructName?: string;
The name of the generated
lambda.Function
subclass.- A pascal cased version of the name of the entrypoint file, with the extension
Function
(e.g.ResizeImageFunction
).
property entrypoint
readonly entrypoint: string;
A path from the project root directory to a TypeScript file which contains the AWS Lambda handler entrypoint (exports a
handler
function).This is relative to the root directory of the project.
Example 1
"src/subdir/foo.lambda.ts"
interface LambdaRuntimeOptions
interface LambdaRuntimeOptions {}
Options for the AWS Lambda function runtime
property defaultExternals
readonly defaultExternals?: string[];
Packages that are considered externals by default when bundling
['@aws-sdk/*']
enum ApprovalLevel
enum ApprovalLevel { NEVER = 'never', ANY_CHANGE = 'any-change', BROADENING = 'broadening',}
Which approval is required when deploying CDK apps.
member ANY_CHANGE
ANY_CHANGE = 'any-change'
Requires approval on any IAM or security-group-related change
member BROADENING
BROADENING = 'broadening'
Requires approval when IAM statements or traffic rules are added; removals don't require approval
member NEVER
NEVER = 'never'
Approval is never required
namespace build
module 'lib/build/index.d.ts' {}
class BuildWorkflow
class BuildWorkflow extends Component {}
constructor
constructor(project: Project, options: BuildWorkflowOptions);
property buildJobIds
readonly buildJobIds: string[];
Returns a list of job IDs that are part of the build.
property name
readonly name: string;
Name of generated github workflow
method addPostBuildJob
addPostBuildJob: (id: string, job: Job) => void;
Adds another job to the build workflow which is executed after the build job succeeded.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter id
The id of the new job
Parameter job
The job specification
method addPostBuildJobCommands
addPostBuildJobCommands: ( id: string, commands: string[], options?: AddPostBuildJobCommandsOptions) => void;
Run a sequence of commands as a job within the build workflow which is executed after the build job succeeded.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter options
Specify tools and other options
method addPostBuildJobTask
addPostBuildJobTask: (task: Task, options?: AddPostBuildJobTaskOptions) => void;
Run a task as a job within the build workflow which is executed after the build job succeeded.
The job will have access to build artifacts and will install project dependencies in order to be able to run any commands used in the tasks.
Jobs are executed _only_ if the build did NOT self mutate. If the build self-mutate, the branch will either be updated or the build will fail (in forks), so there is no point in executing the post-build job.
Parameter options
Specify tools and other options
method addPostBuildSteps
addPostBuildSteps: (...steps: JobStep[]) => void;
Adds steps that are executed after the build.
Parameter steps
The job steps
interface AddPostBuildJobCommandsOptions
interface AddPostBuildJobCommandsOptions {}
Options for
BuildWorkflow.addPostBuildJobCommands
property checkoutRepo
readonly checkoutRepo?: boolean;
Check out the repository at the pull request branch before commands are run.
false
property installDeps
readonly installDeps?: boolean;
Install project dependencies before running commands.
checkoutRepo
must also be set to true.Currently only supported for
NodeProject
.false
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property tools
readonly tools?: Tools;
Tools that should be installed before the commands are run.
interface AddPostBuildJobTaskOptions
interface AddPostBuildJobTaskOptions {}
Options for
BuildWorkflow.addPostBuildJobTask
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property tools
readonly tools?: Tools;
Tools that should be installed before the task is run.
interface BuildWorkflowCommonOptions
interface BuildWorkflowCommonOptions {}
property name
readonly name?: string;
Name of the buildfile (e.g. "build" becomes "build.yml").
"build"
property permissions
readonly permissions?: JobPermissions;
Permissions granted to the build job To limit job permissions for
contents
, the desired permissions have to be explicitly set, e.g.:{ contents: JobPermission.NONE }
{ contents: JobPermission.WRITE }
property preBuildSteps
readonly preBuildSteps?: JobStep[];
Steps to execute before the build. []
property workflowTriggers
readonly workflowTriggers?: Triggers;
Build workflow triggers "{ pullRequest: {}, workflowDispatch: {} }"
interface BuildWorkflowOptions
interface BuildWorkflowOptions extends BuildWorkflowCommonOptions {}
property artifactsDirectory
readonly artifactsDirectory?: string;
A name of a directory that includes build artifacts. "dist"
property buildTask
readonly buildTask: Task;
The task to execute in order to build the project.
property containerImage
readonly containerImage?: string;
The container image to use for builds. - the default workflow container
property env
readonly env?: { [key: string]: string;};
Build environment variables. {}
property gitIdentity
readonly gitIdentity?: GitIdentity;
Git identity to use for the workflow. - default identity
property mutableBuild
readonly mutableBuild?: boolean;
Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
This is enabled by default only if
githubTokenSecret
is set. Otherwise it is disabled, which implies that file changes that happen during build will not be pushed back to the branch.true
property postBuildSteps
readonly postBuildSteps?: JobStep[];
Steps to execute after build. []
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
namespace cdk
module 'lib/cdk/index.d.ts' {}
class AutoDiscoverBase
abstract class AutoDiscoverBase extends Component {}
Base class for auto-discovering and creating project subcomponents.
constructor
constructor(project: Project, options: AutoDiscoverBaseOptions);
property entrypoints
readonly entrypoints: string[];
Auto-discovered entry points with paths relative to the project directory.
class ConstructLibrary
abstract class ConstructLibrary extends JsiiProject {}
A multi-language library for CDK constructs.
constructor
constructor(options: ConstructLibraryOptions);
class IntegrationTestAutoDiscoverBase
class IntegrationTestAutoDiscoverBase extends AutoDiscoverBase {}
Base class for locating integration tests in the project's test tree.
constructor
constructor(project: Project, options: IntegrationTestAutoDiscoverBaseOptions);
class IntegrationTestBase
abstract class IntegrationTestBase extends Component {}
constructor
constructor(project: Project, options: IntegrationTestBaseOptions);
property assertTask
readonly assertTask: Task;
Synthesizes the integration test and compares against a local copy (runs during build).
property deployTask
readonly deployTask: Task;
Deploy the integration test and update the snapshot upon success.
property name
protected readonly name: string;
Integration test name.
property snapshotDir
protected readonly snapshotDir: string;
Snapshot output directory.
property snapshotTask
readonly snapshotTask: Task;
Just update snapshot (without deployment).
property tmpDir
protected readonly tmpDir: string;
Temporary directory for each integration test.
class JsiiDocgen
class JsiiDocgen extends Component {}
Creates a markdown file based on the jsii manifest: - Adds a
docgen
script to package.json - Runsjsii-docgen
after compilation - Enforces that markdown file is checked in
constructor
constructor(scope: IConstruct, options?: JsiiDocgenOptions);
class JsiiProject
class JsiiProject extends TypeScriptProject {}
Multi-language jsii library project
jsii
constructor
constructor(options: JsiiProjectOptions);
interface AutoDiscoverBaseOptions
interface AutoDiscoverBaseOptions {}
Options for
AutoDiscoverBase
property extension
readonly extension: string;
Locate files with the given extension.
Example 1
".integ.ts"
property projectdir
readonly projectdir: string;
Locate entrypoints in the given project directory.
Example 1
"test"
interface Catalog
interface Catalog {}
interface ConstructLibraryOptions
interface ConstructLibraryOptions extends JsiiProjectOptions {}
property catalog
readonly catalog?: Catalog;
Libraries will be picked up by the construct catalog when they are published to npm as jsii modules and will be published under:
https://awscdk.io/packages/[@SCOPE/]PACKAGE@VERSION
The catalog will also post a tweet to https://twitter.com/awscdkio with the package name, description and the above link. You can disable these tweets through
{ announce: false }
.You can also add a Twitter handle through
{ twitter: 'xx' }
which will be mentioned in the tweet.See Also
https://github.com/construct-catalog/catalog
- new version will be announced
interface IntegrationTestAutoDiscoverBaseOptions
interface IntegrationTestAutoDiscoverBaseOptions {}
Options for
IntegrationTestAutoDiscoverBase
property testdir
readonly testdir: string;
Test source tree.
interface IntegrationTestBaseOptions
interface IntegrationTestBaseOptions {}
Options for IntegrationTest
property entrypoint
readonly entrypoint: string;
A path from the project root directory to a TypeScript file which contains the integration test app.
This is relative to the root directory of the project.
Example 1
"test/subdir/foo.integ.ts"
property name
readonly name?: string;
Name of the integration test - Derived from the entrypoint filename.
property tsconfigPath
readonly tsconfigPath: string;
The path of the tsconfig.json file to use when running integration test cdk apps.
interface JsiiDocgenOptions
interface JsiiDocgenOptions {}
Options for
JsiiDocgen
interface JsiiDotNetTarget
interface JsiiDotNetTarget extends NugetPublishOptions {}
property dotNetNamespace
readonly dotNetNamespace: string;
property iconUrl
readonly iconUrl?: string;
property packageId
readonly packageId: string;
interface JsiiGoTarget
interface JsiiGoTarget extends GoPublishOptions {}
Go target configuration
property moduleName
readonly moduleName: string;
The name of the target repository in which this module will be published (e.g. github.com/owner/repo).
The module itself will always be published under a subdirectory named according to the
packageName
of the module (e.g. github.com/foo/bar/pkg).Example 1
github.com/owner/repo
property packageName
readonly packageName?: string;
The name of the Go package name.
If not specified, package name will be derived from the JavaScript module name by removing non-alphanumeric characters (e.g. @projen/foo-bar will be projenfoobar).
- derived from the JavaScript module name
property versionSuffix
readonly versionSuffix?: string;
A suffix appended at the end of the module version (e.g
"-devprefix"
).- none
interface JsiiJavaTarget
interface JsiiJavaTarget extends MavenPublishOptions {}
property javaPackage
readonly javaPackage: string;
property mavenArtifactId
readonly mavenArtifactId: string;
property mavenGroupId
readonly mavenGroupId: string;
interface JsiiProjectOptions
interface JsiiProjectOptions extends TypeScriptProjectOptions {}
property author
readonly author: string;
The name of the library author. $GIT_USER_NAME
property authorAddress
readonly authorAddress: string;
Email or URL of the library author. $GIT_USER_EMAIL
property compat
readonly compat?: boolean;
Automatically run API compatibility test against the latest version published to npm after compilation.
- You can manually run compatibility tests using
yarn compat
if this feature is disabled. - You can ignore compatibility failures by adding lines to a ".compatignore" file.false
property compatIgnore
readonly compatIgnore?: string;
Name of the ignore file for API compatibility tests.
".compatignore"
property compressAssembly
readonly compressAssembly?: boolean;
Emit a compressed version of the assembly false
property docgenFilePath
readonly docgenFilePath?: string;
File path for generated docs. "API.md"
property dotnet
readonly dotnet?: JsiiDotNetTarget;
Deprecated
use
publishToNuget
property excludeTypescript
readonly excludeTypescript?: string[];
Accepts a list of glob patterns. Files matching any of those patterns will be excluded from the TypeScript compiler input.
By default, jsii will include all *.ts files (except .d.ts files) in the TypeScript compiler input. This can be problematic for example when the package's build or test procedure generates .ts files that cannot be compiled with jsii's compiler settings.
property jsiiVersion
readonly jsiiVersion?: string;
Version of the jsii compiler to use.
Set to "*" if you want to manually manage the version of jsii in your project by managing updates to
package.json
on your own.NOTE: The jsii compiler releases since 5.0.0 are not semantically versioned and should remain on the same minor, so we recommend using a
~
dependency (e.g.~5.0.0
)."~5.6.0" "~5.8.0"
property publishToGo
readonly publishToGo?: JsiiGoTarget;
Publish Go bindings to a git repository. - no publishing
property publishToMaven
readonly publishToMaven?: JsiiJavaTarget;
Publish to maven - no publishing
property publishToNuget
readonly publishToNuget?: JsiiDotNetTarget;
Publish to NuGet - no publishing
property publishToPypi
readonly publishToPypi?: JsiiPythonTarget;
Publish to pypi - no publishing
property python
readonly python?: JsiiPythonTarget;
Deprecated
use
publishToPyPi
property repositoryUrl
readonly repositoryUrl: string;
Git repository URL. $GIT_REMOTE
property rootdir
readonly rootdir?: string;
"."
interface JsiiPythonTarget
interface JsiiPythonTarget extends PyPiPublishOptions {}
enum Stability
enum Stability { EXPERIMENTAL = 'experimental', STABLE = 'stable', DEPRECATED = 'deprecated',}
member DEPRECATED
DEPRECATED = 'deprecated'
member EXPERIMENTAL
EXPERIMENTAL = 'experimental'
member STABLE
STABLE = 'stable'
namespace cdk8s
module 'lib/cdk8s/index.d.ts' {}
class AutoDiscover
class AutoDiscover extends Component {}
Automatically discovers and creates
IntegrationTest
s from entry points found in the test tree.
constructor
constructor(project: Project, options: AutoDiscoverOptions);
class Cdk8sDeps
abstract class Cdk8sDeps extends Component {}
Manages dependencies on the CDK8s.
constructor
constructor(project: Project, options: Cdk8sDepsOptions);
property cdk8sMajorVersion
readonly cdk8sMajorVersion: number;
The major version of the CDK8s (e.g. 1, 2, ...)
property cdk8sMinimumVersion
readonly cdk8sMinimumVersion: string;
The minimum version of the CDK8s (e.g.
2.0.0
)
property cdk8sVersion
readonly cdk8sVersion: string;
The dependency requirement for CDK8s.
method packageNames
protected abstract packageNames: () => Cdk8sPackageNames;
Return a configuration object with information about package naming in various languages
class Cdk8sDepsPy
class Cdk8sDepsPy extends Cdk8sDeps {}
method packageNames
protected packageNames: () => Cdk8sPackageNames;
class Cdk8sPythonApp
class Cdk8sPythonApp extends PythonProject {}
CDK8s app in Python
cdk8s-app-py
constructor
constructor(options: Cdk8sPythonOptions);
property appEntrypoint
readonly appEntrypoint: string;
The CDK8s app entrypoint
property cdk8sDeps
readonly cdk8sDeps: Cdk8sDeps;
class Cdk8sTypeScriptApp
class Cdk8sTypeScriptApp extends TypeScriptAppProject {}
CDK8s app in TypeScript
cdk8s-app-ts
constructor
constructor(options: Cdk8sTypeScriptAppOptions);
property appEntrypoint
readonly appEntrypoint: string;
The CDK8s app entrypoint
property cdk8sDeps
readonly cdk8sDeps: Cdk8sDeps;
class ConstructLibraryCdk8s
class ConstructLibraryCdk8s extends ConstructLibrary {}
CDK8s construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the CDK for Kubernetes (CDK8s), with a friendly workflow and automatic publishing to the construct catalog.
cdk8s-construct
constructor
constructor(options: ConstructLibraryCdk8sOptions);
property cdk8sVersion
readonly cdk8sVersion: string;
The CDK8s version this app is using.
property constructsVersion
readonly constructsVersion: string;
The constructs version this app is using.
class IntegrationTest
class IntegrationTest extends IntegrationTestBase {}
CDK8S integration test.
constructor
constructor(project: Project, options: IntegrationTestOptions);
class IntegrationTestAutoDiscover
class IntegrationTestAutoDiscover extends IntegrationTestAutoDiscoverBase {}
Discovers and creates integration tests from files in the test root.
constructor
constructor(project: Project, options: IntegrationTestAutoDiscoverOptions);
interface AutoDiscoverOptions
interface AutoDiscoverOptions extends IntegrationTestAutoDiscoverOptions {}
Options for
AutoDiscover
.
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Automatically discover integration tests
true
interface Cdk8sDepsCommonOptions
interface Cdk8sDepsCommonOptions {}
Options for
Cdk8sDeps
property cdk8sCliVersion
readonly cdk8sCliVersion?: string;
Minimum version of the cdk8s-cli to depend on.
"2.0.28"
property cdk8sCliVersionPinning
readonly cdk8sCliVersionPinning?: boolean;
Use pinned version instead of caret version for cdk8s-cli.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property cdk8sPlus
readonly cdk8sPlus?: boolean;
Include cdk8s-plus
true
property cdk8sPlusVersion
readonly cdk8sPlusVersion?: string;
Minimum version of the cdk8s-plus-XX to depend on.
"2.0.0-rc.26"
property cdk8sPlusVersionPinning
readonly cdk8sPlusVersionPinning?: boolean;
Use pinned version instead of caret version for cdk8s-plus-17.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property cdk8sVersion
readonly cdk8sVersion: string;
Minimum version of the cdk8s to depend on.
"2.3.33"
property cdk8sVersionPinning
readonly cdk8sVersionPinning?: boolean;
Use pinned version instead of caret version for cdk8s.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property constructsVersion
readonly constructsVersion?: string;
Minimum version of the
constructs
library to depend on."10.1.42"
property constructsVersionPinning
readonly constructsVersionPinning?: boolean;
Use pinned version instead of caret version for constructs.
You can use this to prevent yarn to mix versions for your consructs package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property k8sMinorVersion
readonly k8sMinorVersion?: number;
The cdk8s-plus library depends of Kubernetes minor version For example, cdk8s-plus-22 targets kubernetes version 1.22.0 cdk8s-plus-21 targets kubernetes version 1.21.0
22
interface Cdk8sDepsOptions
interface Cdk8sDepsOptions extends Cdk8sDepsCommonOptions {}
property cdk8sCliDependency
readonly cdk8sCliDependency: boolean;
Add cdk8s-cli only to Node projects
false
property dependencyType
readonly dependencyType: DependencyType;
The type of dependency to use for runtime CDK8s and
constructs
modules.For libraries, use peer dependencies and for apps use runtime dependencies.
interface Cdk8sPackageNames
interface Cdk8sPackageNames {}
property cdk8s
readonly cdk8s: string;
Fully qualified name of the core framework package
property cdk8sClient
readonly cdk8sClient?: string;
Fully qualified name of the client package. Used only on Node projects
property cdk8sPlus
readonly cdk8sPlus: string;
Fully qualified name of the cdk9s-plus-XX library package
property constructs
readonly constructs: string;
Fully qualified name of the constructs library package
interface Cdk8sPythonOptions
interface Cdk8sPythonOptions extends PythonProjectOptions, Cdk8sDepsCommonOptions {}
Options for
Cdk8sPythonApp
property appEntrypoint
readonly appEntrypoint?: string;
The CDK8s app's entrypoint
"app.py"
property cdk8sImports
readonly cdk8sImports?: string[];
Import additional specs
- no additional specs imported
property k8sSpecVersion
readonly k8sSpecVersion?: string;
Import a specific Kubernetes spec version.
- Use the cdk8s default
interface Cdk8sTypeScriptAppOptions
interface Cdk8sTypeScriptAppOptions extends TypeScriptProjectOptions, Cdk8sDepsCommonOptions {}
property appEntrypoint
readonly appEntrypoint?: string;
The CDK8s app's entrypoint (relative to the source directory, which is "src" by default).
"main.ts"
property cdk8sImports
readonly cdk8sImports?: string[];
Import additional specs
- no additional specs imported
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Automatically adds an
cdk8s.IntegrationTest
for each.integ.ts
app in your test directory. If this is disabled, you can manually add ancdk8s.AutoDiscover
component to your project.true
property k8sSpecVersion
readonly k8sSpecVersion?: string;
Import a specific Kubernetes spec version.
- Use the cdk8s default
interface ConstructLibraryCdk8sOptions
interface ConstructLibraryCdk8sOptions extends ConstructLibraryOptions {}
property cdk8sPlusVersionPinning
readonly cdk8sPlusVersionPinning?: boolean;
Use pinned version instead of caret version for cdk8s-plus-17.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property cdk8sVersion
readonly cdk8sVersion: string;
Minimum target version this library is tested against.
"1.4.10"
property cdk8sVersionPinning
readonly cdk8sVersionPinning?: boolean;
Use pinned version instead of caret version for CDK8s.
You can use this to prevent yarn to mix versions for your CDK8s package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property constructsVersion
readonly constructsVersion?: string;
constructs verion
"3.3.196"
property constructsVersionPinning
readonly constructsVersionPinning?: boolean;
Use pinned version instead of caret version for constructs.
You can use this to prevent yarn to mix versions for your consructs package and to prevent auto-updates. If you use experimental features this will let you define the moment you include breaking changes.
false
property integrationTestAutoDiscover
readonly integrationTestAutoDiscover?: boolean;
Automatically adds an
cdk8s.IntegrationTest
for each.integ.ts
app in your test directory. If this is disabled, you can manually add ancdk8s.AutoDiscover
component to your project.true
interface IntegrationTestAutoDiscoverOptions
interface IntegrationTestAutoDiscoverOptions extends IntegrationTestAutoDiscoverBaseOptions {}
property tsconfigPath
readonly tsconfigPath: string;
Path to the tsconfig file to use for integration tests.
interface IntegrationTestOptions
interface IntegrationTestOptions extends IntegrationTestBaseOptions {}
Options for IntegrationTest
namespace cdktf
module 'lib/cdktf/index.d.ts' {}
class ConstructLibraryCdktf
class ConstructLibraryCdktf extends ConstructLibrary {}
CDKTF construct library project
A multi-language (jsii) construct library which vends constructs designed to use within the CDK for Terraform (CDKTF), with a friendly workflow and automatic publishing to the construct catalog.
cdktf-construct
constructor
constructor(options: ConstructLibraryCdktfOptions);
interface ConstructLibraryCdktfOptions
interface ConstructLibraryCdktfOptions extends ConstructLibraryOptions {}
property cdktfVersion
readonly cdktfVersion: string;
Minimum target version this library is tested against. "^0.13.0"
property constructsVersion
readonly constructsVersion?: string;
Construct version to use "^10.3.0"
namespace circleci
module 'lib/circleci/index.d.ts' {}
variable FilterMainBranchOnly
const FilterMainBranchOnly: Filter;
constant to create a filter to make a job or workflow only run on master
function isObjectContainingFieldExactly
isObjectContainingFieldExactly: (obj: any, field: string) => boolean;
class Circleci
class Circleci extends Component {}
Circleci Class to manage
.circleci/config.yml
. Check projen's docs for more information.See Also
https://circleci.com/docs/2.0/configuration-reference/
constructor
constructor(project: Project, options?: CircleCiProps);
property file
readonly file: YamlFile;
The yaml file for the Circleci pipeline
method addOrb
addOrb: (name: string, orb: string) => void;
Add a Circleci Orb to pipeline. Will throw error if the orb already exists
Parameter name
Parameter orb
method addWorkflow
addWorkflow: (workflow: Workflow) => void;
add new workflow to existing pipeline
Parameter workflow
interface CircleCiProps
interface CircleCiProps {}
Options for class Circleci
See Also
https://circleci.com/docs/2.0/configuration-reference/
property jobs
readonly jobs?: Job[];
List of Jobs to create unique steps per pipeline, e.g.
jobs: [{identifier: "compile",docker: { image: "golang:alpine" }steps: ["checkout", run: {command: "go build ."}]}]See Also
https://circleci.com/docs/2.0/configuration-reference/#jobs
property orbs
readonly orbs?: Record<string, string>;
Contains a map of CirclCi Orbs
orbs: {node: "circleci/node@5.0.1"slack: "circleci/slack@4.8.3"}
property setup
readonly setup?: boolean;
The setup field enables you to conditionally trigger configurations from outside the primary .circleci parent directory, update pipeline parameters, or generate customized configurations.
See Also
https://circleci.com/docs/2.0/configuration-reference/#setup
property version
readonly version?: number;
pipeline version
2.1
See Also
https://circleci.com/docs/2.0/configuration-reference/#version
property workflows
readonly workflows?: Workflow[];
List of Workflows of pipeline, e.g.
workflows: {{identifier: "build",jobs: [{identifier: "node/install",context: ["npm"],}]}}See Also
https://circleci.com/docs/2.0/configuration-reference/#workflows
interface Docker
interface Docker {}
Options for docker executor
See Also
https://circleci.com/docs/2.0/configuration-reference/#docker
property auth
readonly auth?: Record<string, string>;
Authentication for registries using standard docker login credentials
property awsAuth
readonly awsAuth?: Record<string, string>;
Authentication for AWS Elastic Container Registry (ECR)
property command
readonly command?: string[];
The command used as pid 1 (or args for entrypoint) when launching the container
property entrypoint
readonly entrypoint?: string[];
The command used as executable when launching the container
property environment
readonly environment?: Record<string, string | number | boolean>;
A map of environment variable names and values
property image
readonly image: string;
The name of a custom docker image to use
property name
readonly name?: string;
The name the container is reachable by. By default, container services are accessible through localhost
property user
readonly user?: string;
Which user to run commands as within the Docker container
interface Filter
interface Filter {}
The branches key controls whether the current branch should have a schedule trigger created for it, where current branch is the branch containing the config.yml file with the trigger stanza. That is, a push on the main branch will only schedule a workflow for the main branch.
Branches can have the keys only and ignore which either map to a single string naming a branch. You may also use regular expressions to match against branches by enclosing them with /’s, or map to a list of such strings. Regular expressions must match the entire string.
Any branches that match only will run the job. Any branches that match ignore will not run the job. If neither only nor ignore are specified then all branches will run the job. If both only and ignore are specified the only is considered before ignore.
See Also
https://circleci.com/docs/2.0/configuration-reference/#filters
interface FilterConfig
interface FilterConfig {}
set an inclusive or exclusive filter
See Also
https://circleci.com/docs/2.0/configuration-reference/#filters
interface Job
interface Job extends INamed {}
A Workflow is comprised of one or more uniquely named jobs. Jobs are specified in the jobs map, see Sample 2.0 config.yml for two examples of a job map. The name of the job is the key in the map, and the value is a map describing the job.
See Also
https://circleci.com/docs/2.0/configuration-reference/#jobs
interface Job
interface Job {}
Each job consists of the job’s name as a key and a map as a value. A name should be case insensitive unique within a current jobs list.
See Also
https://circleci.com/docs/2.0/configuration-reference/#job_name
property docker
readonly docker?: Docker[];
property environment
readonly environment?: Record<string, string | number | boolean>;
A map of environment variable names and values.
property machine
readonly machine?: Machine;
property macos
readonly macos?: Macos;
property parallelism
readonly parallelism?: number;
Number of parallel instances of this job to run (default: 1)
property parameters
readonly parameters?: Record<string, PipelineParameter>;
Parameters for making a job explicitly configurable in a workflow.
property resourceClass
readonly resourceClass?: ResourceClass | string;
property shell
readonly shell?: string;
Shell to use for execution command in all steps. Can be overridden by shell in each step
property steps
readonly steps?: any[];
no type support here, for syntax
property workingDirectory
readonly workingDirectory?: string;
In which directory to run the steps. Will be interpreted as an absolute path. Default:
~/project
interface Machine
interface Machine {}
property dockerLayerCaching
readonly dockerLayerCaching?: string;
enable docker layer caching
See Also
https://circleci.com/docs/2.0/configuration-reference/#available-machine-images
property image
readonly image: string;
The VM image to use.
See Also
https://circleci.com/docs/2.0/configuration-reference/#available-machine-images
interface Macos
interface Macos {}
CircleCI supports running jobs on macOS, to allow you to build, test, and deploy apps for macOS, iOS, tvOS and watchOS. To run a job in a macOS virtual machine, you must add the macos key to the top-level configuration for the job and specify the version of Xcode you would like to use.
See Also
https://circleci.com/docs/2.0/configuration-reference/#macos
property xcode
readonly xcode: string;
The version of Xcode that is installed on the virtual machine
interface Matrix
interface Matrix {}
The matrix stanza allows you to run a parameterized job multiple times with different arguments.
See Also
https://circleci.com/docs/2.0/configuration-reference/#matrix-requires-version-21
property alias
readonly alias?: string;
An alias for the matrix, usable from another job’s requires stanza. Defaults to the name of the job being executed
property parameters
readonly parameters?: Record<string, string[] | number[]>;
A map of parameter names to every value the job should be called with
interface PipelineParameter
interface PipelineParameter {}
Parameters are declared by name under a job, command, or executor.
See Also
https://circleci.com/docs/2.0/reusing-config#using-the-parameters-declaration
property default
readonly default?: string | number | boolean;
The default value for the parameter. If not present, the parameter is implied to be required.
property description
readonly description?: string;
Used to generate documentation for your orb.
property type
readonly type: PipelineParameterType;
The parameter type, required.
interface Run
interface Run {}
Used for invoking all command-line programs, taking either a map of configuration values, or, when called in its short-form, a string that will be used as both the command and name. Run commands are executed using non-login shells by default, so you must explicitly source any dotfiles as part of the command.
Not used because type incompatible types in steps array
See Also
https://circleci.com/docs/2.0/configuration-reference/#run
property background
readonly background?: string;
Whether this step should run in the background (default: false)
property command
readonly command: string;
Command to run via the shell
property environment
readonly environment?: string;
Additional environmental variables, locally scoped to command
property name
readonly name?: string;
Title of the step to be shown in the CircleCI UI (default: full command)
property noOutputTimeout
readonly noOutputTimeout?: string;
Elapsed time the command can run without output such as “20m”, “1.25h”, “5s”. The default is 10 minutes
property shell
readonly shell?: string;
Shell to use for execution command
property when
readonly when?: JobWhen | string;
Specify when to enable or disable the step.
property workingDirectory
readonly workingDirectory?: string;
In which directory to run this step. Will be interpreted relative to the working_directory of the job). (default: .)
interface Schedule
interface Schedule {}
A workflow may have a schedule indicating it runs at a certain time.
See Also
https://circleci.com/docs/2.0/configuration-reference/#schedule
interface StepRun
interface StepRun {}
Execution steps for Job
See Also
https://circleci.com/docs/2.0/configuration-reference/#steps
property run
readonly run?: Run;
interface Triggers
interface Triggers {}
Specifies which triggers will cause this workflow to be executed. Default behavior is to trigger the workflow when pushing to a branch.
See Also
https://circleci.com/docs/2.0/configuration-reference/#triggers
property schedule
readonly schedule?: Schedule;
interface Workflow
interface Workflow extends INamed {}
Used for orchestrating all jobs. Each workflow consists of the workflow name as a key and a map as a value. A name should be unique within the current config.yml. The top-level keys for the Workflows configuration are version and jobs.
See Also
https://circleci.com/docs/2.0/configuration-reference/#workflows
interface WorkflowJob
interface WorkflowJob extends INamed {}
A Job is part of Workflow. A Job can be created with Job or it can be provided by the orb
See Also
https://circleci.com/docs/2.0/configuration-reference/#jobs-in-workflow
property context
readonly context?: string[];
The name of the context(s). The initial default name is org-global. Each context name must be unique.
property filters
readonly filters?: Filter;
Job Filters can have the key branches or tags
property matrix
readonly matrix?: Matrix;
property name
readonly name?: string;
A replacement for the job name. Useful when calling a job multiple times
property orbParameters
readonly orbParameters?: Record<string, string | number | boolean>;
Parameters passed to job when referencing a job from orb
property requires
readonly requires?: string[];
A list of jobs that must succeed for the job to start.
property type
readonly type?: JobType;
A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed.
enum JobType
enum JobType { APPROVAL = 'approval',}
A job may have a type of approval indicating it must be manually approved before downstream jobs may proceed
See Also
https://circleci.com/docs/2.0/configuration-reference/#type
member APPROVAL
APPROVAL = 'approval'
enum JobWhen
enum JobWhen { ALWAYS = 'always', ON_SUCCESS = 'on_success', ON_FAIL = 'on_fail',}
Specify when to enable or disable the step.
See Also
https://circleci.com/docs/2.0/configuration-reference/#steps
member ALWAYS
ALWAYS = 'always'
member ON_FAIL
ON_FAIL = 'on_fail'
member ON_SUCCESS
ON_SUCCESS = 'on_success'
enum PipelineParameterType
enum PipelineParameterType { STRING = 'string', BOOLEAN = 'boolean', INTEGER = 'integer', ENUM = 'enum',}
Pipeline parameter types
See Also
https://circleci.com/docs/2.0/reusing-config#parameter-syntax
enum ResourceClass
enum ResourceClass { SMALL = 'small', MEDIUM = 'medium', MEDIUM_PLUS = 'medium+', LARGE_X = 'xlarge', LARGE_2X = '2xlarge', LARGE_2X_PLUS = '2xlarge+',}
The resource_class feature allows configuring CPU and RAM resources for each job. Different resource classes are available for different executors, as described in the tables below.
See Also
https://circleci.com/docs/2.0/configuration-reference/#resourceclass
member LARGE_2X
LARGE_2X = '2xlarge'
member LARGE_2X_PLUS
LARGE_2X_PLUS = '2xlarge+'
member LARGE_X
LARGE_X = 'xlarge'
member MEDIUM
MEDIUM = 'medium'
member MEDIUM_PLUS
MEDIUM_PLUS = 'medium+'
member SMALL
SMALL = 'small'
namespace github
module 'lib/github/index.d.ts' {}
class AutoApprove
class AutoApprove extends Component {}
Auto approve pull requests that meet a criteria
constructor
constructor(github: GitHub, options?: AutoApproveOptions);
property label
readonly label: string;
class AutoMerge
class AutoMerge extends Component {}
Automatically merge Pull Requests using Mergify
> [!NOTE] > GitHub now natively provides the same features, so you don't need Mergify > anymore. See
GitHubOptions.mergeQueue
andMergeQueueOptions.autoQueue
.If
buildJob
is specified, the specified GitHub workflow job ID is required to succeed in order for the PR to be merged.approvedReviews
specified the number of code review approvals required for the PR to be merged.See Also
https://mergify.com/
constructor
constructor(github: GitHub, options?: AutoMergeOptions);
method addConditions
addConditions: (...conditions: string[]) => void;
Adds conditions to the auto merge rule.
Parameter conditions
The conditions to add (mergify syntax)
method addConditionsLater
addConditionsLater: (later: IAddConditionsLater) => void;
Adds conditions that will be rendered only during synthesis.
Parameter later
The later
class AutoQueue
class AutoQueue extends Component {}
Automatically add pull requests to the merge queue PRs will be merged once they pass required checks.
constructor
constructor(scope: IConstruct, options?: gh.AutoQueueOptions);
class Dependabot
class Dependabot extends Component {}
Defines dependabot configuration for node projects.
Since module versions are managed in projen, the versioning strategy will be configured to "lockfile-only" which means that only updates that can be done on the lockfile itself will be proposed.
constructor
constructor(github: GitHub, options?: DependabotOptions);
property config
readonly config: any;
The raw dependabot configuration.
See Also
https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates
property ignoresProjen
readonly ignoresProjen: boolean;
Whether or not projen is also upgraded in this config,
method addAllow
addAllow: (dependencyName: string) => void;
Allows a dependency from automatic updates.
Parameter dependencyName
Use to allow updates for dependencies with matching names, optionally using
*
to match zero or more characters.
method addIgnore
addIgnore: (dependencyName: string, ...versions: string[]) => void;
Ignores a dependency from automatic updates.
Parameter dependencyName
Use to ignore updates for dependencies with matching names, optionally using
*
to match zero or more characters.Parameter versions
Use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager (for example:
^1.0.0
for npm, or~> 2.0
for Bundler).
class GitHub
class GitHub extends Component {}
constructor
constructor(project: Project, options?: GitHubOptions);
property actions
readonly actions: GitHubActionsProvider;
The GitHub Actions provider used to manage the versions of actions used in steps
property downloadLfs
readonly downloadLfs: boolean;
Whether downloading from LFS is enabled for this GitHub project
property mergeQueue
readonly mergeQueue?: MergeQueue;
The
MergeQueue
component configured on this repository This isundefined
if merge queues are not enabled for this repository.
property mergify
readonly mergify?: Mergify;
The
Mergify
component configured on this repository This isundefined
if Mergify is not enabled for this repository.
property projenCredentials
readonly projenCredentials: GithubCredentials;
GitHub API authentication method used by projen workflows.
property workflows
readonly workflows: GithubWorkflow[];
All workflows.
property workflowsEnabled
readonly workflowsEnabled: boolean;
Are workflows enabled?
method addDependabot
addDependabot: (options?: DependabotOptions) => Dependabot;
method addPullRequestTemplate
addPullRequestTemplate: (...content: string[]) => PullRequestTemplate;
method addWorkflow
addWorkflow: (name: string) => GithubWorkflow;
Adds a workflow to the project.
Parameter name
Name of the workflow
Returns
a GithubWorkflow instance
method of
static of: (project: Project) => GitHub | undefined;
Returns the
GitHub
component of a project orundefined
if the project does not have a GitHub component.
method tryFindWorkflow
tryFindWorkflow: (name: string) => undefined | GithubWorkflow;
Finds a GitHub workflow by name. Returns
undefined
if the workflow cannot be found.Parameter name
The name of the GitHub workflow
class GitHubActionsProvider
class GitHubActionsProvider {}
Manage the versions used for GitHub Actions used in steps
method get
get: (action: string) => string;
Resolve an action name to the version that should be used, taking into account any overrides.
method set
set: (action: string, override: string) => void;
Define an override for a given action.
Specify the action name without a version to override all usages of the action. You can also override a specific action version, by providing the version string. Specific overrides take precedence over overrides without a version.
If an override for the same action name is set multiple times, the last override is used.
Example 1
// Force any use of
actions/checkout
to use a pin a specific commit project.github.actions.set("actions/checkout", "actions/checkout@aaaaaa");// But pin usage of
v4
to a different commit project.github.actions.set("actions/checkout@v4", "actions/checkout@ffffff");
class GithubCredentials
class GithubCredentials {}
Represents a method of providing GitHub API access for projen workflows.
property setupSteps
readonly setupSteps: JobStep[];
Setup steps to obtain GitHub credentials.
property tokenRef
readonly tokenRef: string;
The value to use in a workflow when a GitHub token is expected. This typically looks like "${{ some.path.to.a.value }}".
method fromApp
static fromApp: (options?: GithubCredentialsAppOptions) => GithubCredentials;
Provide API access through a GitHub App.
The GitHub App must be installed on the GitHub repo, its App ID and a private key must be added as secrets to the repo. The name of the secrets can be specified here.
See Also
https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app
https://projen.io/docs/integrations/github/#github-app - app id stored in "PROJEN_APP_ID" and private key stored in "PROJEN_APP_PRIVATE_KEY" with all permissions attached to the app
method fromPersonalAccessToken
static fromPersonalAccessToken: ( options?: GithubCredentialsPersonalAccessTokenOptions) => GithubCredentials;
Provide API access through a GitHub personal access token.
The token must be added as a secret to the GitHub repo, and the name of the secret can be specified here.
See Also
https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token - a secret named "PROJEN_GITHUB_TOKEN"
class GitHubProject
class GitHubProject extends Project {}
GitHub-based project.
Deprecated
This is a *temporary* class. At the moment, our base project types such as
NodeProject
andJavaProject
are derived from this, but we want to be able to use these project types outside of GitHub as well. One of the next steps to address this is to abstract workflows so that different "engines" can be used to implement our CI/CD solutions.
constructor
constructor(options: GitHubProjectOptions);
property autoApprove
readonly autoApprove?: AutoApprove;
Auto approve set up for this project.
property devContainer
readonly devContainer: DevContainer;
Access for .devcontainer.json (used for GitHub Codespaces)
This will be
undefined
if devContainer boolean is false
property github
readonly github: GitHub;
Access all github components.
This will be
undefined
for subprojects.
property gitpod
readonly gitpod: Gitpod;
Access for Gitpod
This will be
undefined
if gitpod boolean is false
property projectType
readonly projectType: ProjectType;
property vscode
readonly vscode: VsCode;
Access all VSCode components.
This will be
undefined
for subprojects.
method annotateGenerated
annotateGenerated: (glob: string) => void;
Marks the provided file(s) as being generated. This is achieved using the github-linguist attributes. Generated files do not count against the repository statistics and language breakdown.
Parameter glob
the glob pattern to match (could be a file path).
See Also
https://github.com/github/linguist/blob/master/docs/overrides.md
class GithubWorkflow
class GithubWorkflow extends Component {}
Workflow for GitHub.
A workflow is a configurable automated process made up of one or more jobs.
See Also
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
constructor
constructor(github: GitHub, name: string, options?: GithubWorkflowOptions);
Parameter github
The GitHub component of the project this workflow belongs to.
Parameter name
The name of the workflow, displayed under the repository's "Actions" tab.
Parameter options
Additional options to configure the workflow.
property concurrency
readonly concurrency?: ConcurrencyOptions;
The concurrency configuration of the workflow. undefined means no concurrency limitations.
property env
readonly env?: Record<string, string>;
Additional environment variables to set for the workflow.
property file
readonly file: YamlFile;
The workflow YAML file. May not exist if
workflowsEnabled
is false onGitHub
.
property name
readonly name: string;
The name of the workflow. GitHub displays the names of your workflows under your repository's "Actions" tab.
See Also
https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name
property projenCredentials
readonly projenCredentials: GithubCredentials;
GitHub API authentication method used by projen workflows.
property runName
runName?: string;
The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If
run-name
is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by apush
orpull_request
event, it is set as the commit message.This value can include expressions and can reference
github
andinputs
contexts.
method addJob
addJob: ( id: string, job: workflows.Job | workflows.JobCallingReusableWorkflow) => void;
Adds a single job to the workflow.
Parameter id
The job name (unique within the workflow)
Parameter job
The job specification
method addJobs
addJobs: ( jobs: Record<string, workflows.Job | workflows.JobCallingReusableWorkflow>) => void;
Add jobs to the workflow.
Parameter jobs
Jobs to add.
method getJob
getJob: (id: string) => workflows.Job | workflows.JobCallingReusableWorkflow;
Get a single job from the workflow.
Parameter id
The job name (unique within the workflow)
method on
on: (events: workflows.Triggers) => void;
Add events to triggers the workflow.
Parameter events
The event(s) to trigger the workflow.
method removeJob
removeJob: (id: string) => void;
Removes a single job to the workflow.
Parameter id
The job name (unique within the workflow)
method updateJob
updateJob: ( id: string, job: workflows.Job | workflows.JobCallingReusableWorkflow) => void;
Updates a single job to the workflow.
Parameter id
The job name (unique within the workflow)
method updateJobs
updateJobs: ( jobs: Record<string, workflows.Job | workflows.JobCallingReusableWorkflow>) => void;
Updates jobs for this worklow Does a complete replace, it does not try to merge the jobs
Parameter jobs
Jobs to update.
class MergeQueue
class MergeQueue extends Component {}
Merge pull requests using a merge queue
constructor
constructor(scope: IConstruct, options?: MergeQueueOptions);
method preSynthesize
preSynthesize: () => void;
class Mergify
class Mergify extends Component {}
constructor
constructor(github: GitHub, options?: MergifyOptions);
method addQueue
addQueue: (queue: MergifyQueue) => void;
method addRule
addRule: (rule: MergifyRule) => void;
class PullRequestBackport
class PullRequestBackport extends Component {}
constructor
constructor(scope: IConstruct, options?: PullRequestBackportOptions);
property file
readonly file: JsonFile;
property workflow
readonly workflow: GithubWorkflow;
class PullRequestLint
class PullRequestLint extends Component {}
Configure validations to run on GitHub pull requests. Only generates a file if at least one linter is configured.
constructor
constructor(github: GitHub, options?: PullRequestLintOptions);
method preSynthesize
preSynthesize: () => void;
class PullRequestTemplate
class PullRequestTemplate extends TextFile {}
Template for GitHub pull requests.
constructor
constructor(github: GitHub, options?: PullRequestTemplateOptions);
method of
static of: (project: Project) => PullRequestTemplate | undefined;
Returns the
PullRequestTemplate
instance associated with a project orundefined
if there is no PullRequestTemplate.Parameter project
The project
Returns
A PullRequestTemplate
class Stale
class Stale extends Component {}
Warns and then closes issues and PRs that have had no activity for a specified amount of time.
The default configuration will:
* Add a "Stale" label to pull requests after 14 days and closed after 2 days * Add a "Stale" label to issues after 60 days and closed after 7 days * If a comment is added, the label will be removed and timer is restarted.
See Also
https://github.com/actions/stale
constructor
constructor(github: GitHub, options?: StaleOptions);
class TaskWorkflow
class TaskWorkflow extends GithubWorkflow {}
A GitHub workflow for common build tasks within a project.
constructor
constructor(github: GitHub, options: TaskWorkflowOptions);
property artifactsDirectory
readonly artifactsDirectory?: string;
property jobId
readonly jobId: string;
class TaskWorkflowJob
class TaskWorkflowJob extends Component {}
The primary or initial job of a TaskWorkflow.
{Job}
constructor
constructor(scope: IConstruct, task: Task, options: TaskWorkflowJobOptions);
Parameter scope
should be part of the project the Task belongs to.
Parameter task
the main task that is run as part of this job.
Parameter options
options to configure the TaskWorkflowJob.
property concurrency
readonly concurrency?: {};
property container
readonly container?: ContainerOptions;
property continueOnError
readonly continueOnError?: boolean;
property defaults
readonly defaults?: JobDefaults;
property env
readonly env?: Record<string, string>;
property environment
readonly environment?: {};
property if
readonly if?: string;
property name
readonly name?: string;
property needs
readonly needs?: string[];
property outputs
readonly outputs?: Record<string, JobStepOutput>;
property permissions
readonly permissions: JobPermissions;
property runsOn
readonly runsOn?: string[];
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
property services
readonly services?: Record<string, ContainerOptions>;
property steps
readonly steps: JobStep[];
property strategy
readonly strategy?: JobStrategy;
property timeoutMinutes
readonly timeoutMinutes?: number;
property tools
readonly tools?: Tools;
class WorkflowActions
class WorkflowActions {}
A set of utility functions for creating GitHub actions in workflows.
method checkoutWithPatch
static checkoutWithPatch: (options?: CheckoutWithPatchOptions) => JobStep[];
Checks out a repository and applies a git patch that was created using
uploadGitPatch
.Parameter options
Options
Returns
Job steps
method createPullRequest
static createPullRequest: (options: CreatePullRequestOptions) => JobStep[];
A step that creates a pull request based on the current repo state.
Parameter options
Options
Returns
Job steps
method setupGitIdentity
static setupGitIdentity: (id: GitIdentity) => JobStep[];
Configures the git identity (user name and email).
Parameter id
The identity to use
Returns
Job steps
Deprecated
use
WorkflowSteps.setupGitIdentity
instead
method uploadGitPatch
static uploadGitPatch: (options: UploadGitPatchOptions) => JobStep[];
Creates a .patch file from the current git diff and uploads it as an artifact. Use
checkoutWithPatch
to download and apply in another job.If a patch was uploaded, the action can optionally fail the job.
Parameter options
Options
Returns
Job steps
class WorkflowJobs
class WorkflowJobs {}
A set of utility functions for creating jobs in GitHub Workflows.
method pullRequestFromPatch
static pullRequestFromPatch: (options: PullRequestFromPatchOptions) => Job;
Creates a pull request with the changes of a patch file.
Returns
Job
class WorkflowSteps
class WorkflowSteps {}
A collection of very commonly used, individual, GitHub Workflow Job steps.
method checkout
static checkout: (options?: CheckoutOptions) => JobStep;
Checks out a repository.
Parameter options
Options to configure the
checkout
JobStepReturns
A JobStep that checks out a repository
method downloadArtifact
static downloadArtifact: (options?: DownloadArtifactOptions) => JobStep;
Downloads an artifact.
Parameter options
Options to configure the
download-artifact
JobStepReturns
A JobStep that downloads an artifact
method setupGitIdentity
static setupGitIdentity: (options: SetupGitIdentityOptions) => JobStep;
Configures the git identity (user name and email).
Parameter options
Options to configure the git identity JobStep
Returns
Job step that configures the provided git identity
method tagExists
static tagExists: (tag: string, options: JobStepConfiguration) => JobStep;
Checks if a tag exists.
Requires a checkout step to have been run before this step with "fetch-depth" set to "0".
Outputs: -
exists
: A string value of 'true' or 'false' indicating if the tag exists.Parameter tag
The tag to check. You may use valid bash code instead of a literal string in this field.
Parameter options
Options to configure the
tag-exists
JobStepReturns
Job step that checks if the provided tag exists
method uploadArtifact
static uploadArtifact: (options: UploadArtifactOptions) => JobStep;
Uploads an artifact.
Parameter options
Options to configure the
upload-artifact
JobStepReturns
A JobStep that uploads an artifact
interface AutoApproveOptions
interface AutoApproveOptions {}
Options for 'AutoApprove'
property allowedUsernames
readonly allowedUsernames?: string[];
Only pull requests authored by these Github usernames will be auto-approved. ['github-bot']
property label
readonly label?: string;
Only pull requests with this label will be auto-approved. 'auto-approve'
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property secret
readonly secret?: string;
A GitHub secret name which contains a GitHub Access Token with write permissions for the
pull_request
scope.This token is used to approve pull requests.
Github forbids an identity to approve its own pull request. If your project produces automated pull requests using the Github default token - - that you would like auto approved, such as when using the
depsUpgrade
property inNodeProjectOptions
, then you must use a different token here."GITHUB_TOKEN"
interface AutoMergeOptions
interface AutoMergeOptions {}
property approvedReviews
readonly approvedReviews?: number;
Number of approved code reviews. 1
property blockingLabels
readonly blockingLabels?: string[];
List of labels that will prevent auto-merging. ['do-not-merge']
property queueName
readonly queueName?: string;
Name of the mergify queue 'default'
property ruleName
readonly ruleName?: string;
Name of the mergify rule 'Automatic merge on approval and successful build'
interface AutoQueueOptions
interface AutoQueueOptions {}
Options for 'AutoQueue'
property allowedUsernames
readonly allowedUsernames?: string[];
Only pull requests authored by these Github usernames will have auto-queue enabled. - pull requests from all users are eligible for auto-queuing
property labels
readonly labels?: string[];
Only pull requests with one of this labels will have auto-queue enabled. - all pull requests are eligible for auto-queueing
property mergeMethod
readonly mergeMethod?: MergeMethod;
The method used to add the PR to the merge queue Any branch protection rules must allow this merge method. MergeMethod.SQUASH
property projenCredentials
readonly projenCredentials?: gh.GithubCredentials;
Choose a method for authenticating with GitHub to enable auto-queue on pull requests.
The workflow cannot use a default github token. Queuing a PR with the default token will not trigger any merge queue workflows, which results in the PR just not getting merged at all.
See Also
https://projen.io/docs/integrations/github/ - uses credentials from the GitHub component
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"]
property targetBranches
readonly targetBranches?: string[];
The branch names that we should auto-queue for
This set of branches should be a subset of
MergeQueueOptions.targetBranches
.Be sure not to enable
autoQueue
for branches that don't have branch rules with merge requirements set up, otherwise new PRs will be merged immediately after creating without a chance for review.## Automatically merging a set of Stacked PRs
If you set this to
['main']
you can automatically merge a set of Stacked PRs in the right order. It works like this:- Create PR #1 from branch
a
, targetingmain
. - Create PR #2 from branchb
, targeting brancha
. - Create PR #3 from branchc
, targeting branchb
.Initially, PR #1 will be set to auto-merge, PRs #2 and #3 will not.
Once PR #1 passes all of its requirements it will merge. That will delete branch
a
and change the target branch of PR #2 change tomain
. At that point, auto-queueing will switch on for PR #2 and it gets merged, etc.> [!IMPORTANT] > This component will never disable AutoMerge, only enable it. So if a PR is > initially targeted at one of the branches in this list, and then > subsequently retargeted to another branch, *AutoMerge is not > automatically turned off*.
interface CheckoutOptions
interface CheckoutOptions extends JobStepConfiguration {}
property with
readonly with?: CheckoutWith;
Options for
checkout
.
interface CheckoutWith
interface CheckoutWith {}
Options for
checkout
.
property fetchDepth
readonly fetchDepth?: number;
Number of commits to fetch. 0 indicates all history for all branches and tags.
1
property lfs
readonly lfs?: boolean;
Whether LFS is enabled for the GitHub repository
false
property path
readonly path?: string;
Relative path under $GITHUB_WORKSPACE to place the repository - $GITHUB_WORKSPACE
property ref
readonly ref?: string;
Branch or tag name. - the default branch is implicitly used
property repository
readonly repository?: string;
The repository (owner/repo) to use. - the default repository is implicitly used
property token
readonly token?: string;
A GitHub token to use when checking out the repository.
If the intent is to push changes back to the branch, then you must use a PAT with
repo
(and possiblyworkflows
) permissions. - the default GITHUB_TOKEN is implicitly used
interface CheckoutWithPatchOptions
interface CheckoutWithPatchOptions extends CheckoutWith {}
Options for
checkoutWithPatch
.
property patchFile
readonly patchFile?: string;
The name of the artifact the patch is stored as. ".repo.patch"
interface ConcurrencyOptions
interface ConcurrencyOptions {}
Options for
concurrency
.
property cancelInProgress
readonly cancelInProgress?: boolean;
When a workflow is triggered while another one (in the same group) is running, should GitHub cancel the running workflow?
false
property group
readonly group?: string;
Concurrency group controls which workflow runs will share the same concurrency limit. For example, if you specify
${{ github.workflow }}-${{ github.ref }}
, workflow runs triggered on the same branch cannot run concurrenty, but workflows runs triggered on different branches can.- ${{ github.workflow }}
See Also
https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency#example-concurrency-groups
interface ContributorStatementOptions
interface ContributorStatementOptions {}
Options for requiring a contributor statement on Pull Requests
property exemptLabels
readonly exemptLabels?: string[];
Pull requests with one of these labels are exempted from a contributor statement. - no labels are excluded
property exemptUsers
readonly exemptUsers?: string[];
Pull requests from these GitHub users are exempted from a contributor statement. - no users are exempted
interface CreatePullRequestOptions
interface CreatePullRequestOptions {}
property assignees
readonly assignees?: string[];
Assignees to add on the PR.
- no assignees
property baseBranch
readonly baseBranch?: string;
Sets the pull request base branch.
- The branch checked out in the workflow.
property branchName
readonly branchName?: string;
The pull request branch name.
github-actions/${options.workflowName}
property credentials
readonly credentials?: GithubCredentials;
The job credentials used to create the pull request.
Provided credentials must have permissions to create a pull request on the repository.
property gitIdentity
readonly gitIdentity?: GitIdentity;
The git identity used to create the commit. - the default github-actions user
property labels
readonly labels?: string[];
Labels to apply on the PR.
- no labels.
property pullRequestDescription
readonly pullRequestDescription: string;
Description added to the pull request.
Providence information are automatically added.
property pullRequestTitle
readonly pullRequestTitle: string;
The full title used to create the pull request.
If PR titles are validated in this repo, the title should comply with the respective rules.
property signoff
readonly signoff?: boolean;
Add Signed-off-by line by the committer at the end of the commit log message.
true
property stepId
readonly stepId?: string;
The step ID which produces the output which indicates if a patch was created. "create_pr"
property stepName
readonly stepName?: string;
The name of the step displayed on GitHub. "Create Pull Request"
property workflowName
readonly workflowName: string;
The name of the workflow that will create the PR
interface DependabotAllow
interface DependabotAllow {}
You can use the
allow
option to customize which dependencies are updated. The allow option supports the following options.
property dependencyName
readonly dependencyName: string;
Use to allow updates for dependencies with matching names, optionally using
*
to match zero or more characters.For Java dependencies, the format of the dependency-name attribute is:
groupId:artifactId
, for example:org.kohsuke:github-api
.
interface DependabotGroup
interface DependabotGroup {}
Defines a single group for dependency updates
property excludePatterns
readonly excludePatterns?: string[];
Optionally you can use this to exclude certain dependencies from the group.
property patterns
readonly patterns: string[];
Define a list of strings (with or without wildcards) that will match package names to form this dependency group.
interface DependabotIgnore
interface DependabotIgnore {}
You can use the
ignore
option to customize which dependencies are updated. The ignore option supports the following options.
property dependencyName
readonly dependencyName: string;
Use to ignore updates for dependencies with matching names, optionally using
*
to match zero or more characters.For Java dependencies, the format of the dependency-name attribute is:
groupId:artifactId
, for example:org.kohsuke:github-api
.
property versions
readonly versions?: string[];
Use to ignore specific versions or ranges of versions. If you want to define a range, use the standard pattern for the package manager (for example:
^1.0.0
for npm, or~> 2.0
for Bundler).
interface DependabotOptions
interface DependabotOptions {}
property allow
readonly allow?: DependabotAllow[];
https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#allow
Use the allow option to customize which dependencies are updated. This applies to both version and security updates.
[]
property assignees
readonly assignees?: string[];
Specify individual assignees or teams of assignees for all pull requests raised for a package manager. []
property groups
readonly groups?: { [name: string]: DependabotGroup;};
https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups
You can create groups to package dependency updates together into a single PR.
[]
property ignore
readonly ignore?: DependabotIgnore[];
You can use the
ignore
option to customize which dependencies are updated. The ignore option supports the following options. []
property ignoreProjen
readonly ignoreProjen?: boolean;
Ignores updates to
projen
.This is required since projen updates may cause changes in committed files and anti-tamper checks will fail.
Projen upgrades are covered through the
ProjenUpgrade
class.true
property labels
readonly labels?: string[];
List of labels to apply to the created PR's.
property openPullRequestsLimit
readonly openPullRequestsLimit?: number;
Sets the maximum of pull requests Dependabot opens for version updates. Dependabot will not open any new requests until some of those open requests are merged or closed.
5
property registries
readonly registries?: { [name: string]: DependabotRegistry;};
Map of package registries to use - use public registries
property reviewers
readonly reviewers?: string[];
Specify individual reviewers or teams of reviewers for all pull requests raised for a package manager. []
property scheduleInterval
readonly scheduleInterval?: DependabotScheduleInterval;
How often to check for new versions and raise pull requests.
ScheduleInterval.DAILY
property targetBranch
readonly targetBranch?: string;
https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#target-branch You can configure the target branch for raising pull requests for version updates against
property versioningStrategy
readonly versioningStrategy?: VersioningStrategy;
The strategy to use when edits manifest and lock files.
VersioningStrategy.LOCKFILE_ONLY The default is to only update the lock file because package.json is controlled by projen and any outside updates will fail the build.
interface DependabotRegistry
interface DependabotRegistry {}
Use to add private registry support for dependabot
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries
property key
readonly key?: string;
A reference to a Dependabot secret containing an access key for this registry undefined
property organization
readonly organization?: string;
Used with the hex-organization registry type.
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization undefined
property password
readonly password?: string;
A reference to a Dependabot secret containing the password for the specified user undefined
property replacesBase
readonly replacesBase?: boolean;
For registries with type: python-index, if the boolean value is true, pip esolves dependencies by using the specified URL rather than the base URL of the Python Package Index (by default https://pypi.org/simple) undefined
property token
readonly token?: string;
Secret token for dependabot access e.g. '${{ secrets.DEPENDABOT_PACKAGE_TOKEN }}' undefined
property type
readonly type: DependabotRegistryType;
Registry type e.g. 'npm-registry' or 'docker-registry'
property url
readonly url: string;
Url for the registry e.g. 'https://npm.pkg.github.com' or 'registry.hub.docker.com'
property username
readonly username?: string;
The username that Dependabot uses to access the registry - do not authenticate
interface DownloadArtifactOptions
interface DownloadArtifactOptions extends JobStepConfiguration {}
property with
readonly with: DownloadArtifactWith;
Options for
download-artifact
.
interface DownloadArtifactWith
interface DownloadArtifactWith {}
property mergeMultiple
readonly mergeMultiple?: boolean;
When multiple artifacts are matched, this changes the behavior of the destination directories If true, the downloaded artifacts will be in the same directory specified by path If false, the downloaded artifacts will be extracted into individual named directories within the specified path
false
property name
readonly name?: string;
Name of the artifact to download
- If unspecified, all artifacts for the run are downloaded
property path
readonly path?: string;
A file, directory or wildcard pattern that describes what to download. Supports basic tilde expansion.
- $GITHUB_WORKSPACE
property pattern
readonly pattern?: string;
A glob pattern to the artifacts that should be downloaded This is ignored if name is specified
property repository
readonly repository?: string;
The repository owner and the repository name joined together by "/" If github-token is specified, this is the repository that artifacts will be downloaded from
- ${{ github.repository }}
property runId
readonly runId?: string;
The id of the workflow run where the desired download artifact was uploaded from If github-token is specified, this is the run that artifacts will be downloaded from
- ${{ github.run_id }}
property token
readonly token?: string;
The GitHub token used to authenticate with the GitHub API to download artifacts from a different repository or from a different workflow run
- If unspecified, the action will download artifacts from the current repo and the current workflow run
interface GithubCredentialsAppOptions
interface GithubCredentialsAppOptions {}
Options for
GithubCredentials.fromApp
property appIdSecret
readonly appIdSecret?: string;
The secret containing the GitHub App ID
"PROJEN_APP_ID"
property owner
readonly owner?: string;
The owner of the GitHub App installation
- if empty, defaults to the current repository owner
property permissions
readonly permissions?: AppPermissions;
The permissions granted to the token.
- all permissions granted to the app
property privateKeySecret
readonly privateKeySecret?: string;
The secret containing the GitHub App private key
Escaped newlines (\n) will be automatically replaced with actual newlines.
"PROJEN_APP_PRIVATE_KEY"
property repositories
readonly repositories?: string[];
List of repositories to grant access to
- if owner is set and repositories is empty, access will be scoped to all repositories in the provided repository owner's installation. If owner and repositories are empty, access will be scoped to only the current repository.
interface GithubCredentialsPersonalAccessTokenOptions
interface GithubCredentialsPersonalAccessTokenOptions {}
Options for
GithubCredentials.fromPersonalAccessToken
property secret
readonly secret?: string;
interface GitHubOptions
interface GitHubOptions {}
property downloadLfs
readonly downloadLfs?: boolean;
Download files in LFS in workflows
true if the associated project has
lfsPatterns
,false
otherwise
property mergeQueue
readonly mergeQueue?: boolean;
Whether a merge queue should be used on this repository to merge pull requests. Requires additional configuration of the repositories branch protection rules.
false
property mergeQueueOptions
readonly mergeQueueOptions?: MergeQueueOptions;
Options for MergeQueue.
- default options
property mergify
readonly mergify?: boolean;
Whether mergify should be enabled on this repository or not.
true
property mergifyOptions
readonly mergifyOptions?: MergifyOptions;
Options for Mergify.
- default options
property projenCredentials
readonly projenCredentials?: GithubCredentials;
Choose a method of providing GitHub API access for projen workflows.
- use a personal access token named PROJEN_GITHUB_TOKEN
property projenTokenSecret
readonly projenTokenSecret?: string;
The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. This token needs to have the
repo
,workflows
andpackages
scope."PROJEN_GITHUB_TOKEN"
Deprecated
- use
projenCredentials
property pullRequestBackport
readonly pullRequestBackport?: boolean;
Add a workflow that allows backport of PRs to other branches using labels. When opening a new PR add a backport label to it, and the PR will be backported to the target branches once the PR is merged.
Should not be used together with mergify.
false
property pullRequestBackportOptions
readonly pullRequestBackportOptions?: PullRequestBackportOptions;
Options for configuring pull request backport.
- see defaults in
PullRequestBackportOptions
property pullRequestLint
readonly pullRequestLint?: boolean;
Add a workflow that performs basic checks for pull requests, like validating that PRs follow Conventional Commits.
true
property pullRequestLintOptions
readonly pullRequestLintOptions?: PullRequestLintOptions;
Options for configuring a pull request linter.
- see defaults in
PullRequestLintOptions
property workflows
readonly workflows?: boolean;
Enables GitHub workflows. If this is set to
false
, workflows will not be created.true
interface GitHubProjectOptions
interface GitHubProjectOptions extends ProjectOptions {}
Options for
GitHubProject
.
property autoApproveOptions
readonly autoApproveOptions?: AutoApproveOptions;
Enable and configure the 'auto approve' workflow. - auto approve is disabled
property autoMerge
readonly autoMerge?: boolean;
Enable automatic merging on GitHub. Has no effect if
github.mergify
is set to false. true
property autoMergeOptions
readonly autoMergeOptions?: AutoMergeOptions;
Configure options for automatic merging on GitHub. Has no effect if
github.mergify
orautoMerge
is set to false.- see defaults in
AutoMergeOptions
property clobber
readonly clobber?: boolean;
Add a
clobber
task which resets the repo to origin. - true, but false for subprojects
property devContainer
readonly devContainer?: boolean;
Add a VSCode development environment (used for GitHub Codespaces)
false
property github
readonly github?: boolean;
Enable GitHub integration.
Enabled by default for root projects. Disabled for non-root projects.
true
property githubOptions
readonly githubOptions?: GitHubOptions;
Options for GitHub integration
- see GitHubOptions
property gitpod
readonly gitpod?: boolean;
Add a Gitpod development environment
false
property mergify
readonly mergify?: boolean;
Whether mergify should be enabled on this repository or not.
true
Deprecated
use
githubOptions.mergify
instead
property mergifyOptions
readonly mergifyOptions?: MergifyOptions;
Options for mergify
- default options
Deprecated
use
githubOptions.mergifyOptions
instead
property projectType
readonly projectType?: ProjectType;
Which type of project this is (library/app). ProjectType.UNKNOWN
Deprecated
no longer supported at the base project level
property projenCredentials
readonly projenCredentials?: GithubCredentials;
Choose a method of providing GitHub API access for projen workflows.
- use a personal access token named PROJEN_GITHUB_TOKEN
property projenTokenSecret
readonly projenTokenSecret?: string;
The name of a secret which includes a GitHub Personal Access Token to be used by projen workflows. This token needs to have the
repo
,workflows
andpackages
scope."PROJEN_GITHUB_TOKEN"
Deprecated
use
projenCredentials
property readme
readonly readme?: SampleReadmeProps;
The README setup.
- { filename: 'README.md', contents: '# replace this' }
Example 1
"{ filename: 'readme.md', contents: '# title' }"
property stale
readonly stale?: boolean;
Auto-close of stale issues and pull request. See
staleOptions
for options.false
property staleOptions
readonly staleOptions?: StaleOptions;
Auto-close stale issues and pull requests. To disable set
stale
tofalse
.- see defaults in
StaleOptions
property vscode
readonly vscode?: boolean;
Enable VSCode integration.
Enabled by default for root projects. Disabled for non-root projects.
true
interface GithubWorkflowOptions
interface GithubWorkflowOptions {}
Options for
GithubWorkflow
.
property concurrencyOptions
readonly concurrencyOptions?: ConcurrencyOptions;
Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. Currently in beta.
- { group: ${{ github.workflow }}, cancelInProgress: false }
See Also
https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#concurrency
property env
readonly env?: Record<string, string>;
Additional environment variables to set for the workflow.
- no additional environment variables
property fileName
readonly fileName?: string;
Set a custom file name for the workflow definition file. Must include either a .yml or .yaml file extension.
Use this option to set a file name for the workflow file, that is different than the display name.
Example 1
"build-new.yml"
Example 2
"my-workflow.yaml"
- a path-safe version of the workflow name plus the .yml file ending, e.g. build.yml
property force
readonly force?: boolean;
Force the creation of the workflow even if
workflows
is disabled inGitHub
.false
property limitConcurrency
readonly limitConcurrency?: boolean;
Enable concurrency limitations. Use
concurrencyOptions
to configure specific non default values.false
interface GitIdentity
interface GitIdentity {}
Represents the git identity.
interface IAddConditionsLater
interface IAddConditionsLater {}
method render
render: () => string[];
interface MergeQueueOptions
interface MergeQueueOptions {}
Options for 'MergeQueue'
property autoQueue
readonly autoQueue?: boolean;
Should pull requests be queued automatically to be merged once they pass required checks true
property autoQueueOptions
readonly autoQueueOptions?: AutoQueueOptions;
Configure auto-queue pull requests - see AutoQueueOptions
property targetBranches
readonly targetBranches?: string[];
The branches that can be merged into using MergeQueue
- all branches
interface MergifyConditionalOperator
interface MergifyConditionalOperator {}
The Mergify conditional operators that can be used are:
or
andand
. Note: The number of nested conditions is limited to 3.See Also
https://docs.mergify.io/conditions/#combining-conditions-with-operators
interface MergifyOptions
interface MergifyOptions {}
interface MergifyQueue
interface MergifyQueue {}
property commitMessageTemplate
readonly commitMessageTemplate: string;
Template to use as the commit message when using the merge or squash merge method.
property conditions
readonly conditions: MergifyCondition[];
A list of Conditions string that must match against the pull request for the pull request to be added to the queue.
See Also
https://docs.mergify.com/conditions/#conditions
property mergeMethod
readonly mergeMethod?: string;
Merge method to use.
Possible values are
merge
,squash
,rebase
orfast-forward
.fast-forward
is not supported on queues withspeculative_checks
> 1,batch_size
> 1, or withallow_inplace_checks
set to false."merge"
property name
readonly name: string;
The name of the queue.
property updateMethod
readonly updateMethod?: string;
Method to use to update the pull request with its base branch when the speculative check is done in-place.
Possible values: -
merge
to merge the base branch into the pull request. -rebase
to rebase the pull request against its base branch.Note that the
rebase
method has some drawbacks, see Mergify docs for details.See Also
https://docs.mergify.com/actions/queue/#queue-rules
-
merge
for all merge methods exceptfast-forward
whererebase
is used
interface MergifyRule
interface MergifyRule {}
property actions
readonly actions: { [action: string]: any;};
A dictionary made of Actions that will be executed on the matching pull requests.
See Also
https://docs.mergify.io/actions/#actions
property conditions
readonly conditions: MergifyCondition[];
A list of Conditions string that must match against the pull request for the rule to be applied.
See Also
https://docs.mergify.io/conditions/#conditions
property name
readonly name: string;
The name of the rule. This is not used by the engine directly, but is used when reporting information about a rule.
interface PullRequestBackportOptions
interface PullRequestBackportOptions {}
property autoApproveBackport
readonly autoApproveBackport?: boolean;
Automatically approve backport PRs if the 'auto approve' workflow is available.
true
property backportBranchNamePrefix
readonly backportBranchNamePrefix?: string;
The prefix used to name backport branches.
Make sure to include a separator at the end like
/
or_
."backport/"
property backportPRLabels
readonly backportPRLabels?: string[];
The labels added to the created backport PR.
["backport"]
property branches
readonly branches?: string[];
List of branches that can be a target for backports
- allow backports to all release branches
property createWithConflicts
readonly createWithConflicts?: boolean;
Should this created Backport PRs with conflicts.
Conflicts will have to be resolved manually, but a PR is always created. Set to
false
to prevent the backport PR from being created if there are conflicts.true
property labelPrefix
readonly labelPrefix?: string;
The prefix used to detect PRs that should be backported.
"backport-to-"
property workflowName
readonly workflowName?: string;
The name of the workflow.
"backport"
interface PullRequestFromPatchOptions
interface PullRequestFromPatchOptions extends CreatePullRequestOptions {}
property jobName
readonly jobName?: string;
The name of the job displayed on GitHub. "Create Pull Request"
property patch
readonly patch: PullRequestPatchSource;
Information about the patch that is used to create the pull request.
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
interface PullRequestLintOptions
interface PullRequestLintOptions {}
Options for PullRequestLint
property contributorStatement
readonly contributorStatement?: string;
Require a contributor statement to be included in the PR description. For example confirming that the contribution has been made by the contributor and complies with the project's license.
Appends the statement to the end of the Pull Request template.
- no contributor statement is required
property contributorStatementOptions
readonly contributorStatementOptions?: ContributorStatementOptions;
Options for requiring a contributor statement on Pull Requests - none
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property semanticTitle
readonly semanticTitle?: boolean;
Validate that pull request titles follow Conventional Commits.
true
See Also
https://www.conventionalcommits.org/
property semanticTitleOptions
readonly semanticTitleOptions?: SemanticTitleOptions;
Options for validating the conventional commit title linter. - title must start with "feat", "fix", or "chore"
interface PullRequestPatchSource
interface PullRequestPatchSource extends CheckoutWithPatchOptions {}
property jobId
readonly jobId: string;
The id of the job that created the patch file
property outputName
readonly outputName: string;
The name of the output that indicates if a patch has been created
interface PullRequestTemplateOptions
interface PullRequestTemplateOptions {}
Options for
PullRequestTemplate
.
property lines
readonly lines?: string[];
The contents of the template. You can use
addLine()
to add additional lines.- a standard default template will be created.
interface SemanticTitleOptions
interface SemanticTitleOptions {}
Options for linting that PR titles follow Conventional Commits.
See Also
https://www.conventionalcommits.org/
property requireScope
readonly requireScope?: boolean;
Configure that a scope must always be provided. e.g. feat(ui), fix(core) false
property types
readonly types?: string[];
Configure a list of commit types that are allowed. ["feat", "fix", "chore"]
interface SetupGitIdentityOptions
interface SetupGitIdentityOptions extends JobStepConfiguration {}
property gitIdentity
readonly gitIdentity: GitIdentity;
The identity to use.
interface StaleBehavior
interface StaleBehavior {}
Stale behavior.
property closeMessage
readonly closeMessage?: string;
The comment to add to the issue/PR when it's closed
"Closing this pull request as it hasn't seen activity for a while. Please add a comment a maintainer when you are ready to continue."
property daysBeforeClose
readonly daysBeforeClose?: number;
Days until the issue/PR is closed after it is marked as "Stale". Set to -1 to disable. -
property daysBeforeStale
readonly daysBeforeStale?: number;
How many days until the issue or pull request is marked as "Stale". Set to -1 to disable. -
property enabled
readonly enabled?: boolean;
Determines if this behavior is enabled.
Same as setting
daysBeforeStale
anddaysBeforeClose
to-1
.true
property exemptLabels
readonly exemptLabels?: string[];
Label which exempt an issue/PR from becoming stale. Set to
[]
to disable.- ["backlog"]
property staleLabel
readonly staleLabel?: string;
The label to apply to the issue/PR when it becomes stale. "stale"
property staleMessage
readonly staleMessage?: string;
The comment to add to the issue/PR when it becomes stale. "This pull request is now marked as stale because hasn't seen activity for a while. Add a comment or it will be closed soon."
interface StaleOptions
interface StaleOptions {}
Options for
Stale
.
property issues
readonly issues?: StaleBehavior;
How to handle stale issues.
- By default, stale issues with no activity will be marked as stale after 60 days and closed within 7 days.
property pullRequest
readonly pullRequest?: StaleBehavior;
How to handle stale pull requests.
- By default, pull requests with no activity will be marked as stale after 14 days and closed within 2 days with relevant comments.
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
interface TaskWorkflowJobOptions
interface TaskWorkflowJobOptions {}
Options to create the Job associated with a TaskWorkflow.
property artifactsDirectory
readonly artifactsDirectory?: string;
A directory name which contains artifacts to be uploaded (e.g.
dist
). If this is set, the contents of this directory will be uploaded as an artifact at the end of the workflow run, even if other steps fail.- not set
property checkoutWith
readonly checkoutWith?: CheckoutWith;
Override for the
with
property of the source code checkout step.- not set
property condition
readonly condition?: string;
Adds an 'if' condition to the workflow.
property container
readonly container?: ContainerOptions;
- default image
property downloadLfs
readonly downloadLfs?: boolean;
Whether to download files from Git LFS for this workflow
- Use the setting on the corresponding GitHub project
property env
readonly env?: Record<string, string>;
Workflow environment variables. {}
property gitIdentity
readonly gitIdentity?: GitIdentity;
The git identity to use in this workflow.
property jobDefaults
readonly jobDefaults?: JobDefaults;
Default settings for all steps in the TaskWorkflow Job.
property outputs
readonly outputs?: { [name: string]: JobStepOutput;};
Mapping of job output names to values/expressions.
{}
property permissions
readonly permissions: JobPermissions;
Permissions for the build job.
property postBuildSteps
readonly postBuildSteps?: JobStep[];
Actions to run after the main build step.
- not set
property preBuildSteps
readonly preBuildSteps?: JobStep[];
Steps to run before the main build step.
- not set
property preCheckoutSteps
readonly preCheckoutSteps?: JobStep[];
Initial steps to run before the source code checkout.
- not set
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
interface TaskWorkflowOptions
interface TaskWorkflowOptions extends TaskWorkflowJobOptions {}
Options to create a TaskWorkflow.
property jobId
readonly jobId?: string;
The primary job id. "build"
property name
readonly name: string;
The workflow name.
property task
readonly task: Task;
The main task to be executed.
property triggers
readonly triggers?: Triggers;
The triggers for the workflow.
- by default workflows can only be triggered by manually.
interface UploadArtifactOptions
interface UploadArtifactOptions extends JobStepConfiguration {}
property with
readonly with: UploadArtifactWith;
Options for
upload-artifact
.
interface UploadArtifactWith
interface UploadArtifactWith {}
property compressionLevel
readonly compressionLevel?: number;
The level of compression for Zlib to be applied to the artifact archive.
The value can range from 0 to 9. For large files that are not easily compressed, a value of 0 is recommended for significantly faster uploads.
6
property ifNoFilesFound
readonly ifNoFilesFound?: 'error' | 'warn' | 'ignore';
The desired behavior if no files are found using the provided path. Available Options: warn: Output a warning but do not fail the action error: Fail the action with an error message ignore: Do not output any warnings or errors, the action does not fail
"warn"
property includeHiddenFiles
readonly includeHiddenFiles?: boolean;
Whether to include hidden files in the provided path in the artifact
The file contents of any hidden files in the path should be validated before enabled this to avoid uploading sensitive information.
false
property name
readonly name?: string;
Name of the artifact to upload.
"artifact"
property overwrite
readonly overwrite?: boolean;
Whether action should overwrite an existing artifact with the same name (should one exist)
Introduced in v4 and represents a breaking change from the behavior of the v3 action. To maintain backwards compatibility with existing, this should be set the
true
(the default).true
property path
readonly path: string;
A file, directory or wildcard pattern that describes what to upload
property retentionDays
readonly retentionDays?: number;
Duration after which artifact will expire in days. 0 means using default repository retention.
Minimum 1 day. Maximum 90 days unless changed from the repository settings page.
- The default repository retention
interface UploadGitPatchOptions
interface UploadGitPatchOptions {}
Options for
uploadGitPatch
.
property mutationError
readonly mutationError?: string;
Fail if a mutation was found and print this error message. - do not fail upon mutation
property outputName
readonly outputName: string;
The name of the output to emit. It will be set to
true
if there was a diff.
property patchFile
readonly patchFile?: string;
The name of the artifact the patch is stored as. ".repo.patch"
property stepId
readonly stepId: string;
The step ID which produces the output which indicates if a patch was created.
property stepName
readonly stepName?: string;
The name of the step. "Find mutations"
enum DependabotRegistryType
enum DependabotRegistryType { COMPOSER_REGISTRY = 'composer-registry', DOCKER_REGISTRY = 'docker-registry', GIT = 'git', HEX_ORGANIZATION = 'hex-organization', MAVEN_REPOSITORY = 'maven-repository', NPM_REGISTRY = 'npm-registry', NUGET_FEED = 'nuget-feed', PYTHON_INDEX = 'python-index', RUBYGEMS_SERVER = 'rubygems-server', TERRAFORM_REGISTRY = 'terraform-registry',}
Each configuration type requires you to provide particular settings. Some types allow more than one way to connect
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#configuration-options-for-private-registries
member COMPOSER_REGISTRY
COMPOSER_REGISTRY = 'composer-registry'
The composer-repository type supports username and password.
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#composer-repository
member DOCKER_REGISTRY
DOCKER_REGISTRY = 'docker-registry'
The docker-registry type supports username and password. The docker-registry type can also be used to pull from Amazon ECR using static AWS credentials
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#docker-registry
member GIT
GIT = 'git'
The git type supports username and password
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#git
member HEX_ORGANIZATION
HEX_ORGANIZATION = 'hex-organization'
The hex-organization type supports organization and key
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#hex-organization
member MAVEN_REPOSITORY
MAVEN_REPOSITORY = 'maven-repository'
The maven-repository type supports username and password, or token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#maven-repository
member NPM_REGISTRY
NPM_REGISTRY = 'npm-registry'
The npm-registry type supports username and password, or token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#npm-registry
member NUGET_FEED
NUGET_FEED = 'nuget-feed'
The nuget-feed type supports username and password, or token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#nuget-feed
member PYTHON_INDEX
PYTHON_INDEX = 'python-index'
The python-index type supports username and password, or token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#python-index
member RUBYGEMS_SERVER
RUBYGEMS_SERVER = 'rubygems-server'
The rubygems-server type supports username and password, or token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#rubygems-server
member TERRAFORM_REGISTRY
TERRAFORM_REGISTRY = 'terraform-registry'
The terraform-registry type supports a token
See Also
https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/configuration-options-for-dependency-updates#terraform-registry
enum DependabotScheduleInterval
enum DependabotScheduleInterval { DAILY = 'daily', WEEKLY = 'weekly', MONTHLY = 'monthly',}
How often to check for new versions and raise pull requests for version updates.
enum MergeMethod
enum MergeMethod { SQUASH = 'squash', MERGE = 'merge', REBASE = 'rebase',}
The merge method used to add the PR to the merge queue
Behavior can be further configured in repository settings.
enum VersioningStrategy
enum VersioningStrategy { LOCKFILE_ONLY = 'lockfile-only', AUTO = 'auto', WIDEN = 'widen', INCREASE = 'increase', INCREASE_IF_NECESSARY = 'increase-if-necessary',}
The strategy to use when edits manifest and lock files.
member AUTO
AUTO = 'auto'
- For apps, the version requirements are increased. - For libraries, the range of versions is widened.
member INCREASE
INCREASE = 'increase'
Always increase the version requirement to match the new version.
member INCREASE_IF_NECESSARY
INCREASE_IF_NECESSARY = 'increase-if-necessary'
Increase the version requirement only when required by the new version.
member LOCKFILE_ONLY
LOCKFILE_ONLY = 'lockfile-only'
Only create pull requests to update lockfiles updates. Ignore any new versions that would require package manifest changes.
member WIDEN
WIDEN = 'widen'
Relax the version requirement to include both the new and old version, when possible.
type MergifyCondition
type MergifyCondition = string | MergifyConditionalOperator;
namespace workflows
module 'lib/github/workflows-model.d.ts' {}
The name of the job displayed on GitHub.
interface AppPermissions
interface AppPermissions {}
The permissions available to a GitHub App.
Typically a token for a GitHub App has all the available scopes/permissions available to the app itself; however, a more limited set of permissions can be specified. When permissions are provided, **only** the specified permissions are granted to the token.
See Also
https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app
https://github.com/actions/create-github-app-token/blob/main/action.yml#L28
property actions
readonly actions?: AppPermission;
property administration
readonly administration?: AppPermission;
property attestations
readonly attestations?: AppPermission;
property checks
readonly checks?: AppPermission;
property codespaces
readonly codespaces?: AppPermission;
property contents
readonly contents?: AppPermission;
property dependabotSecrets
readonly dependabotSecrets?: AppPermission;
property deployments
readonly deployments?: AppPermission;
property emailAddresses
readonly emailAddresses?: AppPermission;
property environments
readonly environments?: AppPermission;
property followers
readonly followers?: AppPermission;
property gitSshKeys
readonly gitSshKeys?: AppPermission;
property gpgKeys
readonly gpgKeys?: AppPermission;
property interactionLimits
readonly interactionLimits?: AppPermission;
property issues
readonly issues?: AppPermission;
property members
readonly members?: AppPermission;
property metadata
readonly metadata?: AppPermission;
property organizationAdministration
readonly organizationAdministration?: AppPermission;
property organizationAnnouncementBanners
readonly organizationAnnouncementBanners?: AppPermission;
property organizationCopilotSeatManagement
readonly organizationCopilotSeatManagement?: AppPermission;
property organizationCustomOrgRoles
readonly organizationCustomOrgRoles?: AppPermission;
property organizationCustomProperties
readonly organizationCustomProperties?: AppPermission;
property organizationCustomRoles
readonly organizationCustomRoles?: AppPermission;
property organizationEvents
readonly organizationEvents?: AppPermission;
property organizationHooks
readonly organizationHooks?: AppPermission;
property organizationPackages
readonly organizationPackages?: AppPermission;
property organizationPersonalAccessTokenRequests
readonly organizationPersonalAccessTokenRequests?: AppPermission;
property organizationPersonalAccessTokens
readonly organizationPersonalAccessTokens?: AppPermission;
property organizationPlan
readonly organizationPlan?: AppPermission;
property organizationProjects
readonly organizationProjects?: AppPermission;
property organizationSecrets
readonly organizationSecrets?: AppPermission;
property organizationSelfHostedRunners
readonly organizationSelfHostedRunners?: AppPermission;
property orgnaizationUserBlocking
readonly orgnaizationUserBlocking?: AppPermission;
property packages
readonly packages?: AppPermission;
property pages
readonly pages?: AppPermission;
property profile
readonly profile?: AppPermission;
property pullRequests
readonly pullRequests?: AppPermission;
property repositoryAnnouncementBanners
readonly repositoryAnnouncementBanners?: AppPermission;
Deprecated
removed by GitHub
property repositoryCustomProperties
readonly repositoryCustomProperties?: AppPermission;
property repositoryHooks
readonly repositoryHooks?: AppPermission;
property repositoryProjects
readonly repositoryProjects?: AppPermission;
property secrets
readonly secrets?: AppPermission;
property secretScanningAlerts
readonly secretScanningAlerts?: AppPermission;
property securityEvents
readonly securityEvents?: AppPermission;
property singleFile
readonly singleFile?: AppPermission;
property starring
readonly starring?: AppPermission;
property statuses
readonly statuses?: AppPermission;
property teamDiscussions
readonly teamDiscussions?: AppPermission;
property vulnerabilityAlerts
readonly vulnerabilityAlerts?: AppPermission;
property workflows
readonly workflows?: AppPermission;
interface BranchProtectionRuleOptions
interface BranchProtectionRuleOptions {}
Branch Protection Rule options
property types
readonly types?: Array<'created' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface CheckRunOptions
interface CheckRunOptions {}
Check run options.
property types
readonly types?: Array< 'create' | 'rerequested' | 'completed' | 'requested_action'>;
Which activity types to trigger on.
- all activity types
interface CheckSuiteOptions
interface CheckSuiteOptions {}
Check suite options
property types
readonly types?: Array<'completed' | 'requested' | 'rerequested'>;
Which activity types to trigger on.
- all activity types
interface CommonJobDefinition
interface CommonJobDefinition {}
property concurrency
readonly concurrency?: unknown;
Concurrency ensures that only a single job or workflow using the same concurrency group will run at a time. A concurrency group can be any string or expression. The expression can use any context except for the secrets context.
Modifiers
@experimental
property if
readonly if?: string;
You can use the if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.
property name
readonly name?: string;
The name of the job displayed on GitHub.
property needs
readonly needs?: string[];
Identifies any jobs that must complete successfully before this job will run. It can be a string or array of strings. If a job fails, all jobs that need it are skipped unless the jobs use a conditional expression that causes the job to continue.
property permissions
readonly permissions: JobPermissions;
You can modify the default permissions granted to the GITHUB_TOKEN, adding or removing access as required, so that you only allow the minimum required access.
Use
{ contents: READ }
if your job only needs to clone code.This is intentionally a required field since it is required in order to allow workflows to run in GitHub repositories with restricted default access.
See Also
https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token
property strategy
readonly strategy?: JobStrategy;
A strategy creates a build matrix for your jobs. You can define different variations to run each job in.
interface ContainerCredentials
interface ContainerCredentials {}
Credentials to use to authenticate to Docker registries.
interface ContainerOptions
interface ContainerOptions {}
Options pertaining to container environments.
property credentials
readonly credentials?: ContainerCredentials;
f the image's container registry requires authentication to pull the image, you can use credentials to set a map of the username and password. The credentials are the same values that you would provide to the docker login command.
property env
readonly env?: Record<string, string>;
Sets a map of environment variables in the container.
property image
readonly image: string;
The Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.
property options
readonly options?: string[];
Additional Docker container resource options.
See Also
https://docs.docker.com/engine/reference/commandline/create/#options
property ports
readonly ports?: number[];
Sets an array of ports to expose on the container.
property volumes
readonly volumes?: string[];
Sets an array of volumes for the container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
To specify a volume, you specify the source and destination path:
<source>:<destinationPath>
.
interface CreateOptions
interface CreateOptions {}
The Create event accepts no options.
interface CronScheduleOptions
interface CronScheduleOptions {}
CRON schedule options.
property cron
readonly cron: string;
See Also
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07
interface DeleteOptions
interface DeleteOptions {}
The Delete event accepts no options.
interface DeploymentOptions
interface DeploymentOptions {}
The Deployment event accepts no options.
interface DeploymentStatusOptions
interface DeploymentStatusOptions {}
The Deployment status event accepts no options.
interface DiscussionCommentOptions
interface DiscussionCommentOptions {}
Discussion comment options
property types
readonly types?: Array<'created' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface DiscussionOptions
interface DiscussionOptions {}
Discussion options
property types
readonly types?: Array< | 'created' | 'edited' | 'transferred' | 'pinned' | 'unpinned' | 'labeled' | 'unlabeled' | 'locked' | 'unlocked' | 'category_changed' | 'answered' | 'unanswered'>;
Which activity types to trigger on.
- all activity types
interface ForkOptions
interface ForkOptions {}
The Fork event accepts no options.
interface GollumOptions
interface GollumOptions {}
The Gollum event accepts no options.
interface IssueCommentOptions
interface IssueCommentOptions {}
Issue comment options
property types
readonly types?: Array<'created' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface IssuesOptions
interface IssuesOptions {}
Issues options
property types
readonly types?: Array< | 'opened' | 'edited' | 'deleted' | 'transferred' | 'pinned' | 'unpinned' | 'closed' | 'reopened' | 'assigned' | 'unassigned' | 'labeled' | 'unlabeled' | 'locked' | 'unlocked' | 'milestoned' | 'demilestoned'>;
Which activity types to trigger on.
- all activity types
interface Job
interface Job extends CommonJobDefinition {}
A GitHub Workflow job definition.
property container
readonly container?: ContainerOptions;
A container to run any steps in a job that don't already specify a container. If you have steps that use both script and container actions, the container actions will run as sibling containers on the same network with the same volume mounts.
property continueOnError
readonly continueOnError?: boolean;
Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.
property defaults
readonly defaults?: JobDefaults;
A map of default settings that will apply to all steps in the job. You can also set default settings for the entire workflow.
property env
readonly env?: Record<string, string>;
A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step.
property environment
readonly environment?: unknown;
The environment that the job references. All environment protection rules must pass before a job referencing the environment is sent to a runner.
See Also
https://docs.github.com/en/actions/reference/environments
property outputs
readonly outputs?: Record<string, JobStepOutput>;
A map of outputs for a job. Job outputs are available to all downstream jobs that depend on this job.
property runsOn
readonly runsOn?: string[];
The type of machine to run the job on. The machine can be either a GitHub-hosted runner or a self-hosted runner.
Example 1
["ubuntu-latest"]
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property services
readonly services?: Record<string, ContainerOptions>;
Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.
property steps
readonly steps: JobStep[];
A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.
property timeoutMinutes
readonly timeoutMinutes?: number;
The maximum number of minutes to let a job run before GitHub automatically cancels it.
360
property tools
readonly tools?: Tools;
Tools required for this job. Translates into
actions/setup-xxx
steps at the beginning of the job.
interface JobCallingReusableWorkflow
interface JobCallingReusableWorkflow extends CommonJobDefinition {}
A GitHub Workflow Job calling a reusable workflow
property secrets
readonly secrets?: string | Record<string, string>;
When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.
Use the 'inherit' keyword to pass all the calling workflow's secrets to the called workflow
property uses
readonly uses: string;
The location and version of a reusable workflow file to run as a job.
property with
readonly with?: Record<string, string | boolean>;
When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.
Allowed expression contexts:
github
, andneeds
.
interface JobDefaults
interface JobDefaults {}
Default settings for all steps in the job.
property run
readonly run?: RunSettings;
Default run settings.
interface JobMatrix
interface JobMatrix {}
A job matrix.
property domain
readonly domain?: Record<string, string | JobMatrixValue[]>;
Each option you define in the matrix has a key and value. The keys you define become properties in the matrix context and you can reference the property in other areas of your workflow file. For example, if you define the key os that contains an array of operating systems, you can use the matrix.os property as the value of the runs-on keyword to create a job for each operating system.
property exclude
readonly exclude?: Array<Record<string, JobMatrixValue>>;
You can remove a specific configurations defined in the build matrix using the exclude option. Using exclude removes a job defined by the build matrix.
property include
readonly include?: Array<Record<string, JobMatrixValue>>;
You can add additional configuration options to a build matrix job that already exists. For example, if you want to use a specific version of npm when the job that uses windows-latest and version 8 of node runs, you can use include to specify that additional option.
interface JobPermissions
interface JobPermissions {}
The available scopes and access values for workflow permissions. If you specify the access for any of these scopes, all those that are not specified are set to
JobPermission.NONE
, instead of the default behavior when none is specified.See Also
https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#defining-access-for-the-github_token-permissions
property actions
readonly actions?: JobPermission;
property attestations
readonly attestations?: JobPermission;
property checks
readonly checks?: JobPermission;
property contents
readonly contents?: JobPermission;
property deployments
readonly deployments?: JobPermission;
property discussions
readonly discussions?: JobPermission;
property idToken
readonly idToken?: JobPermission;
property issues
readonly issues?: JobPermission;
property models
readonly models?: JobPermission;
property packages
readonly packages?: JobPermission;
property pages
readonly pages?: JobPermission;
property pullRequests
readonly pullRequests?: JobPermission;
property repositoryProjects
readonly repositoryProjects?: JobPermission;
Deprecated
removed by GitHub
property securityEvents
readonly securityEvents?: JobPermission;
property statuses
readonly statuses?: JobPermission;
interface JobStep
interface JobStep extends Step, JobStepConfiguration {}
JobSteps run as part of a GitHub Workflow Job.
See Also
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps
interface JobStepConfiguration
interface JobStepConfiguration extends StepConfiguration {}
These settings are unique to a JobStep from the fields contained within the metadata action.yaml file present in when creating a new GitHub Action. These fields are not present in action.yml, but are in JobStep, which are using when creating workflows.
property continueOnError
readonly continueOnError?: boolean;
Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.
property timeoutMinutes
readonly timeoutMinutes?: number;
The maximum number of minutes to run the step before killing the process.
interface JobStepOutput
interface JobStepOutput {}
An output binding for a job.
property outputName
readonly outputName: string;
The name of the job output that is being bound.
property stepId
readonly stepId: string;
The ID of the step that exposes the output.
interface JobStrategy
interface JobStrategy {}
A strategy creates a build matrix for your jobs. You can define different variations to run each job in.
property failFast
readonly failFast?: boolean;
When set to true, GitHub cancels all in-progress jobs if any matrix job fails. Default: true
property matrix
readonly matrix?: JobMatrix;
You can define a matrix of different job configurations. A matrix allows you to create multiple jobs by performing variable substitution in a single job definition. For example, you can use a matrix to create jobs for more than one supported version of a programming language, operating system, or tool. A matrix reuses the job's configuration and creates a job for each matrix you configure.
A job matrix can generate a maximum of 256 jobs per workflow run. This limit also applies to self-hosted runners.
property maxParallel
readonly maxParallel?: number;
The maximum number of jobs that can run simultaneously when using a matrix job strategy. By default, GitHub will maximize the number of jobs run in parallel depending on the available runners on GitHub-hosted virtual machines.
interface LabelOptions
interface LabelOptions {}
Label options
property types
readonly types?: Array<'created' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface MergeGroupOptions
interface MergeGroupOptions {}
Merge group options.
experimental
property branches
readonly branches?: string[];
When using the merge_group events, you can configure a workflow to run on specific base branches. If not specified, all branches will trigger the workflow.
interface MilestoneOptions
interface MilestoneOptions {}
Milestone options
property types
readonly types?: Array<'created' | 'closed' | 'opened' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface PageBuildOptions
interface PageBuildOptions {}
The Page build event accepts no options.
interface ProjectCardOptions
interface ProjectCardOptions {}
Project card options
property types
readonly types?: Array<'created' | 'moved' | 'converted' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface ProjectColumnOptions
interface ProjectColumnOptions {}
Probject column options
property types
readonly types?: Array<'created' | 'updated' | 'moved' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface ProjectOptions
interface ProjectOptions {}
Project options
property types
readonly types?: Array< 'created' | 'updated' | 'closed' | 'reopened' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface PublicOptions
interface PublicOptions {}
The Public event accepts no options.
interface PullRequestOptions
interface PullRequestOptions extends PushOptions {}
Pull request options
property types
readonly types?: Array< | 'assigned' | 'unassigned' | 'labeled' | 'unlabeled' | 'opened' | 'edited' | 'closed' | 'reopened' | 'synchronize' | 'ready_for_review' | 'locked' | 'unlocked' | 'review_requested' | 'review_request_removed'>;
Which activity types to trigger on.
- all activity types
interface PullRequestReviewCommentOptions
interface PullRequestReviewCommentOptions {}
Pull request review comment options
property types
readonly types?: Array<'created' | 'edited' | 'deleted'>;
Which activity types to trigger on.
- all activity types
interface PullRequestReviewOptions
interface PullRequestReviewOptions {}
Pull request review options
property types
readonly types?: Array<'submitted' | 'edited' | 'dismissed'>;
Which activity types to trigger on.
- all activity types
interface PullRequestTargetOptions
interface PullRequestTargetOptions extends PushOptions {}
Pull request target options.
property types
readonly types?: Array< | 'assigned' | 'unassigned' | 'labeled' | 'unlabeled' | 'opened' | 'edited' | 'closed' | 'reopened' | 'synchronize' | 'ready_for_review' | 'locked' | 'unlocked' | 'review_requested' | 'review_request_removed'>;
Which activity types to trigger on.
- all activity types
interface PushOptions
interface PushOptions {}
Options for push-like events.
property branches
readonly branches?: string[];
When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags. For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.
See Also
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
property paths
readonly paths?: string[];
When using the push, pull_request and pull_request_target events, you can configure a workflow to run when at least one file does not match paths-ignore or at least one modified file matches the configured paths. Path filters are not evaluated for pushes to tags.
See Also
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
property tags
readonly tags?: string[];
When using the push, pull_request and pull_request_target events, you can configure a workflow to run on specific branches or tags. For a pull_request event, only branches and tags on the base are evaluated. If you define only tags or only branches, the workflow won't run for events affecting the undefined Git ref.
See Also
https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet
interface RegistryPackageOptions
interface RegistryPackageOptions {}
Registry package options
property types
readonly types?: Array<'published' | 'updated'>;
Which activity types to trigger on.
- all activity types
interface ReleaseOptions
interface ReleaseOptions {}
Release options
property types
readonly types?: Array< | 'published' | 'unpublished' | 'created' | 'edited' | 'deleted' | 'prereleased' | 'released'>;
Which activity types to trigger on.
- all activity types
interface RepositoryDispatchOptions
interface RepositoryDispatchOptions {}
Repository dispatch options.
property types
readonly types?: string[];
Which activity types to trigger on.
- all activity types
interface RunSettings
interface RunSettings {}
Run settings for a job.
property shell
readonly shell?: string;
Which shell to use for running the step.
Example 1
"bash"
property workingDirectory
readonly workingDirectory?: string;
Working directory to use when running the step.
interface StatusOptions
interface StatusOptions {}
The Status event accepts no options.
interface Step
interface Step extends StepConfiguration {}
This contains the fields that are common amongst both: - JobStep, which is a step that is part of a Job in Github Actions. This is by far the most common use case. - The metadata file
action.yaml
that is used to define an Action when you are creating one. As in, if you were creating an Action to be used in a JobStep. There is some overlap between the two, and this captures that overlap.See Also
https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions
property run
readonly run?: string;
Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.
property uses
readonly uses?: string;
Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.
property with
readonly with?: Record<string, any>;
A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.
interface StepConfiguration
interface StepConfiguration {}
Fields that describe the How, Why, When, and Who of a Step. These fields can have none present, but can be present on every Step, and have no effect on one another.
This stands in contrast to the Command (non-Configuration) fields, which are mutually exclusive, and describe the What.
property env
readonly env?: Record<string, string>;
Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job.
property id
readonly id?: string;
A unique identifier for the step. You can use the id to reference the step in contexts.
property if
readonly if?: string;
You can use the if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.
property name
readonly name?: string;
A name for your step to display on GitHub.
property workingDirectory
readonly workingDirectory?: string;
Specifies a working directory for a step. Overrides a job's working directory.
interface ToolRequirement
interface ToolRequirement {}
Version requirement for tools.
property version
readonly version: string;
interface Tools
interface Tools {}
Supported tools.
property dotnet
readonly dotnet?: ToolRequirement;
Setup .NET Core - not installed
property go
readonly go?: ToolRequirement;
Setup golang. - not installed
property java
readonly java?: ToolRequirement;
Setup java (temurin distribution). - not installed
property node
readonly node?: ToolRequirement;
Setup node.js - not installed
property python
readonly python?: ToolRequirement;
Setup python. - not installed
interface Triggers
interface Triggers {}
The set of available triggers for GitHub Workflows.
See Also
https://docs.github.com/en/actions/reference/events-that-trigger-workflows
property branchProtectionRule
readonly branchProtectionRule?: BranchProtectionRuleOptions;
Runs your workflow anytime the branch_protection_rule event occurs.
property checkRun
readonly checkRun?: CheckRunOptions;
Runs your workflow anytime the check_run event occurs.
property checkSuite
readonly checkSuite?: CheckSuiteOptions;
Runs your workflow anytime the check_suite event occurs.
property create
readonly create?: CreateOptions;
Runs your workflow anytime someone creates a branch or tag, which triggers the create event.
property delete
readonly delete?: DeleteOptions;
Runs your workflow anytime someone deletes a branch or tag, which triggers the delete event.
property deployment
readonly deployment?: DeploymentOptions;
Runs your workflow anytime someone creates a deployment, which triggers the deployment event. Deployments created with a commit SHA may not have a Git ref.
property deploymentStatus
readonly deploymentStatus?: DeploymentStatusOptions;
Runs your workflow anytime a third party provides a deployment status, which triggers the deployment_status event. Deployments created with a commit SHA may not have a Git ref.
property discussion
readonly discussion?: DiscussionOptions;
Runs your workflow anytime the discussion event occurs. More than one activity type triggers this event.
See Also
https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions
property discussionComment
readonly discussionComment?: DiscussionCommentOptions;
Runs your workflow anytime the discussion_comment event occurs. More than one activity type triggers this event.
See Also
https://docs.github.com/en/graphql/guides/using-the-graphql-api-for-discussions
property fork
readonly fork?: ForkOptions;
Runs your workflow anytime when someone forks a repository, which triggers the fork event.
property gollum
readonly gollum?: GollumOptions;
Runs your workflow when someone creates or updates a Wiki page, which triggers the gollum event.
property issueComment
readonly issueComment?: IssueCommentOptions;
Runs your workflow anytime the issue_comment event occurs.
property issues
readonly issues?: IssuesOptions;
Runs your workflow anytime the issues event occurs.
property label
readonly label?: LabelOptions;
Runs your workflow anytime the label event occurs.
property mergeGroup
readonly mergeGroup?: MergeGroupOptions;
Runs your workflow when a pull request is added to a merge queue, which adds the pull request to a merge group.
experimental
property milestone
readonly milestone?: MilestoneOptions;
Runs your workflow anytime the milestone event occurs.
property pageBuild
readonly pageBuild?: PageBuildOptions;
Runs your workflow anytime someone pushes to a GitHub Pages-enabled branch, which triggers the page_build event.
property project
readonly project?: ProjectOptions;
Runs your workflow anytime the project event occurs.
property projectCard
readonly projectCard?: ProjectCardOptions;
Runs your workflow anytime the project_card event occurs.
property projectColumn
readonly projectColumn?: ProjectColumnOptions;
Runs your workflow anytime the project_column event occurs.
property public
readonly public?: PublicOptions;
Runs your workflow anytime someone makes a private repository public, which triggers the public event.
property pullRequest
readonly pullRequest?: PullRequestOptions;
Runs your workflow anytime the pull_request event occurs.
property pullRequestReview
readonly pullRequestReview?: PullRequestReviewOptions;
Runs your workflow anytime the pull_request_review event occurs.
property pullRequestReviewComment
readonly pullRequestReviewComment?: PullRequestReviewCommentOptions;
Runs your workflow anytime a comment on a pull request's unified diff is modified, which triggers the pull_request_review_comment event.
property pullRequestTarget
readonly pullRequestTarget?: PullRequestTargetOptions;
This event runs in the context of the base of the pull request, rather than in the merge commit as the pull_request event does. This prevents executing unsafe workflow code from the head of the pull request that could alter your repository or steal any secrets you use in your workflow. This event allows you to do things like create workflows that label and comment on pull requests based on the contents of the event payload.
WARNING: The
pull_request_target
event is granted read/write repository token and can access secrets, even when it is triggered from a fork. Although the workflow runs in the context of the base of the pull request, you should make sure that you do not check out, build, or run untrusted code from the pull request with this event. Additionally, any caches share the same scope as the base branch, and to help prevent cache poisoning, you should not save the cache if there is a possibility that the cache contents were altered.See Also
https://securitylab.github.com/research/github-actions-preventing-pwn-requests
property push
readonly push?: PushOptions;
Runs your workflow when someone pushes to a repository branch, which triggers the push event.
property registryPackage
readonly registryPackage?: RegistryPackageOptions;
Runs your workflow anytime a package is published or updated.
property release
readonly release?: ReleaseOptions;
Runs your workflow anytime the release event occurs.
property repositoryDispatch
readonly repositoryDispatch?: RepositoryDispatchOptions;
You can use the GitHub API to trigger a webhook event called repository_dispatch when you want to trigger a workflow for activity that happens outside of GitHub.
property schedule
readonly schedule?: CronScheduleOptions[];
You can schedule a workflow to run at specific UTC times using POSIX cron syntax. Scheduled workflows run on the latest commit on the default or base branch. The shortest interval you can run scheduled workflows is once every 5 minutes.
See Also
https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07
property status
readonly status?: StatusOptions;
Runs your workflow anytime the status of a Git commit changes, which triggers the status event.
property watch
readonly watch?: WatchOptions;
Runs your workflow anytime the watch event occurs.
property workflowCall
readonly workflowCall?: WorkflowCallOptions;
Can be called from another workflow
See Also
https://docs.github.com/en/actions/learn-github-actions/reusing-workflows
property workflowDispatch
readonly workflowDispatch?: WorkflowDispatchOptions;
You can configure custom-defined input properties, default input values, and required inputs for the event directly in your workflow. When the workflow runs, you can access the input values in the github.event.inputs context.
property workflowRun
readonly workflowRun?: WorkflowRunOptions;
This event occurs when a workflow run is requested or completed, and allows you to execute a workflow based on the finished result of another workflow. A workflow run is triggered regardless of the result of the previous workflow.
interface WatchOptions
interface WatchOptions {}
Watch options
property types
readonly types?: Array<'started'>;
Which activity types to trigger on.
- all activity types
interface WorkflowCallOptions
interface WorkflowCallOptions {}
The Workflow Call event accepts no options.
interface WorkflowDispatchOptions
interface WorkflowDispatchOptions {}
The Workflow dispatch event accepts no options.
interface WorkflowRunOptions
interface WorkflowRunOptions {}
Workflow run options
property branches
readonly branches?: Array<string>;
Which branches or branch-ignore to limit the trigger to.
- no branch limits
property types
readonly types?: Array<'completed' | 'requested'>;
Which activity types to trigger on.
- all activity types
property workflows
readonly workflows?: Array<string>;
Which workflow to trigger on.
- any workflows
enum AppPermission
enum AppPermission { READ = 'read', WRITE = 'write', ADMIN = 'admin',}
The permissions available for an access token for a GitHub App.
enum JobPermission
enum JobPermission { READ = 'read', WRITE = 'write', NONE = 'none',}
Access level for workflow permission scopes.
namespace gitlab
module 'lib/gitlab/index.d.ts' {}
class CiConfiguration
class CiConfiguration extends Component {}
CI for GitLab. A CI is a configurable automated process made up of one or more stages/jobs.
See Also
https://docs.gitlab.com/ee/ci/yaml/
constructor
constructor(project: Project, name: string, options?: CiConfigurationOptions);
property defaultAfterScript
readonly defaultAfterScript: string[];
Defines default scripts that should run *after* all jobs. Can be overriden by the job level
afterScript
.
property defaultArtifacts
readonly defaultArtifacts?: Artifacts;
Default list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to Gitlab where they can be downloaded.
property defaultBeforeScript
readonly defaultBeforeScript: string[];
Defines default scripts that should run *before* all jobs. Can be overriden by the job level
afterScript
.
property defaultCache
readonly defaultCache: Cache[];
property defaultIdTokens
readonly defaultIdTokens?: Record<string, IDToken>;
Default ID tokens (JSON Web Tokens) that are used for CI/CD authentication to use globally for all jobs.
property defaultImage
readonly defaultImage?: Image;
Specifies the default docker image to use globally for all jobs.
property defaultInterruptible
readonly defaultInterruptible?: boolean;
The default behavior for whether a job should be canceled when a newer pipeline starts before the job completes (Default: false).
property defaultRetry
readonly defaultRetry?: Retry;
How many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.
property defaultTags
readonly defaultTags: string[];
Used to select a specific runner from the list of all runners that are available for the project.
property defaultTimeout
readonly defaultTimeout?: string;
A default timeout job written in natural language (Ex. one hour, 3600 seconds, 60 minutes).
property file
readonly file: YamlFile;
The workflow YAML file.
property jobs
readonly jobs: Record<string, Job>;
The jobs in the CI configuration.
property name
readonly name: string;
The name of the configuration.
property pages
readonly pages?: Job;
A special job used to upload static sites to Gitlab pages. Requires a
public/
directory withartifacts.path
pointing to it.
property path
readonly path: string;
Path to CI file generated by the configuration.
property stages
readonly stages: string[];
Groups jobs into stages. All jobs in one stage must complete before next stage is executed. Defaults to ['build', 'test', 'deploy'].
property variables
readonly variables: Record<string, string | number | VariableConfig>;
Global variables that are passed to jobs. If the job already has that variable defined, the job-level variable takes precedence.
property workflow
readonly workflow?: Workflow;
Used to control pipeline behavior.
method addDefaultCaches
addDefaultCaches: (caches: Cache[]) => void;
Adds up to 4 default caches configuration to the CI configuration.
Parameter caches
Caches to add.
method addGlobalVariables
addGlobalVariables: (variables: Record<string, any>) => void;
Add a globally defined variable to the CI configuration.
Parameter variables
The variables to add.
method addIncludes
addIncludes: (...includes: Include[]) => void;
Add additional yml/yaml files to the CI includes
Parameter includes
The includes to add.
method addJobs
addJobs: (jobs: Record<string, Job>) => void;
Add jobs and their stages to the CI configuration.
Parameter jobs
Jobs to add.
method addServices
addServices: (...services: Service[]) => void;
Add additional services.
Parameter services
The services to add.
method addStages
addStages: (...stages: string[]) => void;
Add stages to the CI configuration if not already present.
Parameter stages
stages to add.
class GitlabConfiguration
class GitlabConfiguration extends CiConfiguration {}
A GitLab CI for the main
.gitlab-ci.yml
file.
constructor
constructor(project: Project, options?: CiConfigurationOptions);
property nestedTemplates
readonly nestedTemplates: Record<string, NestedConfiguration>;
method createNestedTemplates
createNestedTemplates: (config: Record<string, CiConfigurationOptions>) => void;
Creates and adds nested templates to the includes of the main CI. Additionally adds their stages to the main CI if they are not already present. You can futher customize nested templates through the
nestedTemplates
property. E.g. gitlabConfig.nestedTemplates['templateName']?.addStages('stageName')Parameter config
a record the names and configuraitons of the templates.
class NestedConfiguration
class NestedConfiguration extends CiConfiguration {}
A GitLab CI for templates that are created and included in the
.gitlab-ci.yml
file.
constructor
constructor( project: Project, parent: GitlabConfiguration, name: string, options?: CiConfigurationOptions);
property parent
readonly parent: GitlabConfiguration;
interface AllowFailure
interface AllowFailure {}
Exit code that are not considered failure. The job fails for any other exit code. You can list which exit codes are not considered failures. The job fails for any other exit code.
See Also
https://docs.gitlab.com/ee/ci/yaml/#allow_failure
property exitCodes
readonly exitCodes: number[] | number;
interface Artifacts
interface Artifacts {}
Used to specify a list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to Gitlab where they can be downloaded.
See Also
https://docs.gitlab.com/ee/ci/yaml/#artifacts
property exclude
readonly exclude?: string[];
A list of paths to files/folders that should be excluded in the artifact.
property expireIn
readonly expireIn?: string;
How long artifacts should be kept. They are saved 30 days by default. Artifacts that have expired are removed periodically via cron job. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'.
property exposeAs
readonly exposeAs?: string;
Can be used to expose job artifacts in the merge request UI. GitLab will add a link <expose_as> to the relevant merge request that points to the artifact.
property name
readonly name?: string;
Name for the archive created on job success. Can use variables in the name, e.g. '$CI_JOB_NAME'
property paths
readonly paths?: string[];
A list of paths to files/folders that should be included in the artifact.
property reports
readonly reports?: Reports;
Reports will be uploaded as artifacts, and often displayed in the Gitlab UI, such as in Merge Requests.
property untracked
readonly untracked?: boolean;
Whether to add all untracked files (along with 'artifacts.paths') to the artifact.
property when
readonly when?: CacheWhen;
Configure when artifacts are uploaded depended on job status.
interface Assets
interface Assets {}
Asset configuration for a release.
property links
readonly links: Link[];
Include asset links in the release.
interface Cache
interface Cache {}
Cache Definition.
See Also
https://docs.gitlab.com/ee/ci/yaml/#cache
property fallbackKeys
readonly fallbackKeys?: string[];
Use cache:fallback_keys to specify a list of keys to try to restore cache from if there is no cache found for the cache:key. Caches are retrieved in the order specified in the fallback_keys section.
property key
readonly key?: string | CacheKeyFiles;
Used the to give each cache a unique identifying key. All jobs that use the same cache key use the same cache.
property paths
readonly paths?: string[];
Defines which files or directories to cache.
property policy
readonly policy?: CachePolicy;
Defines the upload and download behaviour of the cache.
property untracked
readonly untracked?: boolean;
If set to true all files that are untracked in your Git repository will be cached.
property when
readonly when?: CacheWhen;
Defines when to save the cache, based on the status of the job (Default: Job Success).
interface CacheKeyFiles
interface CacheKeyFiles {}
Use this construct to generate a new key when one or two specific files change.
See Also
https://docs.gitlab.com/ee/ci/yaml/#cachekeyfiles
interface CiConfigurationOptions
interface CiConfigurationOptions {}
Options for
CiConfiguration
.
property default
readonly default?: Default;
Default settings for the CI Configuration. Jobs that do not define one or more of the listed keywords use the value defined in the default section.
property jobs
readonly jobs?: Record<string, Job>;
An initial set of jobs to add to the configuration.
property pages
readonly pages?: Job;
A special job used to upload static sites to Gitlab pages. Requires a
public/
directory withartifacts.path
pointing to it.
property path
readonly path?: string;
The path of the file to generate.
property stages
readonly stages?: string[];
Groups jobs into stages. All jobs in one stage must complete before next stage is executed. If no stages are specified. Defaults to ['build', 'test', 'deploy'].
property variables
readonly variables?: Record<string, any>;
Global variables that are passed to jobs. If the job already has that variable defined, the job-level variable takes precedence.
property workflow
readonly workflow?: Workflow;
Used to control pipeline behavior.
interface CoverageReport
interface CoverageReport {}
Code coverage report interface https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscoverage_report
property coverageFormat
readonly coverageFormat: string;
property path
readonly path: string;
interface Default
interface Default {}
Default settings for the CI Configuration. Jobs that do not define one or more of the listed keywords use the value defined in the default section.
See Also
https://docs.gitlab.com/ee/ci/yaml/#default
property afterScript
readonly afterScript?: string[];
property artifacts
readonly artifacts?: Artifacts;
property beforeScript
readonly beforeScript?: string[];
property cache
readonly cache?: Cache[];
property idTokens
readonly idTokens?: Record<string, IDToken>;
Specifies the default ID tokens (JSON Web Tokens) that are used for CI/CD authentication to use globally for all jobs.
property image
readonly image?: Image;
property interruptible
readonly interruptible?: boolean;
property retry
readonly retry?: Retry;
property services
readonly services?: Service[];
property tags
readonly tags?: string[];
property timeout
readonly timeout?: string;
interface Engine
interface Engine {}
The engine configuration for a secret.
interface Environment
interface Environment {}
The environment that a job deploys to.
property action
readonly action?: Action;
Specifies what this job will do. 'start' (default) indicates the job will start the deployment. 'prepare' indicates this will not affect the deployment. 'stop' indicates this will stop the deployment.
property autoStopIn
readonly autoStopIn?: string;
The amount of time it should take before Gitlab will automatically stop the environment. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'.
property deploymentTier
readonly deploymentTier?: DeploymentTier;
Explicitly specifies the tier of the deployment environment if non-standard environment name is used.
property kubernetes
readonly kubernetes?: KubernetesConfig;
Used to configure the kubernetes deployment for this environment. This is currently not supported for kubernetes clusters that are managed by Gitlab.
property name
readonly name: string;
The name of the environment, e.g. 'qa', 'staging', 'production'.
property onStop
readonly onStop?: string;
The name of a job to execute when the environment is about to be stopped.
property url
readonly url?: string;
When set, this will expose buttons in various places for the current environment in Gitlab, that will take you to the defined URL.
interface Filter
interface Filter {}
Filtering options for when a job will run.
property changes
readonly changes?: string[];
Filter job creation based on files that were modified in a git push.
property kubernetes
readonly kubernetes?: KubernetesEnum;
Filter job based on if Kubernetes integration is active.
property refs
readonly refs?: string[];
Control when to add jobs to a pipeline based on branch names or pipeline types.
property variables
readonly variables?: string[];
Filter job by checking comparing values of environment variables. Read more about variable expressions: https://docs.gitlab.com/ee/ci/variables/README.html#variables-expressions
interface IDToken
interface IDToken {}
id_tokens Definition.
See Also
https://docs.gitlab.com/ee/ci/yaml/#id_tokens
property aud
aud: string[] | string;
The required aud sub-keyword is used to configure the aud claim for the JWT.
interface Image
interface Image {}
Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of Gitlab runner executor.
See Also
https://docs.gitlab.com/ee/ci/yaml/#image
property entrypoint
readonly entrypoint?: any[];
Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array.
property name
readonly name: string;
Full name of the image that should be used. It should contain the Registry part if needed.
interface Include
interface Include {}
An included YAML file.
See Also
https://docs.gitlab.com/ee/ci/yaml/#include
property file
readonly file?: string[];
Files from another private project on the same GitLab instance. You can use
file
in combination withproject
only.
property local
readonly local?: string;
Relative path from local repository root (
/
) to theyaml
/yml
file template. The file must be on the same branch, and does not work across git submodules.
property project
readonly project?: string;
Path to the project, e.g.
group/project
, orgroup/sub-group/project
.
property ref
readonly ref?: string;
Branch/Tag/Commit-hash for the target project.
property remote
readonly remote?: string;
URL to a
yaml
/yml
template file using HTTP/HTTPS.
property rules
readonly rules?: IncludeRule[];
Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.
property template
readonly template?: string;
Use a
.gitlab-ci.yml
template as a base, e.g.Nodejs.gitlab-ci.yml
.
interface IncludeRule
interface IncludeRule {}
Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.
See Also
https://docs.gitlab.com/ee/ci/yaml/includes.html#use-rules-with-include
property allowFailure
readonly allowFailure?: boolean | AllowFailure;
property changes
readonly changes?: string[];
property exists
readonly exists?: string[];
property if
readonly if?: string;
property needs
readonly needs?: string[];
property startIn
readonly startIn?: string;
property variables
readonly variables?: Record<string, string>;
property when
readonly when?: JobWhen;
interface Inherit
interface Inherit {}
Controls inheritance of globally-defined defaults and variables. Boolean values control inheritance of all default: or variables: keywords. To inherit only a subset of default: or variables: keywords, specify what you wish to inherit. Anything not listed is not inherited.
interface Job
interface Job {}
Jobs are the most fundamental element of a .gitlab-ci.yml file.
See Also
https://docs.gitlab.com/ee/ci/jobs/
property afterScript
readonly afterScript?: string[];
property allowFailure
readonly allowFailure?: boolean | AllowFailure;
Whether to allow the pipeline to continue running on job failure (Default: false).
property artifacts
readonly artifacts?: Artifacts;
property beforeScript
readonly beforeScript?: string[];
property cache
readonly cache?: Cache[];
property coverage
readonly coverage?: string;
Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+.\d+/'
property dependencies
readonly dependencies?: string[];
Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts.
property environment
readonly environment?: Environment | string;
Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project.
property except
readonly except?: string[] | Filter;
Job will run *except* for when these filtering options match.
property extends
readonly extends?: string[];
The name of one or more jobs to inherit configuration from.
property idTokens
readonly idTokens?: Record<string, IDToken>;
Configurable ID tokens (JSON Web Tokens) that are used for CI/CD authentication
property image
readonly image?: Image;
property inherit
readonly inherit?: Inherit;
Controls inheritance of globally-defined defaults and variables. Boolean values control inheritance of all default: or variables: keywords. To inherit only a subset of default: or variables: keywords, specify what you wish to inherit. Anything not listed is not inherited.
property interruptible
readonly interruptible?: boolean;
property needs
readonly needs?: Array<Need | string>;
The list of jobs in previous stages whose sole completion is needed to start the current job.
property only
readonly only?: string[] | Filter;
Job will run *only* when these filtering options match.
property parallel
readonly parallel?: Parallel | number;
Parallel will split up a single job into several, and provide
CI_NODE_INDEX
andCI_NODE_TOTAL
environment variables for the running jobs.
property release
readonly release?: Release;
Indicates that the job creates a Release.
property resourceGroup
readonly resourceGroup?: string;
Limit job concurrency. Can be used to ensure that the Runner will not run certain jobs simultaneously.
property retry
readonly retry?: Retry;
property rules
readonly rules?: IncludeRule[];
Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job.
property script
readonly script?: string[];
Shell scripts executed by the Runner. The only required property of jobs. Be careful with special characters (e.g.
:
,{
,}
,&
) and use single or double quotes to avoid issues.
property secrets
readonly secrets?: Record<string, Record<string, Secret>>;
CI/CD secrets
property services
readonly services?: Service[];
property stage
readonly stage?: string;
Define what stage the job will run in.
property startIn
readonly startIn?: string;
property tags
readonly tags?: string[];
property timeout
readonly timeout?: string;
property trigger
readonly trigger?: Trigger | string;
Trigger allows you to define downstream pipeline trigger. When a job created from trigger definition is started by GitLab, a downstream pipeline gets created. Read more: https://docs.gitlab.com/ee/ci/yaml/README.html#trigger
property variables
readonly variables?: Record<string, string>;
Configurable values that are passed to the Job.
property when
readonly when?: JobWhen;
Describes the conditions for when to run the job. Defaults to 'on_success'.
interface KubernetesConfig
interface KubernetesConfig {}
Used to configure the kubernetes deployment for this environment. This is currently not supported for kubernetes clusters that are managed by Gitlab.
property namespace
readonly namespace?: string;
The kubernetes namespace where this environment should be deployed to.
interface Link
interface Link {}
Link configuration for an asset.
interface Need
interface Need {}
A jobs in a previous stage whose sole completion is needed to start the current job.
interface Parallel
interface Parallel {}
Used to run a job multiple times in parallel in a single pipeline.
property matrix
readonly matrix: Record<string, any[]>[];
Defines different variables for jobs that are running in parallel.
interface Release
interface Release {}
Indicates that the job creates a Release.
property assets
readonly assets?: Assets;
property description
readonly description: string;
Specifies the longer description of the Release.
property milestones
readonly milestones?: string[];
The title of each milestone the release is associated with.
property name
readonly name?: string;
The Release name. If omitted, it is populated with the value of release: tag_name.
property ref
readonly ref?: string;
If the release: tag_name doesn’t exist yet, the release is created from ref. ref can be a commit SHA, another tag name, or a branch name.
property releasedAt
readonly releasedAt?: string;
The date and time when the release is ready. Defaults to the current date and time if not defined. Should be enclosed in quotes and expressed in ISO 8601 format.
property tagName
readonly tagName: string;
The tag_name must be specified. It can refer to an existing Git tag or can be specified by the user.
interface Reports
interface Reports {}
Reports will be uploaded as artifacts, and often displayed in the Gitlab UI, such as in Merge Requests.
See Also
https://docs.gitlab.com/ee/ci/yaml/#artifactsreports
property cobertura
readonly cobertura?: string[];
Path for file(s) that should be parsed as Cobertura XML coverage report
Deprecated
per https://docs.gitlab.com/ee/update/deprecations.html#artifactsreportscobertura-keyword use coverageReport instead
property codequality
readonly codequality?: string[];
Path to file or list of files with code quality report(s) (such as Code Climate).
property containerScanning
readonly containerScanning?: string[];
Path to file or list of files with Container scanning vulnerabilities report(s).
property coverageReport
readonly coverageReport?: CoverageReport;
Code coverage report information
property dast
readonly dast?: string[];
Path to file or list of files with DAST vulnerabilities report(s).
property dependencyScanning
readonly dependencyScanning?: string[];
Path to file or list of files with Dependency scanning vulnerabilities report(s).
property dotenv
readonly dotenv?: string[];
Path to file or list of files containing runtime-created variables for this job.
property junit
readonly junit?: string[];
Path for file(s) that should be parsed as JUnit XML result
property licenseManagement
readonly licenseManagement?: string[];
Deprecated in 12.8: Path to file or list of files with license report(s).
property licenseScanning
readonly licenseScanning?: string[];
Path to file or list of files with license report(s).
property lsif
readonly lsif?: string[];
Path to file or list of files containing code intelligence (Language Server Index Format).
property metrics
readonly metrics?: string[];
Path to file or list of files with custom metrics report(s).
property performance
readonly performance?: string[];
Path to file or list of files with performance metrics report(s).
property requirements
readonly requirements?: string[];
Path to file or list of files with requirements report(s).
property sast
readonly sast?: string[];
Path to file or list of files with SAST vulnerabilities report(s).
property secretDetection
readonly secretDetection?: string[];
Path to file or list of files with secret detection report(s).
property terraform
readonly terraform?: string[];
Path to file or list of files with terraform plan(s).
interface Retry
interface Retry {}
How many times a job is retried if it fails. If not defined, defaults to 0 and jobs do not retry.
See Also
https://docs.gitlab.com/ee/ci/yaml/#retry
interface Service
interface Service {}
Used to specify an additional Docker image to run scripts in. The service image is linked to the image specified in the image keyword.
See Also
https://docs.gitlab.com/ee/ci/yaml/#services
property alias
readonly alias?: string;
Additional alias that can be used to access the service from the job's container. Read Accessing the services for more information.
property command
readonly command?: string[];
Command or script that should be used as the container's command. It will be translated to arguments passed to Docker after the image's name. The syntax is similar to Dockerfile's CMD directive, where each shell token is a separate string in the array.
property entrypoint
readonly entrypoint?: string[];
Command or script that should be executed as the container's entrypoint. It will be translated to Docker's --entrypoint option while creating the container. The syntax is similar to Dockerfile's ENTRYPOINT directive, where each shell token is a separate string in the array.
property name
readonly name: string;
Full name of the image that should be used. It should contain the Registry part if needed.
property pullPolicy
readonly pullPolicy?: PullPolicy[];
The pull policy that the runner uses to fetch the Docker image
property variables
readonly variables?: Record<string, string>;
Additional environment variables that are passed exclusively to the service..
interface Trigger
interface Trigger {}
Trigger a multi-project or a child pipeline. Read more:
See Also
https://docs.gitlab.com/ee/ci/yaml/README.html#simple-trigger-syntax-for-multi-project-pipelines
https://docs.gitlab.com/ee/ci/yaml/README.html#trigger-syntax-for-child-pipeline
property branch
readonly branch?: string;
The branch name that a downstream pipeline will use
property include
readonly include?: TriggerInclude[];
A list of local files or artifacts from other jobs to define the pipeline
property project
readonly project?: string;
Path to the project, e.g.
group/project
, orgroup/sub-group/project
.
property strategy
readonly strategy?: Strategy;
You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend
interface TriggerInclude
interface TriggerInclude {}
References a local file or an artifact from another job to define the pipeline configuration.
See Also
https://docs.gitlab.com/ee/ci/yaml/#triggerinclude
property artifact
readonly artifact?: string;
Relative path to the generated YAML file which is extracted from the artifacts and used as the configuration for triggering the child pipeline.
property file
readonly file?: string;
Relative path from repository root (
/
) to the pipeline configuration YAML file.
property job
readonly job?: string;
Job name which generates the artifact
property local
readonly local?: string;
Relative path from local repository root (
/
) to the local YAML file to define the pipeline configuration.
property project
readonly project?: string;
Path to another private project under the same GitLab instance, like
group/project
orgroup/sub-group/project
.
property ref
readonly ref?: string;
Branch/Tag/Commit hash for the target project.
property template
readonly template?: string;
Name of the template YAML file to use in the pipeline configuration.
interface VariableConfig
interface VariableConfig {}
Explains what the global variable is used for, what the acceptable values are.
See Also
https://docs.gitlab.com/ee/ci/yaml/#variables
property description
readonly description?: string;
Define a global variable that is prefilled when running a pipeline manually. Must be used with value.
property value
readonly value?: string;
The variable value.
interface VaultConfig
interface VaultConfig {}
Specification for a secret provided by a HashiCorp Vault.
See Also
https://www.vaultproject.io/
interface Workflow
interface Workflow {}
Used to control pipeline behavior.
See Also
https://docs.gitlab.com/ee/ci/yaml/#workflow
interface WorkflowRule
interface WorkflowRule {}
Used to control whether or not a whole pipeline is created.
See Also
https://docs.gitlab.com/ee/ci/yaml/#workflowrules
enum Action
enum Action { PREPARE = 'prepare', START = 'start', STOP = 'stop',}
Specifies what this job will do. 'start' (default) indicates the job will start the deployment. 'prepare' indicates this will not affect the deployment. 'stop' indicates this will stop the deployment.
enum CachePolicy
enum CachePolicy { PULL = 'pull', PUSH = 'push', PULL_PUSH = 'pull-push',}
Configure the upload and download behaviour of a cache.
See Also
https://docs.gitlab.com/ee/ci/yaml/#cachepolicy
member PULL
PULL = 'pull'
Only download the cache when the job starts, but never upload changes when the job finishes.
member PULL_PUSH
PULL_PUSH = 'pull-push'
The job downloads the cache when the job starts, and uploads changes to the cache when the job ends.
member PUSH
PUSH = 'push'
Only upload a cache when the job finishes, but never download the cache when the job starts.
enum CacheWhen
enum CacheWhen { ALWAYS = 'always', ON_FAILURE = 'on_failure', ON_SUCCESS = 'on_success',}
Configure when artifacts are uploaded depended on job status.
See Also
https://docs.gitlab.com/ee/ci/yaml/#cachewhen
member ALWAYS
ALWAYS = 'always'
Upload artifacts regardless of job status.
member ON_FAILURE
ON_FAILURE = 'on_failure'
Upload artifacts only when the job fails.
member ON_SUCCESS
ON_SUCCESS = 'on_success'
Upload artifacts only when the job succeeds (this is the default).
enum DefaultElement
enum DefaultElement { AFTER_SCRIPT = 'after_script', ARTIFACTS = 'artifacts', BEFORE_SCRIPT = 'before_script', CACHE = 'cache', IMAGE = 'image', INTERRUPTIBLE = 'interruptible', RETRY = 'retry', SERVICES = 'services', TAGS = 'tags', TIMEOUT = 'timeout',}
member AFTER_SCRIPT
AFTER_SCRIPT = 'after_script'
member ARTIFACTS
ARTIFACTS = 'artifacts'
member BEFORE_SCRIPT
BEFORE_SCRIPT = 'before_script'
member CACHE
CACHE = 'cache'
member IMAGE
IMAGE = 'image'
member INTERRUPTIBLE
INTERRUPTIBLE = 'interruptible'
member RETRY
RETRY = 'retry'
member SERVICES
SERVICES = 'services'
member TAGS
TAGS = 'tags'
member TIMEOUT
TIMEOUT = 'timeout'
enum DeploymentTier
enum DeploymentTier { DEVELOPMENT = 'development', OTHER = 'other', PRODUCTION = 'production', STAGING = 'staging', TESTING = 'testing',}
Explicitly specifies the tier of the deployment environment if non-standard environment name is used.
member DEVELOPMENT
DEVELOPMENT = 'development'
member OTHER
OTHER = 'other'
member PRODUCTION
PRODUCTION = 'production'
member STAGING
STAGING = 'staging'
member TESTING
TESTING = 'testing'
enum JobWhen
enum JobWhen { ALWAYS = 'always', DELAYED = 'delayed', MANUAL = 'manual', NEVER = 'never', ON_FAILURE = 'on_failure', ON_SUCCESS = 'on_success',}
Describes the conditions for when to run the job. Defaults to 'on_success'.
See Also
https://docs.gitlab.com/ee/ci/yaml/#when
member ALWAYS
ALWAYS = 'always'
member DELAYED
DELAYED = 'delayed'
member MANUAL
MANUAL = 'manual'
member NEVER
NEVER = 'never'
member ON_FAILURE
ON_FAILURE = 'on_failure'
member ON_SUCCESS
ON_SUCCESS = 'on_success'
enum KubernetesEnum
enum KubernetesEnum { ACTIVE = 'active',}
Filter job based on if Kubernetes integration is active.
member ACTIVE
ACTIVE = 'active'
enum LinkType
enum LinkType { IMAGE = 'image', OTHER = 'other', PACKAGE = 'package', RUNBOOK = 'runbook',}
The content kind of what users can download via url.
enum PullPolicy
enum PullPolicy { ALWAYS = 'always', NEVER = 'never', IF_NOT_PRESENT = 'if-not-present',}
Describes the conditions for when to pull an image.
See Also
https://docs.gitlab.com/ee/ci/yaml/#servicepull_policy
member ALWAYS
ALWAYS = 'always'
member IF_NOT_PRESENT
IF_NOT_PRESENT = 'if-not-present'
member NEVER
NEVER = 'never'
enum Strategy
enum Strategy { DEPEND = 'depend',}
You can mirror the pipeline status from the triggered pipeline to the source bridge job by using strategy: depend
See Also
https://docs.gitlab.com/ee/ci/yaml/#triggerstrategy
member DEPEND
DEPEND = 'depend'
enum WorkflowWhen
enum WorkflowWhen { ALWAYS = 'always', NEVER = 'never',}
Describes the conditions for when to run the job. Defaults to 'on_success'. The value can only be 'always' or 'never' when used with workflow.
See Also
https://docs.gitlab.com/ee/ci/yaml/#workflowrules
namespace java
module 'lib/java/index.d.ts' {}
function generateJavaOptionNames
generateJavaOptionNames: ( options: ProjectOption[], jsiiManifest: any) => Record<string, string>;
function getJavaImport
getJavaImport: (jsiiType: any, jsiiManifest: any) => string;
class JavaProject
class JavaProject extends GitHubProject {}
Java project.
java
constructor
constructor(options: JavaProjectOptions);
property compile
readonly compile: MavenCompile;
Compile component.
property distdir
readonly distdir: string;
Maven artifact output directory.
property junit
readonly junit?: Junit;
JUnit component.
property packaging
readonly packaging: MavenPackaging;
Packaging component.
property pom
readonly pom: Pom;
API for managing
pom.xml
.
property projenrc
readonly projenrc?: ProjenrcJava;
Projenrc component.
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<groupId>/<artifactId>@<semver>
method addPlugin
addPlugin: (spec: string, options?: PluginOptions) => import('..').Dependency;
Adds a build plugin to the pom.
The plug in is also added as a BUILD dep to the project.
Parameter spec
dependency spec (
group/artifact@version
)Parameter options
plugin options
method addTestDependency
addTestDependency: (spec: string) => void;
Adds a test dependency.
Parameter spec
Format
<groupId>/<artifactId>@<semver>
class Junit
class Junit extends Component {}
Implements JUnit-based testing.
constructor
constructor(project: Project, options: JunitOptions);
class MavenCompile
class MavenCompile extends Component {}
Adds the maven-compiler plugin to a POM file and the
compile
task.
constructor
constructor(project: Project, pom: Pom, options?: MavenCompileOptions);
class MavenPackaging
class MavenPackaging extends Component {}
Configures a maven project to produce a .jar archive with sources and javadocs.
constructor
constructor(project: Project, pom: Pom, options?: MavenPackagingOptions);
property distdir
readonly distdir: string;
The directory containing the package output, relative to the project outdir
class MavenSample
class MavenSample extends Component {}
Java code sample.
constructor
constructor(project: Project, options: MavenSampleOptions);
class Pom
class Pom extends Component {}
A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project.
constructor
constructor(project: Project, options: PomOptions);
property artifactId
readonly artifactId: string;
Maven artifact ID.
property description
readonly description?: string;
Project description.
property fileName
readonly fileName: string;
The name of the pom file.
property groupId
readonly groupId: string;
Maven group ID.
property name
readonly name?: string;
Project display name.
property packaging
readonly packaging: string;
Maven packaging format.
property url
readonly url?: string;
Project URL.
property version
readonly version: string;
Project version.
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<groupId>/<artifactId>@<semver>
method addPlugin
addPlugin: ( spec: string, options?: PluginOptions) => import('../dependencies').Dependency;
Adds a build plugin to the pom.
The plug in is also added as a BUILD dep to the project.
Parameter spec
dependency spec (
group/artifact@version
)Parameter options
plugin options
method addPluginRepository
addPluginRepository: (repository: MavenRepository) => void;
method addProperty
addProperty: (key: string, value: string) => void;
Adds a key/value property to the pom.
Parameter key
the key
Parameter value
the value
method addRepository
addRepository: (repository: MavenRepository) => void;
Adds a repository to the pom
Parameter repository
the repository to add
method addTestDependency
addTestDependency: (spec: string) => void;
Adds a test dependency.
Parameter spec
Format
<groupId>/<artifactId>@<semver>
class Projenrc
class Projenrc extends ProjenrcFile {}
Allows writing projenrc files in java.
This will install
org.projen/projen
as a Maven dependency and will add asynth
task which will compile & executemain()
fromsrc/main/java/projenrc.java
.
constructor
constructor(project: Project, pom: Pom, options?: ProjenrcOptions);
property className
readonly className: string;
The name of the java class that includes the projen entrypoint.
property filePath
readonly filePath: string;
The path of the projenrc file.
class UpdatePolicy
class UpdatePolicy {}
interface JavaProjectCommonOptions
interface JavaProjectCommonOptions extends GitHubProjectOptions, PomOptions {}
Options for
JavaProject
.
property compileOptions
readonly compileOptions?: MavenCompileOptions;
Compile options. - defaults
property deps
readonly deps?: string[];
List of runtime dependencies for this project.
Dependencies use the format:
<groupId>/<artifactId>@<semver>
Additional dependencies can be added via
project.addDependency()
.[]
property distdir
readonly distdir?: string;
Final artifact output directory.
"dist/java"
property junit
readonly junit?: boolean;
Include junit tests. true
property junitOptions
readonly junitOptions?: JunitOptions;
junit options - defaults
property packagingOptions
readonly packagingOptions?: MavenPackagingOptions;
Packaging options. - defaults
property projenrcJava
readonly projenrcJava?: boolean;
Use projenrc in java.
This will install
projen
as a java dependency and will add asynth
task which will compile & executemain()
fromsrc/main/java/projenrc.java
.true
property projenrcJavaOptions
readonly projenrcJavaOptions?: ProjenrcOptions;
Options related to projenrc in java. - default options
property testDeps
readonly testDeps?: string[];
List of test dependencies for this project.
Dependencies use the format:
<groupId>/<artifactId>@<semver>
Additional dependencies can be added via
project.addTestDependency()
.[]
interface JavaProjectOptions
interface JavaProjectOptions extends JavaProjectCommonOptions {}
Options for
JavaProject
.
property sample
readonly sample?: boolean;
Include sample code and test if the relevant directories don't exist. true
property sampleJavaPackage
readonly sampleJavaPackage?: string;
The java package to use for the code sample. "org.acme"
interface JunitOptions
interface JunitOptions {}
Options for
Junit
.
property pom
readonly pom: Pom;
Java pom.
property sampleJavaPackage
readonly sampleJavaPackage?: string;
Java package for test sample. "org.acme"
property version
readonly version?: string;
Junit version
"5.7.0"
interface MavenCompileOptions
interface MavenCompileOptions {}
Options for
MavenCompile
.
interface MavenPackagingOptions
interface MavenPackagingOptions {}
Options for
MavenPackage
.
property distdir
readonly distdir?: string;
Where to place the package output? "dist/java"
property javadocs
readonly javadocs?: boolean;
Include javadocs jar in package. true
property javadocsExclude
readonly javadocsExclude?: string[];
Exclude source files from docs. []
property sources
readonly sources?: boolean;
Include sources jar in package. true
interface MavenRepository
interface MavenRepository {}
Represents a Maven repository
See Also
https://maven.apache.org/guides/introduction/introduction-to-repositories.html
property id
readonly id: string;
The identifier for the repository
property layout
readonly layout?: string;
The layout of the repository
property name
readonly name?: string;
The name of the repository
property releases
readonly releases?: MavenRepositoryPolicy;
Repository Policy for Releases
property snapshots
readonly snapshots?: MavenRepositoryPolicy;
Repository Policy for Snapshots
property url
readonly url: string;
The url of the repository
interface MavenRepositoryPolicy
interface MavenRepositoryPolicy {}
Represents a Maven Repository Policy
See Also
https://maven.apache.org/settings.html#repositories
property checksumPolicy
readonly checksumPolicy?: ChecksumPolicy;
Checksum Policy When Maven deploys files to the repository, it also deploys corresponding checksum files.
property enabled
readonly enabled?: boolean;
property updatePolicy
readonly updatePolicy?: UpdatePolicy;
Update Policy This element specifies how often updates should attempt to occur. Maven will compare the local POM's timestamp (stored in a repository's maven-metadata file) to the remote. UpdatePolicy.DAILY
interface MavenSampleOptions
interface MavenSampleOptions {}
property package
readonly package: string;
Project root java package.
interface ParentPom
interface ParentPom {}
property artifactId
readonly artifactId?: string;
Parent Pom Artifact ID
property groupId
readonly groupId?: string;
Parent Pom Group ID
property relativePath
readonly relativePath?: string;
Parent Pom Relative path from the current pom
property version
readonly version?: string;
Parent Pom Version
interface PluginExecution
interface PluginExecution {}
Plugin execution definition.
property configuration
readonly configuration?: { [key: string]: any;};
Execution key/value configuration {}
property goals
readonly goals: string[];
Which Maven goals this plugin should be associated with.
property id
readonly id: string;
The ID.
property phase
readonly phase?: string;
The phase in which the plugin should execute.
interface PluginOptions
interface PluginOptions {}
Options for Maven plugins.
property configuration
readonly configuration?: { [key: string]: any;};
Plugin key/value configuration {}
property dependencies
readonly dependencies?: string[];
You could configure the dependencies for the plugin.
Dependencies are in
<groupId>/<artifactId>@<semver>
format.[]
property executions
readonly executions?: PluginExecution[];
Plugin executions []
interface PomOptions
interface PomOptions {}
Options for
Pom
.
property artifactId
readonly artifactId: string;
The artifactId is generally the name that the project is known by. Although the groupId is important, people within the group will rarely mention the groupId in discussion (they are often all be the same ID, such as the MojoHaus project groupId: org.codehaus.mojo). It, along with the groupId, creates a key that separates this project from every other project in the world (at least, it should :) ). Along with the groupId, the artifactId fully defines the artifact's living quarters within the repository. In the case of the above project, my-project lives in $M2_REPO/org/codehaus/mojo/my-project. "my-app"
property description
readonly description?: string;
Description of a project is always good. Although this should not replace formal documentation, a quick comment to any readers of the POM is always helpful.
undefined
property groupId
readonly groupId: string;
This is generally unique amongst an organization or a project. For example, all core Maven artifacts do (well, should) live under the groupId org.apache.maven. Group ID's do not necessarily use the dot notation, for example, the junit project. Note that the dot-notated groupId does not have to correspond to the package structure that the project contains. It is, however, a good practice to follow. When stored within a repository, the group acts much like the Java packaging structure does in an operating system. The dots are replaced by OS specific directory separators (such as '/' in Unix) which becomes a relative directory structure from the base repository. In the example given, the org.codehaus.mojo group lives within the directory $M2_REPO/org/codehaus/mojo. "org.acme"
property packaging
readonly packaging?: string;
Project packaging format.
"jar"
property parentPom
readonly parentPom?: ParentPom;
A Parent Pom can be used to have a child project inherit properties/plugins/ect in order to reduce duplication and keep standards across a large amount of repos
undefined
property url
readonly url?: string;
The URL, like the name, is not required. This is a nice gesture for projects users, however, so that they know where the project lives.
undefined
property version
readonly version: string;
This is the last piece of the naming puzzle. groupId:artifactId denotes a single project but they cannot delineate which incarnation of that project we are talking about. Do we want the junit:junit of 2018 (version 4.12), or of 2007 (version 3.8.2)? In short: code changes, those changes should be versioned, and this element keeps those versions in line. It is also used within an artifact's repository to separate versions from each other. my-project version 1.0 files live in the directory structure $M2_REPO/org/codehaus/mojo/my-project/1.0. "0.1.0"
interface ProjenrcOptions
interface ProjenrcOptions {}
Options for
Projenrc
.
property className
readonly className?: string;
The name of the Java class which contains the
main()
method for projen. "projenrc"
property projenVersion
readonly projenVersion?: string;
The projen version to use - current version
property testScope
readonly testScope?: boolean;
Defines projenrc under the test scope instead of the main scope, which is reserved to the app. This means that projenrc will be under
src/test/java/projenrc.java
and projen will be defined as a test dependency. This enforces that application code does not take a dependency on projen code.If this is disabled, projenrc should be under
src/main/java/projenrc.java
.true
enum ChecksumPolicy
enum ChecksumPolicy { IGNORE = 'ignore', FAIL = 'fail', WARN = 'warn',}
namespace javascript
module 'lib/javascript/index.d.ts' {}
function defaultNpmToken
defaultNpmToken: ( npmToken: string | undefined, registry: string | undefined) => string | undefined;
class Bundler
class Bundler extends Component {}
Adds support for bundling JavaScript applications and dependencies into a single file. In the future, this will also supports bundling websites.
constructor
constructor(project: Project, options?: BundlerOptions);
Creates a
Bundler
.
property bundledir
readonly bundledir: string;
Root bundle directory.
property bundleTask
readonly bundleTask: Task;
Gets or creates the singleton "bundle" task of the project.
If the project doesn't have a "bundle" task, it will be created and spawned during the pre-compile phase.
property esbuildVersion
readonly esbuildVersion: string;
The semantic version requirement for
esbuild
(if defined).
method addBundle
addBundle: (entrypoint: string, options: AddBundleOptions) => Bundle;
Adds a task to the project which bundles a specific entrypoint and all of its dependencies into a single javascript output file.
Parameter entrypoint
The relative path of the artifact within the project
Parameter options
Bundling options
method of
static of: (project: Project) => Bundler | undefined;
Returns the
Bundler
instance associated with a project orundefined
if there is no Bundler.Parameter project
The project
Returns
A bundler
class Eslint
class Eslint extends Component {}
Represents eslint configuration.
constructor
constructor(project: NodeProject, options: EslintOptions);
property config
readonly config: any;
Direct access to the eslint configuration (escape hatch)
property eslintTask
readonly eslintTask: Task;
eslint task.
property ignorePatterns
readonly ignorePatterns: string[];
File patterns that should not be linted
property lintPatterns
readonly lintPatterns: string[];
Returns an immutable copy of the lintPatterns being used by this eslint configuration.
property overrides
readonly overrides: EslintOverride[];
eslint overrides.
property rules
readonly rules: { [rule: string]: any[] };
eslint rules.
method addExtends
addExtends: (...extendList: string[]) => void;
Adds an
extends
item to the eslint configuration.Parameter extendList
The list of "extends" to add.
method addIgnorePattern
addIgnorePattern: (pattern: string) => void;
Do not lint these files.
method addLintPattern
addLintPattern: (pattern: string) => void;
Add a file, glob pattern or directory with source files to lint (e.g. [ "src" ])
method addOverride
addOverride: (override: EslintOverride) => void;
Add an eslint override.
method addPlugins
addPlugins: (...plugins: string[]) => void;
Adds an eslint plugin
Parameter plugins
The names of plugins to add
method addRules
addRules: (rules: { [rule: string]: any }) => void;
Add an eslint rule.
method allowDevDeps
allowDevDeps: (pattern: string) => void;
Add a glob file pattern which allows importing dev dependencies.
Parameter pattern
glob pattern.
method of
static of: (project: Project) => Eslint | undefined;
Returns the singleton Eslint component of a project or undefined if there is none.
class Jest
class Jest extends Component {}
Installs the following npm scripts:
-
test
, intended for testing locally and in CI. Will update snapshots unlessupdateSnapshot: UpdateSnapshot: NEVER
is set. -test:watch
, intended for automatically rerunning tests when files change. -test:update
, intended for testing locally and updating snapshots to match the latest unit under test. Only available whenupdateSnapshot: UpdateSnapshot: NEVER
.
constructor
constructor(project: NodeProject, options?: JestOptions);
property config
readonly config: any;
Escape hatch.
property file
readonly file?: JsonFile;
Jest config file.
undefined
if settings are written topackage.json
property jestVersion
readonly jestVersion: string;
Jest version, including
@
symbol, like@^29
method addIgnorePattern
addIgnorePattern: (pattern: string) => void;
method addModuleNameMappers
addModuleNameMappers: (moduleNameMapperAdditions: { [key: string]: string | string[];}) => void;
Adds one or more moduleNameMapper entries to Jest's configuration. Will overwrite if the same key is used as a pre-existing one.
Parameter moduleNameMapperAdditions
A map from regular expressions to module names or to arrays of module names that allow to stub out resources, like images or styles with a single module.
method addModulePaths
addModulePaths: (...modulePaths: string[]) => void;
Adds one or more modulePaths to Jest's configuration.
Parameter modulePaths
An array of absolute paths to additional locations to search when resolving modules *
method addReporter
addReporter: (reporter: JestReporter) => void;
method addRoots
addRoots: (...roots: string[]) => void;
Adds one or more roots to Jest's configuration.
Parameter roots
A list of paths to directories that Jest should use to search for files in.
method addSetupFile
addSetupFile: (file: string) => void;
Adds a a setup file to Jest's setupFiles configuration.
Parameter file
File path to setup file
method addSetupFileAfterEnv
addSetupFileAfterEnv: (file: string) => void;
Adds a a setup file to Jest's setupFilesAfterEnv configuration.
Parameter file
File path to setup file
method addSnapshotResolver
addSnapshotResolver: (file: string) => void;
method addTestMatch
addTestMatch: (pattern: string) => void;
Adds a test match pattern.
Parameter pattern
glob pattern to match for tests
method addWatchIgnorePattern
addWatchIgnorePattern: (pattern: string) => void;
Adds a watch ignore pattern.
Parameter pattern
The pattern (regular expression).
method discoverTestMatchPatternsForDirs
discoverTestMatchPatternsForDirs: ( dirs: string[], options?: JestDiscoverTestMatchPatternsForDirsOptions) => void;
Build standard test match patterns for a directory.
Parameter dirs
The directories to add test matches for. Matches any folder if not specified or an empty array.
Parameter options
Options for building test match patterns.
method of
static of: (project: Project) => Jest | undefined;
Returns the singleton Jest component of a project or undefined if there is none.
class JestReporter
class JestReporter {}
constructor
constructor(name: string, options?: { [key: string]: any });
class LicenseChecker
class LicenseChecker extends Component {}
Enforces allowed licenses used by dependencies.
constructor
constructor(scope: Construct, options: LicenseCheckerOptions);
property task
readonly task: Task;
class NodePackage
class NodePackage extends Component {}
Represents the npm
package.json
file.
constructor
constructor(project: Project, options?: NodePackageOptions);
property allowLibraryDependencies
readonly allowLibraryDependencies: boolean;
Allow project to take library dependencies.
property bunVersion
readonly bunVersion?: string;
The version of Bun to use if using Bun as a package manager.
property codeArtifactOptions
readonly codeArtifactOptions?: CodeArtifactOptions;
Options for npm packages using AWS CodeArtifact. This is required if publishing packages to, or installing scoped packages from AWS CodeArtifact
- undefined
property entrypoint
readonly entrypoint: string;
The module's entrypoint (e.g.
lib/index.js
).
property file
readonly file: JsonFile;
The package.json file.
property installAndUpdateLockfileCommand
readonly installAndUpdateLockfileCommand: string;
Renders
yarn install
ornpm install
with lockfile update (not frozen)
property installCiTask
readonly installCiTask: Task;
The task for installing project dependencies (frozen)
property installCommand
readonly installCommand: string;
Returns the command to execute in order to install all dependencies (always frozen).
property installTask
readonly installTask: Task;
The task for installing project dependencies (non-frozen)
property license
readonly license?: string;
The SPDX license of this module.
undefined
if this package is not licensed.
property lockFile
readonly lockFile: string;
The name of the lock file.
property manifest
readonly manifest: any;
Deprecated
use
addField(x, y)
property maxNodeVersion
readonly maxNodeVersion?: string;
Maximum node version supported by this package.
The value indicates the package is incompatible with newer versions.
property minNodeVersion
readonly minNodeVersion?: string;
The minimum node version required by this package to function.
This value indicates the package is incompatible with older versions.
property npmAccess
readonly npmAccess: NpmAccess;
npm package access level.
property npmProvenance
readonly npmProvenance: boolean;
Should provenance statements be generated when package is published.
property npmRegistry
readonly npmRegistry: string;
The npm registry host (e.g.
registry.npmjs.org
).
property npmRegistryUrl
readonly npmRegistryUrl: string;
npm registry (e.g.
https://registry.npmjs.org
). UsenpmRegistryHost
to get just the host name.
property npmTokenSecret
readonly npmTokenSecret?: string;
GitHub secret which contains the NPM token to use when publishing packages.
property packageManager
readonly packageManager: NodePackageManager;
The package manager to use.
property packageName
readonly packageName: string;
The name of the npm package.
property pnpmVersion
readonly pnpmVersion?: string;
The version of PNPM to use if using PNPM as a package manager.
property projenCommand
readonly projenCommand: string;
The command which executes "projen".
Deprecated
use
project.projenCommand
instead.
property scopedPackagesOptions
readonly scopedPackagesOptions?: ScopedPackagesOptions[];
Options for privately hosted scoped packages
undefined
method addBin
addBin: (bins: Record<string, string>) => void;
method addBundledDeps
addBundledDeps: (...deps: string[]) => void;
Defines bundled dependencies.
Bundled dependencies will be added as normal dependencies as well as to the
bundledDependencies
section of yourpackage.json
.Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addDeps
addDeps: (...deps: string[]) => void;
Defines normal dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addDevDeps
addDevDeps: (...deps: string[]) => void;
Defines development/test dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addEngine
addEngine: (engine: string, version: string) => void;
Adds an
engines
requirement to your package.Parameter engine
The engine (e.g.
node
)Parameter version
The semantic version requirement (e.g.
^10
)
method addField
addField: (name: string, value: any) => void;
Directly set fields in
package.json
.Parameter name
field name
Parameter value
field value
method addKeywords
addKeywords: (...keywords: string[]) => void;
Adds keywords to package.json (deduplicated)
Parameter keywords
The keywords to add
method addPackageResolutions
addPackageResolutions: (...resolutions: string[]) => void;
Defines resolutions for dependencies to change the normally resolved version of a dependency to something else.
Parameter resolutions
Names resolutions to be added. Specify a version or range with this syntax:
module@^7
method addPeerDeps
addPeerDeps: (...deps: string[]) => void;
Defines peer dependencies.
When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addVersion
addVersion: (version: string) => void;
Sets the package version.
Parameter version
Package version.
method hasScript
hasScript: (name: string) => boolean;
Indicates if a script by the given name is defined.
Parameter name
The name of the script
Deprecated
Use
project.tasks.tryFind(name)
method of
static of: (project: Project) => NodePackage | undefined;
Returns the
NodePackage
instance associated with a project orundefined
if there is no NodePackage.Parameter project
The project
Returns
A NodePackage, or undefined
method postSynthesize
postSynthesize: () => void;
method removeScript
removeScript: (name: string) => void;
Removes an npm script (always successful).
Parameter name
The name of the script.
method setScript
setScript: (name: string, command: string) => void;
Add a npm package.json script.
Parameter name
The script name
Parameter command
The command to execute
method synthesize
synthesize: () => void;
method tryResolveDependencyVersion
tryResolveDependencyVersion: (dependencyName: string) => string | undefined;
Attempt to resolve the currently installed version for a given dependency.
Parameter dependencyName
Dependency to resolve for.
Remarks
This method will first look through the current project's dependencies. If found and semantically valid (not '*'), that will be used. Otherwise, it will fall back to locating a
package.json
manifest for the dependency through node's internal resolution reading the version from there.
class NodeProject
class NodeProject extends GitHubProject {}
Node.js project.
node
constructor
constructor(options: NodeProjectOptions);
property allowLibraryDependencies
readonly allowLibraryDependencies: boolean;
Deprecated
use
package.allowLibraryDependencies
property artifactsDirectory
readonly artifactsDirectory: string;
The build output directory. An npm tarball will be created under the
js
subdirectory. For example, if this is set todist
(the default), the npm tarball will be placed underdist/js/boom-boom-1.2.3.tg
.
property artifactsJavascriptDirectory
readonly artifactsJavascriptDirectory: string;
The location of the npm tarball after build (
${artifactsDirectory}/js
).
property autoMerge
readonly autoMerge?: AutoMerge;
Component that sets up mergify for merging approved pull requests.
property buildWorkflow
readonly buildWorkflow?: BuildWorkflow;
The PR build GitHub workflow.
undefined
ifbuildWorkflow
is disabled.
property buildWorkflowJobId
readonly buildWorkflowJobId: string;
The job ID of the build workflow.
property bundler
readonly bundler: Bundler;
property entrypoint
readonly entrypoint: string;
Deprecated
use
package.entrypoint
property jest
readonly jest?: Jest;
The Jest configuration (if enabled)
property manifest
readonly manifest: any;
Deprecated
use
package.addField(x, y)
property maxNodeVersion
readonly maxNodeVersion: string;
Maximum node version supported by this package.
The value indicates the package is incompatible with newer versions.
property minNodeVersion
readonly minNodeVersion: string;
The minimum node version required by this package to function.
This value indicates the package is incompatible with older versions.
property nodeVersion
protected readonly nodeVersion?: string;
property npmignore
readonly npmignore?: IgnoreFile;
The .npmignore file.
property npmrc
readonly npmrc: NpmConfig;
The .npmrc file
property package
readonly package: NodePackage;
API for managing the node package.
property packageManager
readonly packageManager: NodePackageManager;
The package manager to use.
Deprecated
use
package.packageManager
property prettier
readonly prettier?: Prettier;
property publisher
readonly publisher?: Publisher;
Package publisher. This will be
undefined
if the project does not have a release workflow.Deprecated
use
release.publisher
.
property release
readonly release?: Release;
Release management.
property runScriptCommand
readonly runScriptCommand: string;
The command to use to run scripts (e.g.
yarn run
ornpm run
depends on the package manager).
property upgradeWorkflow
readonly upgradeWorkflow?: UpgradeDependencies;
The upgrade workflow.
property workflowBootstrapSteps
protected readonly workflowBootstrapSteps: JobStep[];
property workflowPackageCache
protected readonly workflowPackageCache: boolean;
method addBins
addBins: (bins: Record<string, string>) => void;
method addBundledDeps
addBundledDeps: (...deps: string[]) => void;
Defines bundled dependencies.
Bundled dependencies will be added as normal dependencies as well as to the
bundledDependencies
section of yourpackage.json
.Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addCompileCommand
addCompileCommand: (...commands: string[]) => void;
DEPRECATED
Deprecated
use
project.compileTask.exec()
method addDeps
addDeps: (...deps: string[]) => void;
Defines normal dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addDevDeps
addDevDeps: (...deps: string[]) => void;
Defines development/test dependencies.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addFields
addFields: (fields: { [name: string]: any }) => void;
Directly set fields in
package.json
.Parameter fields
The fields to set
method addKeywords
addKeywords: (...keywords: string[]) => void;
Adds keywords to package.json (deduplicated)
Parameter keywords
The keywords to add
method addPackageIgnore
addPackageIgnore: (pattern: string) => void;
Adds patterns to be ignored by npm.
Parameter pattern
The pattern to ignore.
Remarks
If you are having trouble getting an ignore to populate, try using your construct or component's preSynthesize method to properly delay calling this method.
method addPeerDeps
addPeerDeps: (...deps: string[]) => void;
Defines peer dependencies.
When adding peer dependencies, a devDependency will also be added on the pinned version of the declared peer. This will ensure that you are testing your code against the minimum version required from your consumers.
Parameter deps
Names modules to install. By default, the the dependency will be installed in the next
npx projen
run and the version will be recorded in yourpackage.json
file. You can upgrade manually or using `yarn add/upgrade`. If you wish to specify a version range use this syntax:module@^7
.
method addScripts
addScripts: (scripts: { [name: string]: string }) => void;
Replaces the contents of multiple npm package.json scripts.
Parameter scripts
The scripts to set
method addTestCommand
addTestCommand: (...commands: string[]) => void;
DEPRECATED
Deprecated
use
project.testTask.exec()
method hasScript
hasScript: (name: string) => boolean;
Indicates if a script by the name name is defined.
Parameter name
The name of the script
Deprecated
Use
project.tasks.tryFind(name)
method removeScript
removeScript: (name: string) => void;
Removes the npm script (always successful).
Parameter name
The name of the script.
method renderWorkflowSetup
renderWorkflowSetup: (options?: RenderWorkflowSetupOptions) => JobStep[];
Returns the set of workflow steps which should be executed to bootstrap a workflow.
Parameter options
Options.
Returns
Job steps
method runTaskCommand
runTaskCommand: (task: Task) => string;
Returns the shell command to execute in order to run a task. This will typically be
npx projen TASK
.Parameter task
The task for which the command is required
method setScript
setScript: (name: string, command: string) => void;
Replaces the contents of an npm package.json script.
Parameter name
The script name
Parameter command
The command to execute
class NpmConfig
class NpmConfig extends Component {}
File representing the local NPM config in .npmrc
constructor
constructor(project: NodeProject, options?: NpmConfigOptions);
method addConfig
addConfig: (name: string, value: string) => void;
configure a generic property
Parameter name
the name of the property
Parameter value
the value of the property
method addRegistry
addRegistry: (url: string, scope?: string) => void;
configure a scoped registry
Parameter url
the URL of the registry to use
Parameter scope
the scope the registry is used for; leave empty for the default registry
class Prettier
class Prettier extends Component {}
Represents prettier configuration.
constructor
constructor(project: NodeProject, options: PrettierOptions);
property ignoreFile
readonly ignoreFile?: IgnoreFile;
The .prettierIgnore file.
property overrides
readonly overrides: PrettierOverride[];
Returns all Prettier overrides
property settings
readonly settings: PrettierSettings;
Direct access to the prettier settings
method addIgnorePattern
addIgnorePattern: (pattern: string) => void;
Defines Prettier ignore Patterns these patterns will be added to the file .prettierignore
Parameter pattern
filepatterns so exclude from prettier formatting
method addOverride
addOverride: (override: PrettierOverride) => void;
Add a prettier override
Parameter override
See Also
https://prettier.io/docs/en/configuration.html#configuration-overrides
method of
static of: (project: Project) => Prettier | undefined;
method preSynthesize
preSynthesize: () => void;
class Projenrc
class Projenrc extends ProjenrcFile {}
A projenrc file written in JavaScript
This component can be instantiated in any type of project and has no expectations around the project's main language.
constructor
constructor(project: Project, options?: ProjenrcOptions);
property filePath
readonly filePath: string;
method preSynthesize
preSynthesize: () => void;
class Transform
class Transform {}
constructor
constructor(name: string, options?: any);
class TypescriptConfig
class TypescriptConfig extends Component {}
constructor
constructor(project: Project, options: TypescriptConfigOptions);
property compilerOptions
readonly compilerOptions?: TypeScriptCompilerOptions;
property exclude
readonly exclude: string[];
property extends
readonly extends: string[];
Array of base
tsconfig.json
paths. Any absolute paths are resolved relative to this instance, while any relative paths are used as is.
property file
readonly file: JsonFile;
property fileName
readonly fileName: string;
property include
readonly include: string[];
method addExclude
addExclude: (pattern: string) => void;
Add an exclude pattern to the
exclude
array of the TSConfig.Parameter pattern
The pattern to add.
See Also
https://www.typescriptlang.org/tsconfig#exclude
method addExtends
addExtends: (value: TypescriptConfig) => void;
Extend from base
TypescriptConfig
instance.Parameter value
Base
TypescriptConfig
instance.Remarks
TypeScript 5.0+ is required to extend from more than one base
TypescriptConfig
.
method addInclude
addInclude: (pattern: string) => void;
Add an include pattern to the
include
array of the TSConfig.Parameter pattern
The pattern to add.
See Also
https://www.typescriptlang.org/tsconfig#include
method preSynthesize
preSynthesize: () => void;
method removeExclude
removeExclude: (pattern: string) => void;
Remove an exclude pattern from the
exclude
array of the TSConfig.Parameter pattern
The pattern to remove.
See Also
https://www.typescriptlang.org/tsconfig#exclude
method removeInclude
removeInclude: (pattern: string) => void;
Remove an include pattern from the
include
array of the TSConfig.Parameter pattern
The pattern to remove.
See Also
https://www.typescriptlang.org/tsconfig#include
method resolveExtendsPath
resolveExtendsPath: (configPath: string) => string;
Resolve valid TypeScript extends paths relative to this config.
Parameter configPath
Path to resolve against.
Remarks
This will only resolve the relative path from this config to another given an absolute path as input. Any non-absolute path or other string will be returned as is. This is to preserve manually specified relative paths as well as npm import paths.
class TypescriptConfigExtends
class TypescriptConfigExtends {}
Container for
TypescriptConfig
tsconfig.json
base configuration(s). Extending from more than one base config file requires TypeScript 5.0+.
method fromPaths
static fromPaths: (paths: string[]) => TypescriptConfigExtends;
Factory for creation from array of file paths.
Parameter paths
Absolute or relative paths to base
tsconfig.json
files.Remarks
TypeScript 5.0+ is required to specify more than one value in
paths
.
method fromTypescriptConfigs
static fromTypescriptConfigs: ( configs: TypescriptConfig[]) => TypescriptConfigExtends;
Factory for creation from array of other
TypescriptConfig
instances.Parameter configs
Base
TypescriptConfig
instances.Remarks
TypeScript 5.0+ is required to specify more than on value in
configs
.
method toJSON
toJSON: () => string[];
class UpgradeDependencies
class UpgradeDependencies extends Component {}
Upgrade node project dependencies.
constructor
constructor(project: NodeProject, options?: UpgradeDependenciesOptions);
property containerOptions
containerOptions?: workflows.ContainerOptions;
Container definitions for the upgrade workflow.
property postUpgradeTask
readonly postUpgradeTask: Task;
A task run after the upgrade task.
property upgradeTask
readonly upgradeTask: Task;
The upgrade task.
property workflows
readonly workflows: GithubWorkflow[];
The workflows that execute the upgrades. One workflow per branch.
method addPostBuildSteps
addPostBuildSteps: (...steps: JobStep[]) => void;
Add steps to execute a successful build.
Parameter steps
workflow steps
class UpgradeDependenciesSchedule
class UpgradeDependenciesSchedule {}
How often to check for new versions and raise pull requests for version upgrades.
property cron
readonly cron: string[];
property DAILY
static readonly DAILY: UpgradeDependenciesSchedule;
At 00:00.
property MONTHLY
static readonly MONTHLY: UpgradeDependenciesSchedule;
At 00:00 on day-of-month 1.
property NEVER
static readonly NEVER: UpgradeDependenciesSchedule;
Disables automatic upgrades.
property WEEKDAY
static readonly WEEKDAY: UpgradeDependenciesSchedule;
At 00:00 on every day-of-week from Monday through Friday.
property WEEKLY
static readonly WEEKLY: UpgradeDependenciesSchedule;
At 00:00 on Monday.
method expressions
static expressions: (cron: string[]) => UpgradeDependenciesSchedule;
Create a schedule from a raw cron expression.
class WatchPlugin
class WatchPlugin {}
constructor
constructor(name: string, options?: any);
class Yarnrc
class Yarnrc extends Component {}
constructor
constructor(project: Project, version: string, options?: YarnrcOptions);
interface AddBundleOptions
interface AddBundleOptions extends BundlingOptions {}
Options for
addBundle()
.
property banner
readonly banner?: string;
Use this to insert an arbitrary string at the beginning of generated JavaScript files.
This is similar to footer which inserts at the end instead of the beginning.
This is commonly used to insert comments:
- no comments are passed
property charset
readonly charset?: Charset;
The charset to use for esbuild's output.
By default esbuild's output is ASCII-only. Any non-ASCII characters are escaped using backslash escape sequences. Using escape sequences makes the generated output slightly bigger, and also makes it harder to read. If you would like for esbuild to print the original characters without using escape sequences, use
Charset.UTF8
.See Also
https://esbuild.github.io/api/#charset Charset.ASCII
property define
readonly define?: { [key: string]: string;};
Replace global identifiers with constant expressions.
For example,
{ 'process.env.DEBUG': 'true' }
.Another example,
{ 'process.env.API_KEY': JSON.stringify('xxx-xxxx-xxx') }
.- no replacements are made
property esbuildArgs
readonly esbuildArgs?: { [key: string]: string | boolean;};
Build arguments to pass into esbuild.
For example, to add the [--log-limit](https://esbuild.github.io/api/#log-limit) flag:
project.bundler.addBundle("./src/hello.ts", {platform: "node",target: "node18",sourcemap: true,format: "esm",esbuildArgs: {"--log-limit": "0",},});- no additional esbuild arguments are passed
property executable
readonly executable?: boolean;
Mark the output file as executable. false
property footer
readonly footer?: string;
Use this to insert an arbitrary string at the end of generated JavaScript files.
This is similar to banner which inserts at the beginning instead of the end.
This is commonly used to insert comments
- no comments are passed
property format
readonly format?: string;
Output format for the generated JavaScript files. There are currently three possible values that can be configured:
"iife"
,"cjs"
, and"esm"
.If not set (
undefined
), esbuild picks an output format for you based onplatform
: -"cjs"
ifplatform
is"node"
-"iife"
ifplatform
is"browser"
-"esm"
ifplatform
is"neutral"
Note: If making a bundle to run under node with ESM, set
format
to"esm"
instead of settingplatform
to"neutral"
.undefined
See Also
https://esbuild.github.io/api/#format
property inject
readonly inject?: string[];
This option allows you to automatically replace a global variable with an import from another file.
See Also
https://esbuild.github.io/api/#inject - no code is injected
property keepNames
readonly keepNames?: boolean;
Whether to preserve the original
name
values even in minified code.In JavaScript the
name
property on functions and classes defaults to a nearby identifier in the source code.However, minification renames symbols to reduce code size and bundling sometimes need to rename symbols to avoid collisions. That changes value of the
name
property for many of these cases. This is usually fine because thename
property is normally only used for debugging. However, some frameworks rely on thename
property for registration and binding purposes. If this is the case, you can enable this option to preserve the originalname
values even in minified code.false
property loaders
readonly loaders?: { [key: string]: string;};
Map of file extensions (without dot) and loaders to use for this file type. Loaders are appended to the esbuild command by
--loader:.extension=loader
property logLevel
readonly logLevel?: BundleLogLevel;
Log level for esbuild. This is also propagated to the package manager and applies to its specific install command.
LogLevel.WARNING
property mainFields
readonly mainFields?: string[];
How to determine the entry point for modules. Try ['module', 'main'] to default to ES module versions.
[]
property metafile
readonly metafile?: boolean;
This option tells esbuild to write out a JSON file relative to output directory with metadata about the build.
The metadata in this JSON file follows this schema (specified using TypeScript syntax):
{outputs: {[path: string]: {bytes: numberinputs: {[path: string]: { bytesInOutput: number }}imports: { path: string }[]exports: string[]}}}This data can then be analyzed by other tools. For example, bundle buddy can consume esbuild's metadata format and generates a treemap visualization of the modules in your bundle and how much space each one takes up.
See Also
https://esbuild.github.io/api/#metafile false
property minify
readonly minify?: boolean;
Whether to minify files when bundling.
false
property outfile
readonly outfile?: string;
Bundler output path relative to the asset's output directory. "index.js"
property platform
readonly platform: string;
esbuild platform.
Example 1
"node"
property sourceMapMode
readonly sourceMapMode?: SourceMapMode;
Source map mode to be used when bundling.
See Also
https://esbuild.github.io/api/#sourcemap
SourceMapMode.DEFAULT
property sourcesContent
readonly sourcesContent?: boolean;
Whether to include original source code in source maps when bundling.
See Also
https://esbuild.github.io/api/#sources-content
true
property target
readonly target: string;
esbuild target.
Example 1
"node12"
property tsconfigPath
readonly tsconfigPath?: string;
The path of the tsconfig.json file to use for bundling "tsconfig.json"
interface BuildWorkflowOptions
interface BuildWorkflowOptions extends BuildWorkflowCommonOptions {}
Build workflow options for NodeProject
property mutableBuild
readonly mutableBuild?: boolean;
Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
true
interface Bundle
interface Bundle {}
property bundleTask
readonly bundleTask: Task;
The task that produces this bundle.
property outdir
readonly outdir: string;
Base directory containing the output file (relative to project root).
property outfile
readonly outfile: string;
Location of the output file (relative to project root).
property watchTask
readonly watchTask?: Task;
The "watch" task for this bundle.
interface BundlerOptions
interface BundlerOptions {}
Options for
Bundler
.
property addToPreCompile
readonly addToPreCompile?: boolean;
Install the
bundle
command as a pre-compile phase.true
Deprecated
Use
runBundleTask
instead.
property assetsDir
readonly assetsDir?: string;
Output directory for all bundles. "assets"
property esbuildVersion
readonly esbuildVersion?: string;
The semantic version requirement for
esbuild
.- no specific version (implies latest)
property loaders
readonly loaders?: { [key: string]: string;};
Map of file extensions (without dot) and loaders to use for this file type. Loaders are appended to the esbuild command by
--loader:.extension=loader
property runBundleTask
readonly runBundleTask?: RunBundleTask;
Choose which phase (if any) to add the
bundle
command to.Note: If using
addBundle()
with thebundleCompiledResults
, this option must be set toRunBundleTask.POST_COMPILE
orRunBundleTask.MANUAL
.See Also
AddBundleOptions.bundleCompiledResults
RunBundleTask.PRE_COMPILE
interface BundlingOptions
interface BundlingOptions {}
Options for bundling.
property externals
readonly externals?: string[];
You can mark a file or a package as external to exclude it from your build. Instead of being bundled, the import will be preserved (using require for the iife and cjs formats and using import for the esm format) and will be evaluated at run time instead.
This has several uses. First of all, it can be used to trim unnecessary code from your bundle for a code path that you know will never be executed. For example, a package may contain code that only runs in node but you will only be using that package in the browser. It can also be used to import code in node at run time from a package that cannot be bundled. For example, the fsevents package contains a native extension, which esbuild doesn't support.
[]
property sourcemap
readonly sourcemap?: boolean;
Include a source map in the bundle.
false
property watchTask
readonly watchTask?: boolean;
In addition to the
bundle:xyz
task, createsbundle:xyz:watch
task which will invoke the same esbuild command with the--watch
flag. This can be used to continusouly watch for changes.true
interface CodeArtifactOptions
interface CodeArtifactOptions {}
Options for publishing npm packages to AWS CodeArtifact.
property accessKeyIdSecret
readonly accessKeyIdSecret?: string;
GitHub secret which contains the AWS access key ID to use when publishing packages to AWS CodeArtifact. This property must be specified only when publishing to AWS CodeArtifact (
npmRegistryUrl
contains AWS CodeArtifact URL).- When the
authProvider
value is set toCodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR
, the default is "AWS_ACCESS_KEY_ID". ForCodeArtifactAuthProvider.GITHUB_OIDC
, this value must be left undefined.
property authProvider
readonly authProvider?: CodeArtifactAuthProvider;
Provider to use for authorizing requests to AWS CodeArtifact.
CodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR
property roleToAssume
readonly roleToAssume?: string;
ARN of AWS role to be assumed prior to get authorization token from AWS CodeArtifact This property must be specified only when publishing to AWS CodeArtifact (
registry
contains AWS CodeArtifact URL). When using theCodeArtifactAuthProvider.GITHUB_OIDC
auth provider, this value must be defined.undefined
property secretAccessKeySecret
readonly secretAccessKeySecret?: string;
GitHub secret which contains the AWS secret access key to use when publishing packages to AWS CodeArtifact. This property must be specified only when publishing to AWS CodeArtifact (
npmRegistryUrl
contains AWS CodeArtifact URL).- When the
authProvider
value is set toCodeArtifactAuthProvider.ACCESS_AND_SECRET_KEY_PAIR
, the default is "AWS_SECRET_ACCESS_KEY". ForCodeArtifactAuthProvider.GITHUB_OIDC
, this value must be left undefined.
interface CoverageThreshold
interface CoverageThreshold {}
property branches
readonly branches?: number;
property functions
readonly functions?: number;
property lines
readonly lines?: number;
property statements
readonly statements?: number;
interface EslintCommandOptions
interface EslintCommandOptions {}
interface EslintOptions
interface EslintOptions {}
property aliasExtensions
readonly aliasExtensions?: string[];
Enable import alias for module paths undefined
property aliasMap
readonly aliasMap?: { [key: string]: string;};
Enable import alias for module paths undefined
property commandOptions
readonly commandOptions?: EslintCommandOptions;
Options for eslint command executed by eslint task
property devdirs
readonly devdirs?: string[];
Files or glob patterns or directories with source files that include tests and build tools
These sources are linted but may also import packages from
devDependencies
. []
property dirs
readonly dirs: string[];
Files or glob patterns or directories with source files to lint (e.g. [ "src" ])
property fileExtensions
readonly fileExtensions?: string[];
File types that should be linted (e.g. [ ".js", ".ts" ]) [".ts"]
property ignorePatterns
readonly ignorePatterns?: string[];
List of file patterns that should not be linted, using the same syntax as .gitignore patterns.
[ '*.js', '*.d.ts', 'node_modules/', '*.generated.ts', 'coverage' ]
property lintProjenRc
readonly lintProjenRc?: boolean;
Should we lint .projenrc.js
true
Deprecated
set to
false
to remove any automatic rules and add manually
property lintProjenRcFile
readonly lintProjenRcFile?: string;
Projenrc file to lint. Use empty string to disable. "projenrc.js"
Deprecated
provide as
devdirs
property prettier
readonly prettier?: boolean;
Enable prettier for code formatting false
property sortExtends
readonly sortExtends?: ICompareString;
The extends array in eslint is order dependent. This option allows to sort the extends array in any way seen fit.
- Use known ESLint best practices to place "prettier" plugins at the end of the array
property tsAlwaysTryTypes
readonly tsAlwaysTryTypes?: boolean;
Always try to resolve types under
<root>@types
directory even it doesn't contain any source code. This preventsimport/no-unresolved
eslint errors when importing a@types/*
module that would otherwise remain unresolved. true
property tsconfigPath
readonly tsconfigPath?: string;
Path to
tsconfig.json
which should be used by eslint. "./tsconfig.json"
property yaml
readonly yaml?: boolean;
Write eslint configuration as YAML instead of JSON false
interface EslintOverride
interface EslintOverride {}
eslint rules override
property excludedFiles
readonly excludedFiles?: string[];
Pattern(s) to exclude from this override. If a file matches any of the excluded patterns, the configuration won’t apply.
property extends
readonly extends?: string[];
Config(s) to extend in this override
property files
readonly files: string[];
Files or file patterns on which to apply the override
property parser
readonly parser?: string;
The overridden parser
property plugins
readonly plugins?: string[];
plugins
override
property rules
readonly rules?: { [rule: string]: any;};
The overridden rules
interface HasteConfig
interface HasteConfig {}
property computeSha1
readonly computeSha1?: boolean;
property defaultPlatform
readonly defaultPlatform?: string | undefined;
property hasteImplModulePath
readonly hasteImplModulePath?: string;
property platforms
readonly platforms?: Array<string>;
property throwOnModuleCollision
readonly throwOnModuleCollision?: boolean;
interface JestConfigOptions
interface JestConfigOptions {}
property additionalOptions
readonly additionalOptions?: { [name: string]: any;};
Escape hatch to allow any value
property automock
readonly automock?: boolean;
This option tells Jest that all imported modules in your tests should be mocked automatically. All modules used in your tests will have a replacement implementation, keeping the API surface - false
property bail
readonly bail?: boolean | number;
By default, Jest runs all tests and produces all errors into the console upon completion. The bail config option can be used here to have Jest stop running tests after n failures. Setting bail to true is the same as setting bail to 1. - 0
property cacheDirectory
readonly cacheDirectory?: string;
The directory where Jest should store its cached dependency information - "/tmp/"
property clearMocks
readonly clearMocks?: boolean;
Automatically clear mock calls and instances before every test. Equivalent to calling jest.clearAllMocks() before each test. This does not remove any mock implementation that may have been provided true
property collectCoverage
readonly collectCoverage?: boolean;
Indicates whether the coverage information should be collected while executing the test. Because this retrofits all executed files with coverage collection statements, it may significantly slow down your tests true
property collectCoverageFrom
readonly collectCoverageFrom?: string[];
An array of glob patterns indicating a set of files for which coverage information should be collected. - undefined
property coverageDirectory
readonly coverageDirectory?: string;
The directory where Jest should output its coverage files. "coverage"
property coveragePathIgnorePatterns
readonly coveragePathIgnorePatterns?: string[];
An array of regexp pattern strings that are matched against all file paths before executing the test. If the file path matches any of the patterns, coverage information will be skipped "/node_modules/"
property coverageProvider
readonly coverageProvider?: 'babel' | 'v8';
Indicates which provider should be used to instrument code for coverage. Allowed values are v8 (default) or babel - "v8"
property coverageReporters
readonly coverageReporters?: string[];
A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used - ["json", "lcov", "text", "clover", "cobertura"]
property coverageThreshold
readonly coverageThreshold?: CoverageThreshold;
Specify the global coverage thresholds. This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as global, as a glob, and as a directory or file path. If thresholds aren't met, jest will fail. - undefined
property dependencyExtractor
readonly dependencyExtractor?: string;
This option allows the use of a custom dependency extractor. It must be a node module that exports an object with an extract function - undefined
property displayName
readonly displayName?: string | any;
Allows for a label to be printed alongside a test while it is running. - undefined
property errorOnDeprecated
readonly errorOnDeprecated?: boolean;
Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process. - false
property extraGlobals
readonly extraGlobals?: string[];
Test files run inside a vm, which slows calls to global context properties (e.g. Math). With this option you can specify extra properties to be defined inside the vm for faster lookups. - undefined
property forceCoverageMatch
readonly forceCoverageMatch?: string[];
Test files are normally ignored from collecting code coverage. With this option, you can overwrite this behavior and include otherwise ignored files in code coverage. - ['']
property globals
readonly globals?: any;
A set of global variables that need to be available in all test environments. - {}
property globalSetup
readonly globalSetup?: string;
This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites. This function gets Jest's globalConfig object as a parameter. - undefined
property globalTeardown
readonly globalTeardown?: string;
This option allows the use of a custom global teardown module which exports an async function that is triggered once after all test suites. This function gets Jest's globalConfig object as a parameter. - undefined
property haste
readonly haste?: HasteConfig;
This will be used to configure the behavior of jest-haste-map, Jest's internal file crawler/cache system. - {}
property injectGlobals
readonly injectGlobals?: boolean;
Insert Jest's globals (expect, test, describe, beforeEach etc.) into the global environment. If you set this to false, you should import from @jest/globals - true
property maxConcurrency
readonly maxConcurrency?: number;
A number limiting the number of tests that are allowed to run at the same time when using test.concurrent. Any test above this limit will be queued and executed once a slot is released. - 5
property maxWorkers
readonly maxWorkers?: number | string;
Specifies the maximum number of workers the worker-pool will spawn for running tests. In single run mode, this defaults to the number of the cores available on your machine minus one for the main thread In watch mode, this defaults to half of the available cores on your machine. For environments with variable CPUs available, you can use percentage based configuration: "maxWorkers": "50%" - the number of the cores available on your machine minus one for the main thread
property moduleDirectories
readonly moduleDirectories?: string[];
An array of directory names to be searched recursively up from the requiring module's location. Setting this option will override the default, if you wish to still search node_modules for packages include it along with any other options: ["node_modules", "bower_components"] - ["node_modules"]
property moduleFileExtensions
readonly moduleFileExtensions?: string[];
An array of file extensions your modules use. If you require modules without specifying a file extension, these are the extensions Jest will look for, in left-to-right order. - ["js", "json", "jsx", "ts", "tsx", "node"]
property moduleNameMapper
readonly moduleNameMapper?: { [key: string]: string | string[];};
A map from regular expressions to module names or to arrays of module names that allow to stub out resources, like images or styles with a single module. - null
property modulePathIgnorePatterns
readonly modulePathIgnorePatterns?: string[];
An array of regexp pattern strings that are matched against all module paths before those paths are to be considered 'visible' to the module loader. If a given module's path matches any of the patterns, it will not be require()-able in the test environment. - []
property modulePaths
readonly modulePaths?: string[];
An alternative API to setting the NODE_PATH env variable, modulePaths is an array of absolute paths to additional locations to search when resolving modules. Use the string token to include the path to your project's root directory. Example: ["/app/"]. - []
property notify
readonly notify?: boolean;
Activates notifications for test results. - false
property notifyMode
readonly notifyMode?: | 'always' | 'failure' | 'success' | 'change' | 'success-change' | 'failure-change';
Specifies notification mode. Requires notify: true - failure-change
property preset
readonly preset?: string;
A preset that is used as a base for Jest's configuration. A preset should point to an npm module that has a jest-preset.json or jest-preset.js file at the root. - undefined
property prettierPath
readonly prettierPath?: string;
Sets the path to the prettier node module used to update inline snapshots. - "prettier"
property projects
readonly projects?: Array< | string | { [key: string]: any; }>;
When the projects configuration is provided with an array of paths or glob patterns, Jest will run tests in all of the specified projects at the same time. This is great for monorepos or when working on multiple projects at the same time. - undefined
property reporters
readonly reporters?: JestReporter[];
Use this configuration option to add custom reporters to Jest. A custom reporter is a class that implements onRunStart, onTestStart, onTestResult, onRunComplete methods that will be called when any of those events occurs. - undefined
property resetMocks
readonly resetMocks?: boolean;
Automatically reset mock state before every test. Equivalent to calling jest.resetAllMocks() before each test. This will lead to any mocks having their fake implementations removed but does not restore their initial implementation. - false
property resetModules
readonly resetModules?: boolean;
By default, each test file gets its own independent module registry. Enabling resetModules goes a step further and resets the module registry before running each individual test. - false
property resolver
readonly resolver?: string;
This option allows the use of a custom resolver. https://jestjs.io/docs/en/configuration#resolver-string - undefined
property restoreMocks
readonly restoreMocks?: boolean;
Automatically restore mock state before every test. Equivalent to calling jest.restoreAllMocks() before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation. - false
property rootDir
readonly rootDir?: string;
The root directory that Jest should scan for tests and modules within. If you put your Jest config inside your package.json and want the root directory to be the root of your repo, the value for this config param will default to the directory of the package.json. - directory of the package.json
property roots
readonly roots?: string[];
A list of paths to directories that Jest should use to search for files in. - [""]
property runner
readonly runner?: string;
This option allows you to use a custom runner instead of Jest's default test runner. - "jest-runner"
property setupFiles
readonly setupFiles?: string[];
A list of paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. Since every test runs in its own environment, these scripts will be executed in the testing environment immediately before executing the test code itself. - []
property setupFilesAfterEnv
readonly setupFilesAfterEnv?: string[];
A list of paths to modules that run some code to configure or set up the testing framework before each test file in the suite is executed. Since setupFiles executes before the test framework is installed in the environment, this script file presents you the opportunity of running some code immediately after the test framework has been installed in the environment. - []
property slowTestThreshold
readonly slowTestThreshold?: number;
The number of seconds after which a test is considered as slow and reported as such in the results. - 5
property snapshotResolver
readonly snapshotResolver?: string;
The path to a module that can resolve test<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk. - undefined
property snapshotSerializers
readonly snapshotSerializers?: string[];
A list of paths to snapshot serializer modules Jest should use for snapshot testing. = []
property testEnvironment
readonly testEnvironment?: string;
The test environment that will be used for testing. The default environment in Jest is a browser-like environment through jsdom. If you are building a node service, you can use the node option to use a node-like environment instead. - "jsdom"
property testEnvironmentOptions
readonly testEnvironmentOptions?: any;
Test environment options that will be passed to the testEnvironment. The relevant options depend on the environment. - {}
property testFailureExitCode
readonly testFailureExitCode?: number;
The exit code Jest returns on test failure. - 1
property testMatch
readonly testMatch?: string[];
The glob patterns Jest uses to detect test files. By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). It will also find files called test.js or spec.js. ['**/__tests__/**/*.[jt]s?(x)', '**/*(*.)@(spec|test).[tj]s?(x)']
property testPathIgnorePatterns
readonly testPathIgnorePatterns?: string[];
An array of regexp pattern strings that are matched against all test paths before executing the test. If the test path matches any of the patterns, it will be skipped. - ["/node_modules/"]
property testRegex
readonly testRegex?: string | string[];
The pattern or patterns Jest uses to detect test files. By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). It will also find files called test.js or spec.js. - (/__tests__/.*|(\.|/)(test|spec))\.[jt]sx?$
property testResultsProcessor
readonly testResultsProcessor?: string;
This option allows the use of a custom results processor. - undefined
property testRunner
readonly testRunner?: string;
This option allows the use of a custom test runner. The default is jasmine2. A custom test runner can be provided by specifying a path to a test runner implementation. - "jasmine2"
property testSequencer
readonly testSequencer?: string;
This option allows you to use a custom sequencer instead of Jest's default. Sort may optionally return a Promise. - "@jest/test-sequencer"
property testTimeout
readonly testTimeout?: number;
Default timeout of a test in milliseconds. - 5000
property testURL
readonly testURL?: string;
This option sets the URL for the jsdom environment. It is reflected in properties such as location.href. - "http://localhost"
property timers
readonly timers?: string;
Setting this value to legacy or fake allows the use of fake timers for functions such as setTimeout. Fake timers are useful when a piece of code sets a long timeout that we don't want to wait for in a test. - "real"
property transform
readonly transform?: { [key: string]: Transform;};
A map from regular expressions to paths to transformers. A transformer is a module that provides a synchronous function for transforming source files. - {"\.[jt]sx?$": "babel-jest"}
property transformIgnorePatterns
readonly transformIgnorePatterns?: string[];
An array of regexp pattern strings that are matched against all source file paths before transformation. If the test path matches any of the patterns, it will not be transformed. - ["/node_modules/", "\.pnp\.[^\/]+$"]
property unmockedModulePathPatterns
readonly unmockedModulePathPatterns?: string[];
An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them. If a module's path matches any of the patterns in this list, it will not be automatically mocked by the module loader. - []
property verbose
readonly verbose?: boolean;
Indicates whether each individual test should be reported during the run. All errors will also still be shown on the bottom after execution. Note that if there is only one test file being run it will default to true. - false
property watchman
readonly watchman?: boolean;
Whether to use watchman for file crawling. - true
property watchPathIgnorePatterns
readonly watchPathIgnorePatterns?: string[];
An array of RegExp patterns that are matched against all source file paths before re-running tests in watch mode. If the file path matches any of the patterns, when it is updated, it will not trigger a re-run of tests. - []
property watchPlugins
readonly watchPlugins?: WatchPlugin[];
-
index signature
readonly [name: string]: any;
Escape hatch to allow any value (JS/TS only)
Deprecated
use
additionalOptions
instead.ignore
interface JestDiscoverTestMatchPatternsForDirsOptions
interface JestDiscoverTestMatchPatternsForDirsOptions {}
Options for discoverTestMatchPatternsForDirs.
property fileExtensionPattern
readonly fileExtensionPattern?: string;
The file extension pattern to use. Defaults to "[jt]s?(x)".
interface JestOptions
interface JestOptions {}
property configFilePath
readonly configFilePath?: string;
Path to JSON config file for Jest
- No separate config file, jest settings are stored in package.json
property coverage
readonly coverage?: boolean;
Collect coverage. Deprecated true
Deprecated
use jestConfig.collectCoverage
property coverageText
readonly coverageText?: boolean;
Include the
text
coverage reporter, which means that coverage summary is printed at the end of the jest execution.true
property extraCliOptions
readonly extraCliOptions?: string[];
Additional options to pass to the Jest CLI invocation - no extra options
property ignorePatterns
readonly ignorePatterns?: string[];
Defines
testPathIgnorePatterns
andcoveragePathIgnorePatterns
["/node_modules/"]Deprecated
use jestConfig.coveragePathIgnorePatterns or jestConfig.testPathIgnorePatterns respectively
property jestConfig
readonly jestConfig?: JestConfigOptions;
Jest configuration. - default jest configuration
property jestVersion
readonly jestVersion?: string;
The version of jest to use.
Note that same version is used as version of
@types/jest
andts-jest
(if Typescript in use), so given version should work also for those.- installs the latest jest version
property junitReporting
readonly junitReporting?: boolean;
Result processing with jest-junit.
Output directory is
test-reports/
.true
property passWithNoTests
readonly passWithNoTests?: boolean;
Pass with no tests - true
property preserveDefaultReporters
readonly preserveDefaultReporters?: boolean;
Preserve the default Jest reporter when additional reporters are added.
true
property updateSnapshot
readonly updateSnapshot?: UpdateSnapshot;
Whether to update snapshots in task "test" (which is executed in task "build" and build workflows), or create a separate task "test:update" for updating snapshots.
- ALWAYS
interface LicenseCheckerOptions
interface LicenseCheckerOptions {}
Options to configure the license checker
property allow
readonly allow?: string[];
List of SPDX license identifiers that are allowed to be used.
For the license check to pass, all detected licenses MUST be in this list. Only one of
allowedLicenses
andprohibitedLicenses
can be provided and must not be empty. - no licenses are allowed
property deny
readonly deny?: string[];
List of SPDX license identifiers that are prohibited to be used.
For the license check to pass, no detected licenses can be in this list. Only one of
allowedLicenses
andprohibitedLicenses
can be provided and must not be empty. - no licenses are prohibited
property development
readonly development?: boolean;
Check development dependencies. false
property production
readonly production?: boolean;
Check production dependencies. true
property taskName
readonly taskName?: string;
The name of the task that is added to check licenses
"check-licenses"
interface NodePackageOptions
interface NodePackageOptions {}
property allowLibraryDependencies
readonly allowLibraryDependencies?: boolean;
Allow the project to include
peerDependencies
andbundledDependencies
. This is normally only allowed for libraries. For apps, there's no meaning for specifying these.true
property authorEmail
readonly authorEmail?: string;
Author's e-mail
property authorName
readonly authorName?: string;
Author's name
property authorOrganization
readonly authorOrganization?: boolean;
Is the author an organization
property authorUrl
readonly authorUrl?: string;
Author's URL / Website
property autoDetectBin
readonly autoDetectBin?: boolean;
Automatically add all executables under the
bin
directory to yourpackage.json
file under thebin
section.true
property bin
readonly bin?: Record<string, string>;
Binary programs vended with your module.
You can use this option to add/customize how binaries are represented in your
package.json
, but unlessautoDetectBin
isfalse
, every executable file underbin
will automatically be added to this section.
property bugsEmail
readonly bugsEmail?: string;
The email address to which issues should be reported.
property bugsUrl
readonly bugsUrl?: string;
The url to your project's issue tracker.
property bundledDeps
readonly bundledDeps?: string[];
List of dependencies to bundle into this module. These modules will be added both to the
dependencies
section andbundledDependencies
section of yourpackage.json
.The recommendation is to only specify the module name here (e.g.
express
). This will behave similar toyarn add
ornpm install
in the sense that it will add the module as a dependency to yourpackage.json
file with the latest version (^
). You can specify semver requirements in the same syntax passed tonpm i
oryarn add
(e.g.express@^2
) and this will be what youpackage.json
will eventually include.
property bunVersion
readonly bunVersion?: string;
The version of Bun to use if using Bun as a package manager.
"latest"
property codeArtifactOptions
readonly codeArtifactOptions?: CodeArtifactOptions;
Options for npm packages using AWS CodeArtifact. This is required if publishing packages to, or installing scoped packages from AWS CodeArtifact
- undefined
property deps
readonly deps?: string[];
Runtime dependencies of this module.
The recommendation is to only specify the module name here (e.g.
express
). This will behave similar toyarn add
ornpm install
in the sense that it will add the module as a dependency to yourpackage.json
file with the latest version (^
). You can specify semver requirements in the same syntax passed tonpm i
oryarn add
(e.g.express@^2
) and this will be what youpackage.json
will eventually include.Example 1
[ 'express', 'lodash', 'foo@^2' ] []
property description
readonly description?: string;
The description is just a string that helps people understand the purpose of the package. It can be used when searching for packages in a package manager as well. See https://classic.yarnpkg.com/en/docs/package-json/#toc-description
property devDeps
readonly devDeps?: string[];
Build dependencies for this module. These dependencies will only be available in your build environment but will not be fetched when this module is consumed.
The recommendation is to only specify the module name here (e.g.
express
). This will behave similar toyarn add
ornpm install
in the sense that it will add the module as a dependency to yourpackage.json
file with the latest version (^
). You can specify semver requirements in the same syntax passed tonpm i
oryarn add
(e.g.express@^2
) and this will be what youpackage.json
will eventually include.Example 1
[ 'typescript', '@types/express' ] []
property entrypoint
readonly entrypoint?: string;
Module entrypoint (
main
inpackage.json
)Set to an empty string to not include
main
in your package.json"lib/index.js"
property homepage
readonly homepage?: string;
Package's Homepage / Website
property keywords
readonly keywords?: string[];
Keywords to include in
package.json
.
property license
readonly license?: string;
License's SPDX identifier. See https://github.com/projen/projen/tree/main/license-text for a list of supported licenses. Use the
licensed
option if you want to no license to be specified."Apache-2.0"
property licensed
readonly licensed?: boolean;
Indicates if a license should be added.
true
property maxNodeVersion
readonly maxNodeVersion?: string;
The maximum node version supported by this package. Most projects should not use this option.
The value indicates that the package is incompatible with any newer versions of node. This requirement is enforced via the engines field.
You will normally not need to set this option. Consider this option only if your package is known to not function with newer versions of node.
- no maximum version is enforced
property minNodeVersion
readonly minNodeVersion?: string;
The minimum node version required by this package to function. Most projects should not use this option.
The value indicates that the package is incompatible with any older versions of node. This requirement is enforced via the engines field.
You will normally not need to set this option, even if your package is incompatible with EOL versions of node. Consider this option only if your package depends on a specific feature, that is not available in other LTS versions. Setting this option has very high impact on the consumers of your package, as package managers will actively prevent usage with node versions you have marked as incompatible.
To change the node version of your CI/CD workflows, use
workflowNodeVersion
.- no minimum version is enforced
property npmAccess
readonly npmAccess?: NpmAccess;
Access level of the npm package.
- for scoped packages (e.g.
foo@bar
), the default isNpmAccess.RESTRICTED
, for non-scoped packages, the default isNpmAccess.PUBLIC
.
property npmProvenance
readonly npmProvenance?: boolean;
Should provenance statements be generated when the package is published.
A supported package manager is required to publish a package with npm provenance statements and you will need to use a supported CI/CD provider.
Note that the projen
Release
andPublisher
components are usingpublib
to publish packages, which is using npm internally and supports provenance statements independently of the package manager used.See Also
https://docs.npmjs.com/generating-provenance-statements - true for public packages, false otherwise
property npmRegistry
readonly npmRegistry?: string;
The host name of the npm registry to publish to. Cannot be set together with
npmRegistryUrl
.Deprecated
use
npmRegistryUrl
instead
property npmRegistryUrl
readonly npmRegistryUrl?: string;
The base URL of the npm package registry.
Must be a URL (e.g. start with "https://" or "http://")
"https://registry.npmjs.org"
property npmTokenSecret
readonly npmTokenSecret?: string;
GitHub secret which contains the NPM token to use when publishing packages.
"NPM_TOKEN"
property packageManager
readonly packageManager?: NodePackageManager;
The Node Package Manager used to execute scripts
NodePackageManager.YARN_CLASSIC
property packageName
readonly packageName?: string;
The "name" in package.json - defaults to project name
property peerDependencyOptions
readonly peerDependencyOptions?: PeerDependencyOptions;
Options for
peerDeps
.
property peerDeps
readonly peerDeps?: string[];
Peer dependencies for this module. Dependencies listed here are required to be installed (and satisfied) by the _consumer_ of this library. Using peer dependencies allows you to ensure that only a single module of a certain library exists in the
node_modules
tree of your consumers.Note that prior to npm@7, peer dependencies are _not_ automatically installed, which means that adding peer dependencies to a library will be a breaking change for your customers.
Unless
peerDependencyOptions.pinnedDevDependency
is disabled (it is enabled by default), projen will automatically add a dev dependency with a pinned version for each peer dependency. This will ensure that you build & test your module against the lowest peer version required.[]
property pnpmVersion
readonly pnpmVersion?: string;
The version of PNPM to use if using PNPM as a package manager.
"9"
property repository
readonly repository?: string;
The repository is the location where the actual code for your package lives. See https://classic.yarnpkg.com/en/docs/package-json/#toc-repository
property repositoryDirectory
readonly repositoryDirectory?: string;
If the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.
property scopedPackagesOptions
readonly scopedPackagesOptions?: ScopedPackagesOptions[];
Options for privately hosted scoped packages
- fetch all scoped packages from the public npm registry
property scripts
readonly scripts?: { [name: string]: string;};
npm scripts to include. If a script has the same name as a standard script, the standard script will be overwritten. Also adds the script as a task.
{}
Deprecated
use
project.addTask()
orpackage.setScript()
property stability
readonly stability?: string;
Package's Stability
property yarnBerryOptions
readonly yarnBerryOptions?: YarnBerryOptions;
Options for Yarn Berry
- Yarn Berry v4 with all default options
interface NodeProjectOptions
interface NodeProjectOptions extends GitHubProjectOptions, NodePackageOptions, ReleaseProjectOptions {}
property artifactsDirectory
readonly artifactsDirectory?: string;
A directory which will contain build artifacts.
"dist"
property autoApproveUpgrades
readonly autoApproveUpgrades?: boolean;
Automatically approve deps upgrade PRs, allowing them to be merged by mergify (if configued).
Throw if set to true but
autoApproveOptions
are not defined.- true
property buildWorkflow
readonly buildWorkflow?: boolean;
Define a GitHub workflow for building PRs. - true if not a subproject
property buildWorkflowOptions
readonly buildWorkflowOptions?: BuildWorkflowOptions;
Options for PR build workflow.
property buildWorkflowTriggers
readonly buildWorkflowTriggers?: Triggers;
Build workflow triggers "{ pullRequest: {}, workflowDispatch: {} }"
Deprecated
- Use
buildWorkflowOptions.workflowTriggers
property bundlerOptions
readonly bundlerOptions?: BundlerOptions;
Options for
Bundler
.
property checkLicenses
readonly checkLicenses?: LicenseCheckerOptions;
Configure which licenses should be deemed acceptable for use by dependencies
This setting will cause the build to fail, if any prohibited or not allowed licenses ares encountered.
- no license checks are run during the build and all licenses will be accepted
property codeCov
readonly codeCov?: boolean;
Define a GitHub workflow step for sending code coverage metrics to https://codecov.io/ Uses codecov/codecov-action@v4 A secret is required for private repos. Configured with
@codeCovTokenSecret
false
property codeCovTokenSecret
readonly codeCovTokenSecret?: string;
Define the secret name for a specified https://codecov.io/ token A secret is required to send coverage for private repositories - if this option is not specified, only public repositories are supported
property copyrightOwner
readonly copyrightOwner?: string;
License copyright owner.
- defaults to the value of authorName or "" if
authorName
is undefined.
property copyrightPeriod
readonly copyrightPeriod?: string;
The copyright years to put in the LICENSE file.
- current year
property defaultReleaseBranch
readonly defaultReleaseBranch: string;
The name of the main release branch.
"main"
property dependabot
readonly dependabot?: boolean;
Use dependabot to handle dependency upgrades. Cannot be used in conjunction with
depsUpgrade
.false
property dependabotOptions
readonly dependabotOptions?: DependabotOptions;
Options for dependabot.
- default options
property depsUpgrade
readonly depsUpgrade?: boolean;
Use tasks and github workflows to handle dependency upgrades. Cannot be used in conjunction with
dependabot
.true
property depsUpgradeOptions
readonly depsUpgradeOptions?: UpgradeDependenciesOptions;
Options for
UpgradeDependencies
.- default options
property gitignore
readonly gitignore?: string[];
Additional entries to .gitignore
property jest
readonly jest?: boolean;
Setup jest unit tests true
property jestOptions
readonly jestOptions?: JestOptions;
Jest options - default options
property mutableBuild
readonly mutableBuild?: boolean;
Automatically update files modified during builds to pull-request branches. This means that any files synthesized by projen or e.g. test snapshots will always be up-to-date before a PR is merged.
Implies that PR builds do not have anti-tamper checks.
true
Deprecated
- Use
buildWorkflowOptions.mutableBuild
property npmignore
readonly npmignore?: string[];
Additional entries to .npmignore.
Deprecated
- use
project.addPackageIgnore
property npmignoreEnabled
readonly npmignoreEnabled?: boolean;
Defines an .npmignore file. Normally this is only needed for libraries that are packaged as tarballs.
true
property npmIgnoreOptions
readonly npmIgnoreOptions?: IgnoreFileOptions;
Configuration options for .npmignore file
property package
readonly package?: boolean;
Defines a
package
task that will produce an npm tarball under the artifacts directory (e.g.dist
).true
property prettier
readonly prettier?: boolean;
Setup prettier.
false
property prettierOptions
readonly prettierOptions?: PrettierOptions;
Prettier options - default options
property projenDevDependency
readonly projenDevDependency?: boolean;
Indicates of "projen" should be installed as a devDependency.
- true if not a subproject
property projenrcJs
readonly projenrcJs?: boolean;
Generate (once) .projenrc.js (in JavaScript). Set to
false
in order to disable .projenrc.js generation.- true if projenrcJson is false
property projenrcJsOptions
readonly projenrcJsOptions?: ProjenrcOptions;
Options for .projenrc.js - default options
property projenVersion
readonly projenVersion?: string;
Version of projen to install.
- Defaults to the latest version.
property pullRequestTemplate
readonly pullRequestTemplate?: boolean;
Include a GitHub pull request template.
true
property pullRequestTemplateContents
readonly pullRequestTemplateContents?: string[];
The contents of the pull request template.
- default content
property release
readonly release?: boolean;
Add release management to this project.
- true (false for subprojects)
property releaseToNpm
readonly releaseToNpm?: boolean;
Automatically release to npm when new versions are introduced. false
property releaseWorkflow
readonly releaseWorkflow?: boolean;
DEPRECATED: renamed to
release
.- true if not a subproject
Deprecated
see
release
.
property workflowBootstrapSteps
readonly workflowBootstrapSteps?: JobStep[];
Workflow steps to use in order to bootstrap this repo.
"yarn install --frozen-lockfile && yarn projen"
property workflowGitIdentity
readonly workflowGitIdentity?: GitIdentity;
The git identity to use in workflows.
- GitHub Actions
property workflowNodeVersion
readonly workflowNodeVersion?: string;
The node version used in GitHub Actions workflows.
Always use this option if your GitHub Actions workflows require a specific to run.
-
minNodeVersion
if set, otherwiselts/*
.
property workflowPackageCache
readonly workflowPackageCache?: boolean;
Enable Node.js package cache in GitHub workflows.
false
interface NpmConfigOptions
interface NpmConfigOptions {}
Options to configure the local NPM config
interface PeerDependencyOptions
interface PeerDependencyOptions {}
property pinnedDevDependency
readonly pinnedDevDependency?: boolean;
Automatically add a pinned dev dependency. true
interface PrettierOptions
interface PrettierOptions {}
Options for Prettier
property ignoreFile
readonly ignoreFile?: boolean;
Defines an .prettierIgnore file
true
property ignoreFileOptions
readonly ignoreFileOptions?: IgnoreFileOptions;
Configuration options for .prettierignore file
property overrides
readonly overrides?: PrettierOverride[];
Provide a list of patterns to override prettier configuration.
[]
See Also
https://prettier.io/docs/en/configuration.html#configuration-overrides
property settings
readonly settings?: PrettierSettings;
Prettier settings. - default settings
property yaml
readonly yaml?: boolean;
Write prettier configuration as YAML instead of JSON false
interface PrettierOverride
interface PrettierOverride {}
property excludeFiles
readonly excludeFiles?: Files;
Exclude these files from this override.
property files
readonly files: Files;
Include these files in this override.
property options
readonly options: PrettierSettings;
The options to apply for this override.
interface PrettierSettings
interface PrettierSettings {}
Options to set in Prettier directly or through overrides
See Also
https://prettier.io/docs/en/options.html
property arrowParens
readonly arrowParens?: ArrowParens;
Include parentheses around a sole arrow function parameter.
ArrowParens.ALWAYS
property bracketSameLine
readonly bracketSameLine?: boolean;
Put > of opening tags on the last line instead of on a new line.
false
property bracketSpacing
readonly bracketSpacing?: boolean;
Print spaces between brackets.
true
property cursorOffset
readonly cursorOffset?: number;
Print (to stderr) where a cursor at the given position would move to after formatting. This option cannot be used with --range-start and --range-end.
-1
property embeddedLanguageFormatting
readonly embeddedLanguageFormatting?: EmbeddedLanguageFormatting;
Control how Prettier formats quoted code embedded in the file.
EmbeddedLanguageFormatting.AUTO
property endOfLine
readonly endOfLine?: EndOfLine;
Which end of line characters to apply.
EndOfLine.LF
property filepath
readonly filepath?: string;
Specify the input filepath. This will be used to do parser inference. none
property htmlWhitespaceSensitivity
readonly htmlWhitespaceSensitivity?: HTMLWhitespaceSensitivity;
How to handle whitespaces in HTML.
HTMLWhitespaceSensitivity.CSS
property insertPragma
readonly insertPragma?: boolean;
Insert pragma into file's first docblock comment.
false
property jsxSingleQuote
readonly jsxSingleQuote?: boolean;
Use single quotes in JSX.
false
property parser
readonly parser?: string;
Which parser to use.
- Prettier automatically infers the parser from the input file path, so you shouldn’t have to change this setting.
property plugins
readonly plugins?: string[];
Add a plugin. Multiple plugins can be passed as separate
--plugin
s.[]
property pluginSearchDirs
readonly pluginSearchDirs?: string[];
Custom directory that contains prettier plugins in node_modules subdirectory. Overrides default behavior when plugins are searched relatively to the location of Prettier. Multiple values are accepted.
[]
property printWidth
readonly printWidth?: number;
The line length where Prettier will try wrap.
80
property proseWrap
readonly proseWrap?: ProseWrap;
How to wrap prose.
ProseWrap.PRESERVE
property quoteProps
readonly quoteProps?: QuoteProps;
Change when properties in objects are quoted.
QuoteProps.ASNEEDED
property rangeEnd
readonly rangeEnd?: number;
Format code ending at a given character offset (exclusive). The range will extend forwards to the end of the selected statement. This option cannot be used with --cursor-offset.
null
property rangeStart
readonly rangeStart?: number;
Format code starting at a given character offset. The range will extend backwards to the start of the first line containing the selected statement. This option cannot be used with --cursor-offset.
0
property requirePragma
readonly requirePragma?: boolean;
Require either '@prettier' or '@format' to be present in the file's first docblock comment in order for it to be formatted.
false
property semi
readonly semi?: boolean;
Print semicolons.
true
property singleQuote
readonly singleQuote?: boolean;
Use single quotes instead of double quotes.
false
property tabWidth
readonly tabWidth?: number;
Number of spaces per indentation level.
2
property trailingComma
readonly trailingComma?: TrailingComma;
Print trailing commas wherever possible when multi-line.
TrailingComma.ES5
property useTabs
readonly useTabs?: boolean;
Indent with tabs instead of spaces.
false
property vueIndentScriptAndStyle
readonly vueIndentScriptAndStyle?: boolean;
Indent script and style tags in Vue files.
false
interface ProjenrcOptions
interface ProjenrcOptions {}
property filename
readonly filename?: string;
The name of the projenrc file. ".projenrc.js"
interface RenderWorkflowSetupOptions
interface RenderWorkflowSetupOptions {}
Options for
renderWorkflowSetup()
.
property installStepConfiguration
readonly installStepConfiguration?: JobStepConfiguration;
Configure the install step in the workflow setup.
-
{ name: "Install dependencies" }
Example 1
- { workingDirectory: "rootproject-dir" } for subprojects installing from root.
Example 2
- { env: { NPM_TOKEN: "token" }} for installing from private npm registry.
property mutable
readonly mutable?: boolean;
Should the package lockfile be updated? false
interface ScopedPackagesOptions
interface ScopedPackagesOptions {}
Options for scoped packages
property registryUrl
readonly registryUrl: string;
URL of the registry for scoped packages
property scope
readonly scope: string;
Scope of the packages
Example 1
"@angular"
interface TypeScriptCompilerOptions
interface TypeScriptCompilerOptions {}
property allowArbitraryExtensions
readonly allowArbitraryExtensions?: boolean;
Suppress arbitrary extension import errors with the assumption that a bundler will be handling it.
See Also
https://www.typescriptlang.org/tsconfig#allowArbitraryExtensions undefined
property allowImportingTsExtensions
readonly allowImportingTsExtensions?: boolean;
Allows TypeScript files to import each other with TypeScript-specific extensions (
.ts
,.mts
,.tsx
). RequiresnoEmit
oremitDeclarationOnly
.undefined
property allowJs
readonly allowJs?: boolean;
Allow JavaScript files to be compiled.
false
property allowSyntheticDefaultImports
readonly allowSyntheticDefaultImports?: boolean;
Allow default imports from modules with no default export. This does not affect code emit, just typechecking.
property allowUnreachableCode
readonly allowUnreachableCode?: boolean;
Allow Unreachable Code
When:
-
undefined
(default) provide suggestions as warnings to editors -true
unreachable code is ignored -false
raises compiler errors about unreachable codeThese warnings are only about code which is provably unreachable due to the use of JavaScript syntax.
See Also
https://www.typescriptlang.org/tsconfig#allowUnreachableCode
property allowUnusedLabels
readonly allowUnusedLabels?: boolean;
Allow Unused Labels
When:
-
undefined
(default) provide suggestions as warnings to editors -true
unused labels are ignored -false
raises compiler errors about unused labelsLabels are very rare in JavaScript and typically indicate an attempt to write an object literal:
function verifyAge(age: number) {// Forgot 'return' statementif (age > 18) {verified: true;// ^^^^^^^^ Unused label.}}See Also
https://www.typescriptlang.org/tsconfig#allowUnusedLabels
property alwaysStrict
readonly alwaysStrict?: boolean;
Ensures that your files are parsed in the ECMAScript strict mode, and emit “use strict” for each source file.
true
property baseUrl
readonly baseUrl?: string;
Lets you set a base directory to resolve non-absolute module names.
You can define a root folder where you can do absolute file resolution.
property checkJs
readonly checkJs?: boolean;
Check JS
Works in tandem with [allowJs](https://www.typescriptlang.org/tsconfig#allowJs). When checkJs is enabled then errors are reported in JavaScript files. This is the equivalent of including // @ts-check at the top of all JavaScript files which are included in your project.
See Also
https://www.typescriptlang.org/tsconfig#checkJs
property customConditions
readonly customConditions?: string[];
List of additional conditions that should succeed when TypeScript resolves from an
exports
orimports
field of apackage.json
.See Also
https://www.typescriptlang.org/tsconfig#customConditions undefined
property declaration
readonly declaration?: boolean;
To be specified along with the above
property declarationDir
readonly declarationDir?: string;
Offers a way to configure the root directory for where declaration files are emitted.
property declarationMap
readonly declarationMap?: boolean;
Generates a source map for .d.ts files which map back to the original .ts source file. This will allow editors such as VS Code to go to the original .ts file when using features like Go to Definition.
See Also
property downlevelIteration
readonly downlevelIteration?: boolean;
Downleveling is TypeScript’s term for transpiling to an older version of JavaScript. This flag is to enable support for a more accurate implementation of how modern JavaScript iterates through new concepts in older JavaScript runtimes.
ECMAScript 6 added several new iteration primitives: the for / of loop (for (el of arr)), Array spread ([a, ...b]), argument spread (fn(...args)), and Symbol.iterator. downlevelIteration allows for these iteration primitives to be used more accurately in ES5 environments if a Symbol.iterator implementation is present.
property emitDeclarationOnly
readonly emitDeclarationOnly?: boolean;
Only emit .d.ts files; do not emit .js files.
false
property emitDecoratorMetadata
readonly emitDecoratorMetadata?: boolean;
Enables experimental support for decorators, which is in stage 2 of the TC39 standardization process. Decorators are a language feature which hasn’t yet been fully ratified into the JavaScript specification. This means that the implementation version in TypeScript may differ from the implementation in JavaScript when it it decided by TC39. You can find out more about decorator support in TypeScript in the handbook.
See Also
https://www.typescriptlang.org/docs/handbook/decorators.html undefined
property esModuleInterop
readonly esModuleInterop?: boolean;
Emit __importStar and __importDefault helpers for runtime babel ecosystem compatibility and enable --allowSyntheticDefaultImports for typesystem compatibility.
false
property exactOptionalPropertyTypes
readonly exactOptionalPropertyTypes?: boolean;
Specifies that optional property types should be interpreted exactly as written, meaning that
| undefined
is not added to the type Available with TypeScript 4.4 and newer. false
property experimentalDecorators
readonly experimentalDecorators?: boolean;
Enables experimental support for decorators, which is in stage 2 of the TC39 standardization process.
true
property forceConsistentCasingInFileNames
readonly forceConsistentCasingInFileNames?: boolean;
Disallow inconsistently-cased references to the same file.
false
property importsNotUsedAsValues
readonly importsNotUsedAsValues?: TypeScriptImportsNotUsedAsValues;
This flag works because you can use
import type
to explicitly create animport
statement which should never be emitted into JavaScript.Remarks
For TypeScript 5.0+ use
verbatimModuleSyntax
instead. Posed for deprecation upon TypeScript 5.5.See Also
https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues "remove"
property incremental
readonly incremental?: boolean;
Tells TypeScript to save information about the project graph from the last compilation to files stored on disk. This creates a series of .tsbuildinfo files in the same folder as your compilation output. They are not used by your JavaScript at runtime and can be safely deleted. You can read more about the flag in the 3.4 release notes.
See Also
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#faster-subsequent-builds-with-the---incremental-flag
To control which folders you want to the files to be built to, use the config option tsBuildInfoFile.
property inlineSourceMap
readonly inlineSourceMap?: boolean;
When set, instead of writing out a .js.map file to provide source maps, TypeScript will embed the source map content in the .js files.
true
property inlineSources
readonly inlineSources?: boolean;
When set, TypeScript will include the original content of the .ts file as an embedded string in the source map. This is often useful in the same cases as inlineSourceMap.
true
property isolatedModules
readonly isolatedModules?: boolean;
Perform additional checks to ensure that separate compilation (such as with transpileModule or @babel/plugin-transform-typescript) would be safe.
false
property jsx
readonly jsx?: TypeScriptJsxMode;
Support JSX in .tsx files: "react", "preserve", "react-native" etc.
undefined
property jsxImportSource
readonly jsxImportSource?: string;
Declares the module specifier to be used for importing the jsx and jsxs factory functions when using jsx.
undefined
property lib
readonly lib?: string[];
Reference for type definitions / libraries to use (eg. ES2016, ES5, ES2018).
[ "es2018" ]
property module
readonly module?: string;
Sets the module system for the program. See https://www.typescriptlang.org/docs/handbook/modules.html#ambient-modules.
"CommonJS"
property moduleDetection
readonly moduleDetection?: TypeScriptModuleDetection;
This setting controls how TypeScript determines whether a file is a [script or a module](https://www.typescriptlang.org/docs/handbook/modules/theory.html#scripts-and-modules-in-javascript).
"auto"
property moduleResolution
readonly moduleResolution?: TypeScriptModuleResolution;
Determine how modules get resolved. Either "Node" for Node.js/io.js style resolution, or "Classic".
"node"
property noEmit
readonly noEmit?: boolean;
Do not emit outputs.
false
property noEmitOnError
readonly noEmitOnError?: boolean;
Do not emit compiler output files like JavaScript source code, source-maps or declarations if any errors were reported.
true
property noFallthroughCasesInSwitch
readonly noFallthroughCasesInSwitch?: boolean;
Report errors for fallthrough cases in switch statements. Ensures that any non-empty case inside a switch statement includes either break or return. This means you won’t accidentally ship a case fallthrough bug.
true
property noImplicitAny
readonly noImplicitAny?: boolean;
In some cases where no type annotations are present, TypeScript will fall back to a type of any for a variable when it cannot infer the type.
true
property noImplicitOverride
readonly noImplicitOverride?: boolean;
Using
noImplicitOverride
, you can ensure that sub-classes never go out of sync as they are required to explicitly declare that they are overriding a member using theoverride
keyword. This also improves readability of the programmer's intent.Available with TypeScript 4.3 and newer.
false
property noImplicitReturns
readonly noImplicitReturns?: boolean;
When enabled, TypeScript will check all code paths in a function to ensure they return a value.
true
property noImplicitThis
readonly noImplicitThis?: boolean;
Raise error on ‘this’ expressions with an implied ‘any’ type.
true
property noPropertyAccessFromIndexSignature
readonly noPropertyAccessFromIndexSignature?: boolean;
Raise error on use of the dot syntax to access fields which are not defined.
true
property noUncheckedIndexedAccess
readonly noUncheckedIndexedAccess?: boolean;
Raise error when accessing indexes on objects with unknown keys defined in index signatures.
true
property noUnusedLocals
readonly noUnusedLocals?: boolean;
Report errors on unused local variables.
true
property noUnusedParameters
readonly noUnusedParameters?: boolean;
Report errors on unused parameters in functions.
true
property outDir
readonly outDir?: string;
Output directory for the compiled files.
property paths
readonly paths?: { [key: string]: string[];};
A series of entries which re-map imports to lookup locations relative to the baseUrl, there is a larger coverage of paths in the handbook.
paths lets you declare how TypeScript should resolve an import in your require/imports.
property resolveJsonModule
readonly resolveJsonModule?: boolean;
Allows importing modules with a ‘.json’ extension, which is a common practice in node projects. This includes generating a type for the import based on the static JSON shape.
true
property resolvePackageJsonExports
readonly resolvePackageJsonExports?: boolean;
Forces TypeScript to consult the
exports
field ofpackage.json
files if it ever reads from a package innode_modules
.true
property resolvePackageJsonImports
readonly resolvePackageJsonImports?: boolean;
Forces TypeScript to consult the
imports
field ofpackage.json
when performing a lookup that begins with#
from a file that has apackage.json
as an ancestor.undefined
property rootDir
readonly rootDir?: string;
Specifies the root directory of input files.
Only use to control the output directory structure with
outDir
.
property skipLibCheck
readonly skipLibCheck?: boolean;
Skip type checking of all declaration files (*.d.ts).
false
property sourceMap
readonly sourceMap?: boolean;
Enables the generation of sourcemap files.
undefined
property sourceRoot
readonly sourceRoot?: string;
Specify the location where a debugger should locate TypeScript files instead of relative source locations.
undefined
property strict
readonly strict?: boolean;
The strict flag enables a wide range of type checking behavior that results in stronger guarantees of program correctness. Turning this on is equivalent to enabling all of the strict mode family options, which are outlined below. You can then turn off individual strict mode family checks as needed.
true
property strictNullChecks
readonly strictNullChecks?: boolean;
When strictNullChecks is false, null and undefined are effectively ignored by the language. This can lead to unexpected errors at runtime. When strictNullChecks is true, null and undefined have their own distinct types and you’ll get a type error if you try to use them where a concrete value is expected.
true
property strictPropertyInitialization
readonly strictPropertyInitialization?: boolean;
When set to true, TypeScript will raise an error when a class property was declared but not set in the constructor.
true
property stripInternal
readonly stripInternal?: boolean;
Do not emit declarations for code that has an
@internal
annotation in it’s JSDoc comment.true
property target
readonly target?: string;
Modern browsers support all ES6 features, so ES6 is a good choice. You might choose to set a lower target if your code is deployed to older environments, or a higher target if your code is guaranteed to run in newer environments.
"ES2018"
property tsBuildInfoFile
readonly tsBuildInfoFile?: string;
This setting lets you specify a file for storing incremental compilation information as a part of composite projects which enables faster building of larger TypeScript codebases. You can read more about composite projects in the handbook.
property typeRoots
readonly typeRoots?: string[];
If typeRoots is specified, only packages under typeRoots will be included
See Also
https://www.typescriptlang.org/tsconfig/#typeRoots
property types
readonly types?: string[];
If types is specified, only packages listed will be included in the global scope
See Also
https://www.typescriptlang.org/tsconfig#types
property useUnknownInCatchVariables
readonly useUnknownInCatchVariables?: boolean;
Change the type of the variable in a catch clause from any to unknown Available with TypeScript 4.4 and newer. true
property verbatimModuleSyntax
readonly verbatimModuleSyntax?: boolean;
Simplifies TypeScript's handling of import/export
type
modifiers.See Also
https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax undefined
interface TypescriptConfigOptions
interface TypescriptConfigOptions {}
property compilerOptions
readonly compilerOptions?: TypeScriptCompilerOptions;
Compiler options to use.
Remarks
Must provide either
extends
orcompilerOptions
(or both).
property exclude
readonly exclude?: string[];
Filters results from the "include" option.
- node_modules is excluded by default
property extends
readonly extends?: TypescriptConfigExtends;
Base
tsconfig.json
configuration(s) to inherit from.Remarks
Must provide either
extends
orcompilerOptions
(or both).
property fileName
readonly fileName?: string;
"tsconfig.json"
property include
readonly include?: string[];
Specifies a list of glob patterns that match TypeScript files to be included in compilation.
- all .ts files recursively
interface UpgradeDependenciesOptions
interface UpgradeDependenciesOptions {}
Options for
UpgradeDependencies
.
property exclude
readonly exclude?: string[];
List of package names to exclude during the upgrade.
- Nothing is excluded.
property include
readonly include?: string[];
List of package names to include during the upgrade.
- Everything is included.
property includeDeprecatedVersions
readonly includeDeprecatedVersions?: boolean;
Include deprecated packages.
By default, deprecated versions will be excluded from upgrades.
See Also
https://github.com/raineorshine/npm-check-updates?tab=readme-ov-file#options
false
property pullRequestTitle
readonly pullRequestTitle?: string;
Title of the pull request to use (should be all lower-case).
"upgrade dependencies"
property satisfyPeerDependencies
readonly satisfyPeerDependencies?: boolean;
Check peer dependencies of installed packages and filter updates to compatible versions.
By default, the upgrade workflow will adhere to version constraints from peer dependencies. Sometimes this is not desirable and can be disabled.
See Also
https://github.com/raineorshine/npm-check-updates#peer
true
property semanticCommit
readonly semanticCommit?: string;
The semantic commit type.
'chore'
property signoff
readonly signoff?: boolean;
Add Signed-off-by line by the committer at the end of the commit log message.
true
property target
readonly target?: string;
Determines the target version to upgrade dependencies to.
See Also
https://github.com/raineorshine/npm-check-updates#target
"minor"
property taskName
readonly taskName?: string;
The name of the task that will be created. This will also be the workflow name.
"upgrade".
property types
readonly types?: DependencyType[];
Specify which dependency types the upgrade should operate on.
- All dependency types.
property workflow
readonly workflow?: boolean;
Include a github workflow for creating PR's that upgrades the required dependencies, either by manual dispatch, or by a schedule.
If this is
false
, only a local projen task is created, which can be executed manually to upgrade the dependencies.- true for root projects, false for subprojects.
property workflowOptions
readonly workflowOptions?: UpgradeDependenciesWorkflowOptions;
Options for the github workflow. Only applies if
workflow
is true.- default options.
interface UpgradeDependenciesWorkflowOptions
interface UpgradeDependenciesWorkflowOptions {}
Options for
UpgradeDependencies.workflowOptions
.
property assignees
readonly assignees?: string[];
Assignees to add on the PR.
- no assignees
property branches
readonly branches?: string[];
List of branches to create PR's for.
- All release branches configured for the project.
property container
readonly container?: workflows.ContainerOptions;
Job container options.
- defaults
property gitIdentity
readonly gitIdentity?: GitIdentity;
The git identity to use for commits. "github-actions@github.com"
property labels
readonly labels?: string[];
Labels to apply on the PR.
- no labels.
property permissions
readonly permissions?: JobPermissions;
Permissions granted to the upgrade job To limit job permissions for
contents
, the desired permissions have to be explicitly set, e.g.:{ contents: JobPermission.NONE }
{ contents: JobPermission.READ }
property projenCredentials
readonly projenCredentials?: GithubCredentials;
Choose a method for authenticating with GitHub for creating the PR.
When using the default github token, PR's created by this workflow will not trigger any subsequent workflows (i.e the build workflow), so projen requires API access to be provided through e.g. a personal access token or other method.
See Also
https://github.com/peter-evans/create-pull-request/issues/48 - personal access token named PROJEN_GITHUB_TOKEN
property runsOn
readonly runsOn?: string[];
Github Runner selection labels ["ubuntu-latest"] Defines a target Runner by labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property runsOnGroup
readonly runsOnGroup?: GroupRunnerOptions;
Github Runner Group selection options Defines a target Runner Group by name and/or labels
Throws
{Error} if both
runsOn
andrunsOnGroup
are specified
property schedule
readonly schedule?: UpgradeDependenciesSchedule;
Schedule to run on.
UpgradeDependenciesSchedule.DAILY
interface YarnBerryOptions
interface YarnBerryOptions {}
Configure Yarn Berry
property version
readonly version?: string;
A fully specified version to use for yarn (e.g., x.x.x)
- 4.0.1
property yarnRcOptions
readonly yarnRcOptions?: YarnrcOptions;
The yarnrc configuration.
- a blank Yarn RC file
property zeroInstalls
readonly zeroInstalls?: boolean;
Should zero-installs be enabled? Learn more at: https://yarnpkg.com/features/caching#zero-installs
false
interface YarnLogFilter
interface YarnLogFilter {}
https://yarnpkg.com/configuration/yarnrc#logFilters
interface YarnNetworkSetting
interface YarnNetworkSetting {}
https://yarnpkg.com/configuration/yarnrc#networkSettings
property caFilePath
readonly caFilePath?: string;
Deprecated
- use httpsCaFilePath in Yarn v4 and newer
property enableNetwork
readonly enableNetwork?: boolean;
property httpProxy
readonly httpProxy?: string;
property httpsCaFilePath
readonly httpsCaFilePath?: string;
property httpsCertFilePath
readonly httpsCertFilePath?: string;
property httpsKeyFilePath
readonly httpsKeyFilePath?: string;
property httpsProxy
readonly httpsProxy?: string;
interface YarnNpmRegistry
interface YarnNpmRegistry {}
https://yarnpkg.com/configuration/yarnrc#npmRegistries
property npmAlwaysAuth
readonly npmAlwaysAuth?: boolean;
property npmAuthIdent
readonly npmAuthIdent?: string;
property npmAuthToken
readonly npmAuthToken?: string;
interface YarnNpmScope
interface YarnNpmScope {}
https://yarnpkg.com/configuration/yarnrc#npmScopes
property npmAlwaysAuth
readonly npmAlwaysAuth?: boolean;
property npmAuthIdent
readonly npmAuthIdent?: string;
property npmAuthToken
readonly npmAuthToken?: string;
property npmPublishRegistry
readonly npmPublishRegistry?: string;
property npmRegistryServer
readonly npmRegistryServer?: string;
interface YarnPackageExtension
interface YarnPackageExtension {}
https://yarnpkg.com/configuration/yarnrc#packageExtensions
property dependencies
readonly dependencies?: Record<string, string>;
property peerDependencies
readonly peerDependencies?: Record<string, string>;
property peerDependenciesMeta
readonly peerDependenciesMeta?: Record< string, Record<string, YarnPeerDependencyMeta>>;
interface YarnPeerDependencyMeta
interface YarnPeerDependencyMeta {}
https://yarnpkg.com/configuration/yarnrc#packageExtensions
property optional
readonly optional?: boolean;
interface YarnrcOptions
interface YarnrcOptions {}
Configuration for .yarnrc.yml in Yarn Berry v4
property cacheFolder
readonly cacheFolder?: string;
https://yarnpkg.com/configuration/yarnrc#cacheFolder
property cacheMigrationMode
readonly cacheMigrationMode?: YarnCacheMigrationMode;
https://yarnpkg.com/configuration/yarnrc#cacheMigrationMode
property changesetBaseRefs
readonly changesetBaseRefs?: string[];
https://yarnpkg.com/configuration/yarnrc#changesetBaseRefs
property changesetIgnorePatterns
readonly changesetIgnorePatterns?: string[];
https://yarnpkg.com/configuration/yarnrc#changesetIgnorePatterns
property checksumBehavior
readonly checksumBehavior?: YarnChecksumBehavior;
https://yarnpkg.com/configuration/yarnrc#checksumBehavior
property cloneConcurrency
readonly cloneConcurrency?: number;
https://yarnpkg.com/configuration/yarnrc#cloneConcurrency
property compressionLevel
readonly compressionLevel?: number | string;
https://yarnpkg.com/configuration/yarnrc#compressionLevel
property constraintsPath
readonly constraintsPath?: string;
https://yarnpkg.com/configuration/yarnrc#constraintsPath
property defaultLanguageName
readonly defaultLanguageName?: string;
https://yarnpkg.com/configuration/yarnrc#defaultLanguageName
property defaultProtocol
readonly defaultProtocol?: string;
https://yarnpkg.com/configuration/yarnrc#defaultProtocol
property defaultSemverRangePrefix
readonly defaultSemverRangePrefix?: YarnDefaultSemverRangePrefix;
https://yarnpkg.com/configuration/yarnrc#defaultSemverRangePrefix
property deferredVersionFolder
readonly deferredVersionFolder?: string;
https://yarnpkg.com/configuration/yarnrc#deferredVersionFolder
property enableColors
readonly enableColors?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableColors
property enableConstraintsCheck
readonly enableConstraintsCheck?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableConstraintsCheck
property enableGlobalCache
readonly enableGlobalCache?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableGlobalCache
property enableHardenedMode
readonly enableHardenedMode?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableHardenedMode
property enableHyperlinks
readonly enableHyperlinks?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableHyperlinks
property enableImmutableCache
readonly enableImmutableCache?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableImmutableCache
property enableImmutableInstalls
readonly enableImmutableInstalls?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableImmutableInstalls
property enableInlineBuilds
readonly enableInlineBuilds?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableInlineBuilds
property enableInlineHunks
readonly enableInlineHunks?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableInlineHunks
property enableMessageNames
readonly enableMessageNames?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableMessageNames
property enableMirror
readonly enableMirror?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableMirror
property enableNetwork
readonly enableNetwork?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableNetwork
property enableOfflineMode
readonly enableOfflineMode?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableOfflineMode
property enableProgressBars
readonly enableProgressBars?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableProgressBars
property enableScripts
readonly enableScripts?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableScripts
property enableStrictSsl
readonly enableStrictSsl?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableStrictSsl
property enableTelemetry
readonly enableTelemetry?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableTelemetry
property enableTimers
readonly enableTimers?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableTimers
property enableTransparentWorkspaces
readonly enableTransparentWorkspaces?: boolean;
https://yarnpkg.com/configuration/yarnrc#enableTransparentWorkspaces
property globalFolder
readonly globalFolder?: string;
https://yarnpkg.com/configuration/yarnrc#globalFolder
property httpProxy
readonly httpProxy?: string;
https://yarnpkg.com/configuration/yarnrc#httpProxy
property httpRetry
readonly httpRetry?: number;
https://yarnpkg.com/configuration/yarnrc#httpRetry
property httpsCaFilePath
readonly httpsCaFilePath?: string;
https://yarnpkg.com/configuration/yarnrc#httpsCaFilePath
property httpsCertFilePath
readonly httpsCertFilePath?: string;
https://yarnpkg.com/configuration/yarnrc#httpsCertFilePath
property httpsKeyFilePath
readonly httpsKeyFilePath?: string;
https://yarnpkg.com/configuration/yarnrc#httpsKeyFilePath
property httpsProxy
readonly httpsProxy?: string;
https://yarnpkg.com/configuration/yarnrc#httpsProxy
property httpTimeout
readonly httpTimeout?: number;
https://yarnpkg.com/configuration/yarnrc#httpTimeout
property ignoreCwd
readonly ignoreCwd?: boolean;
https://v3.yarnpkg.com/configuration/yarnrc#ignoreCwd
Deprecated
- removed in Yarn v4 and newer
property ignorePath
readonly ignorePath?: boolean;
https://yarnpkg.com/configuration/yarnrc#ignorePath
property immutablePatterns
readonly immutablePatterns?: string[];
https://yarnpkg.com/configuration/yarnrc#immutablePatterns
property initFields
readonly initFields?: Record<string, any>;
https://yarnpkg.com/configuration/yarnrc#initFields
property initScope
readonly initScope?: string;
https://yarnpkg.com/configuration/yarnrc#initScope
property injectEnvironmentFiles
readonly injectEnvironmentFiles?: string[];
https://yarnpkg.com/configuration/yarnrc#injectEnvironmentFiles
property installStatePath
readonly installStatePath?: string;
https://yarnpkg.com/configuration/yarnrc#installStatePath
property lockfileFilename
readonly lockfileFilename?: string;
https://v3.yarnpkg.com/configuration/yarnrc#lockfileFilename
Deprecated
- removed in Yarn v4 and newer
property logFilters
readonly logFilters?: YarnLogFilter[];
https://yarnpkg.com/configuration/yarnrc#logFilters
property networkConcurrency
readonly networkConcurrency?: number;
https://yarnpkg.com/configuration/yarnrc#networkConcurrency
property networkSettings
readonly networkSettings?: Record<string, YarnNetworkSetting>;
https://yarnpkg.com/configuration/yarnrc#networkSettings
property nmHoistingLimits
readonly nmHoistingLimits?: YarnNmHoistingLimit;
https://yarnpkg.com/configuration/yarnrc#nmHoistingLimits
property nmMode
readonly nmMode?: YarnNmMode;
https://yarnpkg.com/configuration/yarnrc#nmMode
property nmSelfReferences
readonly nmSelfReferences?: boolean;
https://yarnpkg.com/configuration/yarnrc#nmSelfReferences
property nodeLinker
readonly nodeLinker?: YarnNodeLinker;
https://yarnpkg.com/configuration/yarnrc#nodeLinker
property npmAlwaysAuth
readonly npmAlwaysAuth?: boolean;
https://yarnpkg.com/configuration/yarnrc#npmAlwaysAuth
property npmAuditExcludePackages
readonly npmAuditExcludePackages?: string[];
https://yarnpkg.com/configuration/yarnrc#npmAuditExcludePackages
property npmAuditIgnoreAdvisories
readonly npmAuditIgnoreAdvisories?: string[];
https://yarnpkg.com/configuration/yarnrc#npmAuditIgnoreAdvisories
property npmAuditRegistry
readonly npmAuditRegistry?: string;
https://yarnpkg.com/configuration/yarnrc#npmAuditRegistry
property npmAuthIdent
readonly npmAuthIdent?: string;
https://yarnpkg.com/configuration/yarnrc#npmAuthIdent
property npmAuthToken
readonly npmAuthToken?: string;
https://yarnpkg.com/configuration/yarnrc#npmAuthToken
property npmPublishAccess
readonly npmPublishAccess?: YarnNpmPublishAccess;
https://yarnpkg.com/configuration/yarnrc#npmPublishAccess
property npmPublishRegistry
readonly npmPublishRegistry?: string;
https://yarnpkg.com/configuration/yarnrc#npmPublishRegistry
property npmRegistries
readonly npmRegistries?: Record<string, YarnNpmRegistry>;
https://yarnpkg.com/configuration/yarnrc#npmRegistries
property npmRegistryServer
readonly npmRegistryServer?: string;
https://yarnpkg.com/configuration/yarnrc#npmRegistryServer
property npmScopes
readonly npmScopes?: Record<string, YarnNpmScope>;
https://yarnpkg.com/configuration/yarnrc#npmScopes
property packageExtensions
readonly packageExtensions?: Record<string, YarnPackageExtension>;
https://yarnpkg.com/configuration/yarnrc#packageExtensions
property patchFolder
readonly patchFolder?: string;
https://yarnpkg.com/configuration/yarnrc#patchFolder
property pnpDataPath
readonly pnpDataPath?: string;
https://v3.yarnpkg.com/configuration/yarnrc#pnpDataPath
Deprecated
- removed in Yarn v4 and newer
property pnpEnableEsmLoader
readonly pnpEnableEsmLoader?: boolean;
https://yarnpkg.com/configuration/yarnrc#pnpEnableEsmLoader
property pnpEnableInlining
readonly pnpEnableInlining?: boolean;
https://yarnpkg.com/configuration/yarnrc#pnpEnableInlining
property pnpFallbackMode
readonly pnpFallbackMode?: YarnPnpFallbackMode;
https://yarnpkg.com/configuration/yarnrc#pnpFallbackMode
property pnpIgnorePatterns
readonly pnpIgnorePatterns?: string[];
https://yarnpkg.com/configuration/yarnrc#pnpIgnorePatterns
property pnpMode
readonly pnpMode?: YarnPnpMode;
https://yarnpkg.com/configuration/yarnrc#pnpMode
property pnpShebang
readonly pnpShebang?: string;
https://yarnpkg.com/configuration/yarnrc#pnpShebang
property pnpUnpluggedFolder
readonly pnpUnpluggedFolder?: string;
https://yarnpkg.com/configuration/yarnrc#pnpUnpluggedFolder
property preferAggregateCacheInfo
readonly preferAggregateCacheInfo?: boolean;
https://v3.yarnpkg.com/configuration/yarnrc#preferAggregateCacheInfo
Deprecated
- removed in Yarn v4 and newer
property preferDeferredVersions
readonly preferDeferredVersions?: boolean;
https://yarnpkg.com/configuration/yarnrc#preferDeferredVersions
property preferInteractive
readonly preferInteractive?: boolean;
https://yarnpkg.com/configuration/yarnrc#preferInteractive
property preferReuse
readonly preferReuse?: boolean;
https://yarnpkg.com/configuration/yarnrc#preferReuse
property preferTruncatedLines
readonly preferTruncatedLines?: boolean;
https://yarnpkg.com/configuration/yarnrc#preferTruncatedLines
property progressBarStyle
readonly progressBarStyle?: YarnProgressBarStyle;
https://yarnpkg.com/configuration/yarnrc#progressBarStyle
property rcFilename
readonly rcFilename?: string;
https://yarnpkg.com/configuration/yarnrc#rcFilename
property supportedArchitectures
readonly supportedArchitectures?: YarnSupportedArchitectures;
https://yarnpkg.com/configuration/yarnrc#supportedArchitectures
property taskPoolConcurrency
readonly taskPoolConcurrency?: string;
https://yarnpkg.com/configuration/yarnrc#taskPoolConcurrency
property telemetryInterval
readonly telemetryInterval?: number;
https://yarnpkg.com/configuration/yarnrc#telemetryInterval
property telemetryUserId
readonly telemetryUserId?: string;
https://yarnpkg.com/configuration/yarnrc#telemetryUserId
property tsEnableAutoTypes
readonly tsEnableAutoTypes?: boolean;
https://yarnpkg.com/configuration/yarnrc#tsEnableAutoTypes
property unsafeHttpWhitelist
readonly unsafeHttpWhitelist?: string[];
https://yarnpkg.com/configuration/yarnrc#unsafeHttpWhitelist
property virtualFolder
readonly virtualFolder?: string;
https://yarnpkg.com/configuration/yarnrc#virtualFolder
property winLinkType
readonly winLinkType?: YarnWinLinkType;
https://yarnpkg.com/configuration/yarnrc#winLinkType
property workerPoolMode
readonly workerPoolMode?: YarnWorkerPoolMode;
https://yarnpkg.com/configuration/yarnrc#workerPoolMode
property yarnPath
readonly yarnPath?: string;
https://yarnpkg.com/configuration/yarnrc#yarnPath
interface YarnSupportedArchitectures
interface YarnSupportedArchitectures {}
https://yarnpkg.com/configuration/yarnrc#supportedArchitectures
enum ArrowParens
enum ArrowParens { ALWAYS = 'always', AVOID = 'avoid',}
enum AutoRelease
enum AutoRelease { EVERY_COMMIT = 0, DAILY = 1,}
Automatic bump modes
member DAILY
DAILY = 1
Automatically bump & release a new version on a daily basis.
member EVERY_COMMIT
EVERY_COMMIT = 0
Automatically bump & release a new version for every commit to "main"
enum BundleLogLevel
enum BundleLogLevel { VERBOSE = 'verbose', DEBUG = 'debug', INFO = 'info', WARNING = 'warning', ERROR = 'error', SILENT = 'silent',}
Log levels for esbuild and package managers' install commands.
member DEBUG
DEBUG = 'debug'
Show everything from info and some additional messages for debugging
member ERROR
ERROR = 'error'
Show errors only
member INFO
INFO = 'info'
Show warnings, errors, and an output file summary
member SILENT
SILENT = 'silent'
Show nothing
member VERBOSE
VERBOSE = 'verbose'
Show everything
member WARNING
WARNING = 'warning'
Show warnings and errors
enum Charset
enum Charset { ASCII = 'ascii', UTF8 = 'utf8',}
Charset for esbuild's output
enum CodeArtifactAuthProvider
enum CodeArtifactAuthProvider { ACCESS_AND_SECRET_KEY_PAIR = 'ACCESS_AND_SECRET_KEY_PAIR', GITHUB_OIDC = 'GITHUB_OIDC',}
Options for authorizing requests to a AWS CodeArtifact npm repository.
member ACCESS_AND_SECRET_KEY_PAIR
ACCESS_AND_SECRET_KEY_PAIR = 'ACCESS_AND_SECRET_KEY_PAIR'
Fixed credentials provided via Github secrets.
member GITHUB_OIDC
GITHUB_OIDC = 'GITHUB_OIDC'
Ephemeral credentials provided via Github's OIDC integration with an IAM role. See: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
enum EmbeddedLanguageFormatting
enum EmbeddedLanguageFormatting { AUTO = 'auto', OFF = 'off',}
enum EndOfLine
enum EndOfLine { AUTO = 'auto', CR = 'cr', CRLF = 'crlf', LF = 'lf',}
member AUTO
AUTO = 'auto'
Maintain existing (mixed values within one file are normalised by looking at what's used after the first line)
member CR
CR = 'cr'
Carriage Return character only (\r), used very rarely
member CRLF
CRLF = 'crlf'
Carriage Return + Line Feed characters (\r\n), common on Windows
member LF
LF = 'lf'
Line Feed only (\n), common on Linux and macOS as well as inside git repos
enum HTMLWhitespaceSensitivity
enum HTMLWhitespaceSensitivity { CSS = 'css', IGNORE = 'ignore', STRICT = 'strict',}
enum NodePackageManager
enum NodePackageManager { YARN = 'yarn', YARN2 = 'yarn2', YARN_CLASSIC = 'yarn_classic', YARN_BERRY = 'yarn_berry', NPM = 'npm', PNPM = 'pnpm', BUN = 'bun',}
The node package manager to use.
member BUN
BUN = 'bun'
Use
bun
as the package manager
member NPM
NPM = 'npm'
Use
npm
as the package manager.
member PNPM
PNPM = 'pnpm'
Use
pnpm
as the package manager.
member YARN
YARN = 'yarn'
Use
yarn
as the package manager.Deprecated
For
yarn
1.x useYARN_CLASSIC
foryarn
>= 2 useYARN_BERRY
. Currently,NodePackageManager.YARN
meansYARN_CLASSIC
. In the future, we might repurpose it to meanYARN_BERRY
.
member YARN_BERRY
YARN_BERRY = 'yarn_berry'
Use
yarn
versions >= 2 as the package manager.
member YARN_CLASSIC
YARN_CLASSIC = 'yarn_classic'
Use
yarn
1.x as the package manager.
member YARN2
YARN2 = 'yarn2'
Use
yarn
versions >= 2 as the package manager.Deprecated
use YARN_BERRY instead
enum NpmAccess
enum NpmAccess { PUBLIC = 'public', RESTRICTED = 'restricted',}
Npm package access level
member PUBLIC
PUBLIC = 'public'
Package is public.
member RESTRICTED
RESTRICTED = 'restricted'
Package can only be accessed with credentials.
enum ProseWrap
enum ProseWrap { ALWAYS = 'always', NEVER = 'never', PRESERVE = 'preserve',}
enum QuoteProps
enum QuoteProps { ASNEEDED = 'as-needed', CONSISTENT = 'consistent', PRESERVE = 'preserve',}
member ASNEEDED
ASNEEDED = 'as-needed'
Only add quotes around object properties where required.
member CONSISTENT
CONSISTENT = 'consistent'
If at least one property in an object requires quotes, quote all properties.
member PRESERVE
PRESERVE = 'preserve'
Respect the input use of quotes in object properties.
enum RunBundleTask
enum RunBundleTask { MANUAL = 'manual', PRE_COMPILE = 'pre_compile', POST_COMPILE = 'post_compile',}
Options for BundlerOptions.runBundleTask
member MANUAL
MANUAL = 'manual'
Don't bundle automatically as part of the build.
member POST_COMPILE
POST_COMPILE = 'post_compile'
Bundle automatically after compilation. This is useful if you want to bundle the compiled results.
Thus will run compilation tasks (using tsc, etc.) before running file through bundling step.
This is only required unless you are using new experimental features that are not supported by
esbuild
but are supported by typescript'stsc
compiler. One example of such feature isemitDecoratorMetadata
.// In a TypeScript project with output configured// to go to the "lib" directory:const project = new TypeScriptProject({name: "test",defaultReleaseBranch: "main",tsconfig: {compilerOptions: {outDir: "lib",},},bundlerOptions: {// ensure we compile with `tsc` before bundlingrunBundleTask: RunBundleTask.POST_COMPILE,},});// Tell the bundler to bundle the compiled results (from the "lib" directory)project.bundler.addBundle("./lib/index.js", {platform: "node",target: "node18",sourcemap: false,format: "esm",});
member PRE_COMPILE
PRE_COMPILE = 'pre_compile'
Bundle automatically before compilation.
enum SourceMapMode
enum SourceMapMode { DEFAULT = 'default', EXTERNAL = 'external', INLINE = 'inline', BOTH = 'both',}
SourceMap mode for esbuild
See Also
https://esbuild.github.io/api/#sourcemap
member BOTH
BOTH = 'both'
Both sourceMap mode - If you want to have the effect of both inline and external simultaneously
member DEFAULT
DEFAULT = 'default'
Default sourceMap mode - will generate a .js.map file alongside any generated .js file and add a special //# sourceMappingURL= comment to the bottom of the .js file pointing to the .js.map file
member EXTERNAL
EXTERNAL = 'external'
External sourceMap mode - If you want to omit the special //# sourceMappingURL= comment from the generated .js file but you still want to generate the .js.map files
member INLINE
INLINE = 'inline'
Inline sourceMap mode - If you want to insert the entire source map into the .js file instead of generating a separate .js.map file
enum TrailingComma
enum TrailingComma { ALL = 'all', ES5 = 'es5', NONE = 'none',}
enum TypeScriptImportsNotUsedAsValues
enum TypeScriptImportsNotUsedAsValues { REMOVE = 'remove', PRESERVE = 'preserve', ERROR = 'error',}
This flag controls how
import
works, there are 3 different options.See Also
https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues
member ERROR
ERROR = 'error'
This preserves all imports (the same as the preserve option), but will error when a value import is only used as a type. This might be useful if you want to ensure no values are being accidentally imported, but still make side-effect imports explicit.
member PRESERVE
PRESERVE = 'preserve'
Preserves all
import
statements whose values or types are never used. This can cause imports/side-effects to be preserved.
member REMOVE
REMOVE = 'remove'
The default behavior of dropping
import
statements which only reference types.
enum TypeScriptJsxMode
enum TypeScriptJsxMode { PRESERVE = 'preserve', REACT = 'react', REACT_NATIVE = 'react-native', REACT_JSX = 'react-jsx', REACT_JSXDEV = 'react-jsxdev',}
Determines how JSX should get transformed into valid JavaScript.
See Also
https://www.typescriptlang.org/docs/handbook/jsx.html
member PRESERVE
PRESERVE = 'preserve'
Keeps the JSX as part of the output to be further consumed by another transform step (e.g. Babel).
member REACT
REACT = 'react'
Converts JSX syntax into React.createElement, does not need to go through a JSX transformation before use, and the output will have a .js file extension.
member REACT_JSX
REACT_JSX = 'react-jsx'
Passes
key
separately from props and always passeschildren
as props (since React 17).See Also
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html#react-17-jsx-factories
member REACT_JSXDEV
REACT_JSXDEV = 'react-jsxdev'
Same as
REACT_JSX
with additional debug data.
member REACT_NATIVE
REACT_NATIVE = 'react-native'
Keeps all JSX like 'preserve' mode, but output will have a .js extension.
enum TypeScriptModuleDetection
enum TypeScriptModuleDetection { AUTO = 'auto', LEGACY = 'legacy', FORCE = 'force',}
This setting controls how TypeScript determines whether a file is a script or a module.
See Also
https://www.typescriptlang.org/docs/handbook/modules/theory.html#scripts-and-modules-in-javascript
member AUTO
AUTO = 'auto'
TypeScript will not only look for import and export statements, but it will also check whether the "type" field in a package.json is set to "module" when running with module: nodenext or node16, and check whether the current file is a JSX file when running under jsx: react-jsx.
See Also
https://www.typescriptlang.org/tsconfig/#moduleDetection
member FORCE
FORCE = 'force'
Ensures that every non-declaration file is treated as a module.
See Also
https://www.typescriptlang.org/tsconfig/#moduleDetection
member LEGACY
LEGACY = 'legacy'
The same behavior as 4.6 and prior, usings import and export statements to determine whether a file is a module.
See Also
https://www.typescriptlang.org/tsconfig/#moduleDetection
enum TypeScriptModuleResolution
enum TypeScriptModuleResolution { CLASSIC = 'classic', NODE = 'node', NODE10 = 'node10', NODE16 = 'node16', NODE_NEXT = 'nodenext', BUNDLER = 'bundler',}
Determines how modules get resolved.
See Also
https://www.typescriptlang.org/docs/handbook/module-resolution.html
member BUNDLER
BUNDLER = 'bundler'
Resolution strategy which attempts to mimic resolution patterns of modern bundlers; from TypeScript 5.0 onwards.
See Also
https://www.typescriptlang.org/tsconfig#moduleResolution
member CLASSIC
CLASSIC = 'classic'
TypeScript's former default resolution strategy.
See Also
https://www.typescriptlang.org/docs/handbook/module-resolution.html#classic
member NODE
NODE = 'node'
Resolution strategy which attempts to mimic the Node.js module resolution strategy at runtime.
See Also
https://www.typescriptlang.org/docs/handbook/module-resolution.html#node
member NODE_NEXT
NODE_NEXT = 'nodenext'
Node.js’ ECMAScript Module Support from TypeScript 4.7 onwards
See Also
https://www.typescriptlang.org/tsconfig#moduleResolution
member NODE10
NODE10 = 'node10'
--moduleResolution node
was renamed tonode10
(keepingnode
as an alias for backward compatibility) in TypeScript 5.0. It reflects the CommonJS module resolution algorithm as it existed in Node.js versions earlier than v12. It should no longer be used.See Also
https://www.typescriptlang.org/docs/handbook/modules/reference.html#node10-formerly-known-as-node
member NODE16
NODE16 = 'node16'
Node.js’ ECMAScript Module Support from TypeScript 4.7 onwards
See Also
https://www.typescriptlang.org/tsconfig#moduleResolution
enum UpdateSnapshot
enum UpdateSnapshot { ALWAYS = 'always', NEVER = 'never',}
enum YarnCacheMigrationMode
enum YarnCacheMigrationMode { REQUIRED_ONLY = 'requied-only', MATCH_SPEC = 'match-spec', ALWAYS = 'always',}
https://yarnpkg.com/configuration/yarnrc#cacheMigrationMode
member ALWAYS
ALWAYS = 'always'
member MATCH_SPEC
MATCH_SPEC = 'match-spec'
member REQUIRED_ONLY
REQUIRED_ONLY = 'requied-only'
enum YarnChecksumBehavior
enum YarnChecksumBehavior { THROW = 'throw', UPDATE = 'update', RESET = 'reset', IGNORE = 'ignore',}
https://yarnpkg.com/configuration/yarnrc#checksumBehavior
enum YarnDefaultSemverRangePrefix
enum YarnDefaultSemverRangePrefix { CARET = '^', TILDE = '~', EMPTY_STRING = '',}
https://yarnpkg.com/configuration/yarnrc#defaultSemverRangePrefix
enum YarnLogFilterLevel
enum YarnLogFilterLevel { INFO = 'info', WARNING = 'warning', ERROR = 'error', DISCARD = 'discard',}
https://v3.yarnpkg.com/configuration/yarnrc#logFilters.0.level
enum YarnNmHoistingLimit
enum YarnNmHoistingLimit { DEPENDENCIES = 'dependencies', NONE = 'none', WORKSPACES = 'workspaces',}
https://yarnpkg.com/configuration/yarnrc#nmHoistingLimits
member DEPENDENCIES
DEPENDENCIES = 'dependencies'
member NONE
NONE = 'none'
member WORKSPACES
WORKSPACES = 'workspaces'
enum YarnNmMode
enum YarnNmMode { CLASSIC = 'classic', HARDLINKS_LOCAL = 'hardlinks-local', HARDLINKS_GLOBAL = 'hardlinks-global',}
https://yarnpkg.com/configuration/yarnrc#nmMode
member CLASSIC
CLASSIC = 'classic'
member HARDLINKS_GLOBAL
HARDLINKS_GLOBAL = 'hardlinks-global'
member HARDLINKS_LOCAL
HARDLINKS_LOCAL = 'hardlinks-local'
enum YarnNodeLinker
enum YarnNodeLinker { PNP = 'pnp', PNPM = 'pnpm', NODE_MODULES = 'node-modules',}
https://yarnpkg.com/configuration/yarnrc#nodeLinker
enum YarnNpmPublishAccess
enum YarnNpmPublishAccess { PUBLIC = 'public', RESTRICTED = 'restricted',}
https://yarnpkg.com/configuration/yarnrc#npmPublishAccess
member PUBLIC
PUBLIC = 'public'
member RESTRICTED
RESTRICTED = 'restricted'
enum YarnPnpFallbackMode
enum YarnPnpFallbackMode { NONE = 'none', DEPENDENCIES_ONLY = 'dependencies-only', ALL = 'all',}
https://yarnpkg.com/configuration/yarnrc#pnpFallbackMode
member ALL
ALL = 'all'
member DEPENDENCIES_ONLY
DEPENDENCIES_ONLY = 'dependencies-only'
member NONE
NONE = 'none'
enum YarnPnpMode
enum YarnPnpMode { STRICT = 'strict', LOOSE = 'loose',}
https://yarnpkg.com/configuration/yarnrc#pnpMode
enum YarnProgressBarStyle
enum YarnProgressBarStyle { PATRICK = 'patrick', SIMBA = 'simba', JACK = 'jack', HOGSFATHER = 'hogsfather', DEFAULT = 'default',}
https://yarnpkg.com/configuration/yarnrc#progressBarStyle
member DEFAULT
DEFAULT = 'default'
member HOGSFATHER
HOGSFATHER = 'hogsfather'
member JACK
JACK = 'jack'
member PATRICK
PATRICK = 'patrick'
member SIMBA
SIMBA = 'simba'
enum YarnWinLinkType
enum YarnWinLinkType { JUNCTIONS = 'junctions', SYMLINKS = 'symlinks',}
https://yarnpkg.com/configuration/yarnrc#winLinkType
enum YarnWorkerPoolMode
enum YarnWorkerPoolMode { ASYNC = 'async', WORKERS = 'workers',}
type Files
type Files = string[] | string;
Exclude these files from this override.
Include these files in this override.
namespace python
module 'lib/python/index.d.ts' {}
function resolvePythonImportName
resolvePythonImportName: (jsiiFqn: string, jsiiManifest: any) => string;
class Pip
class Pip extends Component implements IPythonDeps {}
Manages dependencies using a requirements.txt file and the pip CLI tool.
constructor
constructor(project: Project, _options?: PipOptions);
property installCiTask
readonly installCiTask: Task;
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<module>@<semver>
method addDevDependency
addDevDependency: (spec: string) => void;
Adds a dev dependency.
Parameter spec
Format
<module>@<semver>
method installDependencies
installDependencies: () => void;
Installs dependencies (called during post-synthesis).
class Poetry
class Poetry extends Component implements IPythonDeps, IPythonEnv, IPythonPackaging {}
Manage project dependencies, virtual environments, and packaging through the poetry CLI tool.
constructor
constructor(project: Project, options: PoetryOptions);
property installCiTask
readonly installCiTask: Task;
Task for installing dependencies according to the existing lockfile.
property installTask
readonly installTask: Task;
Task for updating the lockfile and installing project dependencies.
property publishTask
readonly publishTask: Task;
Task for publishing the package to a package repository.
property publishTestTask
readonly publishTestTask: Task;
Task for publishing the package to the Test PyPI repository for testing purposes.
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<module>@<semver>
method addDevDependency
addDevDependency: (spec: string) => void;
Adds a dev dependency.
Parameter spec
Format
<module>@<semver>
method installDependencies
installDependencies: () => void;
Installs dependencies (called during post-synthesis).
method setupEnvironment
setupEnvironment: () => void;
Initializes the virtual environment if it doesn't exist (called during post-synthesis).
class PoetryPyproject
class PoetryPyproject extends Component {}
Represents configuration of a pyproject.toml file for a Poetry project.
See Also
https://python-poetry.org/docs/pyproject/
constructor
constructor(project: Project, options: PoetryPyprojectOptions);
property file
readonly file: TomlFile;
class Projenrc
class Projenrc extends ProjenrcFile {}
Allows writing projenrc files in python.
This will install
projen
as a Python dependency and will add asynth
task which will run.projenrc.py
.
constructor
constructor(project: Project, options?: ProjenrcOptions);
property filePath
readonly filePath: string;
The name of the projenrc file.
property pythonExec
readonly pythonExec: string;
Path to the python executable to use.
class Pytest
class Pytest extends Component {}
constructor
constructor(project: Project, options?: PytestOptions);
property testdir
readonly testdir: string;
Deprecated
Use
sampleTestdir
on the project instead.
property testMatch
readonly testMatch: string[];
class PytestSample
class PytestSample extends Component {}
Python test code sample.
constructor
constructor(project: Project, options: PytestSampleOptions);
class PythonProject
class PythonProject extends GitHubProject {}
Python project.
python
constructor
constructor(options: PythonProjectOptions);
property depsManager
readonly depsManager: IPythonDeps;
API for managing dependencies.
property envManager
readonly envManager: IPythonEnv;
API for mangaging the Python runtime environment.
property moduleName
readonly moduleName: string;
Python module name (the project name, with any hyphens or periods replaced with underscores).
property packagingManager
readonly packagingManager?: IPythonPackaging;
API for managing packaging the project as a library. Only applies when the
projectType
is LIB.
property pytest
pytest?: Pytest;
Pytest component.
property sampleTestdir
readonly sampleTestdir: string;
Directory where sample tests are located. "tests"
property version
readonly version: string;
Version of the package for distribution (should follow semver).
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<module>@<semver>
method addDevDependency
addDevDependency: (spec: string) => void;
Adds a dev dependency.
Parameter spec
Format
<module>@<semver>
method postSynthesize
postSynthesize: () => void;
class PythonSample
class PythonSample extends Component {}
Python code sample.
constructor
constructor(project: Project, options: PythonSampleOptions);
class RequirementsFile
class RequirementsFile extends FileBase {}
Specifies a list of packages to be installed using pip.
See Also
https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format
constructor
constructor( project: Project, filePath: string, options: RequirementsFileOptions);
method addPackages
addPackages: (...packages: string[]) => void;
Adds the specified packages provided in semver format.
Comment lines (start with
#
) are ignored.Parameter packages
Package version in format
<module>@<semver>
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class SetupPy
class SetupPy extends FileBase {}
Python packaging script where package metadata can be placed.
constructor
constructor(project: Project, options: SetupPyOptions);
method synthesizeContent
protected synthesizeContent: (resolver: IResolver) => string | undefined;
class Setuptools
class Setuptools extends Component implements IPythonPackaging {}
Manages packaging through setuptools with a setup.py script.
constructor
constructor(project: Project, options: SetuptoolsOptions);
property publishTask
readonly publishTask: Task;
property publishTestTask
readonly publishTestTask: Task;
A task that uploads the package to the Test PyPI repository.
class Venv
class Venv extends Component implements IPythonEnv {}
Manages a virtual environment through the Python venv module.
constructor
constructor(project: Project, options?: VenvOptions);
method setupEnvironment
setupEnvironment: () => void;
Initializes the virtual environment if it doesn't exist (called during post-synthesis).
interface IPackageProvider
interface IPackageProvider {}
property packages
readonly packages: Dependency[];
An array of packages (may be dynamically generated).
interface IPythonDeps
interface IPythonDeps {}
property installCiTask
readonly installCiTask: Task;
A task that installs and updates dependencies.
method addDependency
addDependency: (spec: string) => void;
Adds a runtime dependency.
Parameter spec
Format
<module>@<semver>
method addDevDependency
addDevDependency: (spec: string) => void;
Adds a dev dependency.
Parameter spec
Format
<module>@<semver>
method installDependencies
installDependencies: () => void;
Installs dependencies (called during post-synthesis).
interface IPythonEnv
interface IPythonEnv {}
method setupEnvironment
setupEnvironment: () => void;
Initializes the virtual environment if it doesn't exist (called during post-synthesis).
interface IPythonPackaging
interface IPythonPackaging {}
property publishTask
readonly publishTask: Task;
A task that uploads the package to a package repository.
interface PipOptions
interface PipOptions {}
Options for pip
interface PoetryOptions
interface PoetryOptions extends PythonPackagingOptions, PythonExecutableOptions {}
interface PoetryPyprojectOptions
interface PoetryPyprojectOptions extends PoetryPyprojectOptionsWithoutDeps {}
Poetry-specific options.
See Also
https://python-poetry.org/docs/pyproject/
property dependencies
readonly dependencies?: { [key: string]: any;};
A list of dependencies for the project.
The python version for which your package is compatible is also required.
Example 1
{ requests: "^2.13.0" }
property devDependencies
readonly devDependencies?: { [key: string]: any;};
A list of development dependencies for the project.
Example 1
{ requests: "^2.13.0" }
interface PoetryPyprojectOptionsWithoutDeps
interface PoetryPyprojectOptionsWithoutDeps {}
Poetry-specific options.
See Also
https://python-poetry.org/docs/pyproject/
property authors
readonly authors?: string[];
The authors of the package. Must be in the form "name "
property classifiers
readonly classifiers?: string[];
A list of PyPI trove classifiers that describe the project.
See Also
https://pypi.org/classifiers/
property description
readonly description?: string;
A short description of the package (required).
property documentation
readonly documentation?: string;
A URL to the documentation of the project.
property exclude
readonly exclude?: string[];
A list of patterns that will be excluded in the final package.
If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (.gitignore for git for example).
property extras
readonly extras?: { [key: string]: string[];};
Package extras
property homepage
readonly homepage?: string;
A URL to the website of the project.
property include
readonly include?: string[];
A list of patterns that will be included in the final package.
property keywords
readonly keywords?: string[];
A list of keywords (max: 5) that the package is related to.
property license
readonly license?: string;
License of this package as an SPDX identifier.
If the project is proprietary and does not use a specific license, you can set this value as "Proprietary".
property maintainers
readonly maintainers?: string[];
the maintainers of the package. Must be in the form "name "
property name
readonly name?: string;
Name of the package (required).
property packageMode
readonly packageMode?: boolean;
Package mode (optional).
Example 1
false
See Also
https://python-poetry.org/docs/pyproject/#package-mode true
property packages
readonly packages?: any[];
A list of packages and modules to include in the final distribution.
property plugins
readonly plugins?: any;
Plugins. Must be specified as a table.
See Also
https://toml.io/en/v1.0.0#table
property readme
readonly readme?: string;
The name of the readme file of the package.
property repository
readonly repository?: string;
A URL to the repository of the project.
property scripts
readonly scripts?: { [key: string]: any;};
The scripts or executables that will be installed when installing the package.
property source
readonly source?: any[];
Source registries from which packages are retrieved.
property urls
readonly urls?: { [key: string]: string;};
Project custom URLs, in addition to homepage, repository and documentation. E.g. "Bug Tracker"
property version
readonly version?: string;
Version of the package (required).
interface ProjenrcOptions
interface ProjenrcOptions {}
Options for
Projenrc
.
property filename
readonly filename?: string;
The name of the projenrc file. ".projenrc.py"
property projenVersion
readonly projenVersion?: string;
The projen version to use - current version
property pythonExec
readonly pythonExec?: string;
Path to the python executable to use. "python"
interface PytestOptions
interface PytestOptions {}
property maxFailures
readonly maxFailures?: number;
Stop the testing process after the first N failures
property testdir
readonly testdir?: string;
Location of sample tests. Typically the same directory where project tests will be located.
"tests"
Deprecated
Reference
sampleTestdir
on the project instead; to change the directory where tests are discovered from, usetestMatch
.
property testMatch
readonly testMatch?: string[];
List of paths to test files or directories. Useful when all project tests are in a known location to speed up test collection and to avoid picking up undesired tests by accident.
Leave empty to discover all test_*.py or *_test.py files, per Pytest default.
The array will be concatenated and passed as a single argument to pytest.
Example 1
["tests/unit", "tests/qa"] []
property version
readonly version?: string;
Pytest version
"7.4.3"
interface PytestSampleOptions
interface PytestSampleOptions {}
Options for python test code sample.
property moduleName
readonly moduleName: string;
Name of the python package as used in imports and filenames.
property testdir
readonly testdir: string;
Test directory
interface PythonExecutableOptions
interface PythonExecutableOptions {}
property pythonExec
readonly pythonExec?: string;
Path to the python executable to use. "python"
interface PythonPackagingOptions
interface PythonPackagingOptions {}
property authorEmail
readonly authorEmail: string;
Author's e-mail
$GIT_USER_EMAIL
property authorName
readonly authorName: string;
Author's name
$GIT_USER_NAME
property classifiers
readonly classifiers?: string[];
A list of PyPI trove classifiers that describe the project.
See Also
https://pypi.org/classifiers/
property description
readonly description?: string;
A short description of the package.
property homepage
readonly homepage?: string;
A URL to the website of the project.
property license
readonly license?: string;
License of this package as an SPDX identifier.
property packageName
readonly packageName?: string;
Package name.
property poetryOptions
readonly poetryOptions?: PoetryPyprojectOptionsWithoutDeps;
Additional options to set for poetry if using poetry
property setupConfig
readonly setupConfig?: { [key: string]: any;};
Additional fields to pass in the setup() function if using setuptools
property version
readonly version: string;
Version of the package.
"0.1.0"
interface PythonProjectOptions
interface PythonProjectOptions extends GitHubProjectOptions, PythonPackagingOptions, PythonExecutableOptions {}
Options for
PythonProject
.
property deps
readonly deps?: string[];
List of runtime dependencies for this project.
Dependencies use the format:
<module>@<semver>
Additional dependencies can be added via
project.addDependency()
.[]
property devDeps
readonly devDeps?: string[];
List of dev dependencies for this project.
Dependencies use the format:
<module>@<semver>
Additional dependencies can be added via
project.addDevDependency()
.[]
property moduleName
readonly moduleName: string;
Name of the python package as used in imports and filenames.
Must only consist of alphanumeric characters and underscores.
$PYTHON_MODULE_NAME
property pip
readonly pip?: boolean;
Use pip with a requirements.txt file to track project dependencies.
- true, unless poetry is true, then false
property poetry
readonly poetry?: boolean;
Use poetry to manage your project dependencies, virtual environment, and (optional) packaging/publishing.
This feature is incompatible with pip, setuptools, or venv. If you set this option to
true
, then pip, setuptools, and venv must be set tofalse
.false
property projenrcJs
readonly projenrcJs?: boolean;
Use projenrc in javascript.
This will install
projen
as a JavaScript dependency and add asynth
task which will run.projenrc.js
.false
property projenrcJsOptions
readonly projenrcJsOptions?: ProjenrcJsOptions;
Options related to projenrc in JavaScript. - default options
property projenrcPython
readonly projenrcPython?: boolean;
Use projenrc in Python.
This will install
projen
as a Python dependency and add asynth
task which will run.projenrc.py
.true
property projenrcPythonOptions
readonly projenrcPythonOptions?: ProjenrcPythonOptions;
Options related to projenrc in python. - default options
property projenrcTs
readonly projenrcTs?: boolean;
Use projenrc in TypeScript.
This will create a tsconfig file (default:
tsconfig.projen.json
) and usets-node
in the default task to parse the project source files.false
property projenrcTsOptions
readonly projenrcTsOptions?: ProjenrcTsOptions;
Options related to projenrc in TypeScript. - default options
property pytest
readonly pytest?: boolean;
Include pytest tests. true
property pytestOptions
readonly pytestOptions?: PytestOptions;
pytest options - defaults
property sample
readonly sample?: boolean;
Include sample code and test if the relevant directories don't exist. true
property sampleTestdir
readonly sampleTestdir?: string;
Location of sample tests. Typically the same directory where project tests will be located. "tests"
property setuptools
readonly setuptools?: boolean;
Use setuptools with a setup.py script for packaging and publishing.
- true, unless poetry is true, then false
property venv
readonly venv?: boolean;
Use venv to manage a virtual environment for installing dependencies inside.
- true, unless poetry is true, then false
property venvOptions
readonly venvOptions?: VenvOptions;
Venv options - defaults
interface PythonSampleOptions
interface PythonSampleOptions {}
Options for python sample code.
property dir
readonly dir: string;
Sample code directory
interface RequirementsFileOptions
interface RequirementsFileOptions {}
property packageProvider
readonly packageProvider?: IPackageProvider;
Provide a list of packages that can be dynamically updated.
interface SetupPyOptions
interface SetupPyOptions {}
Fields to pass in the setup() function of setup.py
See Also
https://docs.python.org/3/distutils/setupscript.html
property additionalOptions
readonly additionalOptions?: { [name: string]: any;};
Escape hatch to allow any value
property authorEmail
readonly authorEmail?: string;
Author's e-mail
property authorName
readonly authorName?: string;
Author's name
property classifiers
readonly classifiers?: string[];
A list of PyPI trove classifiers that describe the project.
See Also
https://pypi.org/classifiers/
property description
readonly description?: string;
A short project description
property homepage
readonly homepage?: string;
Package's Homepage / Website
property license
readonly license?: string;
The project license
property name
readonly name?: string;
Name of the package
property packages
readonly packages?: string[];
List of submodules to be packaged
property version
readonly version?: string;
Manually specify package version
index signature
readonly [name: string]: any;
Escape hatch to allow any value (JS/TS only)
Deprecated
Prefer using
additionalOptions
instead.ignore
interface SetuptoolsOptions
interface SetuptoolsOptions extends PythonPackagingOptions, PythonExecutableOptions {}
interface VenvOptions
interface VenvOptions {}
Options for venv.
property envdir
readonly envdir?: string;
Name of directory to store the environment in
".env"
property pythonExec
readonly pythonExec?: string;
Path to the python executable to use. "python"
namespace release
module 'lib/release/index.d.ts' {}
function isAwsCodeArtifactRegistry
isAwsCodeArtifactRegistry: ( registryUrl: string | undefined) => boolean | '' | undefined;
Evaluates if the
registryUrl
is a AWS CodeArtifact registry.Parameter registryUrl
url of registry
Returns
true for AWS CodeArtifact
class Publisher
class Publisher extends Component {}
Implements GitHub jobs for publishing modules to package managers.
Under the hood, it uses https://github.com/aws/publib
constructor
constructor(project: Project, options: PublisherOptions);
property artifactName
readonly artifactName: string;
property buildJobId
readonly buildJobId: string;
property condition
readonly condition?: string;
property jsiiReleaseVersion
readonly jsiiReleaseVersion: string;
Deprecated
use
publibVersion
property publibVersion
readonly publibVersion: string;
property PUBLISH_GIT_TASK_NAME
static readonly PUBLISH_GIT_TASK_NAME: string;
method addGitHubPostPublishingSteps
addGitHubPostPublishingSteps: (...steps: JobStep[]) => void;
Adds post publishing steps for the GitHub release job.
Parameter steps
The steps.
method addGitHubPrePublishingSteps
addGitHubPrePublishingSteps: (...steps: JobStep[]) => void;
Adds pre publishing steps for the GitHub release job.
Parameter steps
The steps.
method publishToGit
publishToGit: (options: GitPublishOptions) => import('..').Task;
Publish to git.
This includes generating a project-level changelog and release tags.
Parameter options
Options
method publishToGitHubReleases
publishToGitHubReleases: (options: GitHubReleasesPublishOptions) => void;
Creates a GitHub Release.
Parameter options
Options
method publishToGo
publishToGo: (options?: GoPublishOptions) => void;
Adds a go publishing job.
Parameter options
Options
method publishToMaven
publishToMaven: (options?: MavenPublishOptions) => void;
Publishes artifacts from
java/**
to Maven.Parameter options
Options
method publishToNpm
publishToNpm: (options?: NpmPublishOptions) => void;
Publishes artifacts from
js/**
to npm.Parameter options
Options