From b8e64ae69540f1f00a46823bb15f50fa53e9c08e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Apr 2026 14:43:04 +0000 Subject: [PATCH 1/2] Update npm dependencies guide for Shopware 6.7 Vite migration - Remove outdated webpack-based approach for the Administration - Add new Administration section explaining Vite handles npm package resolution automatically - Add optional vite.config.mts example for custom configuration - Keep Webpack approach for the Storefront (still webpack-based) - Update build commands (composer build:js:admin for admin, ./bin/build-storefront.sh for storefront) - Remove outdated YouTube video reference showing webpack approach - Add link to Webpack to Vite migration guide Agent-Logs-Url: https://github.com/shopware/docs/sessions/07bcf0eb-b3cc-4003-919c-f691029a5fd0 Co-authored-by: Isengo1989 <8600299+Isengo1989@users.noreply.github.com> --- .../dependencies/using-npm-dependencies.md | 82 ++++++++++++------- 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/guides/plugins/plugins/dependencies/using-npm-dependencies.md b/guides/plugins/plugins/dependencies/using-npm-dependencies.md index 4cfed0b199..f2c2b2d7b2 100644 --- a/guides/plugins/plugins/dependencies/using-npm-dependencies.md +++ b/guides/plugins/plugins/dependencies/using-npm-dependencies.md @@ -7,53 +7,83 @@ nav: # Adding NPM Dependencies -In this guide, you'll learn how to add NPM dependencies to your project. +In this guide, you'll learn how to add NPM dependencies to your plugin. ## Prerequisites All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course, you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further, a basic understanding of Node and NPM is required. -## Video +## Installing an npm package -This guide is also available as a video: +Presuming you have `npm` installed, run `npm init -y` in the `/src/Resources/app/administration/` folder or the `/src/Resources/app/storefront/` folder. This command creates a `package.json` file in the respective folder, depending on the environment you're working in. - +To add a package to the `package.json` file, run the `npm install` command. In this example we will be installing [`missionlog`](https://www.npmjs.com/package/missionlog): -::: warning -This video shows how to resolve the NPM package name as an alias. We recommend resolving all node_modules instead like shown in the code example below. -::: +```bash +npm install missionlog +``` + +## Administration (Shopware 6.7+ with Vite) + +Since Shopware 6.7, the Administration build system has been migrated from Webpack to [Vite](https://vite.dev/). With Vite, you no longer need a custom `webpack.config.js` file to use npm packages. Vite resolves npm packages from your plugin's `node_modules` directory automatically using standard Node.js module resolution. + +You can import npm packages directly in your code without any additional build configuration: + +```javascript +// /src/Resources/app/administration/src/example-component.js +import { log } from 'missionlog'; + +// Initializing the logger +log.init({ initializer: 'INFO' }, (level, tag, msg, params) => { + console.log(`${level}: [${tag}] `, msg, ...params); +}); +``` -## Adding a npm package to the Administration or the Storefront +If you need custom Vite configuration (for example, path aliases), create a `vite.config.mts` file in the `/src/Resources/app/administration/src/` directory: -Presuming you have `npm` installed, run `npm init -y` in the `src/Resources/app/administration/` folder or the `src/Resources/app/storefront/` folder. This command creates a `package.json` file in the respective folder, depending on the environment you're working in. To add a package to the `package.json` file simply run the `npm install` command. In this example we will be installing [`missionlog`](https://www.npmjs.com/package/missionlog). +```typescript +// /src/Resources/app/administration/src/vite.config.mts +import { defineConfig } from 'vite'; -So in order to install `missionlog`, run `npm install missionlog` in the folder you have created your `package.json` file in. +export default defineConfig({ + resolve: { + alias: { + '@my-alias': '/path/to/module', + }, + }, +}); +``` -## Registering a package in the build system +Build the Administration using: -Shopware's storefront as well as administration is based on the build system [Webpack](https://webpack.js.org/). Webpack is a source file bundler: In essence it bundles all the source files into a single `bundle.js` to be shipped to a browser. So in order to make Webpack aware of the new dependency, we have to register it and give it an alias/pseudonym so that the package can be bundled correctly. +```bash +composer build:js:admin +``` + +For more information on migrating from Webpack to Vite, see the [Webpack to Vite migration guide](/guides/upgrades-migrations/administration/vite). + +## Storefront (Webpack) -To do this, we create a new folder called "build" under either `Resources/app/storefront` or `Resources/app/administration`. In this build folder we create a new file with the name `webpack.config.js`. We thereby make it possible to extend the Webpack configuration of Shopware. +The Storefront build system continues to use [Webpack](https://webpack.js.org/). To make Webpack aware of the npm packages installed in your plugin, create a `webpack.config.js` file in the `/src/Resources/app/storefront/build/` directory: ```javascript +// /src/Resources/app/storefront/build/webpack.config.js module.exports = (params) => { - return { - resolve: { + return { + resolve: { modules: [ `${params.basePath}/Resources/app/storefront/node_modules`, ], - } - }; + } + }; } ``` -Let us take a closer look at the code. In the first line, we export a so-called arrow function. The build system from Shopware calls this function when either the Administration or Storefront is being built. +This tells Webpack to also search for modules in your plugin's `node_modules` folder, in addition to Shopware's own `node_modules`. -Now we add the `node_modules` folder from our extension. `resolve.modules` tells webpack what directories should be searched when resolving modules. By default, the shopware webpack config only considers the `node_modules` folder of the platform. By accessing `params.basePath` we get the absolute path to our extension. We then add the rest of the path to our extensions `node_modules`. Now webpack will also search for modules in our `node_modules` folder. +### Using the dependency in the Storefront -## Using the dependency - -Once we have installed all the dependencies and registered the package in the build system, we can use the package in our own code. +Once you have installed all the dependencies and registered the plugin's `node_modules` path in the build system, you can import and use the package in your code: ```javascript // /src/Resources/app/storefront/src/example.plugin.js @@ -78,7 +108,7 @@ export default class ExamplePlugin extends PluginBaseClass { } ``` -We import the function log as well as the constants tag via `destructuring` in the specified code and register our above plugin in our main.js file, so it can be loaded by the plugin system. +Register the plugin in your `main.js` file so it can be loaded by the plugin system: ```javascript // /src/Resources/app/storefront/src/main.js @@ -90,14 +120,10 @@ PluginManager.register( ); ``` -The final step in this process is to build your Storefront or Administration so that your changes are processed by Webpack. +Build the Storefront using: ```bash -# Build the Storefront ./bin/build-storefront.sh - -# Build the Administration -./bin/build-administration.sh ``` ## Next steps From dd3b37210e3d6e24e6198fc2a926034da9cfd2d3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 16 Apr 2026 14:44:06 +0000 Subject: [PATCH 2/2] Clarify vite.config.mts location and fix example alias path - Add note clarifying that vite.config.mts is placed in src/ (next to entry file) while package.json stays in administration/ - Replace placeholder absolute path with realistic relative path in alias example Agent-Logs-Url: https://github.com/shopware/docs/sessions/07bcf0eb-b3cc-4003-919c-f691029a5fd0 Co-authored-by: Isengo1989 <8600299+Isengo1989@users.noreply.github.com> --- guides/plugins/plugins/dependencies/using-npm-dependencies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/plugins/dependencies/using-npm-dependencies.md b/guides/plugins/plugins/dependencies/using-npm-dependencies.md index f2c2b2d7b2..2be15e03c3 100644 --- a/guides/plugins/plugins/dependencies/using-npm-dependencies.md +++ b/guides/plugins/plugins/dependencies/using-npm-dependencies.md @@ -39,7 +39,7 @@ log.init({ initializer: 'INFO' }, (level, tag, msg, params) => { }); ``` -If you need custom Vite configuration (for example, path aliases), create a `vite.config.mts` file in the `/src/Resources/app/administration/src/` directory: +If you need custom Vite configuration (for example, path aliases), create a `vite.config.mts` file in the `/src/Resources/app/administration/src/` directory (alongside your entry file, e.g., `main.js`). Note that `package.json` stays in `/src/Resources/app/administration/`: ```typescript // /src/Resources/app/administration/src/vite.config.mts @@ -48,7 +48,7 @@ import { defineConfig } from 'vite'; export default defineConfig({ resolve: { alias: { - '@my-alias': '/path/to/module', + '@my-module': 'src/my-module', }, }, });