Locals Block

The locals block allows defining computed values for a specific project. Project locals can reference workspace variables, workspace locals, and predefined variables.

Scope: Project locals are only available within the PROJECT file where they are defined. They cannot override workspace locals with the same name (this is an error).

Usage

Project locals are referenced using the local.<identifier> syntax. They can reference:

• Workspace variables: var.config
• Workspace locals: local.registry (from WORKSPACE)
• Predefined variables: terrabuild.project
• Other project locals: local.other_local
• Functions and expressions

Example Usage

Simple Project Local

locals {
  app_name = "api"
  project_path = "src/apps/api"
}

Using Workspace Values

# In WORKSPACE:
locals {
  registry = "ghcr.io/myorg"
}

# In PROJECT:
locals {
  app_name = "api"
  # Reference workspace local
  full_image = local.registry + "/" + local.app_name
}

Complex Project-Specific Computations

# In WORKSPACE:
variable environment {
  default = "dev"
}
locals {
  registry = "ghcr.io/myorg"
  base_tag = var.environment + "-" + terrabuild.branch_or_tag
}

# In PROJECT:
locals {
  app_name = "api"
  # Combine workspace locals with project-specific values
  image_name = local.registry + "/" + local.app_name
  image_tag = local.base_tag
  full_image = local.image_name + ":" + local.image_tag
  
  # Use in extension defaults
  docker_args = {
    image: local.full_image
    platform: "linux/amd64"
  }
}

extension @docker {
  defaults = local.docker_args
}

Using in Targets

locals {
  app_name = "api"
  output_dir = "dist/" + local.app_name
}

target build {
  @dotnet build {
    output = local.output_dir
  }
}

Important Notes

• Cannot override workspace locals: If a workspace defines local.registry, a project cannot define a local.registry with a different value. This will cause an error.
• Scope isolation: Project locals are only visible within the PROJECT file. Other projects cannot access them.
• Multiple blocks: You can define multiple locals blocks in the same PROJECT file, as long as identifiers are unique.