{"id":22854633,"url":"https://github.com/kanopi/kanopi-pack-asset-loader","last_synced_at":"2025-04-30T12:14:51.866Z","repository":{"id":64869218,"uuid":"502186257","full_name":"kanopi/kanopi-pack-asset-loader","owner":"kanopi","description":null,"archived":false,"fork":false,"pushed_at":"2024-01-31T17:12:42.000Z","size":23,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T16:03:58.441Z","etag":null,"topics":["composer-package","do-not-archive","internal-tool"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanopi.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-06-10T21:33:07.000Z","updated_at":"2024-04-22T19:40:39.000Z","dependencies_parsed_at":"2023-10-14T23:04:06.649Z","dependency_job_id":null,"html_url":"https://github.com/kanopi/kanopi-pack-asset-loader","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanopi%2Fkanopi-pack-asset-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanopi%2Fkanopi-pack-asset-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanopi%2Fkanopi-pack-asset-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanopi%2Fkanopi-pack-asset-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanopi","download_url":"https://codeload.github.com/kanopi/kanopi-pack-asset-loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251699351,"owners_count":21629809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer-package","do-not-archive","internal-tool"],"created_at":"2024-12-13T07:07:49.348Z","updated_at":"2025-04-30T12:14:51.824Z","avatar_url":"https://github.com/kanopi.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kanopi Pack Asset Loader\n\nPHP library for use in PHP and WordPress applications to facilitate development using Kanopi Pack (wrapper for Webpack) and deployment of its published assets. Loader provides a systematic method to enqueue scripts and styles produced from Webpack entry points.\n\n\n## Documentation Reference\n\n* [Classes](#classes)\n* [WordPress Configuration Note](#wordpress-configuration-note)\n* [WordPress Examples](#wordpress-examples)\n\n\n## Classes\n\n### Loader Configuration Class\n\nAll assets are registered with the following sets of configuration parameters:\n\n| Parameter                    | Default              |\n|------------------------------|----------------------|\n| `Asset Manifest Path`        | None                 |\n| `Development Styles In Head` | False                |\n| `Handle Prefixes`            | kanopi-pack-         |\n| `Production Domains`         | None                 |\n| `Script Path`                | /assets/dist/js/     |\n| `Static Path`                | /assets/dist/static/ |\n| `Style Path`                 | /assets/dist/css/    |\n| `Version`                    | None                 |\n\n\n| Class Method                                                                                                                                                                                                                                 | Description                                                   |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|\n| `__construct( ?string $_version = null, ?array $_production_domains = null, ?string $_asset_manifest_path = null, ?string $_handle_prefix = null, ?string $_script_path = null, ?string $_style_path = null, ?string $_static_path = null )` | Override any default values associated with the configuration |\n\n\n### Asset Loader API Class\n\nThe underlying class, which coordinates the load of assets from a Kanopi Pack configuration, is located at `Kanopi\\Assets\\AssetLoader`. \n\nWebpack generates two special script types which are loaded at specific times, though are optional based on other assets present in the app/site: \n\n1. **Runtime** - Present to coordinate modules shared between multiple packages. For instance, if `app1.js` and `app2.js` share Vue3, a runtime file (default handle of `runtime`) is generated and must be loaded before either.\n2. **Vendor** - Contains any third-party imported modules, either listed under the `package.json` key of `require`, or referenced in an entry point with `@import \u003cnamed_node_module\u003e`. For instance, if `app1.js` and `app2.js` share Vue3, a vendor file (default handle of `vendor`) is generated and must be loaded before any Runtime and App entry points. **NOTE** - Webpack may also generate another module coordinating file, default handle of `central`, which is always present on the Dev Server. \n\n| Class Method                                                                                             | Description                                                                                                                     |\n|----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|\n| `__construct( string $_base_url, ?string $_development_url, Model\\LoaderConfiguration $_configuration )` | Coordinate the asset loader, based on a set of production and development URLs, and path configurations                         |\n| `enqueue_assets()`                                                                                       | Helper function generates a series of WordPress `wp_enqueue_*` calls                                                            |\n| `in_development_mode(): bool`                                                                            | Flag to tell whether the assets are currently loaded in Production or Development mode                                          |\n| `register_applications( string $_handle, array $_dependencies = [] )`                                    | Register an application (contains both script and styles), via entry point handle and any preceding script handles (not styles) |\n| `register_runtime_script( string $_handle, array $_dependencies = [] )`                                  | Register the Webpack runtime script, via entry point handle and any preceding scripts                                           |\n| `register_script( string $_handle, array $_dependencies = [] )`                                          | Register a script, via entry point handle and any preceding scripts                                                             |\n| `register_style( string $_handle, array $_dependencies = [] )`                                           | Register a style, via entry point handle and any preceding styles; In development mode, these are ignored.                      |\n| `register_vendor_script( string $_handle, array $_dependencies = [] )`                                   | Register a Webpack generated vendor script, via entry point handle and any preceding scripts                                    |\n\n\n### WordPress Enqueue Registry\n\nCoordinates enqueuing assets within WordPress with the Front-end and Block Editor for Kanopi Pack.\n\n#### API\n\nThe main WordPress registration class is located at `Kanopi\\Assets\\Registry\\WordPress`. \n\n| Class Method                                          | Description                                                                                  |\n|-------------------------------------------------------|----------------------------------------------------------------------------------------------|\n| `__construct( LoaderConfiguration $_configuration )`  | Configures the asset manifest and versioning features                                        |\n| `register_block_editor_scripts( callback $_closure )` | Wrapper to enqueue scripts and styles for the Block Editor                                   |\n| `register_frontend_scripts( callback $_closure )`     | Wrapper to enqueue scripts and styles on the site front-end                                  |\n| `update_block_editor_priority`                        | Configure the WordPress action priority of the loaded scripts and styles in the Block Editor |\n| `update_frontend_priority`                            | Configure the WordPress action priority of the loaded scripts and styles on the front-end    |\n\n\n## WordPress Configuration Note\n\nIn default implementations, the package assumes the constant `KANOPI_DEVELOPMENT_ASSET_URL` is defined before calling the package, otherwise only Production mode is available\n\n\n## WordPress Examples\n\n#### Single set of assets in the active WordPress theme\n\nConsider this sample set of Kanopi Pack entry points:\n\n```js\nmodule.exports = {\n    //... other configuration ...\n    \"filePatterns\": {\n        \"cssOutputPath\": \"css/[name].css\",\n        \"entryPoints\": {\n            \"theme\": \"./assets/src/scss/theme/index.scss\",\n            \"theme-app\": \"./assets/src/js/theme/index.js\"\n        },\n        \"jsOutputPath\": \"js/[name].js\"\n    },\n    //... other configuration ...\n}\n```\n\nAn example loader sequence is as follows, though it's recommended this be placed in a module or some other structure.\n\n```php\nuse Kanopi\\Assets\\Registry\\WordPress;\n\n$loader = WordPress( \n            new LoaderConfiguration(\n\t\t\t\tWordPress::read_theme_version(),\n\t\t\t\t[ \n                    // ... list of Domain names, no protocol or path\n                    'domain-name.com',\n                    'staging.domain-name.com'\n                 ],\n\t\t\t\t'/assets/dist/webpack-assets.json'\n            )\n        );\n\n$loader-\u003eregister_frontend_scripts( function ( $_registry ) {\n    $loader = $_registry-\u003easset_loader();\n    $loader-\u003eregister_vendor_script( 'central' );\n    $loader-\u003eregister_vendor_script( 'vendor' );\n\n    $loader-\u003eregister_runtime_script( 'runtime', [ 'jquery' ] );\n    $loader-\u003eregister_style( 'theme' );\n    $loader-\u003eregister_script( 'theme-app' );\n\n    $loader-\u003eenqueue_assets();\n\n    // Required theme stylesheet\n    wp_register_style(\n        'site-theme',\n        esc_url_raw( get_stylesheet_directory_uri() . '/style.css' ),\n        [],\n        $_registry::read_theme_version();\n    );\n    wp_enqueue_style( 'site-theme' );\n});\n```\n\n### Adding a New Script or Style\n\nWhen a new script of style is added, add the handle to the appropriate registration function. \n\nConsider adding a new script and style for a Song post type to the site in the [previous example](#single-set-of-assets-in-the-active-wordpress-theme).\n\nThe new configuration becomes:\n\n```js\nmodule.exports = {\n    //... other configuration ...\n    \"filePatterns\": {\n        \"cssOutputPath\": \"css/[name].css\",\n        \"entryPoints\": {\n            \"song\": \"./assets/src/scss/song/index.scss\",\n            \"song-app\": \"./assets/src/js/song/index.js\",\n            \"theme\": \"./assets/src/scss/theme/index.scss\",\n            \"theme-app\": \"./assets/src/js/theme/index.js\"\n        },\n        \"jsOutputPath\": \"js/[name].js\"\n    },\n    //... other configuration ...\n}\n```\n\n```php\nuse Kanopi\\Assets\\Registry\\WordPress;\n\n$loader = WordPress( \n            new LoaderConfiguration(\n\t\t\t\tWordPress::read_theme_version(),\n\t\t\t\t[ \n                    // ... list of Domain names, no protocol or path\n                    'domain-name.com',\n                    'staging.domain-name.com'\n                 ],\n\t\t\t\t'/assets/dist/webpack-assets.json'\n            )\n        );\n\n$loader-\u003eregister_frontend_scripts( function ( $_registry ) {\n    $loader = $_registry-\u003easset_loader();\n    $loader-\u003eregister_vendor_script( 'central' );\n    $loader-\u003eregister_vendor_script( 'vendor' );\n\n    $loader-\u003eregister_runtime_script( 'runtime', [ 'jquery' ] );\n    $loader-\u003eregister_style( 'theme' );\n    $loader-\u003eregister_style( 'song' );\n    $loader-\u003eregister_script( 'theme-app' );\n    $loader-\u003eregister_script( 'song-app' );\n\n    $loader-\u003eenqueue_assets();\n\n    // Required theme stylesheet\n    wp_register_style(\n        'site-theme',\n        esc_url_raw( get_stylesheet_directory_uri() . '/style.css' ),\n        [],\n        $_registry::read_theme_version();\n    );\n    wp_enqueue_style( 'site-theme' );\n});\n```\n\n### Adding Gutenberg Blocks to the Site\n\nWhen a new script of style is added, add the handle to the appropriate registration function. \n\nConsider adding new Song Listing and Testimonial blocks to the site in the [previous example](#single-set-of-assets-in-the-active-wordpress-theme). \n\nIt is strongly recommended to add all of the blocks to the site through a common script with an auto-loader function for HMR. Also, styles written modularly for each block can be included in their front-end stylesheets and separately included in a Block Editor specific sheet, `blocks-theme` entry point.\n\n Both blocks, in this example, are registered both in PHP and in the `block-editor` entry point. Both blocks contain front-end script functionality, the song listing is a widget on all pages so is included here. The testimonial block, however, is situational, so we will let the `block.json` on the PHP side register its scripts and styles.  \n\nThe new configuration becomes:\n\n```js\nmodule.exports = {\n    //... other configuration ...\n    \"filePatterns\": {\n        \"cssOutputPath\": \"css/[name].css\",\n        \"entryPoints\": {\n            \"block-editor\": \"./assets/src/js/block-editor/index.ts\",\n            \"block-theme\": \"./assets/src/scss/block-editor/index.scss\",\n            \"song-listing\": \"./assets/src/scss/song-listing/index.scss\",\n            \"song-listing-app\": \"./assets/src/js/song-listing/index.js\",\n            \"testimonial\": \"./assets/src/scss/testimonial/index.scss\",\n            \"testimonial-app\": \"./assets/src/js/testimonial/index.js\",\n            \"theme\": \"./assets/src/scss/theme/index.scss\",\n            \"theme-app\": \"./assets/src/js/theme/index.js\"\n        },\n        \"jsOutputPath\": \"js/[name].js\"\n    },\n    //... other configuration ...\n}\n```\n\n```php\nuse Kanopi\\Assets\\Registry\\WordPress;\n\n$loader = WordPress( \n            new LoaderConfiguration(\n\t\t\t\tWordPress::read_theme_version(),\n\t\t\t\t[ \n                    // ... list of Domain names, no protocol or path\n                    'domain-name.com',\n                    'staging.domain-name.com'\n                 ],\n\t\t\t\t'/assets/dist/webpack-assets.json'\n            )\n        );\n\n$loader-\u003eregister_frontend_scripts( function ( $_registry ) {\n    $loader = $_registry-\u003easset_loader();\n    $loader-\u003eregister_vendor_script( 'central' );\n    $loader-\u003eregister_vendor_script( 'vendor' );\n\n    $loader-\u003eregister_runtime_script( 'runtime', [ 'jquery' ] );\n    $loader-\u003eregister_style( 'theme' );\n    $loader-\u003eregister_style( 'song-listing' );\n    $loader-\u003eregister_script( 'theme-app' );\n    $loader-\u003eregister_script( 'song-listing-app' );\n    // Note, the Testimonial script and style are not included, the block.json for the block covers conditionally including those assets. Add a dependency handle of kanopi-pack-runtime (or adjust kanopi-pack if you changed the handle prefix) to ensure all of its modules are available.\n\n    $loader-\u003eenqueue_assets();\n\n    // Required theme stylesheet\n    wp_register_style(\n        'site-theme',\n        esc_url_raw( get_stylesheet_directory_uri() . '/style.css' ),\n        [],\n        $_registry::read_theme_version();\n    );\n    wp_enqueue_style( 'site-theme' );\n});\n\n$loader-\u003eregister_block_editor_scripts( function ( $_registry ) {\n    $loader = $_registry-\u003easset_loader();\n    $loader-\u003eregister_vendor_script( 'central' );\n    $loader-\u003eregister_vendor_script( 'vendor' );\n\n    $loader-\u003eregister_runtime_script( 'runtime', [ 'jquery' ] );\n    $loader-\u003eregister_style( 'block-theme' );\n    $loader-\u003eregister_script( 'block-editor' );\n\n    $loader-\u003eenqueue_assets();\n});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanopi%2Fkanopi-pack-asset-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanopi%2Fkanopi-pack-asset-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanopi%2Fkanopi-pack-asset-loader/lists"}