# _build

The `_build` operator evaluates at build time. This allows looping over a list in a JSON file generated by another application to calculate a value at build time, or to read environment variables.

# Operator methods:

## _build.env

```
(key: string): any
(all: boolean): any
```

The `_build.env` method reads from your environment variables. The return value of `_build.env` will form part of the build output, so the [`_secret`](/_secret) operator should rather be used for reading any secrets.

#### Examples

###### Read environment from environment variables:
With the following development and production environment variables, we can use the `_build.env` method to determine which environment we are in.

`Development environment .env`
```
MY_ENVIRONMENT="development"
```
`Production environment`
```
MY_ENVIRONMENT="production"
```

```yaml
_build.env: MY_ENVIRONMENT
```

This will return "development" in the development environment and "production" in the production environment.

## _build.[operator]

The `_build` operator can be used to evaluate normal operators at build time. Note that when using an operator as a method, the `_` gets left out of the original operator. For example, when using `_and` as a method, we write `_build.and`. When using an operator which has methods itself, we can just chain the methods: `_array.map` as a method becomes `_build.array.map`.

The following operators can be used during the build:
- [_and](/_and)
- [_app](/_app)
- [_args](/_args)
- [_array](/_array)
- [_base64](/_base64)
- [_date](/_date)
- [_divide](/_divide)
- [_eq](/_eq)
- [_function](/_function)
- [_get](/_get)
- [_gt](/_gt)
- [_gte](/_gte)
- [_hash](/_hash)
- [_hmac](/_hmac)
- [_if](/_if)
- [_if_none](/_if_none)
- [_intl](/_intl)
- [_json](/_json)
- [_log](/_log)
- [_lt](/_lt)
- [_lte](/_lte)
- [_math](/_math)
- [_ne](/_ne)
- [_not](/_not)
- [_number](/_number)
- [_object](/_object)
- [_operator](/_operator)
- [_or](/_or)
- [_product](/_product)
- [_random](/_random)
- [_regex](/_regex)
- [_string](/_string)
- [_subtract](/_subtract)
- [_sum](/_sum)
- [_switch](/_switch)
- [_type](/_type)
- [_uri](/_uri)

#### Examples

###### Use the app slug as a map key at build time:
The [`_app`](/_app) operator also resolves at build time, so `_build.app: slug` can supply a key for a build-time map. Because the key must be a string when `_build.object.fromEntries` runs, the runtime `_app` form would arrive too late here.

```yaml
_build.object.fromEntries:
  - - _build.app: slug
    - enabled: true
```
Returns (when `slug` is `my-app`):
```yaml
my-app:
  enabled: true
```

###### Check environment variables to determine which url to link to:
Use the `Link` action to link to a production url if the build is a production build in Vercel (the `VERCEL_ENV` variable will be set to "production"), otherwise link to a preview url.

```yaml
id: link_to_website
type: Link
params:
  url:
    _build.if:
      test:
        _build.eq:
          - _build.env: VERCEL_ENV
          - production
      then: "https://www.productionsite.com"
      else: "https://productionsite-git-develop-org.vercel.app"
```

###### Loop over a static list at build time:
Let's say we have a static list of fruit and their sales in a file called `fruit_sales.json` which is generated by another application. We can map over this list at build time to return a list of the fruit and their total sales.

`fruit_sales.json`
```json
[
  {
    "name": "Apples",
    "sales": [
      15,
      20,
      10,
      25
    ]
  },
  {
    "name": "Bananas",
    "sales": [
      20,
      5,
      25,
      17
    ]
  },
  {
    "name": "Oranges",
    "sales": [
      21,
      12,
      31,
      40
    ]
  }
]
```
```yaml
_build.array.map:
  on:
    _ref: fruit_sales.json
  callback:
    _build.function:
      name:
        __build.args: 0.name
      total_sales:
        __build.sum:
          __build.args: 0.sales
```
Returns:
```
- name: Apples
  total_sales: 70
- name: Bananas
  total_sales: 67
- name: Oranges
  total_sales: 104
```