Skip to content

API.md

Latest commit

 

History

History
1701 lines (1046 loc) · 54.8 KB

API.md

File metadata and controls

1701 lines (1046 loc) · 54.8 KB

API Reference

Structs

TypeScriptCompilerPlugins

Extends the {@link TypeScriptCompilerOptions} interface with the {@link plugins} property for configuring Language Service Plugins and ts-patch plugins.

projen/projen#1482

Initializer 

import { TypeScriptCompilerPlugins } from '@functionless/projen'

const typeScriptCompilerPlugins: TypeScriptCompilerPlugins = { ... }

Properties

Name Type Description
plugins TypeScriptPlugin[] A list of Language Service and ts-patch plugins to run as part of TypeScript compilation.
pluginsOptional 
public readonly plugins: TypeScriptPlugin[];

A list of Language Service and ts-patch plugins to run as part of TypeScript compilation.

TypeScriptPlugin

Configures a Language Service or Transformer Plugin to run as part of TypeScript compilation.

https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin

Initializer 

import { TypeScriptPlugin } from '@functionless/projen'

const typeScriptPlugin: TypeScriptPlugin = { ... }

Properties

Name Type Description
name string Name of a NPM module that implements the TypeScript Language Service Plugin interface.
transform string Path to a module implementing the ts-patch Transformer Plugin interface.
nameOptional 
public readonly name: string;
  • Type: string

Name of a NPM module that implements the TypeScript Language Service Plugin interface.

It must be the name of a NPM module and cannot be a path to an individual JS file.

Valid:

{
   name: "@functionless/language-service"
}

Invalid:

{
   name: "@functionless/language-service/lib/plugin"
}

https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin

transformOptional 
public readonly transform: string;
  • Type: string

Path to a module implementing the ts-patch Transformer Plugin interface.

Example:

{
   transform: "functionless/lib/compile"
}

https://github.com/nonara/ts-patch

Classes

Functionless

Component that configures a TypeScript project to use Functionless by adding the necessary dependencies and setting up ts-patch.

Initializers 

import { Functionless } from '@functionless/projen'

new Functionless(tsProject: TypeScriptProject)
Name Type Description
tsProject projen.typescript.TypeScriptProject No description.
tsProjectRequired
  • Type: projen.typescript.TypeScriptProject

Methods

Name Description
postSynthesize Called after synthesis.
preSynthesize Called before synthesis.
synthesize Synthesizes files to the project output directory.
postSynthesize 
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize 
public preSynthesize(): void

Called before synthesis.

synthesize 
public synthesize(): void

Synthesizes files to the project output directory.

Properties

Name Type Description
project projen.Project No description.
swcrc projen.JsonFile No description.
tsProject projen.typescript.TypeScriptProject No description.
projectRequired 
public readonly project: Project;
  • Type: projen.Project
swcrcRequired 
public readonly swcrc: JsonFile;
  • Type: projen.JsonFile
tsProjectRequired 
public readonly tsProject: TypeScriptProject;
  • Type: projen.typescript.TypeScriptProject

Constants

Name Type Description
coreDependency string No description.
dependencies string[] No description.
devDependencies string[] No description.
languageServiceDependency string No description.
coreDependencyRequired 
public readonly coreDependency: string;
  • Type: string
dependenciesRequired 
public readonly dependencies: string[];
  • Type: string[]
devDependenciesRequired 
public readonly devDependencies: string[];
  • Type: string[]
languageServiceDependencyRequired 
public readonly languageServiceDependency: string;
  • Type: string

FunctionlessProject

Project that wraps an AwsCdkTypeScriptProject and adds configures Functionless.

Initializers 

import { FunctionlessProject } from '@functionless/projen'

new FunctionlessProject(options: AwsCdkTypeScriptAppOptions)
Name Type Description
options projen.awscdk.AwsCdkTypeScriptAppOptions No description.
optionsRequired
  • Type: projen.awscdk.AwsCdkTypeScriptAppOptions

Methods

Name Description
addExcludeFromCleanup Exclude the matching files from pre-synth cleanup.
addGitIgnore Adds a .gitignore pattern.
addPackageIgnore Exclude these files from the bundled package.
addTask Adds a new task to this project.
addTip Prints a "tip" message during synthesis.
annotateGenerated Marks the provided file(s) as being generated.
postSynthesize Called after all components are synthesized.
preSynthesize Called before all components are synthesized.
removeTask Removes a task from a project.
runTaskCommand Returns the shell command to execute in order to run a task.
synth Synthesize all project files into outdir.
tryFindFile Finds a file at the specified relative path within this project and all its subprojects.
tryFindJsonFile Finds a json file by name.
tryFindObjectFile Finds an object file (like JsonFile, YamlFile, etc.) by name.
tryRemoveFile Finds a file at the specified relative path within this project and removes it.
addBins No description.
addBundledDeps Defines bundled dependencies.
addCompileCommand DEPRECATED.
addDeps Defines normal dependencies.
addDevDeps Defines development/test dependencies.
addFields Directly set fields in package.json.
addKeywords Adds keywords to package.json (deduplicated).
addPeerDeps Defines peer dependencies.
addTestCommand DEPRECATED.
hasScript Indicates if a script by the name name is defined.
removeScript Removes the npm script (always successful).
renderWorkflowSetup Returns the set of workflow steps which should be executed to bootstrap a workflow.
setScript Replaces the contents of an npm package.json script.
addCdkDependency Adds an AWS CDK module dependencies.
addExcludeFromCleanup 
public addExcludeFromCleanup(globs: string): void

Exclude the matching files from pre-synth cleanup.

Can be used when, for example, some source files include the projen marker and we don't want them to be erased during synth.

globsRequired
  • Type: string

The glob patterns to match.

addGitIgnore 
public addGitIgnore(pattern: string): void

Adds a .gitignore pattern.

patternRequired
  • Type: string

The glob pattern to ignore.

addPackageIgnore 
public addPackageIgnore(pattern: string): void

Exclude these files from the bundled package.

Implemented by project types based on the packaging mechanism. For example, NodeProject delegates this to .npmignore.

patternRequired
  • Type: string
addTask 
public addTask(name: string, props?: TaskOptions): Task

Adds a new task to this project.

This will fail if the project already has a task with this name.

nameRequired
  • Type: string

The task name to add.

propsOptional
  • Type: projen.TaskOptions

Task properties.

addTip 
public addTip(message: string): void

Prints a "tip" message during synthesis.

messageRequired
  • Type: string

The message.

annotateGenerated 
public annotateGenerated(glob: string): void

Marks the provided file(s) as being generated.

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

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

globRequired
  • Type: string

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

postSynthesize 
public postSynthesize(): void

Called after all components are synthesized.

Order is not guaranteed.

preSynthesize 
public preSynthesize(): void

Called before all components are synthesized.

removeTask 
public removeTask(name: string): Task

Removes a task from a project.

nameRequired
  • Type: string

The name of the task to remove.

runTaskCommand 
public runTaskCommand(task: Task): string

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

This will typically be npx projen TASK.

taskRequired
  • Type: projen.Task

The task for which the command is required.

synth 
public synth(): void

Synthesize all project files into outdir.

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

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

filePathRequired
  • Type: string

The file path.

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

tryFindJsonFile 
public tryFindJsonFile(filePath: string): JsonFile

Finds a json file by name.

filePathRequired
  • Type: string

The file path.

tryFindObjectFile 
public tryFindObjectFile(filePath: string): ObjectFile

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

filePathRequired
  • Type: string

The file path.

tryRemoveFile 
public tryRemoveFile(filePath: string): FileBase

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

filePathRequired
  • Type: string

The file path.

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

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

Defines bundled dependencies.

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

depsRequired
  • Type: string

Names modules to install.

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

addCompileCommand 
public addCompileCommand(commands: string): void

DEPRECATED.

commandsRequired
  • Type: string
addDeps 
public addDeps(deps: string): void

Defines normal dependencies.

depsRequired
  • Type: string

Names modules to install.

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

addDevDeps 
public addDevDeps(deps: string): void

Defines development/test dependencies.

depsRequired
  • Type: string

Names modules to install.

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

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

Directly set fields in package.json.

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

The fields to set.

addKeywords 
public addKeywords(keywords: string): void

Adds keywords to package.json (deduplicated).

keywordsRequired
  • Type: string

The keywords to add.

addPeerDeps 
public addPeerDeps(deps: string): void

Defines peer dependencies.

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

depsRequired
  • Type: string

Names modules to install.

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

addTestCommand 
public addTestCommand(commands: string): void

DEPRECATED.

commandsRequired
  • Type: string
hasScript 
public hasScript(name: string): boolean

Indicates if a script by the name name is defined.

nameRequired
  • Type: string

The name of the script.

removeScript 
public removeScript(name: string): void

Removes the npm script (always successful).

nameRequired
  • Type: string

The name of the script.

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

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

optionsOptional
  • Type: projen.javascript.RenderWorkflowSetupOptions

Options.

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

Replaces the contents of an npm package.json script.

nameRequired
  • Type: string

The script name.

commandRequired
  • Type: string

The command to execute.

addCdkDependency 
public addCdkDependency(modules: string): void

Adds an AWS CDK module dependencies.

modulesRequired
  • Type: string

The list of modules to depend on.

Properties

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

Whether to commit the managed files by default.

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

Returns all the components within this project.

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

Project dependencies.

ejectedRequired 
public readonly ejected: boolean;
  • Type: boolean

