{"_id":"@10up/ignite-dependency-extraction-webpack-plugin","_rev":"3-19ee50d29ba2721442326419bff301f2","name":"@10up/ignite-dependency-extraction-webpack-plugin","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@10up/ignite-dependency-extraction-webpack-plugin","version":"1.0.0","keywords":["webpack","plugin","wordpress","ignite","dependency","extraction","interactivity-api","script-modules"],"author":{"name":"10up"},"license":"MIT","_id":"@10up/ignite-dependency-extraction-webpack-plugin@1.0.0","maintainers":[{"name":"fabiankaegy","email":"mail@fabian-kaegy.de"},{"name":"brandwaffle","email":"vhauri@gmail.com"},{"name":"eugene-manuilov","email":"eugene.manuilov@gmail.com"},{"name":"christianc1","email":"christian.m.chung@gmail.com"},{"name":"nicholasio","email":"nicholasio.oliveira@gmail.com"},{"name":"joesnellpdx","email":"joesnellpdx@gmail.com"},{"name":"tlovett1","email":"tlovett88@gmail.com"},{"name":"devinle","email":"devin.leggett@gmail.com"},{"name":"darylldoyle","email":"daryll.doyle@10up.com"}],"homepage":"https://github.com/10up/ignite-wp-monorepo#readme","bugs":{"url":"https://github.com/10up/ignite-wp-monorepo/issues"},"dist":{"shasum":"6910bdaea0ce4aea4049c734521e716ad3b2bbc6","tarball":"https://registry.npmjs.org/@10up/ignite-dependency-extraction-webpack-plugin/-/ignite-dependency-extraction-webpack-plugin-1.0.0.tgz","fileCount":3,"integrity":"sha512-8x1Vl0o9Z7U+76ej7CwyES08UWuGOCqeAdtb3mBuzX6pch6Ryr2ze1pkVWd7QomjgyH6Mxs8KE6n/kY6XszEPw==","signatures":[{"sig":"MEUCIEkhcR+Bg68HojTptj42d0ZDoF/pPkXCmiQZz1xg4Un/AiEAvBZaSoxVbOS29kVzxHqW1EBlfb/E8BTEyT1gXgD1awY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16127},"main":"index.js","engines":{"node":">=18.0.0"},"gitHead":"05dff7b21cf749f826a73f34d4a3ff9ca6c0a3e4","_npmUser":{"name":"fabiankaegy","email":"mail@fabian-kaegy.de"},"repository":{"url":"git+https://github.com/10up/ignite-wp-monorepo.git","type":"git","directory":"packages/ignite-dependency-extraction-webpack-plugin"},"_npmVersion":"10.9.2","description":"Webpack plugin for automatically externalizing Ignite WP packages and WordPress Interactivity API modules","directories":{},"_nodeVersion":"23.5.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"webpack":"^5.0.0","@wordpress/dependency-extraction-webpack-plugin":"^6.36.0"},"_npmOperationalInternal":{"tmp":"tmp/ignite-dependency-extraction-webpack-plugin_1.0.0_1765450051191_0.2745818880519826","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-12-11T10:47:31.109Z","modified":"2026-08-21T19:38:58.164Z","1.0.0":"2025-12-11T10:47:31.332Z"},"bugs":{"url":"https://github.com/10up/ignite-wp-monorepo/issues"},"author":{"name":"10up"},"license":"MIT","homepage":"https://github.com/10up/ignite-wp-monorepo#readme","keywords":["webpack","plugin","wordpress","ignite","dependency","extraction","interactivity-api","script-modules"],"repository":{"url":"git+https://github.com/10up/ignite-wp-monorepo.git","type":"git","directory":"packages/ignite-dependency-extraction-webpack-plugin"},"description":"Webpack plugin for automatically externalizing Ignite WP packages and WordPress Interactivity API modules","maintainers":[{"email":"mail@fabian-kaegy.de","name":"fabiankaegy"},{"email":"eugene.manuilov@gmail.com","name":"eugene-manuilov"},{"email":"christian.m.chung@gmail.com","name":"christianc1"},{"email":"nicholasio.oliveira@gmail.com","name":"nicholasio"},{"email":"joesnellpdx@gmail.com","name":"joesnellpdx"},{"email":"devin.leggett@gmail.com","name":"devinle"},{"email":"daryll.doyle@10up.com","name":"darylldoyle"},{"email":"jeffpaul@hotmail.com","name":"jeffpaul"}],"readme":"# Ignite Dependency Extraction Webpack Plugin\n\nA webpack plugin that automatically externalizes Ignite WP packages and WordPress Interactivity API modules. This plugin extends `@wordpress/dependency-extraction-webpack-plugin` to handle Ignite-specific dependencies with zero configuration.\n\n## Why Use This Plugin?\n\nWhen building WordPress plugins or themes that use Ignite WP packages (like `@ignite-wp-carousel/splide`), you need to externalize these imports so they use the shared modules provided by Ignite plugins. This prevents code duplication and reduces bundle sizes.\n\nThis plugin automatically:\n\n- Externalizes all `@ignite-wp-*` package imports as script modules\n- Handles WordPress Interactivity API (`@wordpress/interactivity`) correctly\n- Supports custom package prefixes\n- Provides sensible defaults for WordPress development\n\n## Installation\n\n```bash\nnpm install --save-dev @10up/ignite-dependency-extraction-webpack-plugin\n```\n\n## Basic Usage\n\nReplace the standard WordPress Dependency Extraction Plugin with the Ignite version:\n\n```javascript\nconst IgniteDependencyExtractionWebpackPlugin = require('@10up/ignite-dependency-extraction-webpack-plugin');\nconst config = require('10up-toolkit/config/webpack.config.js');\n\nconst [scriptConfig, moduleConfig] = config;\n\nmodule.exports = [\n\tscriptConfig,\n\t{\n\t\t...moduleConfig,\n\t\tplugins: [\n\t\t\t// Remove the default WordPress plugin\n\t\t\t...moduleConfig.plugins.filter(\n\t\t\t\t(plugin) => plugin.constructor.name !== 'DependencyExtractionWebpackPlugin',\n\t\t\t),\n\t\t\t// Add the Ignite plugin\n\t\t\tnew IgniteDependencyExtractionWebpackPlugin(),\n\t\t],\n\t},\n];\n```\n\nThat's it! The plugin will now automatically externalize:\n\n- **Any package starting with `@ignite-wp-`** → `import @ignite-wp-*/*`\n  - `@ignite-wp-carousel/*` → `import @ignite-wp-carousel/*`\n  - `@ignite-wp-core/*` → `import @ignite-wp-core/*`\n  - `@ignite-wp-navigation/*` → `import @ignite-wp-navigation/*`\n  - Future Ignite packages are automatically supported!\n- `@wordpress/interactivity` → `module @wordpress/interactivity`\n- `@wordpress/interactivity-router` → `import @wordpress/interactivity-router`\n\n## Configuration\n\n### Default Configuration\n\nThe plugin comes with sensible defaults:\n\n```javascript\n{\n\tignitePackagePrefix: '@ignite-wp-',\n\tadditionalPackagePrefixes: [],\n\tinjectPolyfill: false,\n}\n```\n\nThe `ignitePackagePrefix` uses a wildcard pattern, so any package starting with `@ignite-wp-` is automatically externalized. This means new Ignite packages work without updating the plugin!\n\n**Important**: This plugin extends the WordPress Dependency Extraction Plugin without breaking its default behavior. All WordPress packages (`@wordpress/*`), React, jQuery, Lodash, etc. continue to work exactly as they do in the core plugin.\n\n### Adding Custom Package Prefixes\n\nYou can add additional package prefixes to externalize:\n\n```javascript\nnew IgniteDependencyExtractionWebpackPlugin({\n\tadditionalPackagePrefixes: [\n\t\t'@my-company/',  // Matches @my-company/anything\n\t\t'@my-plugin/',   // Matches @my-plugin/anything\n\t],\n});\n```\n\n### Changing the Ignite Prefix\n\nIf you need to use a different prefix (not recommended):\n\n```javascript\nnew IgniteDependencyExtractionWebpackPlugin({\n\tignitePackagePrefix: '@custom-prefix-',\n});\n```\n\n### Custom Request Handlers\n\nYou can extend the plugin with custom logic. **Your handlers are called first**, then the plugin falls back to Ignite handling, and finally to WordPress defaults:\n\n```javascript\nnew IgniteDependencyExtractionWebpackPlugin({\n\t// For script modules (called before Ignite and WordPress defaults)\n\trequestToExternalModule: (request) => {\n\t\t// Custom logic for specific packages\n\t\tif (request === '@my-custom/package') {\n\t\t\treturn 'import @my-custom/package';\n\t\t}\n\t\t// Return undefined to let the plugin handle it\n\t\treturn undefined;\n\t},\n\t// For regular scripts (called before Ignite and WordPress defaults)\n\trequestToExternal: (request) => {\n\t\t// Custom logic for non-module scripts\n\t\tif (request === '@my-custom/package') {\n\t\t\treturn ['window', 'MyCustomPackage'];\n\t\t}\n\t\treturn undefined;\n\t},\n\t// For WordPress script handles (called before WordPress defaults)\n\trequestToHandle: (request) => {\n\t\t// Custom logic for WordPress script handles\n\t\tif (request === '@my-custom/package') {\n\t\t\treturn 'my-custom-package';\n\t\t}\n\t\treturn undefined;\n\t},\n});\n```\n\n**Handler Priority**:\n1. Your custom handler (if provided)\n2. Ignite package handling (`@ignite-wp-*` and `additionalPackagePrefixes`)\n3. WordPress default handling (`@wordpress/*`, React, jQuery, etc.)\n\n## Complete Example\n\nHere's a complete example of using Ignite packages in your custom plugin:\n\n### webpack.config.js\n\n```javascript\nconst IgniteDependencyExtractionWebpackPlugin = require('@10up/ignite-dependency-extraction-webpack-plugin');\nconst config = require('10up-toolkit/config/webpack.config.js');\n\nconst [scriptConfig, moduleConfig] = config;\n\nmodule.exports = [\n\tscriptConfig,\n\t{\n\t\t...moduleConfig,\n\t\tplugins: [\n\t\t\t...moduleConfig.plugins.filter(\n\t\t\t\t(plugin) => plugin.constructor.name !== 'DependencyExtractionWebpackPlugin',\n\t\t\t),\n\t\t\tnew IgniteDependencyExtractionWebpackPlugin(),\n\t\t],\n\t},\n];\n```\n\n### my-carousel.js\n\n```javascript\nimport { store, getElement, getContext } from '@wordpress/interactivity';\nimport { Splide } from '@ignite-wp-carousel/splide';\n\nstore('my-plugin/carousel', {\n\tactions: {\n\t\tinit: () => {\n\t\t\tconst { ref } = getElement();\n\t\t\tconst slider = new Splide(ref, {\n\t\t\t\ttype: 'loop',\n\t\t\t\tperPage: 3,\n\t\t\t});\n\t\t\tslider.mount();\n\t\t},\n\t},\n});\n```\n\n### register-module.php\n\n```php\nadd_action('init', function() {\n\twp_register_script_module(\n\t\t'my-plugin/carousel',\n\t\tMY_PLUGIN_URL . 'dist/js/my-carousel.js',\n\t\t[\n\t\t\t'@wordpress/interactivity',\n\t\t\t'@ignite-wp-carousel/splide',\n\t\t],\n\t\tMY_PLUGIN_VERSION\n\t);\n});\n```\n\n## How It Works\n\nThe plugin wraps `@wordpress/dependency-extraction-webpack-plugin` and extends its behavior:\n\n1. **Handler Chain**: For each import, the plugin calls handlers in this order:\n   - Your custom handler (if provided)\n   - Ignite package handler (wildcard match on `@ignite-wp-*`)\n   - WordPress default handler (`@wordpress/*`, React, jQuery, etc.)\n\n2. **Detect Ignite Packages**: When webpack encounters an import like `import { Splide } from '@ignite-wp-carousel/splide'`, it recognizes the `@ignite-wp-` prefix pattern using a wildcard match.\n\n3. **Externalize as Module**: Instead of bundling the code, webpack marks it as an external dependency: `import @ignite-wp-carousel/splide`.\n\n4. **Generate Dependencies**: The plugin creates a `.asset.php` file listing the external dependencies, which WordPress uses to load them in the correct order.\n\n5. **Runtime Loading**: At runtime, WordPress loads the Ignite plugin's shared module before your code, ensuring the import resolves correctly.\n\n### Wildcard Pattern Matching\n\nThe plugin uses `startsWith()` to match package names, which means:\n\n- `@ignite-wp-carousel/splide` ✅ Matches `@ignite-wp-`\n- `@ignite-wp-core/icons` ✅ Matches `@ignite-wp-`\n- `@ignite-wp-future-package/utils` ✅ Matches `@ignite-wp-` (future packages work automatically!)\n- `@wordpress/interactivity` ✅ Handled by WordPress defaults\n- `@other-package/utils` ❌ Does not match (unless in `additionalPackagePrefixes`)\n\nThis wildcard approach means new Ignite packages are automatically supported without updating the plugin, and all WordPress core functionality remains intact.\n\n## Benefits\n\n- **Zero Configuration**: Works out of the box for all Ignite packages\n- **Smaller Bundles**: Shared code isn't duplicated in your bundle\n- **Better Performance**: Shared modules are cached by the browser\n- **Automatic Updates**: When Ignite plugins update, your code uses the new version\n- **Type Safety**: Import errors are caught at build time\n\n## Supported Ignite Packages\n\nThe plugin automatically handles **any package starting with `@ignite-wp-`**, including:\n\n- **@ignite-wp-carousel/splide**: Shared Splide carousel library\n- **@ignite-wp-core/***: Core utilities and components\n- **@ignite-wp-navigation/***: Navigation components\n- **@ignite-wp-***: Any future Ignite packages (automatically supported!)\n\nThe wildcard pattern means you never need to update the plugin when new Ignite packages are released.\n\n## Requirements\n\n- Node.js 18+\n- Webpack 5+\n- `@wordpress/dependency-extraction-webpack-plugin` 5.0+ or 6.0+\n- WordPress 6.5+ (for script module support)\n\n## Troubleshooting\n\n### Module not found error\n\nIf you see \"Module not found: @ignite-wp-*\":\n\n1. Ensure the corresponding Ignite plugin is active in WordPress\n2. Verify your webpack config uses the Ignite plugin\n3. Check that you're building for production (script modules)\n\n### Dependencies not loading\n\nIf dependencies aren't loading in the correct order:\n\n1. Check that your PHP code lists the Ignite modules as dependencies\n2. Verify the `.asset.php` file is being generated\n3. Ensure you're using `wp_register_script_module()` (not `wp_register_script()`)\n\n### Custom packages not externalizing\n\nIf your custom packages aren't being externalized:\n\n1. Add them to `additionalPackages` in the plugin config\n2. Ensure they're registered as script modules in WordPress\n3. Verify the package prefix matches exactly (case-sensitive)\n\n## Contributing\n\nContributions are welcome! Please open an issue or pull request on the [Ignite WP Monorepo](https://github.com/10up/ignite-wp-monorepo).\n\n## License\n\nMIT\n\n## Credits\n\nCreated by [10up](https://10up.com) as part of the Ignite WP project.\n","readmeFilename":"README.md"}