Skip to content

docs: add a how-to on environment variables in React views - #6709

Merged
peholmst merged 2 commits into
mainfrom
claude/github-issue-1546-d3e3f2
Nov 19, 2026
Merged

peholmst merged 2 commits into
mainfrom
claude/github-issue-1546-d3e3f2

Conversation

@peholmst

Copy link
Copy Markdown
Member

Summary

React views read environment variables through Vite, but no page explained how that works in a Vaadin project. Two things trip people up, as in the issue:

  • Vaadin makes the frontend folder (src/main/frontend) the root of Vite, and Vite reads .env files from its root. A .env file next to pom.xml is silently ignored.
  • import.meta.env isn't typed in a Vaadin project, so the production build fails with Property 'env' does not exist on type 'ImportMeta' until the Vite client types are added.

What changed

New how-to page building-apps/react/environment-variables.adoc (Use Environment Variables), listed in the React Views section overview. It covers:

  • where the .env files go, and the VITE_ prefix
  • variables set in the environment of the build or the dev-mode application, which take precedence over the files
  • the vite-env.d.ts declaration that makes import.meta.env type-check
  • .env.development and .env.production
  • the envDir option in vite.config.ts for keeping the files in the project root
  • that the values are fixed at build time and visible in the browser, with a pointer to Spring configuration and browser-callable services for secrets and per-deployment values

Verification

Every statement was checked in a test application with a React view on 25.4.0-beta1, in both a production build (inspecting the generated bundle) and development mode (in the browser):

  • a root .env is ignored, the one in src/main/frontend is read, and unprefixed variables are left out
  • mode files take precedence over .env, and shell variables take precedence over both
  • the build fails without vite-env.d.ts and passes with it
  • envDir: import.meta.dirname makes Vite read the root .env, and Vaadin keeps the customized vite.config.ts
  • in development mode, Vite restarts when a .env file changes
  • with React views, every build runs Vite, so a changed .env always reaches the bundle

The .env location, the type error, the declaration fix and envDir behave the same on 25.3.5, hence the target/v25.3 label. Vale reports nothing with .vale-pr.ini.

Fixes #1546

🤖 Generated with Claude Code

React views read environment variables through Vite, but no page
explained how this works in a Vaadin project. Vaadin makes the frontend
folder the root of Vite, so a .env file next to pom.xml is ignored, and
import.meta.env fails the type check of the production build until the
Vite client types are added.

The new page covers where the .env files go, the VITE_ prefix,
variables set in the build environment, the vite-env.d.ts declaration,
the mode-specific files, and the envDir option for keeping the files in
the project root. It also explains that the values are fixed at build
time and visible in the browser, and points to Spring configuration and
browser-callable services for secrets and per-deployment values.

Fixes #1546

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst peholmst added the target/v25.3 Automatically cherry-pick to the v25.3 branch label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6709.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

Built from f7a9ec6

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 1 comment.

Finding
⚠️ Pointing secrets at application.properties contradicts two existing pages

The section on values that differ between deployments suggested
application.properties for secrets too, which contradicts the guidance
to keep secrets out of the project files. Link to the Configure the
Application guide, which covers passing secrets and per-environment
settings from outside the build, instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@peholmst
peholmst merged commit 25dbe65 into main Nov 19, 2026
11 checks passed
@peholmst
peholmst deleted the claude/github-issue-1546-d3e3f2 branch November 19, 2026 12:34
@vaadin-bot

Copy link
Copy Markdown
Contributor

Hi @peholmst and @peholmst, when i performed cherry-pick to this commit to v25.3, i have encountered the following issue. Can you take a look and pick it manually?
Error Message:
Error: Command failed: git cherry-pick 25dbe65
error: could not apply 25dbe65... docs: add a how-to on environment variables in React views (#6709)
hint: After resolving the conflicts, mark them with
hint: "git add/rm ", then run
hint: "git cherry-pick --continue".
hint: You can instead skip this commit with "git cherry-pick --skip".
hint: To abort and get back to the state before "git cherry-pick",
hint: run "git cherry-pick --abort".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

need to pick manually v25.3 target/v25.3 Automatically cherry-pick to the v25.3 branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how to use environment variables in Hilla

3 participants