repository·master·Indexed 19 days ago
https://github.com/magesuite/magepackA performance optimization tool for Magento 2 frontends that improves Google Lighthouse scores and reduces JavaScript load times. Magepack creates optimized bundles of RequireJS dependencies as a flexible alternative to standard Magento JS bundling or Baler. It includes a CLI for generating configurations via page crawling and bundling JavaScript files with support for minification via Terser and sourcemap generation.
Once the bundles are generated and created, you must enable Magepack in your Magento instance. This can be done via the Admin Panel (Stores -> Configuration -> Advanced -> Developer) or via the CLI.
After enabling, ensure you clear the Magento cache.
# Enable Magepack via CLI
bin/magento config:set dev/js/enable_magepack_js_bundling 1
# Clear cache
bin/magento cache:cleanMagepack requires Node.js version 10 or higher. You must also have the magepack-magento module installed in your Magento instance.
Compatibility Notes:
mixins.js module.jquery.cookie module shim.Install the CLI globally using npm or yarn.
# Using npm
npm install -g magepack
# Using yarn
yarn global add magepackThe first step in the optimization process is to generate a magepack.config.js file. This is done by running the generate command against a working shop to collect RequireJS dependencies for specific page layouts.
Magepack prepares the following bundles:
cms: Modules for CMS pages.category: Modules for category pages.product: Modules for product pages.checkout: Modules for cart and checkout pages.common: Modules required by all the above bundles.Required Options:
--cms-url: URL to a CMS page (e.g., homepage).--category-url: URL to a category page.--product-url: URL to a product page.Note: By default, Magepack will visit the product page, add the product to the cart, and visit both the cart and checkout pages to collect dependencies. Use --skip-checkout to prevent this behavior.
magepack generate --cms-url="{{CMS_PAGE_URL}}" --category-url="{{CATEGORY_PAGE_URL}}" --product-url="{{PRODUCT_PAGE_URL}}"After generating the configuration, run the bundle command in your shop's root directory. Important: This must be executed after the Magento static content deployment stage has finished.
The command iterates over deployed locales (excluding Magento/blank) to prepare the bundles.
magepack bundleIf you encounter issues, use the following troubleshooting steps:
--debug or -d flag to output detailed information about the ongoing process.When running magepack bundle, you can use the following optional flags to customize the process:
-c, --config: Path to a specific configuration file (useful for multiple themes).-g, --glob: Defines where to look for locales to bundle.-s, --sourcemap: Enables sourcemap generation for bundled JS.-m, --minify: Overrides Magento 2 JS minification settings by minifying the bundle using Terser.Important regarding Sourcemaps:
To ensure sourcemaps are meaningful, Magento 2 JS minification should be turned off in Magento settings, and you should use the -m, --minify flag to let Magepack handle minification via Terser. Magepack's sourcemaps do not respect existing sourcemaps for individual JS files.
# Example: Bundling with a specific config and sourcemaps enabled
magepack bundle -c custom-theme.config.js -s -mThe lib/generate/collector/index.js module exports a collection of category-specific collectors. These collectors are used to gather data for different types of entities within Magepack. The available categories are:
category: Handles category-related data collection.cms: Handles CMS page-related data collection.product: Handles product-related data collection.checkout: Handles checkout-related data collection.const collectors = require('./lib/generate/collector/index.js');
// Example access:
const productCollector = collectors.product;
const cmsCollector = collectors.cms;Use getModuleRealPath to resolve the actual file path for a module, accounting for minification and stripping plugin prefixes.
text!, it is treated as a text plugin and the path is returned via stripPlugin without adding .js or .min suffixes.isMinifyOn is true and the path doesn't already end in .min, it appends .min..js to the path (unless it's a text! module).stripPlugin to the resulting path.const { getModuleRealPath } = require('./lib/bundle/pathResolver');
// Example: Standard module with minification enabled
const path = getModuleRealPath('myModule', '/path/to/module', true);
// Returns: '/path/to/module.min.js' (after stripPlugin)
// Example: Text plugin module
const textPath = getModuleRealPath('text!template', '/path/to/template', true);
// Returns: '/path/to/template' (after stripPlugin)Use getBundlePath to determine the absolute file path for a generated Magepack bundle. The function constructs a filename following the pattern bundle-{bundleName}.js or bundle-{bundleName}.min.js if minification is enabled, and places it within a magepack subdirectory of the provided locale path.
const { getBundlePath } = require('./lib/bundle/pathResolver');
// Example usage:
const bundlePath = getBundlePath('/var/www/html/pub/static/frontend/Vendor/theme/en_US', 'my-bundle', true);
// Returns: '/var/www/html/pub/static/frontend/Vendor/theme/en_US/magepack/bundle-my-bundle.min.js'Use getBundleConfigPath to determine the absolute file path for a Magepack RequireJS configuration file. The function constructs a filename following the pattern requirejs-config-{bundleName}.js or requirejs-config-{bundleName}.min.js if minification is enabled, and places it within a magepack subdirectory of the provided locale path.
const { getBundleConfigPath } = require('./lib/bundle/pathResolver');
// Example usage:
const configPath = getBundleConfigPath('/var/www/html/pub/static/frontend/Vendor/theme/en_US', 'my-bundle', false);
// Returns: '/var/www/html/pub/static/frontend/Vendor/theme/en_US/magepack/requirejs-config-my-bundle.js'Output the current version of the magepack CLI.
magepack -v
# or
magepack --versionUse the generate command to create an optimization configuration by crawling specific Magento page types. This command requires URLs for a CMS page, a Category page, and a Product page to analyze the required JavaScript assets.
Required Options:
--cms-url <url>: The URL of a CMS page.--category-url <url>: The URL of a Category page.--product-url <url>: The URL of a Product page.Optional Options:
-u, --auth-username <user>: Basic authentication username for protected URLs.-p, --auth-password <password>: Basic authentication password for protected URLs.-d, --debug: Enable detailed debugging logs.--skip-checkout: Prevents the generation of a bundle for the checkout page.magepack generate --cms-url <url> --category-url <url> --product-url <url>