Providing a cache key when custom transformers use external inputs

Raised by @cancit in a Tweet.

Do you want to request a feature or report a bug?
Feature/docs

What is the current behavior?
When using custom plugins (like babel-plugin-transform-inline-environment-variables) outside factors may influence the build, which breaks transform cache invalidation.

What is the expected behavior?
We probably can't do anything automatically for arbitrary plugins, but at the very least there should be a documented way to tell the transform cache about outside factors. We have cacheVersion, but it's not well documented ("There is generally no need to set this explicitly") and feels surprising.

A way to explicitly specify/allowlist environment variables in particular (like we do with Buck) might be worthwhile, since that's likely to be the most common outside factor.

Workaround

// metro.config.js
module.exports = {
  cacheVersion: [process.env.VAR_ONE, process.env.VAR_TWO].join('-') // Hash this if the values aren't safe for a file name
  // ...
}

Start by reading Metro's cacheVersion configuration and transform-cache documentation, then trace how custom transformer inputs and environment variables affect invalidation. Define the supported way to provide external inputs, including whether an environment-variable allowlist is in scope; done means the behavior and configuration are documented and covered by relevant tests.