diff --git a/.github/styles/Vocab/Docs/accept.txt b/.github/styles/Vocab/Docs/accept.txt index 008936a9cf..521272f5aa 100644 --- a/.github/styles/Vocab/Docs/accept.txt +++ b/.github/styles/Vocab/Docs/accept.txt @@ -18,6 +18,7 @@ Azure Brotli [bB]rowsable [bB]rowser-less +bun [bB]undlers? [cC]acheable classpath @@ -89,6 +90,7 @@ Liferay Liquibase Lit LitElement +lockfile Logback Lumo macOS diff --git a/articles/configuration/development-mode/index.asciidoc b/articles/configuration/development-mode/index.adoc similarity index 88% rename from articles/configuration/development-mode/index.asciidoc rename to articles/configuration/development-mode/index.adoc index df6df7fd8c..ed4c3004a3 100644 --- a/articles/configuration/development-mode/index.asciidoc +++ b/articles/configuration/development-mode/index.adoc @@ -27,11 +27,11 @@ When running with the frontend development server, JavaScript and CSS and other [role="since:com.vaadin:vaadin@V24"] == Faster Starts by Pre-Compiling -The build and start-up time can be decreased significantly if no frontend installation or compilation is made. This means not installing the tools Node.js, npm/pnpm. It also means not downloading npm packages, or running the Vite development server. +The build and start-up time can be decreased significantly if no frontend installation or compilation is made. This means not installing the tools Node.js, npm/pnpm/bun. It also means not having to download npm packages, or running the Vite development server. -If your project uses only the standard Vaadin Flow components or third-party Vaadin add-ons (e.g., from Vaadin Directory) without client code, Vaadin skips frontend compilation and uses the default themes and frontend files shipped with the Vaadin platform. +If your project uses only the standard Vaadin Flow components or third-party Vaadin add-ons (e.g., from the Vaadin Directory) without client code, Vaadin skips frontend compilation and uses the default themes and frontend files shipped with the Vaadin platform. -Adding any custom JavaScript/TypeScript or add-ons with frontend customizations to a project can trigger the frontend re-compilation using Vite during the next start-up of the application. Any new or missing frontend packages are downloaded using npm/pnpm before building. Vaadin automatically does this, and spots the frontend customizations. +Adding any custom JavaScript/TypeScript or add-ons with frontend customizations to a project can trigger the frontend re-compilation using Vite the next time the application is started. Any new or missing frontend packages are downloaded using npm/pnpm/bun before building. Vaadin does this automatically, and spots the frontend customizations. Making a new frontend bundle takes time. However, the generated frontend files are compressed to the `src/main/bundles/prod.bundle` file inside the project’s root. This file can be added to the Version Control System, which allows other developers to fetch the application bundle and thereby run it. @@ -41,7 +41,7 @@ The application bundle is the same as the default bundle, but it's made for a sp Vaadin generates an application bundle in the following situations: -- An npm/pnpm package is added with `@NpmPackage`, or directly into [filename]`package.json`; +- An npm package is added with `@NpmPackage`, or directly into [filename]`package.json`; - CSS or JavaScript is added with `@CssImport`, `@JsModule`, or `@JavaScript`; - Vaadin add-on with frontend customizations is added; - Custom theme packaged as a `JAR` dependency is added, if it defines any assets to be added to the project; or @@ -65,7 +65,7 @@ When working with a frontend heavy project, there can be a frontend development Vaadin uses Vite to quicken frontend development by enabling the client-side live reload. By doing this, JavaScript/TypeScript changes are updated immediately in the browser. Vite only re-compiles what has changed, making hot reloads fast. -Vite installation is made through npm/pnpm. Running Vite requires Node.js. See <<{articles}/configuration/development-mode/node-js#,Node.js installation>> and <<{articles}/configuration/development-mode/npm-pnpm#,Configuring frontend package manager>> for more information. +Vite installation is made through npm/pnpm/bun. Running Vite requires Node.js. See <<{articles}/configuration/development-mode/node-js#,Node.js installation>> and <<{articles}/configuration/development-mode/npm-pnpm-bun#,Configuring frontend package manager>> for more information. This mode is recommended if components or views use <<{articles}/create-ui/templates#,Templates>> and are edited often. This mode is used when the configuration parameter `frontend.hotdeploy` is set to `true` (see <<{articles}/configuration/properties#,Configuration Properties>> for more information). diff --git a/articles/configuration/development-mode/npm-pnpm-bun.adoc b/articles/configuration/development-mode/npm-pnpm-bun.adoc new file mode 100644 index 0000000000..702c485b8d --- /dev/null +++ b/articles/configuration/development-mode/npm-pnpm-bun.adoc @@ -0,0 +1,183 @@ +--- +title: npm/pnpm/bun +description: Configuring the frontend package manager. +order: 20 +--- + + += Configuring npm/pnpm/bun + +https://docs.npmjs.com/cli/v8/commands/npm[npm] is the recommended and default package manager for Vaadin projects. This page explains how to configure npm and how to change to an alternative package manager (i.e., pnpm or bun). + + +== Install a Custom Package + +To install a custom frontend package into your project with `npm`, run `npm i xxx`. For example, to add the `mobx` package as a dependency in [filename]`package.json` as well as install it into `node_modules`, run the following command in the project directory: + +[source,terminal] +---- +npm i mobx +---- + +[NOTE] +Vaadin expects transitive platform dependencies to be available directly under `node_modules`. +Vaadin uses the `npm` https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides[overrides feature] (since `npm` 8.3.0) to lock the transitive platform dependencies versions. + + +== Switch Among npm, pnpm & bun + +`npm` is used as the default frontend package manager. Vaadin also supports using https://pnpm.io[_pnpm_] (also known as, _performant npm_). To switch to `pnpm`, you can set the `vaadin.pnpm.enable` system property to `true`. + +When using `pnpm`, the framework installs it locally using `npm` if it isn't installed globally. The [filename]`package-lock.json` file that's used by `npm` is incompatible with `pnpm` and is removed automatically if `pnpm` is used. `pnpm` uses the [filename]`pnpm-lock.yaml` file instead of [filename]`package-lock.json`. Any custom dependency configurations should go to [filename]`pnpm-lock.yaml`. + +Using https://bun.sh[_bun_] is also supported by Vaadin. With bun, packages are cached locally by default and linked -- instead of downloaded -- for every project. This results in reduced disk space usage, and faster recurring builds compared to npm. To switch to `bun`, you can set the `vaadin.bun.enable` system property to `true`. + +When using bun, a https://bun.sh/docs/install/lockfile[_binary lockfile_] named [filename]`bun.lockb` is used when `bun install` is run. This lockfile is not included in or used from Vaadin development bundle. + +[NOTE] +Vaadin does not support automatic installation of bun - instead please follow the https://bun.sh/package-manager[_installation instructions_]. + + +=== Switching in a Spring Boot Project + +For a Spring Boot-based project, you can add `vaadin.pnpm.enable = true` or `vaadin.bun.enable = true` to the [filename]`application.properties` file. + + +=== Switching in a Plain Java or JavaEE Project + +For a plain Java or a JavaEE-based project, you can set the `pnpmEnable` or `bunEnable` configuration property inside the `vaadin-maven-plugin`. + +.Enable pnpm (plain Java / JavaEE) +[source,xml] +---- + + com.vaadin + vaadin-maven-plugin + ${project.version} + + + + prepare-frontend + + + + + true + + +---- + +.Enable bun (plain Java / JavaEE) +[source,xml] +---- + + com.vaadin + vaadin-maven-plugin + ${project.version} + + + + prepare-frontend + + + + + true + + +---- + +Alternatively, you can use the Servlet 3.0 `@WebServlet` annotation: + +.Enable pnpm (via annotation) +[source,java] +---- +@WebServlet(urlPatterns = "/*", name = "myservlet", asyncSupported = true, loadOnStartup = 1, + initParams = { @WebInitParam(name = "pnpm.enable", value = "true") }) +public class CustomServlet extends VaadinServlet { +} +---- + +.Enable bun (via annotation) +[source,java] +---- +@WebServlet(urlPatterns = "/*", name = "myservlet", asyncSupported = true, loadOnStartup = 1, + initParams = { @WebInitParam(name = "bun.enable", value = "true") }) +public class CustomServlet extends VaadinServlet { +} +---- + +or use the traditional [filename]`web.xml` file: + +.Enable pnpm (via web.xml) +[source,xml] +---- + + + + + myservlet + + com.vaadin.flow.server.VaadinServlet + + 1 + + + pnpm.enable + true + + + + + myservlet + /* + + +---- + +.Enable bun (via web.xml) +[source,xml] +---- + + + + + myservlet + + com.vaadin.flow.server.VaadinServlet + + 1 + + + bun.enable + true + + + + + myservlet + /* + + +---- + +For more about how to set properties, see <<{articles}/configuration/properties#,Configuration Properties>>. + + +[discussion-id]`B8A479EF-56AF-4F64-A52B-A2C01F1E5991` + +++++ + +++++ diff --git a/articles/configuration/development-mode/npm-pnpm.asciidoc b/articles/configuration/development-mode/npm-pnpm.asciidoc deleted file mode 100644 index fd29dc3e5d..0000000000 --- a/articles/configuration/development-mode/npm-pnpm.asciidoc +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: npm/pnpm -description: Configuring the frontend package manager. -order: 20 ---- - - -= Configuring npm/pnpm - -https://docs.npmjs.com/cli/v8/commands/npm[npm] is the recommended and default package manager for Vaadin projects. This page explains how to configure this package manager. - - -== Install a Custom Package - -To install a custom frontend package into your project with `npm`, run `npm i xxx`. -For example, to add the `mobx` package as a dependency in [filename]`package.json` as well as install it into `node_modules`, run the following command in the project directory: - -[source,terminal] ----- -npm i mobx ----- - -[NOTE] -Vaadin expects transitive platform dependencies to be available directly under `node_modules`. -Vaadin uses the `npm` https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides[overrides feature] (since `npm` 8.3.0) to lock the transitive platform dependencies versions. - - -== Switch between npm and pnpm - -`npm` is used as the default frontend package manager. - -Vaadin also supports using https://pnpm.io[_pnpm_] (also known as _performant npm_). -To switch to `pnpm`, you can set the `vaadin.pnpm.enable` system property to `true`. - -When using `pnpm`, the framework installs it locally using `npm` if it isn't installed globally. -The [filename]`package-lock.json` file that's used by `npm` is incompatible with `pnpm` and is removed automatically if `pnpm` is used. -`pnpm` uses the [filename]`pnpm-lock.yaml` file instead of [filename]`package-lock.json`. -This means that any custom dependency configurations should go to [filename]`pnpm-lock.yaml`. - -=== Switch between npm and pnpm in a Spring Boot Project -For a Spring Boot-based project, you can add `vaadin.pnpm.enable = true` to the [filename]`application.properties` file. - -=== Switch between npm and pnpm in a Plain Java or JavaEE Project -For a plain Java or a JavaEE-based project, you can set the `pnpmEnable` configuration property inside the `vaadin-maven-plugin`. - -[source,xml] ----- - - com.vaadin - vaadin-maven-plugin - ${project.version} - - - - prepare-frontend - - - - - true - - ----- - -Alternatively, you can use the Servlet 3.0 `@WebServlet` annotation: - -[source,java] ----- -@WebServlet(urlPatterns = "/*", name = "myservlet", asyncSupported = true, loadOnStartup = 1, - initParams = { @WebInitParam(name = "pnpm.enable", value = "true") }) -public class CustomServlet extends VaadinServlet { -} ----- - -or use the traditional [filename]`web.xml` file: - -[source,xml] ----- - - - - - myservlet - - com.vaadin.flow.server.VaadinServlet - - 1 - - - pnpm.enable - true - - - - - myservlet - /* - - ----- - -For more about how to set properties, see <<{articles}/configuration/properties#,Configuration Properties>>. - - -[discussion-id]`B8A479EF-56AF-4F64-A52B-A2C01F1E5991` - -++++ - -++++ diff --git a/articles/configuration/properties.adoc b/articles/configuration/properties.adoc index 3e9e57626c..11f224eb46 100644 --- a/articles/configuration/properties.adoc +++ b/articles/configuration/properties.adoc @@ -159,7 +159,11 @@ The following table contains the properties that are defined in the [classname]` |`pnpm.enable` |`false` -|Enables `pnpm`, instead of `npm`, to resolve and download frontend dependencies. It's set by default to `false` since `npm` is used typically. Set it to `true` to enable `pnpm`. See <> for more information. +|Enables `pnpm`, instead of `npm`, to resolve and download frontend dependencies. It's set by default to `false` since `npm` is used typically. Set it to `true` to enable `pnpm`. See <> for more information. + +|`bun.enable` +|`false` +|Enables `bun`, instead of `npm`, to resolve and download frontend dependencies. It's set by default to `false` since `npm` is used typically. Set it to `true` to enable `bun`. See <> for more information. |`productionMode` |`false` @@ -209,7 +213,7 @@ The following table contains the properties that are used only by the Vaadin Mav |`vaadin.ci.build` |`ciBuild` -|Determines whether `npm ci` is run, instead of `npm i`, for production frontend builds. If you use `pnpm`, the install command runs with the `--frozen-lockfile` parameter. The build fails if the [filename]`package.json` and [filename]`package-lock.json` files have mismatching versions. +|Determines whether `npm ci` is run, instead of `npm i`, for production frontend builds. If you use `pnpm` or `bun`, the install command runs with the `--frozen-lockfile` parameter. The build fails if the [filename]`package.json` and the lockfile have mismatching versions. |`false` |`vaadin.force.production.build` diff --git a/articles/create-ui/web-components/index.asciidoc b/articles/create-ui/web-components/index.adoc similarity index 97% rename from articles/create-ui/web-components/index.asciidoc rename to articles/create-ui/web-components/index.adoc index fafa571d55..e22003af6b 100644 --- a/articles/create-ui/web-components/index.asciidoc +++ b/articles/create-ui/web-components/index.adoc @@ -13,9 +13,9 @@ To use a Web Component in Vaadin, you first have to load the HTML, JavaScript, a The Web Component's client-side files -- typically JavaScript module files -- are available using https://www.npmjs.com/[npm], which Vaadin supports by default. It automatically installs and uses `npm` packages. It also serves the static files to the browser. -.Using pnpm instead of npm +.Using pnpm or bun instead of npm [TIP] -Vaadin also supports using https://www.npmjs.com/package/pnpm[pnpm] (known as _performant npm_). See <<{articles}/configuration/development-mode/npm-pnpm#,Configuring npm/pnpm>> for details. +Vaadin also supports using https://www.npmjs.com/package/pnpm[pnpm] (known as _performant npm_) or https://bun.sh[_bun_]. See <<{articles}/configuration/development-mode/npm-pnpm-bun#,Configuring npm/pnpm/bun>> for details. == Integrating a JS Module into Vaadin diff --git a/articles/guide/start/gradle.asciidoc b/articles/guide/start/gradle.adoc similarity index 99% rename from articles/guide/start/gradle.asciidoc rename to articles/guide/start/gradle.adoc index 0f9d129cff..2df8acd87c 100644 --- a/articles/guide/start/gradle.asciidoc +++ b/articles/guide/start/gradle.adoc @@ -1,6 +1,6 @@ --- title: Starting a Vaadin Project with Gradle -description: How to start a Vaadin project with the build tool, Gradle. +description: Starting a Vaadin project with the build tool, Gradle. tab-title: Gradle order: 500 --- @@ -523,6 +523,9 @@ Use `pnpm` for installing `npm` frontend resources. Defaults to `false`. `useGlobalPnpm: Boolean = false`:: Use the globally installed `pnpm` tool or the default supported `pnpm` version. Defaults to `false`. +`bunEnable: Boolean = false`:: +Use `bun` for installing `npm` frontend resources. Defaults to `false`. + `requireHomeNodeExec: Boolean = false`:: Force use of Vaadin home node executable. If it's set to `true`, Vaadin home node is checked, and installed if absent. This is then be used instead of the globally or locally installed node. diff --git a/articles/production/production-build.adoc b/articles/production/production-build.adoc index d203a1246f..d5996d5dc3 100644 --- a/articles/production/production-build.adoc +++ b/articles/production/production-build.adoc @@ -18,7 +18,7 @@ Executing this line builds a `JAR` or `WAR` file, with all of the dependencies a If no add-ons or frontend files are used in the application, the previous command uses a pre-compiled production bundle to eliminate the need to run frontend tools like `npm` and Vite. However, frontend tools are still used to generate an application-specific bundle in the following situations: -- An `npm`/`pnpm` package is added with `@NpmPackage`, or provided directly through [filename]`package.json`; +- An `npm` package is added with `@NpmPackage`, or provided directly through [filename]`package.json`; - CSS or JavaScript is added with `@CssImport`, `@JsModule`, or `@JavaScript`; - Vaadin add-on with frontend customizations is added; - Custom theme packaged as a `JAR` dependency is included, if it defines any assets to be added to the project; @@ -53,7 +53,7 @@ By default, Vaadin uses `npm install` to install frontend packages. This can be -Dvaadin.ci.build=true ---- -When set, Vaadin interrupts package installation if it spots any mismatch between package versions in the [filename]`package.json` and [filename]`package-lock.json` files. It'll then recommend re-running `npm install`. This makes production builds in the CI pipelines reproducible, enabling you to identify problems in advance. +When set, Vaadin interrupts package installation if it spots any mismatch between package versions in the [filename]`package.json` and the lock file. It'll then recommend re-running `npm install`. This makes production builds in the CI pipelines reproducible, enabling you to identify problems in advance. == Enabling Production Builds