Whether or not the project is being ejected.

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

All files in this project.

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

The .gitattributes file for this repository.

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

.gitignore.

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

Logging utilities.

nameRequired 
public readonly name: string;
  • Type: string

Project name.

outdirRequired 
public readonly outdir: string;
  • Type: string

Absolute output directory of this project.

packageTaskRequired 
public readonly packageTask: Task;
  • Type: projen.Task
postCompileTaskRequired 
public readonly postCompileTask: Task;
  • Type: projen.Task
preCompileTaskRequired 
public readonly preCompileTask: Task;
  • Type: projen.Task
projectBuildRequired 
public readonly projectBuild: ProjectBuild;
  • Type: projen.ProjectBuild

Manages the build process of the project.

projenCommandRequired 
public readonly projenCommand: string;
  • Type: string

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

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

The root project.

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

Project tasks.

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

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

Undefined if the project is being ejected.

initProjectOptional 
public readonly initProject: InitProject;
  • Type: projen.InitProject

The options used when this project is bootstrapped via projen new.

It includes the original set of options passed to the CLI and also the JSII FQN of the project type.

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

A parent project.

If undefined, this is the root project.

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

Auto approve set up for this project.

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

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

This will be undefined if devContainer boolean is false

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

Access all github components.

This will be undefined for subprojects.

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

Access for Gitpod.

This will be undefined if gitpod boolean is false

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

Access all VSCode components.

This will be undefined for subprojects.

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

The build output directory.

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

artifactsJavascriptDirectoryRequired 
public readonly artifactsJavascriptDirectory: string;
  • Type: string

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

bundlerRequired 
public readonly bundler: Bundler;
  • Type: projen.javascript.Bundler
entrypointRequired
  • Deprecated: use package.entrypoint
public readonly entrypoint: string;
  • Type: string
manifestRequired
  • Deprecated: use package.addField(x, y)
public readonly manifest: any;
  • Type: any
packageRequired 
public readonly package: NodePackage;
  • Type: projen.javascript.NodePackage

API for managing the node package.

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

The package manager to use.

runScriptCommandRequired 
public readonly runScriptCommand: string;
  • Type: string

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

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

Component that sets up mergify for merging approved pull requests.

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

The PR build GitHub workflow.

undefined if buildWorkflow is disabled.

buildWorkflowJobIdOptional 
public readonly buildWorkflowJobId: string;
  • Type: string

The job ID of the build workflow.

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

The Jest configuration (if enabled).

maxNodeVersionOptional 
public readonly maxNodeVersion: string;
  • Type: string

Maximum node version required by this pacakge.

minNodeVersionOptional 
public readonly minNodeVersion: string;
  • Type: string

Minimum node.js version required by this package.

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

The .npmignore file.

prettierOptional 
public readonly prettier: Prettier;
  • Type: projen.javascript.Prettier
publisherOptional
  • Deprecated: use release.publisher.
public readonly publisher: Publisher;
  • Type: projen.release.Publisher

Package publisher.

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

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

Release management.

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

The upgrade workflow.

docsDirectoryRequired 
public readonly docsDirectory: string;
  • Type: string
libdirRequired 
public readonly libdir: string;
  • Type: string

The directory in which compiled .js files reside.

srcdirRequired 
public readonly srcdir: string;
  • Type: string

The directory in which the .ts sources reside.

testdirRequired 
public readonly testdir: string;
  • Type: string

The directory in which tests reside.

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

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

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

The "watch" task.

docgenOptional 
public readonly docgen: boolean;
  • Type: boolean
eslintOptional 
public readonly eslint: Eslint;
  • Type: projen.javascript.Eslint
tsconfigOptional 
public readonly tsconfig: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig
tsconfigEslintOptional 
public readonly tsconfigEslint: TypescriptConfig;
  • Type: projen.javascript.TypescriptConfig
appEntrypointRequired 
public readonly appEntrypoint: string;
  • Type: string

The CDK app entrypoint.

cdkConfigRequired 
public readonly cdkConfig: CdkConfig;
  • Type: projen.awscdk.CdkConfig

cdk.json configuration.

cdkDepsRequired 
public readonly cdkDeps: AwsCdkDeps;
  • Type: projen.awscdk.AwsCdkDeps
cdkTasksRequired 
public readonly cdkTasks: CdkTasks;
  • Type: projen.awscdk.CdkTasks

Common CDK tasks.

cdkVersionRequired 
public readonly cdkVersion: string;
  • Type: string

The CDK version this app is using.

Constants

Name Type Description
DEFAULT_TASK string The name of the default task (the task executed when projen is run without arguments).
DEFAULT_TASKRequired 
public readonly DEFAULT_TASK: string;
  • Type: string

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

Normally this task should synthesize the project files.