docs(start): add Docker production setup guide for React

[kristiyan-velkov]

Summary

Adds comprehensive Docker documentation for TanStack Start React applications, covering production-ready containerization best practices.

Changes

• Add docker-production-setup.md guide with:
  • Multi-stage Dockerfile with automatic package manager detection (npm, yarn, pnpm)
  • Optimized .dockerignore for minimal build context
  • BuildKit cache mounts for faster builds
  • Docker Compose configuration examples
  • Security best practices (non-root user, slim images, secrets handling)
  • Package manager specific Dockerfile alternatives
  • Common troubleshooting scenarios
• Update config.json navigation to include the new guide

Documentation

This guide helps developers containerize their TanStack Start applications following Docker best practices.

Checklist

• Documentation follows TanStack style guidelines
• Examples are copy-paste ready
• No breaking changes

Summary by CodeRabbit

• Documentation
  • Added comprehensive Docker production setup guide covering multi-stage builds for optimized images, runtime and build-time optimizations, security best practices, cache mount configurations, environment variable management, Docker Compose integration, and detailed troubleshooting with step-by-step examples for multiple package managers.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a navigation entry for "Docker Production Setup" in the React guides section of the documentation configuration, and creates a new comprehensive guide file documenting multi-stage Docker builds, optimization strategies, security practices, and deployment patterns for TanStack Start applications.

Changes

Cohort / File(s)	Summary
Navigation Configuration docs/start/config.json	Added new navigation item "Docker Production Setup" linking to the React Docker production guide under the React Guides section
Docker Production Guide docs/start/framework/react/guide/docker-production-setup.md	New documentation file covering multi-stage Docker builds, build and runtime optimizations, caching strategies, security best practices, Dockerignore guidelines, Docker Compose integration, environment variable handling, and troubleshooting with examples for pnpm, npm, and yarn

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Clarify SEO meaning for developers #6207: Modifies the React guides navigation array in docs/start/config.json to add new documentation entries, similar navigation structure changes.

Suggested labels

documentation

Poem

🐰 A Docker guide hops into place,
With Dockerfiles set at a steady pace,
Multi-stage builds, secure and clean,
The finest production setup we've seen!
From pnpm to yarn, all paths align,
TanStack Start shall surely shine! 🐳

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a Docker production setup guide for React, which matches the primary content additions in the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In @docs/start/framework/react/guide/docker-production-setup.md:
- Line 411: Change the heading "## Package Manager Specific Dockerfiles" to use
hyphenation for the compound modifier by renaming it to "##
Package-Manager-Specific Dockerfiles" so the compound adjective correctly
modifies "Dockerfiles".
- Line 98: The fenced code block showing the .dockerignore example is missing a
language identifier; update the triple-backtick fence for that `.dockerignore`
code block to include the "gitignore" language specifier (i.e., change the
opening ``` to ```gitignore) so the block is rendered with the correct language
hint for accessibility and linting.

🧹 Nitpick comments (2)

docs/start/framework/react/guide/docker-production-setup.md (2)

426-426: Consider pinning pnpm to a specific version for reproducibility.

Using pnpm@latest can lead to non-reproducible builds if pnpm releases a new version between builds. Consider specifying a version like pnpm@9.15.0.

♻️ Proposed change

-RUN corepack enable && corepack prepare pnpm@latest --activate
+RUN corepack enable && corepack prepare pnpm@9.15.0 --activate

---

417-536: Consider adding BuildKit cache mounts to package-specific Dockerfiles.

The main Dockerfile emphasizes that BuildKit cache mounts can reduce build times by 50-80%. The simplified package-specific Dockerfiles omit these optimizations. While this keeps the examples simpler, consider adding at least a note mentioning that cache mounts can be added for better performance, referencing the main Dockerfile example.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7cd1f82 and 6175eaf.

📒 Files selected for processing (2)

• docs/start/config.json
• docs/start/framework/react/guide/docker-production-setup.md

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

Use relative links to docs/ folder format (e.g., ./guide/data-loading) for internal documentation references

Files:

• docs/start/framework/react/guide/docker-production-setup.md

🪛 LanguageTool

docs/start/framework/react/guide/docker-production-setup.md

[grammar] ~411-~411: Use a hyphen to join words.
Context: ...r .gitignore file. ## Package Manager Specific Dockerfiles The main Dockerfil...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

docs/start/framework/react/guide/docker-production-setup.md

98-98: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (5)

docs/start/config.json (1)

144-147: LGTM! Navigation entry correctly placed.

The new navigation entry follows the existing pattern and is logically positioned after "Hosting" in the guides section.

docs/start/framework/react/guide/docker-production-setup.md (4)

1-17: LGTM! Clear prerequisites and helpful getting-started guidance.

The frontmatter and prerequisites section provides appropriate external references and sets clear expectations for readers.

---

248-325: Excellent explanatory content with accurate Docker best practices.

The documentation effectively explains multi-stage builds, layer caching, BuildKit cache mounts, and security considerations. The educational approach helps readers understand not just what to do but why.

---

326-410: LGTM! Comprehensive Docker Compose guidance with proper security practices.

The Docker Compose section provides practical examples and correctly emphasizes secrets management best practices with appropriate warnings.

---

538-600: LGTM! Practical troubleshooting guidance with actionable solutions.

The troubleshooting section addresses common deployment issues with clear diagnostic steps and solutions. The example repository link provides additional hands-on resources.

[schiller-manuel]

not sure we should add this. does this cover anything specific about Start? looks like any doc about how to run a nodejs app in docker would cover this?

[kristiyan-velkov]

Thank you for the comment @schiller-manuel . Short answer is -> Not exactly. This is not a generic Node.js-in-Docker guide.

Take a look the official documentation about Node.js as a reference.

TanStack Start has its own specifics, and this documentation addresses those directly:

• The Dockerfile includes Start-specific build and runtime logic.
• The .dockerignore is tailored to TanStack Start’s structure and output.
• The setup reflects how Start actually runs in production, not a vanilla Node.js app.

Yes, you can run a Node.js app with generic docs—but that’s like saying any JS framework is the same. It isn’t.
Having official, Start-specific documentation removes guesswork, prevents wrong assumptions, and saves time for people adopting TanStack Start.

This will be useful, especially for developers who want a clear, correct, and repeatable Docker setup instead of piecing things together from generic Node.js examples. Also this guide is following the best practices of writing Docker files.

[kristiyan-velkov]

Thanks for the discussion @schiller-manuel. By the way, did you notice the update I shared about this roughly a week ago? I addressed some of these points there as well—happy to clarify further if needed.