{"id":14955155,"url":"https://github.com/ionos-wordpress/cm4all-wp-bundle","last_synced_at":"2025-10-24T07:30:56.678Z","repository":{"id":62289062,"uuid":"556795651","full_name":"IONOS-WordPress/cm4all-wp-bundle","owner":"IONOS-WordPress","description":"A nano-sized high performance js/css resource bundler targeting WordPress Gutenberg.","archived":false,"fork":false,"pushed_at":"2024-08-15T11:11:06.000Z","size":343,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-01-29T08:34:37.025Z","etag":null,"topics":["esbuild","gutenberg","react","wordpress","wordpress-development"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IONOS-WordPress.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-24T14:26:50.000Z","updated_at":"2024-08-15T12:13:06.000Z","dependencies_parsed_at":"2023-02-19T07:16:01.364Z","dependency_job_id":null,"html_url":"https://github.com/IONOS-WordPress/cm4all-wp-bundle","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/IONOS-WordPress%2Fcm4all-wp-bundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IONOS-WordPress%2Fcm4all-wp-bundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IONOS-WordPress%2Fcm4all-wp-bundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IONOS-WordPress%2Fcm4all-wp-bundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IONOS-WordPress","download_url":"https://codeload.github.com/IONOS-WordPress/cm4all-wp-bundle/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237932070,"owners_count":19389560,"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":["esbuild","gutenberg","react","wordpress","wordpress-development"],"created_at":"2024-09-24T13:10:35.589Z","updated_at":"2025-10-24T07:30:56.100Z","avatar_url":"https://github.com/IONOS-WordPress.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\n`cm4all-wp-bundle` is a nano-sized JS/CSS bundler for [WordPress](https://make.wordpress.org/)/[Gutenberg](https://wordpress.org/gutenberg/) related projects.\n\nThe provided bundler transpiles JavaScript and JSX (including CSS `import` statements) into bundled Javascript/CSS runnable in the Browser.\n\n\u003e What means Transpilation/bundling ?\n\u003e\n\u003e JavaScript imports of `@wordpress/*` and `react` NPM packages will be transformed to their matching global pendants (`window.wp.*` and `window.react`). JSX/PostCSS/SCSS support is built-in.\n\nIt can act as a lightweight (and expotential faster) alternative to the `build` script provided by [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts).\n\n\u003e `cm4all-wp-bundle` uses [esbuild](https://esbuild.github.io/) and [sass](https://www.npmjs.com/package/sass) under the hood to provide JavaScript/SCSS/Sass transpilation capabilities instead of [webpack](https://webpack.js.org/). And nothing more.\n\n## Target audience\n\nIf you are developing Javascript/CSS for the [WordPress](https://make.wordpress.org/)/[Gutenberg](https://wordpress.org/gutenberg/) Ecosystem like [Wordpress plugins/themes](https://wordpress.org/plugins/) or [WordPress blocks](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-blocks/) this package will give you the opportunity to much faster build times and less project dependencies.\n\n# Installation\n\nThe package can be used as NPM package [`cm4all-wp-bundle`](https://www.npmjs.com/package/cm4all-wp-bundle) or preinstalled in [Docker](https://docs.docker.com/) image [`'lgersman/cm4all-wp-bundle'`](https://hub.docker.com/repository/docker/lgersman/cm4all-wp-bundle).\n\n\u003e If you are not planning to use additional [esbuild plugins](https://esbuild.github.io/plugins/) I would suggest you to use the [`'lgersman/cm4all-wp-bundle'`](https://hub.docker.com/repository/docker/lgersman/cm4all-wp-bundle) [Docker](https://docs.docker.com/) image since it minimizes the hassle (NodeJS version/package dependency bloating) of your project configuration.\n\n## Docker\n\nYou don't need to install anything when using the docker image - just execute a container, the docker image will be downloaded on demand :\n\n```sh\ndocker run\n  -i \\\n  --rm \\\n  --mount type=bind,source=$(pwd)/your-repo,target=/app \\\n  lgersman/cm4all-wp-bundle:latest \\\n  --outdir=dist/ \\\n  ./src/gutenberg-extension.js\n  ./src/blocks/my-block/edit.js\n```\n\nMore [Docker](https://docs.docker.com/) image specific documentation can be found at the official [`'lgersman/cm4all-wp-bundle'`](https://hub.docker.com/repository/docker/lgersman/cm4all-wp-bundle) docker hub page.\n\n## NPM\n\nExecuting `npm install --save-dev cm4all-wp-bundle` will install the package as development dependency in your project.\n\nThe NPM package provides a same named package script `cm4all-wp-bundle` which can be used in your build scripts.\n\n```json\n  ...\n  \"scripts\": {\n      ...\n      \"build\": \"cm4all-wp-bundle --outdir=./dist ./src/gutenberg-extension.js ./src/blocks/my-block/edit.js\"\n      ...\n    },\n  ...\n```\n\nIf you want to execute the bundler directly in your Javascript Code (or planning to use additional [esbuild plugins](https://esbuild.github.io/plugins/)) you can even use the JavaScript API:\n\n```js\nimport bundle from 'cm4all-wp-bundle';\n\n...\n\nawait bundle({\n  entryPoints: ['./src/gutenberg-extension.js', './src/blocks/my-block/edit.js'],\n  outdir: './test/fixtures/wordpress/build',\n});\n```\n\n# Configuration\n\n## CLI\n\nThe bundler script `cm4all-wp-bundle` provided by the package supports various commandline arguments :\n\n### Arguments\n\n- `--watch`/`-w`\n\n  (optional)\n\n  Listen for changes on the file system and to rebuild whenever a file changes that could invalidate the build.\n\n- `--verbose`/`-v`\n\n  (optional)\n\n  Produces more verbose log output.\n\n- `--mode=[production|development]`\n\n  (default=production)\n\n  Produces a production (\\*.min.\\*) or development version of bundled js/css code.\n\n  In case of `mode == 'production'` the transpiled sources will also be [minifed](https://esbuild.github.io/api/#minify).\n\n- `--banner=\u003cstring\u003e`\n\n  (default='')\n\n  Use this to insert an arbitrary string at the beginning of generated JavaScript and CSS files.\n\n- `--footer=\u003cstring\u003e`\n\n  (default='')\n\n  Use this to insert an arbitrary string at the end of generated JavaScript and CSS files.\n\n- `--target=\u003cstring\u003e`\n\n  (default='esnext') May occur multiple times.\n\n  Target environments for the generated JavaScript and/or CSS code (see https://esbuild.github.io/api/#target).\n\n- `--global-name=\u003cstring\u003e`\n\n  (optional)\n\n  Sets the name of the global variable which is used to store the exports from the entry point.\n\n  Can only be used if a single file gets transpiled (see https://esbuild.github.io/api/#global-name)\n\n- `--analyze=\u003cboolean\u003e`\n\n  (default=false) Generates an easy-to-read report about the contents of your bundle\n\n- `--outdir=\u003cpath\u003e`\n\n  (default=[current working directory])\n\n  This option sets the output directory for the build operation.\n\n### Advanced CLI configuration\n\nIn advance to the commandline arguments you reconfigure almost any [esbuild](https://esbuild.github.io/) option using STDIN to the bundler.\n\nThe STDIN CLI interface let's you override presets preconfigured using the commandline arguments.\n\nYou can provide the advanced configuration\n\n- using a file\n\n  ```json\n  // cm4all-wp-bundle.json\n  {\n    \"wordpress\": {\n      // adds additional mapping from import statements =\u003e global variable (window.*)\n      \"mappings\": {\n        \"@cm4all-impex/debug\": \"wp.impex.debug\",\n        \"@cm4all-impex/filters\": \"wp.impex.filters\",\n        \"React\": \"React\"\n      }\n    }\n  }\n  ```\n\n  and execute\n\n  ```sh\n  cat ./cm4all-wp-bundle.json | \\\n  cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  ```\n\n  Same same using the docker image:\n\n  ```sh\n  cat ./cm4all-wp-bundle.json | \\\n  docker run -i --rm -v $(pwd):/app lgersman/cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  ```\n\n- using `echo`\n\n  ```sh\n  echo '{ \"wordpress\" : { \"mappings\" : { \"@cm4all-impex/debug\" : \"wp.impex.debug\", \"@cm4all-impex/filters\" : \"wp.impex.filters\", \"React\": \"React\" } }}' | \\\n  cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  ```\n\n  The `docker` command looks quite similar as you might guess:\n\n  ```sh\n  echo '{ \"wordpress\" : { \"mappings\" : { \"@cm4all-impex/debug\" : \"wp.impex.debug\", \"@cm4all-impex/filters\" : \"wp.impex.filters\", \"React\": \"React\" } }}' | \\\n  docker run -i --rm -v $(pwd):/app lgersman/cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  ```\n\n- using `cat` and shell HEREDOC syntax :\n\n  ```sh\n  cat \u003c\u003c EOF | cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  {\n    \"wordpress\" : {\n      \"mappings\" : {\n        \"@cm4all-impex/debug\" : \"wp.impex.debug\",\n        \"@cm4all-impex/filters\" : \"wp.impex.filters\",\n        \"React\": \"React\"\n      }\n    }\n  }\n  EOF\n  ```\n\n  Same same using the docker image:\n\n  ```sh\n  cat \u003c\u003c EOF | docker run -i --rm -v $(pwd):/app lgersman/cm4all-wp-bundle --global-name=wp.impex.store --outdir=./dist ./src/wp.impex.store.mjs\n  {\n    \"wordpress\" : {\n      \"mappings\" : {\n        \"@cm4all-impex/debug\" : \"wp.impex.debug\",\n        \"@cm4all-impex/filters\" : \"wp.impex.filters\",\n        \"React\": \"React\"\n      }\n    }\n  }\n  EOF\n  ```\n\n### Advanced JSON Schema structure\n\nThe JSON provided via STDIN must match the `cm4all-wp-bundle` JSON Schema (can be found here : [bundle-configuration.schema.json](https://github.com/IONOS-WordPress/cm4all-wp-bundle/blob/develop/bundle-configuration.schema.json)).\n\nThe `cm4all-wp-bundle` JSON Schema declares 3 top level properties :\n\n- `\"wordpress\" : { ... }`\n\n  This property may be used to define additional _import-package_ =\u003e _global_variable_ mappings using the sub property `\"mappings\"`. Using this property you can declare additional _import-package_ =\u003e _global_variable_ mappings to apply during transpilation. Each entry in `\"mappings\"` declares a single mappings where the _key_ is the _import-package_ and the _value_ the global variable to map to.\n\n  See https://github.com/IONOS-WordPress/cm4all-wp-bundle/blob/develop/src/plugins/wordpress.js to get a picture of all by default mapped packages.\n\n  An example:\n\n  Suppose you want to use NPM package [`\"debug\"`](https://www.npmjs.com/package/debug). But this package should not be bundled in your code. And you've already managed that this package is already in the browser in global variable `window.myapp.debug`;\n\n  This scenario can simply expressed using the Advanced JSON Schema configuration :\n\n  ```json\n  {\n    \"wordpress\": {\n      \"mappings\": {\n        \"debug\": \"myapp.debug\"\n      }\n    }\n  }\n  ```\n\n  _The mapping target will automatically be prefixed with `\"window.\"`_\n\n- `\"sass\" : { ... }`\n\n  The `\"sass\"` property can be used to express a custom sass configuration to the bundler.\n\n  An example :\n\n  You have some shared Sass files located somewhere else in your project repository and use them in your code :\n\n  ```css\n  ...\n  /*\n    this file is located in ./src/components/my-component.scss\n  */\n  ...\n  /*\n    common.sass is located in ./shared-css/\n  */\n  @import common.sass;\n  ...\n  ```\n\n  To get the Sass compiler a chance to find these shared files you could use the Sass option [`\"loadPaths\"`](https://sass-lang.com/documentation/js-api/interfaces/Options#loadPaths)\n\n  ```json\n  {\n    \"sass\": {\n      \"loadPaths\": [\"./shared-css/\"]\n    }\n  }\n  ```\n\n  _You can provide Sass any configuration property as stated in the [Sass compiler documentation](https://sass-lang.com/documentation/js-api)._\n\n- `\"esbuild\" : { ... }`\n\n  Using this property it's possible to customize the `esbuild's` transpilation process.\n\n  An example:\n\n  Suppose you want\n\n  - configuring a loader for a given file type lets you load that file type with an import statement or a require call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image:\n\n    ```js\n    import url from './example.png';\n    let image = new Image();\n    image.src = url;\n    document.body.appendChild(image);\n\n    import svg from './example.svg';\n    let doc = new DOMParser().parseFromString(svg, 'application/xml');\n    let node = document.importNode(doc.documentElement, true);\n    document.body.appendChild(node);\n    ```\n\n    The above code can be bundled using the the following advanced configuration :\n\n    ```json\n    {\n      \"esbuild\": {\n        \"loader\": {\n          \".png\": \"dataurl\",\n          \".svg\": \"text\"\n        }\n      }\n    }\n    ```\n\n  - let's add another condition : We want accidental `console.*` and `debugger` statements to be removed. This can be done using `esbuild's` [drop](https://esbuild.github.io/api/#drop) option :\n\n    ```json\n    {\n      \"esbuild\": {\n        \"loader\": {\n          \".png\": \"dataurl\",\n          \".svg\": \"text\"\n        },\n        \"drop\": [\"console\", \"debugger\"]\n      }\n    }\n    ```\n\n  \u003e Please note that [cm4all-wp-bundle](https://github.com/IONOS-WordPress/cm4all-wp-bundle) already need to preconfigure some esbuild options to get your sources correctly transformed. So it might be that case that you override preconfigured options using the `cm4all-wp-bundle` JSON Schema configuration. Use can use the bundlers `verbose` options esbuild options get computed by `cm4all-wp-bundle`.\n\n  _You can provide [esbuild](https://esbuild.github.io/api/#build-api) any of it's configuration options using the `\"esbuild\"` property._\n\n#### Editing/Validation support\n\nYou can get editing/validation support for your file based `cm4all-wp-bundle` JSON Schema configuration. Create a new JSON file with following contents:\n\n```json\n{\n  \"$schema\": \"https://github.com/IONOS-WordPress/cm4all-wp-bundle/blob/develop/bundle-configuration.schema.json\"\n}\n```\n\n_If you've installed the `cm4all-wp-bundle` NPM package you can also reference the locally installed JSON schema file contained in the package (a lot of JSON Schema supporting editor alternatives to VSCode is available online)._\n\nVoilà - VSCode (and any other Schema aware editor) provides you autocompletion, documentation and so on.\n\n## Javascript API\n\nThe JavaScript API of this package let's you integrate the bundler into custom JavaScript build scripts.\n\nThe package exports a single function [`async bundle(options)`](https://github.com/IONOS-WordPress/cm4all-wp-bundle/blob/develop/src/cm4all-wp-bundle.js) exposing the bundler.\n\nExample (see [tests](https://github.com/IONOS-WordPress/cm4all-wp-bundle/blob/develop/test/test-in-browser.js) for real live usage) :\n\n```js\n...\nawait bundle({\n  mode: 'development',\n  entryPoints: ['./test/fixtures/wordpress/mylib.js', './test/fixtures/wordpress/figure.js'],\n  wordpress: {\n    mappings: {\n      './mylib.js': 'window.my.lib',\n    },\n  },\n  outdir: './test/fixtures/wordpress/build',\n});\n...\n```\n\nThe options argument has the same shape as esbuild's [`build/buildSync(...)`](https://esbuild.github.io/api/#build-api) function.\n\nPlease refer to [esbuild's build `options` documentation](https://esbuild.github.io/api/#simple-options) to see all available options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionos-wordpress%2Fcm4all-wp-bundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionos-wordpress%2Fcm4all-wp-bundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionos-wordpress%2Fcm4all-wp-bundle/lists"}