configuring-taubyte-build-runtime

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: configuring-taubyte-build-runtime
description: Configures the per-resource build/runtime files Taubyte runs server-side — `.taubyte/config.yaml` (image + workflow + similar metadata) and `.taubyte/build.sh` (the actual build script, where build-time environment variables also live as `export …`). Covers Go function builds (`taubyte/go-wasi:latest|v2`), website builds tailored to the actual stack (Vite `dist/`, CRA `build/`, plain static), and library builds. Use when adding/editing build scripts, declaring env vars, switching build images, or debugging "build succeeds but produces nothing" / "env var is empty in handler".
---

# Configuring Taubyte Build & Runtime

## When to use

- Adding a `.taubyte/build.sh` to a function/website/library repo for the first time
- Switching the build image (e.g. `taubyte/go-wasi:latest` → `taubyte/go-wasi:v2`)
- Declaring environment variables that the build needs to see
- A website builds but serves nothing (empty `/out`)
- A function compiles to WASM but the runtime sees an empty / wrong env value
- The build script for one stack (Vite) was copy-pasted onto another (CRA) and now the bundle output isn't found

## The two files (every Taubyte buildable resource has them)

```text
<resource>/
└── .taubyte/
    ├── config.yaml      # image + workflow metadata (NOT env vars)
    └── build.sh         # the actual build script (where env vars live)
```

Where `<resource>` is one of:

| Resource | Path |
| --- | --- |
| Function | `<project>/code/.../functions/<name>/.taubyte/` |
| Website | `<project>/websites/<repo>/.taubyte/` |
| Library | `<project>/libraries/<repo>/.taubyte/` |

## Hard rules

1. **`.taubyte/config.yaml`** is for **build metadata** (image, workflow). It is **not** a place to declare runtime env vars.
2. **`.taubyte/build.sh`** is the **only** correct place for build-time env vars. Use `export NAME=value` at the top, before the build commands.
3. **`.taubyte/build.sh` must be non-empty and executable.** An empty `build.sh` "builds successfully" while producing nothing — this is the most common silent failure.
4. **Websites must write deployable static output to `/out`.** See [building-taubyte-websites](../building-taubyte-websites/SKILL.md).
5. **Don't guess the website framework's output directory.** Vite emits `dist/`, Create React App emits `build/`, Next.js emits `.next/` (then exports), etc. Read `package.json` (`scripts.build`) to confirm before scripting.

## Function — `config.yaml` (canonical pattern)

```yaml
version: 1.00
environment:
  image: taubyte/go-wasi:latest
workflow:
  - build
```

Picking an image:

| Image | Use for |
| --- | --- |
| `taubyte/go-wasi:latest` | Default for Go serverless functions and libraries (TinyGo + WASI; handlers use `package lib` in the usual scaffold). |
| `taubyte/go-wasi:v2` | Pinned major when you need stability across CI runs (image/layout may differ from `latest`; only switch when you intend to). |

If you change the image here, **also use the same image** for any local Docker WASM verify (see [verifying-taubyte-functions](../verifying-taubyte-functions/SKILL.md)) so local and cloud builds match.

## Function — `build.sh` (canonical pattern)

```bash
#!/bin/bash

# taubyte/go-wasi:latest: non-login build environments (Dream/monkey, some Docker invocations) often lack
# go/tinygo on default PATH — export before wasm.sh or builds fail ("go: command not found", tinygo missing).
export PATH="/usr/local/go/bin:/usr/local/tinygo/bin:${PATH}"

. /utils/wasm.sh

# Build-time env vars for this resource — declare here, NOT in config.yaml:
# export API_BASE_URL="https://api.example.com"
# export FEATURE_FLAG_X=1

build "${FILENAME}"
ret=$?
echo -n $ret > /out/ret-code
exit $ret
```

What this does:

- `export PATH=...` makes **`taubyte/go-wasi:latest`** reliably find **`go`** and **`tinygo`** when the shell is not a full login environment (matches what [verifying-taubyte-functions](../verifying-taubyte-functions/SKILL.md) does i