Adding NPM Dependencies
In this guide you'll learn how add NPM dependencies to your project.
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 Node and NPM is required.
Video
This guide is also available as a video:
Shopware 6: Your custom NPM dependencies (Developer Tutorial) - YouTube
Adding a npm package to the Administration or the Storefront
Presuming you have npm
installed, run npm init -y
in the <plugin root>src/Resources/app/administration/
folder or the <plugin root>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
.
So in order to install missionlog
, run npm install missionlog
in the folder you have created your package.json
file in.
Registering a package in the build system
Shopware's storefront as well as administration is based on the build system Webpack. 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.
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.
// <plugin root>/src/Resources/app/storefront/build/webpack.config.js
const { join, resolve } = require('path');
module.exports = () => {
return {
resolve: {
alias: {
'@missionlog': resolve(
join(__dirname, '..', 'node_modules', 'missionlog')
)
}
}
};
}
Let us take a closer look at the code. In the first line, we import the two functions join
and resolve
for the path module of Node.js. In the second 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.
After that, there comes the exciting part for us: registering the alias. The alias for missionlog
is given the prefix @
, so it is possible to recognize later on in the source files. We will use the result of the two functions of the path module previously imported as a value.
We proceed from the inside to the outside. We use join
to reflect the path to the package inside the node_modules
folder. The node_modules
folder contains all the packages that we have installed via npm install
. After we identified the relevant path to the package, we use the resolve
function to transform this path into an absolute path.
Using the dependency
Once we have installed all the dependencies and registered the package in the build system with an alias, we can use the package in our own code.
// <plugin root>/src/Resources/app/storefront/src/main.js
import Plugin from 'src/plugin-system/plugin.class';
// Import logger
import { log } from '@missionlog';
// Initializing the logger
log.init({ initializer: 'INFO' }, (level, tag, msg, params) => {
console.log(`${level}: [${tag}] `, msg, ...params);
});
// The plugin skeleton
export default class ExamplePlugin extends Plugin {
init() {
console.log('init');
// Use logger
log.info('initializer', 'example plugin got started', this);
}
}
We import the function log as well as the constants tag via destructuring
in the specified code. Through the use of the alias, we keep the paths short and recognize that this is an alias at first glance via the prefix.
The final step in this process is to build your Storefront or Administration so that your changes are processed by Webpack.
Next steps
Now that you know how to include new npm
dependencies you might want to create a service with them. Learn how to do that in this guide: How to add a custom-service
If you want to add Composer dependencies, or even other plugin dependencies, we've got you covered as well.