Important
You are browsing documentation for version 5.0 of OroCommerce, supported until January 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Managing NPM dependencies with Composer
Oro application code (including PHP code, Javascript code, SCSS, etc.) is distributed via Composer packages. In the previous versions, we also used Composer to manage all external dependencies - both PHP and frontend. The PHP package dependencies were managed by Composer natively, and the frontend dependencies (NPM and Bower packages) - via a Composer “proxy gateway” (asset-packagist) to NPM and Bower registries.
As NPM allows a lot more freedom in package naming, we could no longer update some of our NPM dependencies because Composer does not recognize or does not allow some NPM package names (e.g., with a different letter case or special characters). That is why we had to switch from using asset packagist to calling NPM directly from the composer install and composer update scripts.
Minimum Requirements
The following software is required for composer to install JS dependencies:
Hint
For instructions on how to install Node.js, navigate to the official website.
General Information
NPM packages represent JS dependencies of the application. NPM packages are recursively collected from composer.json files of all application dependencies. During composer install (either update or require) they are passed to NPM utility, which handles further installation.
Hint
For more information on NPM, see NPM documentation.
Workflow
Initial Install of Application
During the composer install command composer runs the Oro\Bundle\InstallerBundle\Composer\ScriptHandler::installAssets post-install command, which recursively collects NPM packages from composer.json files of all application dependencies. Collected NPM packages are passed to npm install which handles further installation:
updates dependencies section in existing package.json or creates new file
generates package-lock.json file
fetches NPM packages and puts them into node_modules/ directory
Hint
The generated package.json file is a technical file which should not be changed manually and is ignored by Git.
An example of composer.json containing NPM dependencies in the extra.npm section:
{
"name": "oro/calendar-bundle",
"_comment": "skipped part of file",
"extra": {
"npm": {
"fullcalendar": "3.4.0"
},
}
}
Application Install When Lock Files Already Exist
If package-lock.json already exists, post-install command Oro\Bundle\InstallerBundle\Composer\ScriptHandler::installAssets runs npm ci which looks into the lock file, fetches NPM packages, and puts them into the node_modules/ directory.
Adding New NPM Dependencies
Add the NPM package name and version constraint to the extra.npm section of composer.json, e.g “fullcalendar”: “3.4.0”.
Delete composer.lock and the package-lock.json files.
Run composer install.
Resolving Conflicting NPM Dependencies
It is possible that you can have two different versions of the same NPM package defined in two separate Composer packages. To resolve this conflict, define the version that you want to use in the root composer.json file of your application.