Skip to content

Anni/workers build image defaults #20243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Feb 26, 2025
Merged

Anni/workers build image defaults #20243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5486d30
pnpm 10 support in workers builds release note
aninibread Feb 24, 2025
c9a66aa
Updates in skip_dependency_install and default version specification
aninibread Feb 25, 2025
a1448e8
Update src/content/docs/pages/configuration/build-configuration.mdx
aninibread Feb 25, 2025
3f47560
Update src/content/docs/pages/configuration/build-image.mdx
aninibread Feb 25, 2025
4cc0f56
Update src/content/docs/pages/configuration/build-image.mdx
aninibread Feb 25, 2025
5cf3ae9
Update src/content/docs/workers/ci-cd/builds/build-image.mdx
aninibread Feb 25, 2025
71826a9
Update src/content/docs/workers/ci-cd/builds/build-image.mdx
aninibread Feb 25, 2025
c312659
add pages changelog
aninibread Feb 26, 2025
af2b4a8
update dates
aninibread Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/content/docs/pages/configuration/build-configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ If you are not using a preset, use `exit 0` as your **Build command**.

## Environment variables

If your project makes use of environment variables to build your site, provide custom environment variables:
If your project makes use of environment variables to build your site, you can provide custom environment variables:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
Expand Down
12 changes: 11 additions & 1 deletion src/content/docs/pages/configuration/build-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,9 @@ For example, if you use Gatsby, your `package.json` should include the following

When your build starts, if not already [cached](/pages/configuration/build-caching/), version 5.13.7 of Gatsby will be installed using `npm install`.

## Overriding default versions
## Advanced Settings

### Override default versions

To override default versions of languages and tools in the build system, you can either set the desired version through environment variables or by adding files to your project.

Expand All @@ -63,6 +65,14 @@ Or, to set the version by adding a file to your project, you can:

For example, if you were previously relying on the default version of Node.js in the v1 build system, to migrate to v2, you must specify that you need Node.js `12.18.0` by setting a `NODE_VERSION = 12.18.0` environment variable or by adding a `.node-version` or `.nvmrc` file to your project with `12.18.0` added as the contents to the file.

### Skip dependency install

You can add the following environment variable to disable automatic dependency installation, and run a custom install command instead.

| Build variable | Value |
| ------------------------- | ------------- |
| `SKIP_DEPENDENCY_INSTALL` | `1` or `true` |

## V2 build system

