From bb1da8d8fa65b9ee0b09be724b617793c919df5f Mon Sep 17 00:00:00 2001 From: mikhail Date: Mon, 21 Sep 2026 11:49:01 +0300 Subject: [PATCH 1/3] docs: index.html is generated into frontend/generated again A project index.html is optional: the default is written to frontend/generated/ and a frontend/index.html only overrides it. The pages still placed the generated file in frontend/ and in target/. Co-Authored-By: Claude Opus 5 (1M context) --- articles/flow/advanced/modifying-the-bootstrap-page.adoc | 8 ++++---- articles/flow/configuration/source-control.adoc | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/articles/flow/advanced/modifying-the-bootstrap-page.adoc b/articles/flow/advanced/modifying-the-bootstrap-page.adoc index c25579992f..d2bcb7d672 100644 --- a/articles/flow/advanced/modifying-the-bootstrap-page.adoc +++ b/articles/flow/advanced/modifying-the-bootstrap-page.adoc @@ -18,17 +18,17 @@ The _Application Shell_ in Vaadin Flow is also known as the _Bootstrap Page_, or The developer has full control of the contents of [filename]`index.html`. You can modify it in various ways. -On the client side, you can edit [filename]`frontend/index.html` when the content is static, for instance the `` tag. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. +On the client side, you can add an [filename]`index.html` of your own to the [filename]`frontend` folder and edit it when the content is static, for instance the `` tag. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. You can implement [interfacename]`AppShellConfigurator` for cases covered by the [classname]`AppShellSettings` API, or by annotations. And you can configure an [interfacename]`IndexHtmlRequestListener` for advanced cases to modify the document structure. == Application Shell Template -The Vaadin servlet uses the [filename]`frontend/index.html` file as a template to generate the bootstrap page response. The servlet processes the template and injects the following information: +The Vaadin servlet uses an [filename]`index.html` file as a template to generate the bootstrap page response: the one in the [filename]`frontend` folder where the project has one, and the generated default otherwise. The servlet processes the template and injects the following information: - ``: Vaadin calculates the relative path from the current request path to the root path of the application. This is required for relative links in view templates to work correctly. -- Bundled script: Vaadin automatically adds the bundled and optimized script generated from the [filename]`frontend/index.tsx` file. It uses a pre-configured https://vitejs.dev/[Vite] instance that's included with `vaadin-maven-plugin` as a module bundler. Therefore, the [filename]`frontend/index.html` template doesn't need to include explicitly the [filename]`index.tsx` script -- or the [filename]`index.ts` or [filename]`index.js` script. +- Bundled script: Vaadin automatically adds the bundled and optimized script generated from the [filename]`frontend/index.tsx` file. It uses a pre-configured https://vitejs.dev/[Vite] instance that's included with `vaadin-maven-plugin` as a module bundler. Therefore, the [filename]`index.html` template doesn't need to include explicitly the [filename]`index.tsx` script -- or the [filename]`index.ts` or [filename]`index.js` script. [TIP] The `frontend` directory path can be changed with the `frontendDirectory` parameter of `vaadin-maven-plugin`, which the `prepare-frontend` and `build-frontend` goals use. The build records the path so that the application can read it at runtime from the `vaadin.frontend.folder` property. See <<{articles}/flow/configuration/maven#properties, Plugin Configuration Options>> for details. @@ -36,7 +36,7 @@ The `frontend` directory path can be changed with the `frontendDirectory` parame === Default Template & Entry Point [[default-bootstrap-template-and-entry-point]] -If the [filename]`index.html` or [filename]`index.tsx` files in the frontend folder are missing, `vaadin-maven-plugin` generates a default corresponding file in the [filename]`target` folder. In that case, the application uses only server-side routing. You can take control of these files by moving them into the [filename]`frontend` folder. By default, these files look similar to the following: +Where the [filename]`index.html` or [filename]`index.tsx` file is missing from the frontend folder, the build [since:com.vaadin:vaadin@V25.3]#generates a default into [filename]`frontend/generated/`#, so neither file has to exist in the project. Without an [filename]`index.tsx`, the application uses only server-side routing. To take control of one of these files, copy it from [filename]`frontend/generated/` into the [filename]`frontend` folder, where it replaces the generated default. By default, these files look similar to the following: .Default `index.html` [source,html] diff --git a/articles/flow/configuration/source-control.adoc b/articles/flow/configuration/source-control.adoc index fe65ef1b8f..76a2ad39dd 100644 --- a/articles/flow/configuration/source-control.adoc +++ b/articles/flow/configuration/source-control.adoc @@ -41,7 +41,7 @@ vite.generated.ts <16> <4> Compressed archive containing development time frontend files/resources. <5> Compressed archive containing production time frontend files/resources. <6> Frontend resources, like TypeScript and JavaScript files, are placed in this folder. -<7> [filename]`index.html` is an initially auto-generated file that defines the outermost structure of the application. This file can be added to source control, and should be if customized. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>. +<7> [filename]`index.html` defines the outermost structure of the application. A project doesn't need one of its own: Vaadin generates a default into [filename]`frontend/generated/`, which stays out of source control. Add an [filename]`index.html` to the [filename]`frontend` folder only to customize the application shell. It then replaces the generated default and should be committed. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>. <8> Static web resources such as images and stylesheets are placed in this folder. <9> Test sources. <10> [filename]`package.json` defines the version ranges of the frontend dependencies. @@ -64,7 +64,7 @@ The following files and folders should be added to source control: * <2> [filename]`src/main/` - Application sources * <3> <4> <5> [filename]`bundles/` - Pre-compiled frontend bundles * <6> [filename]`frontend/` - Frontend resources (excluding `generated/`) -* <7> [filename]`index.html` - Can be committed if generated, should be if customized +* <7> [filename]`index.html` - Only when the project has one of its own * <8> [filename]`META-INF/resources/` - Static web resources * <9> [filename]`src/test/` - Test sources * <10> [filename]`package.json` - If exists From 2b99f5b1e14cbde8fba0493af6536f9cebfc9576 Mon Sep 17 00:00:00 2001 From: "totally-not-ai[bot]" <290682512+totally-not-ai[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 11:55:06 +0000 Subject: [PATCH 2/3] docs: tell readers to copy the generated index.html A project index.html should start from the generated default in frontend/generated/ rather than be written from scratch. Co-Authored-By: Claude Opus 5 (1M context) --- articles/flow/advanced/modifying-the-bootstrap-page.adoc | 2 +- articles/flow/configuration/source-control.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/flow/advanced/modifying-the-bootstrap-page.adoc b/articles/flow/advanced/modifying-the-bootstrap-page.adoc index d2bcb7d672..b9767e3fc3 100644 --- a/articles/flow/advanced/modifying-the-bootstrap-page.adoc +++ b/articles/flow/advanced/modifying-the-bootstrap-page.adoc @@ -18,7 +18,7 @@ The _Application Shell_ in Vaadin Flow is also known as the _Bootstrap Page_, or The developer has full control of the contents of [filename]`index.html`. You can modify it in various ways. -On the client side, you can add an [filename]`index.html` of your own to the [filename]`frontend` folder and edit it when the content is static, for instance the `` tag. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. +On the client side, you can take control of [filename]`index.html` when the content is static, for instance the `` tag. Rather than writing one from scratch, copy the generated [filename]`frontend/generated/index.html` into the [filename]`frontend` folder and edit it there. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. You can implement [interfacename]`AppShellConfigurator` for cases covered by the [classname]`AppShellSettings` API, or by annotations. And you can configure an [interfacename]`IndexHtmlRequestListener` for advanced cases to modify the document structure. diff --git a/articles/flow/configuration/source-control.adoc b/articles/flow/configuration/source-control.adoc index 76a2ad39dd..706890a384 100644 --- a/articles/flow/configuration/source-control.adoc +++ b/articles/flow/configuration/source-control.adoc @@ -41,7 +41,7 @@ vite.generated.ts <16> <4> Compressed archive containing development time frontend files/resources. <5> Compressed archive containing production time frontend files/resources. <6> Frontend resources, like TypeScript and JavaScript files, are placed in this folder. -<7> [filename]`index.html` defines the outermost structure of the application. A project doesn't need one of its own: Vaadin generates a default into [filename]`frontend/generated/`, which stays out of source control. Add an [filename]`index.html` to the [filename]`frontend` folder only to customize the application shell. It then replaces the generated default and should be committed. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>. +<7> [filename]`index.html` defines the outermost structure of the application. A project doesn't need one of its own: Vaadin generates a default into [filename]`frontend/generated/`, which stays out of source control. To customize the application shell, copy the generated file into the [filename]`frontend` folder. It then replaces the generated default and should be committed. For customization of index.html see <<../advanced/modifying-the-bootstrap-page#modifying-the-application-shell, Modifying the Application Shell>>. <8> Static web resources such as images and stylesheets are placed in this folder. <9> Test sources. <10> [filename]`package.json` defines the version ranges of the frontend dependencies. From 6a56275967e9d7a706a8d804a7b7b853af866e33 Mon Sep 17 00:00:00 2001 From: "totally-not-ai[bot]" <290682512+totally-not-ai[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 12:03:18 +0000 Subject: [PATCH 3/3] docs: scope the 25.3 index.html change and cover the upgrade The frontend/generated/ location is new only for index.html; index.tsx was already generated there. Upgraded projects keep a committed frontend/index.html that shadows the generated default. Co-Authored-By: Claude Opus 5 (1M context) --- articles/flow/advanced/modifying-the-bootstrap-page.adoc | 4 ++-- articles/flow/configuration/source-control.adoc | 4 ++-- articles/upgrading/index.adoc | 6 ++++++ 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/articles/flow/advanced/modifying-the-bootstrap-page.adoc b/articles/flow/advanced/modifying-the-bootstrap-page.adoc index b9767e3fc3..72ea1d90c8 100644 --- a/articles/flow/advanced/modifying-the-bootstrap-page.adoc +++ b/articles/flow/advanced/modifying-the-bootstrap-page.adoc @@ -18,7 +18,7 @@ The _Application Shell_ in Vaadin Flow is also known as the _Bootstrap Page_, or The developer has full control of the contents of [filename]`index.html`. You can modify it in various ways. -On the client side, you can take control of [filename]`index.html` when the content is static, for instance the `` tag. Rather than writing one from scratch, copy the generated [filename]`frontend/generated/index.html` into the [filename]`frontend` folder and edit it there. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. +On the client side, you can take control of [filename]`index.html` when the content is static, for instance the `` tag. Copy the generated file into the [filename]`frontend` folder rather than writing one from scratch, as described in <>. On the server side, you can make changes that require dynamic server content, or when Java syntax is preferred. An example of would be making the application installable by enabling the `@PWA` built-in feature. You can implement [interfacename]`AppShellConfigurator` for cases covered by the [classname]`AppShellSettings` API, or by annotations. And you can configure an [interfacename]`IndexHtmlRequestListener` for advanced cases to modify the document structure. @@ -36,7 +36,7 @@ The `frontend` directory path can be changed with the `frontendDirectory` parame === Default Template & Entry Point [[default-bootstrap-template-and-entry-point]] -Where the [filename]`index.html` or [filename]`index.tsx` file is missing from the frontend folder, the build [since:com.vaadin:vaadin@V25.3]#generates a default into [filename]`frontend/generated/`#, so neither file has to exist in the project. Without an [filename]`index.tsx`, the application uses only server-side routing. To take control of one of these files, copy it from [filename]`frontend/generated/` into the [filename]`frontend` folder, where it replaces the generated default. By default, these files look similar to the following: +Where the [filename]`index.html` or [filename]`index.tsx` file is missing from the frontend folder, the build generates a default into [filename]`frontend/generated/`, so neither file has to exist in the project. For [filename]`index.html`, that location is [since:com.vaadin:vaadin@V25.3]#new in Vaadin 25.3#: earlier versions generated the file into the [filename]`frontend` folder itself. Without an [filename]`index.tsx`, the application uses only server-side routing. To take control of one of these files, copy it from [filename]`frontend/generated/` into the [filename]`frontend` folder, where it replaces the generated default. By default, these files look similar to the following: .Default `index.html` [source,html] diff --git a/articles/flow/configuration/source-control.adoc b/articles/flow/configuration/source-control.adoc index 706890a384..90ab4a88dc 100644 --- a/articles/flow/configuration/source-control.adoc +++ b/articles/flow/configuration/source-control.adoc @@ -19,8 +19,8 @@ src/ │ │ ├── dev.bundle <4> │ │ └── prod.bundle <5> │ ├── frontend/ <6> -│ │ ├── generated/ -│ │ └── index.html <7> +│ │ └── generated/ +│ │ └── index.html <7> │ ├── java/ │ └── resources/ │ └── META-INF/ diff --git a/articles/upgrading/index.adoc b/articles/upgrading/index.adoc index 2b377f12e6..a5b611d11a 100644 --- a/articles/upgrading/index.adoc +++ b/articles/upgrading/index.adoc @@ -222,6 +222,12 @@ Update any build step that reads the bundle straight from the build directory -- Starting with Vaadin 25.2, npm package versions published less than one day ago are ignored when frontend dependencies are installed, as a protection against supply-chain attacks. If your project depends on a package version that was published less than a day ago, the installation fails or resolves to an older version until the package version is old enough. The minimum age is configured with the `vaadin.npm.minimumFrontendPackageAgeDays` system property; setting it to `0` disables the check. See <<{articles}/flow/configuration/development-mode/npm-pnpm-bun#delayed-package-installation, Delayed Installation of Recently Published Packages>> for details. +=== Default `index.html` Generated Into `frontend/generated/` + +Starting with Vaadin 25.3, the build writes the default [filename]`index.html` to [filename]`frontend/generated/` rather than to the [filename]`frontend` folder, and generates it only when the project has no [filename]`frontend/index.html` of its own. + +A project upgraded from an earlier version usually has an [filename]`index.html` in [filename]`frontend`, auto-generated there by the older build and committed to source control. That file still takes precedence, so an uncustomized copy keeps shadowing the default and the application doesn't pick up later improvements to it. Compare the file against the default; if it hasn't been customized, delete it and let the build generate it. Keep it only for customizations of the application shell. See <<{articles}/flow/advanced/modifying-the-bootstrap-page#default-bootstrap-template-and-entry-point, Default Template & Entry Point>> for details. + == Development Tools Development tools are opt-in feature in Vaadin 25. `vaadin-dev` module isn't included transitively by default anymore via `vaadin` or `vaadin-core` or any other Vaadin dependencies. To include it, add following dependency to your build configuration: