From 23f231fdfdb421a0ff8fc3c0699477144635f70a Mon Sep 17 00:00:00 2001
From: Anthony Shew <anthony.shew@vercel.com>
Date: Fri, 26 Jan 2024 11:38:18 -0700
Subject: [PATCH] Document handling of Node.js versions, OS, and arch. (#7072)

### Description

While we may consider OS and arch handling as a feature in the future,
we don't today. Here, we're documenting how to handle this advanced use
case as well as jotting down a proper way of handling Node.js versions.

Closes https://github.com/vercel/turbo/issues/4124 and
https://github.com/vercel/turbo/issues/1315

---------

Co-authored-by: Nicholas Yang <nicholas.yang@vercel.com>
---
 .../pages/repo/docs/core-concepts/caching.mdx | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/docs/pages/repo/docs/core-concepts/caching.mdx b/docs/pages/repo/docs/core-concepts/caching.mdx
index df638ed26d4bb..59a3ac82e9b37 100644
--- a/docs/pages/repo/docs/core-concepts/caching.mdx
+++ b/docs/pages/repo/docs/core-concepts/caching.mdx
@@ -83,6 +83,85 @@ turbo run build --force
 
 Note that `--force` disables cache reads but does not disable cache writes. If you want to disable cache writes, use the `--no-cache` flag.
 
+## Handling Node.js versions
+
+To account for Node.js versions, use [the `engines` key in package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines). Turborepo will see the changes to your `package.json` and miss cache when the field is updated.
+
+## Handling platforms and other arbitrary hash contributors
+
+For advanced use cases, you may want the operating system (OS), architecture, or other external factors to contribute to your hash. You can do this in four quick steps.
+
+### 1. Write an arbitrary file to disk
+
+First, create a script that accounts for the hash contributors that you are interested in. For example, here is a Node.js script that looks at platform and architecture and writes those details to a file (`turbo-cache-key.json`):
+
+```js
+#!/usr/bin/env node
+
+const { writeFileSync } = require('fs');
+const { join } = require('path');
+
+const { platform, arch } = process;
+const file = "turbo-cache-key.json";
+const str = JSON.stringify({ platform, arch });
+console.log(`Generating cache key: ${str}`);
+writeFileSync(file, str);
+```
+
+### 2. Add the file to your .gitignore
+
+You won't want to commit this file to source control since it's dependent on environment. Add it to your `.gitignore`:
+
+```txt
+// .gitignore
+
++ turbo-cache-key.json
+```
+
+### 3. Add the file to the hash
+
+Now, make sure that `turbo` is aware of the file by adding it to task inputs. You can do this two ways:
+
+- **For specific tasks**: Include the file in [the `inputs` array](/repo/docs/reference/configuration#inputs) of the task(s):
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipelines": {
+    "build-for-platforms": {
+      "dependsOn": ["^build"],
+      "inputs": ["turbo-cache-key.json", ...]
+    }
+  }
+}
+```
+
+- **For all tasks**: Add the file to [`globalDependencies`](/repo/docs/reference/configuration#globaldependencies)
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": ["turbo-cache-key.json"],
+  "pipelines": {
+    ...
+  }
+}
+```
+
+### 4. Generate the file before running `turbo`
+
+Last, you'll want to ensure that you run the script before running `turbo`. For example:
+
+```json
+{
+  "scripts": {
+    "build-for-platforms": "node ./scripts/create-turbo-cache-key.js && turbo run build"
+  }
+}
+```
+
+`turbo run build` will now take into account the contents of `turbo-cache-key.json` when calculating the hash for the `build` task.
+
 ## Logs
 
 Not only does `turbo` cache the output of your tasks, it also records the terminal output (i.e. combined `stdout` and `stderr`) to (`<package>/.turbo/run-<command>.log`). When `turbo` encounters a cached task, it will replay the output as if it happened again, but instantly, with the package name slightly dimmed.