> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# projecttoml
> Explains project.toml for Cloud Native Buildpacks, covering builder selection, include and exclude patterns, buildpack groups, and build time environment variables to make builds repeatable.
This guide explains the `project.toml` file used with Cloud Native Buildpacks. The file centralizes build configuration for an application repository: you can set the default builder image, control which files are included or excluded from the build context, declare which buildpacks should run, and specify build-time environment variables.
Below is a minimal example `project.toml`, followed by a field-by-field walkthrough.
```toml theme={null}
[project]
schema-version = "0.2"
id = "io.buildpacks.node-app"
name = "node app"
version = "1.0.0"
[io.buildpacks]
builder = "gcr.io/buildpacks/builder:google-22"
exclude = [
"node_modules",
".env",
"tests/**",
"dummyfile.txt"
]
include = []
[[io.buildpacks.group]]
uri = "bash-script-buildpack/"
[[io.buildpacks.build.env]]
name = "HELLO"
value = "WORLD"
```
Always verify the `schema-version` against the Buildpacks project configuration documentation ([https://buildpacks.io/docs/reference/config/project/](https://buildpacks.io/docs/reference/config/project/)) or your platform documentation to ensure you use the correct schema for your tooling.
Explanation of the main fields (in the order shown above):
* `[project]`
* `schema-version`: Specifies the project file schema version. Use the correct schema for your tooling and Buildpacks implementation; different pack/buildpack versions may require different schema versions. See the project configuration docs for supported versions.
* `id`: Machine-readable identifier for the project (commonly reverse-DNS style, e.g., `io.example.myapp`).
* `name`: Human-friendly application name shown in UI or logs.
* `version`: Application version (semantic versioning recommended).
* `[io.buildpacks]`
* `builder`: Default builder image for the repository (for example, `gcr.io/buildpacks/builder:google-22`). When present, `pack build` will use this builder unless you override it with `--builder`.
* `exclude`: Array of file globs to exclude from the build context (behaves like `.dockerignore`). Typical entries: `node_modules`, `.env`, test folders, or any large files you don’t want copied into the image context. By default, pack copies all files except those matching `exclude`.
* `include`: Optional array of file paths or globs to explicitly include in the build context. Use this to ensure specific files are added even if defaults or other ignore rules would omit them.
* `[[io.buildpacks.group]]`
* Lists buildpacks (or buildpack URIs) that form the buildpack group for this project. The group controls which buildpacks are considered and in which order they are applied during a build.
* `[[io.buildpacks.build.env]]`
* `name` and `value`: Define build-time environment variables. These variables are provided to buildpacks during execution and affect the build process; they are not necessarily present at runtime unless a buildpack explicitly forwards them into the launch environment.
Summary table
| Field | Purpose | Example |
| - | - | - |
| `schema-version` | Project file schema used by buildpack tooling | `0.2` |
| `id` | Machine-readable project identifier | `io.buildpacks.node-app` |
| `name` | Human-readable project name | `node app` |
| `version` | Application version | `1.0.0` |
| `builder` | Default builder image used by `pack` | `gcr.io/buildpacks/builder:google-22` |
| `exclude` | Globs to exclude from build context | `["node_modules", ".env", "tests/**"]` |
| `include` | Globs to explicitly include in build context | `[]` |
| `group` | Buildpacks (or URIs) to run | `[[io.buildpacks.group]]` with `uri = "bash-script-buildpack/"` |
| `build.env` | Build-time environment variables | `name = "HELLO"`, `value = "WORLD"` |
Common usage patterns and tips
* Use `builder` to standardize builds across CI and local development so contributors don't need to pass `--builder` every time. You can still override from the CLI: `pack build --builder `.
* Use `exclude` to shrink the build context and speed up builds—exclude node\_modules, local SQLite files, or large test assets.
* If you need to include a file that would otherwise be excluded, add it to `include`.
* Define a `group` to pin specific buildpacks or to ensure an ordered set of buildpacks executes.
* Put sensitive or runtime-only secrets in a secure secrets store (CI secrets or runtime environment) rather than `project.toml`. `[[io.buildpacks.build.env]]` is visible in the repo and is intended for non-sensitive build-time variables.
Example: building with pack
* Default builder from `project.toml`:
* `pack build my-app`
* Override builder on the command line:
* `pack build my-app --builder gcr.io/my/custom-builder:latest`
References
* [Buildpacks Project Configuration — project.toml](https://buildpacks.io/docs/reference/config/project/)
* [pack CLI — pack build](https://buildpacks.io/docs/reference/pack/pack_build/)
* [Cloud Native Buildpacks](https://buildpacks.io/)
Use `project.toml` to centralize builder selection, control the build context, declare buildpacks, and provide build-specific environment variables—reducing the need to supply repeated flags on the command line and making builds repeatable across environments.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.