Projen defines a standard way for building software through a fixed set of
build phases. This is implemented via a set of tasks defined in
Project base class.
build task spawns a set of sub-tasks which represent the various build phases:
default- this task is responsible to execute your projenrc and synthesize all project files.
pre-compile- runs before compilation (eg. bundle assets)
compile- compile your code (if needed)
post-compile- runs immediately after a successful compilation
test- runs tests
package- creates a distribution package
To extend the build process, components and projects can use
project.projectBuild.xxxTask and interact with the
Task object (i.e.
project.projectBuild.postCompileTask.exec("echo hi") will execute
echo hi after
buildtask is locked. This means that any attempt to extend it (i.e. call
reset, etc) will throw an exception. Instead of extending
build, just extend one of the phases. This ensures that phases are always executed in the right order.
build workflow is responsible to build your project when a pull request is
submitted against it.
Projen synthesizes files that are part of your source repository. This means
that when you change you projenrc file, and execute
projen, other files in
your repo may change as a result.
This is also relevant in other situations where your build process mutates your repository. For example, if you use snapshot testing, your repository includes snapshots which represent expected test results. When your code changes, you will likely need to update those snapshots as well.
To ensure that a pull request branch always represent the final state of the
repository, you can enable the
mutableBuild option in your project
configuration (currently only supported for projects derived from
When enabled, the PR build workflow (also called
build) will push any modified
files to the PR branch after a successful build, so that the branch will always
reflect the most up-to-date version of all generated files.
This feature does not work for forks since it is impossible to safely push changes to a fork from a PR build. If a PR is created from a fork of the repository and there are build mutations, the PR build will fail (indicating that it cannot push to the fork). To fix this, the branch needs to be updated (same behavior as if mutable builds was disabled).