The [v2 build system](https://blog.cloudflare.com/moderizing-cloudflare-pages-builds-toolbox/) announced in May 2023 brings several improvements to project builds.
Expand Down
49 changes: 38 additions & 11 deletions src/content/docs/workers/ci-cd/builds/build-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,39 @@ sidebar:

Workers Builds uses a build image with support for a variety of languages and tools such as Node.js, Python, PHP, Ruby, and Go.

## Supported Languages and Tools
## Supported Tooling

In the following table, review the preinstalled versions for languages and tools included in the Cloudflare Workers' build image, and the environment variables and/or files available for [overriding the preinstalled version](/workers/ci-cd/builds/build-image/#overriding-default-versions):

| Tool | Default version | Environment variable | File |
| ----------- | ---------------- | -------------------- | ---------------------------- |
| **Go** | 1.23.0 | `GO_VERSION` | |
| **Node.js** | 22 | `NODE_VERSION` | .nvmrc, .node-version |
| **Python** | 3.12.5 | `PYTHON_VERSION` | .python-version, runtime.txt |
| **Ruby** | 3.3.5 | `RUBY_VERSION` | .ruby-version |
| **Bun** | 1.1.28 | `BUN_VERSION` | |
| **Hugo** | extended_0.134.3 | `HUGO_VERSION` | |
Workers Builds supports a variety of runtimes, languages, and tools. Builds will use the default versions listed below unless a custom version is detected or specified. You can [override the default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) using environment variables or version files. All versions are available for override.

:::note[Default version updates]
The default versions will be updated regularly to the latest minor version. No major version updates will be made without notice. If you need a specific minor version, please specify it by overriding the default version.
:::

### Runtime

| Tool | Default version | Environment variable | File |
| ----------- | --------------- | -------------------- | ---------------------------- |
| **Go** | 1.23.0 | `GO_VERSION` | |
| **Node.js** | 22.9.0 | `NODE_VERSION` | .nvmrc, .node-version |
| **Python** | 3.12.5 | `PYTHON_VERSION` | .python-version, runtime.txt |
| **Ruby** | 3.3.5 | `RUBY_VERSION` | .ruby-version |

### Tools and langauges

| Tool | Default version | Environment variable |
| ----------- | ---------------- | -------------------- |
| **Bun** | 1.1.33 | `BUN_VERSION` |
| **Hugo** | extended_0.134.3 | `HUGO_VERSION` |
| **npm** | 10.8.3 | |
| **yarn** | 4.5.0 | `YARN_VERSION` |
| **pnpm** | 9.10.0 | `PNPM_VERSION` |
| **pip** | 24.2 | |
| **gem** | 3.5.19 | |
| **poetry** | 1.8.3 | |
| **pipx** | 1.7.1 | |
| **bundler** | 2.4.10 | |

## Advanced Settings

### Overriding Default Versions

Expand All @@ -37,6 +56,14 @@ Or, to set the version by adding a file to your project, you can:
1. Find the filename for the language or tool (e.g. `.nvmrc`)
2. Add the specified file name to the root directory and set the desired version number as the file's content. For example, if the version number is 22, the file should contain '22'.

### Skip dependency install

You can add the following build variable to disable automatic dependency installation and run a custom install command instead.

| Build variable | Value |
| ------------------------- | ------------- |
| `SKIP_DEPENDENCY_INSTALL` | `1` or `true` |

## Pre-installed Packages

In the following table, review the pre-installed packages in the build image. The packages are installed with `apt`, a package manager for Linux distributions.
Expand Down
4 changes: 3 additions & 1 deletion src/content/docs/workers/ci-cd/builds/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Note that when you update and save build settings, the updated settings will be

| Setting | Description |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Git account** | Select the Git account you would like to use. After the initial connection, you can continue to use this Git account for future projects. |
| **Git account** | Select the Git account you would like to use. After the initial connection, you can continue to use this Git account for future projects. |
| **Git repository** | Choose the Git repository you would like to connect your Worker to. |
| **Git branch** | Select the branch you would like Cloudflare to listen to for new commits. This will be defaulted to `main`. |
| **Build command** _(Optional)_ | Set a build command if your project requires a build step (e.g. `npm run build`). This is necessary, for example, when using a [front-end framework](/workers/ci-cd/builds/configuration/#framework-support) such as Next.js or Remix. |
Expand Down Expand Up @@ -49,6 +49,8 @@ Examples of other deploy commands you can set include:

### API token

The API token in Workers Builds defines the access granted to Workers Builds for interacting with your account's resources. Currently, only user tokens are supported, with account-owned token support coming soon.

When you select **Create new token**, a new API token will be created automatically with the following permissions:

- **Account:** Account Settings (read), Workers Scripts (edit), Workers KV Storage (edit), Workers R2 Storage (edit)
Expand Down
4 changes: 4 additions & 0 deletions src/content/release-notes/pages.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@ productLink: "/pages/"
productArea: Developer platform
productAreaLink: /workers/platform/changelog/platform/
entries:
- publish_date: "2025-02-26"
title: Support for pnpm 10 in build system
description: |-
- Pages build system now supports building projects that use **pnpm 10** as the package manager. If your build previously failed due to this unsupported version, retry your build. No config changes needed.
- publish_date: "2024-12-19"
title: Cloudflare GitHub App Permissions Update
description: |-
Expand Down
3 changes: 3 additions & 0 deletions src/content/release-notes/workers.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ productLink: "/workers/"
productArea: Developer platform
productAreaLink: /workers/platform/changelog/platform/
entries:
- publish_date: "2025-02-26"
description: |-
- [Workers Builds](/workers/ci-cd/builds/) now supports building projects that use **pnpm 10** as the package manager. If your build previously failed due to this unsupported version, retry your build. No config changes needed.
- publish_date: "2025-02-13"
description: |-
- [Smart Placement](/workers/configuration/smart-placement/) no longer runs Workers in the same location as D1 databases they are bound to. The same [placement logic](/workers/configuration/smart-placement/#understand-how-smart-placement-works) now applies to all Workers that use Smart Placement, regardless of whether they use D1 bindings.
Expand Down
Loading