Avoiding Accidental Public Exposure of Files in Gatsby's Static Directory

Direct Answer

Gatsby does not provide a documented, supported, or experimental configuration to prevent specific files in static from being copied to public. The static folder is a public asset bucket by design. During gatsby build, its contents are copied verbatim into public, preserving relative paths. A file at static/foo.txt is served at /foo.txt on the deployed site.

Confirmed Facts vs. Likely Explanation

Confirmed: The copy step is part of Gatsby's core build pipeline. Environment variables influence rendering and page generation, but they do not alter the static-to-public copy. Plugins that read from static (such as image transformers) emit outputs into public as well.

Likely explanation: Because the copy is hard-coded into the build pipeline, there is no per-file privacy intent to express. Any behavior that skips copying specific files would be unsupported and could break across Gatsby versions or plugin combinations. Treat such behavior as unavailable until it appears in official documentation or changelogs.

What About Future Releases?

There is no verified information that an upcoming Gatsby release will introduce a privacy flag for static assets. Do not architect around a future option. If you need to confirm the status for your exact version, check the official Gatsby release notes and GitHub issues for your installed version.

Best-Practice Patterns

1. Keep confidential data out of static and out of the repository. Secrets, private documents, and internal data should not be committed or baked into the build image.
2. Use authenticated storage or an API. Serve confidential files from private object storage or a backend endpoint that enforces authentication and authorization. Use short-lived signed URLs if direct access is required.
3. Fetch private inputs at build time. If a confidential file is needed only to generate derived public assets, fetch it during the build using build-time credentials (for example, via a source plugin or a pre-build script). Write only the derived, public-safe output to static or public.
4. Add a CI guard. Scan static and public for deny-listed paths or extensions and fail the build if a match is found. This catches accidental commits and plugin-generated leaks.

Practical Verification

You can verify exposure and enforce the guard with scoped commands:

# After a clean build, check whether a sensitive filename leaked into public
ls public/foo.txt

# Or scan for deny-listed patterns (example: .env, private keys, internal docs)
grep -rE '\.(env|pem|key)$|internal' public/ --include='*' -l

# Example CI assertion (fail if forbidden paths exist in static or public)
if find static public -type f \( -name '*.env' -o -name '*.pem' \) | grep -q .; then
  echo "Forbidden file detected in static or public"; exit 1
fi

Also test the replacement path end to end: an unauthenticated request to the confidential resource must be rejected, and an authenticated request must return only authorized content.

Version Note

Exact copy behavior and plugin outputs can vary by Gatsby version and plugin set. The guidance above assumes a standard Gatsby build where static is copied to public. Verify against your installed version if you observe different behavior.