{"id":20749266,"url":"https://github.com/jprieton/underscores-webpack","last_synced_at":"2025-09-11T06:36:40.180Z","repository":{"id":73850465,"uuid":"433168336","full_name":"jprieton/underscores-webpack","owner":"jprieton","description":"Instructions to enable webpack 5.x in underscore based theme","archived":false,"fork":false,"pushed_at":"2024-07-12T15:06:16.000Z","size":46,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-07-12T17:13:17.142Z","etag":null,"topics":["bash-script","sass","theme-development","underscore","webpack","wordpress","wordpress-theme"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jprieton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-29T19:19:10.000Z","updated_at":"2024-07-12T15:06:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"314e91ce-5e66-417f-a17d-a2772b169974","html_url":"https://github.com/jprieton/underscores-webpack","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprieton%2Funderscores-webpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprieton%2Funderscores-webpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprieton%2Funderscores-webpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jprieton%2Funderscores-webpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jprieton","download_url":"https://codeload.github.com/jprieton/underscores-webpack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225015281,"owners_count":17407370,"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":["bash-script","sass","theme-development","underscore","webpack","wordpress","wordpress-theme"],"created_at":"2024-11-17T08:21:54.632Z","updated_at":"2024-11-17T08:21:55.136Z","avatar_url":"https://github.com/jprieton.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Enable webpack 5.x in underscore based theme \n\nThis guide allows to you use webpack 5.x with `_s`, we need do some adjusts. \n\nPlease read the entire guide carefully to understand the steps involved in this change, you can find a link to a bash script for the automation of these tasks at the end of this document, additionally you can see the source code of this script [here](https://github.com/jprieton/underscore-webpack/blob/main/enable-webpack.sh).\n\n\u003cbr\u003e\n\n\u003e **Note**\n\u003e  \n\u003e For this guide I will use a clean installation of [_s](https://underscores.me/) starter theme.\n\u003e\n\u003e This guide only cover the SASS watcher, other topics, as bundle scripts, are treated superficially.\n\u003e\n\u003e Maybe is required to update the bundled version of [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) if your theme uses a version prior to 18.0.0, before following the steps in this guide, please check if your project requires that version. \n\u003e\n\u003e Isn't recommended for ongoing projects, please go to caution if you want apply to an ongoing project, if you use [CleanWebpackPlugin](https://github.com/johnagan/clean-webpack-plugin) you will lose your files without a minimum configuration, further in this guide I will explain to avoid this in detail.\n\n\u003cbr\u003e\n\n## Installation of _s theme\n\nThere are several ways to create your underscore based theme\n\n- Generate a  from the [underscore](https://underscores.me/) site, remember check the *sassify* option (recommended),\n\n- Using the command line interface WP-CLI, read more [here](https://developer.wordpress.org/cli/commands/scaffold/_s/) how to use the `scaffold` command, remember use the `-sassify` option, you can execute a command similar to this on the root of your WordPress installation,\n\n  ```shell-script\n  # Example\n  wp scaffold _s sample-theme --theme_name=\"Sample Theme\" --author=\"John Doe\" --sassify\n  ```\n  \n- Or download from GitHub [repository](https://github.com/automattic/_s).\n\nTo start using all the tools that come with `_s` you need to install the necessary Node.js and Composer dependencies, go to your theme root directory and execute in terminal the following command:\n\n```bash\ncomposer install\nnpm install\n```\n\n\u003cbr\u003e\n\n\n## Update @wordpress/scripts (optional)\n\n\u003e **Note**\n\u003e\n\u003e Latest version of underscores uses the 19.2.2 version of @wordpress/scripts\n\u003e \n\u003e This step is not included in the bash file\n\nThis step is required only if you have an installation of `_s` that uses [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) prior to 18.0.0, in a clean install this step is not required\n\nIf you have as dependency the [@wordpress/scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) prior to version 18.0.0, this version uses webpack 4.x, we need update to more recent version to use webpack 5.x in our project, (recommended 19.2.2, already tested in this guide) to do this and avoid the *Fix the upstream dependency conflict* we need uninstall and reinstall the @wordpress/scripts package, then execute in terminal the following command:\n\n```bash\nnpm remove @wordpress/scripts \u0026\u0026 npm install @wordpress/scripts@19.2.2 --save-dev\n```\n\nYes, in this case, only a package is required to be updated.\n\n\u003cbr\u003e\n\n## Move the `sass` folder\n\nIt's a personal preference, I'm prefer have all sources in the `src` folder.\n\nTo do this run:\n\n```bash\nmkdir ./src/\nmv ./sass/ ./src/scss/\n```\n\n\u003cbr\u003e\n\n## Add `webpack.config.js` file\n\nIn this repository there are a bare minimum `webpack.config.js` that allows to you start to work in your theme, you can download [here](https://raw.githubusercontent.com/jprieton/underscore-webpack/main/webpack.config.js) and put it on your root theme directory or run the following command:\n\n```bash\ncurl -o webpack.config.js https://raw.githubusercontent.com/jprieton/underscores-webpack/main/webpack.config.js\n```\n\nPlease read this about the `CleanWebpackPlugin`.\n\nIn this file pay attention on the initialization of `MiniCssExtractPlugin`, this configuration allow creates the `style.css` and `woocommerce.css` files in the root directory of the theme, any other will be created in the `dist` directory (o any other that you configure in the `BUILD_DIR`)\n\nif you check *WooCommerce boilerplate* option when you generate your theme, uncomment the `woocomerce` entry point\n\n\u003cbr\u003e\n\n## Add `postcss.config.js` file\n\nIn this repository there are a bare minimum `postcss.config.js`, you can download [here](https://raw.githubusercontent.com/jprieton/underscores-webpack/main/postcss.config.js) and put it on your root theme directory or run the following command:\n\n```bash\ncurl -o postcss.config.js https://raw.githubusercontent.com/jprieton/underscores-webpack/main/postcss.config.js\n```\n\n\u003cbr\u003e\n\n## Update `package.json` file\n\nFinally it's necessary update the `scripts` property of the `package.json` file\n\n```js\n// Before\n{\n  // Other settings\n  \"scripts\": {\n    // Other scripts\n    \"watch\": \"node-sass sass/ -o ./ --source-map true --output-style expanded --indent-type tab --indent-width 1 -w\",\n    \"compile:css\": \"node-sass sass/ -o ./ \u0026\u0026 stylelint '*.css' --fix || true \u0026\u0026 stylelint '*.css' --fix\",\n    // Update this lines only if you moved the sass directory to src folder\n \t\"lint:scss\": \"wp-scripts lint-style 'sass/**/*.scss'\",\n    // Other scripts\n  }\n  // Other settings\n}\n    \n// After\n{\n  // Other settings\n  \"scripts\": {\n    // Other scripts\n    \"watch\": \"webpack --watch --mode=development\",\n    \"compile:css\": \"webpack --mode=production \u0026\u0026 stylelint '*.css' --fix || true \u0026\u0026 stylelint '*.css' --fix\",\n    // Update this lines only if you moved the sass directory to src folder\n    \"lint:scss\": \"wp-scripts lint-style 'src/scss/**/*.scss'\",\n    // Other scripts\n  }\n  // Other settings\n}\n```\n\nAnd that's is all, you must be capable of run any of the scripts without issues. From here you can customize you webpack environment as you like \n\n\u003cbr\u003e\n\n## Generate entry poitns\n\nIn the `webpack.config.js` file there are two entry points, `styles` and `woocommerce`, we need create the files associated to these entry points executing in terminal the following commands:\n\n```bash\n# Create the required directories\nmkdir -p ./src/js/\n\n# Generate the entry point script to manage the styles\necho \"import '../scss/style.scss';\" \u003e ./src/js/style.js\necho \"import '../scss/woocommerce.scss';\" \u003e ./src/js/woocommerce.js\n```\n\n\u003cbr\u003e\n\n## `CleanWebpackPlugin` workaround :warning:\t\n\n\u003e **Note**\n\u003e \n\u003e This step it is not required if you starts a clean installation of _s theme and download the `webpack.config.js` from this repository, \n\n\n\u003e **Warning**\n\u003e \n\u003e If you are working in a preexistent theme, please read carefully this instructions, make a backup and double check the configuration of the *CleanWebpackPlugin* before run webpack, **you can lose your files if you set the incorrect path to clean!**\n\n Since the build folder in our `webpack.config.js` is same the root of our theme, enable `CleanWebpackPlugin` with default configuration all files and folders in your theme will be deleted! (`.git` folder is erased too!), it's necessary define what folder the plugin can clean, in our `webpack.config.js` are ready \n\n```js\nnew CleanWebpackPlugin({\n    cleanStaleWebpackAssets: true,\n    verbose: true, // Optional\n    cleanOnceBeforeBuildPatterns: [\n        \"*.map\",      // Allow clean style.map file from root folder\n        \"dist/**/**\", // Allow clean dist folder recursively\n    ]\n}),\n```\n\nYou can read in detail how to configure this plugin and other options [here](https://github.com/johnagan/clean-webpack-plugin), please take a look if you are no sure about your configuration is safe or if you need check if all is OK.\n\nIf you have a better configuration or you can improve this document don't hesitate in create a issue ticket.\n\n\u003cbr\u003e\n\n## There are an automated way to do this?\n\nYes, you can download [here](https://raw.githubusercontent.com/jprieton/underscore-webpack/main/enable-webpack.sh) the bash script o run:\n\n```bash\ncurl https://raw.githubusercontent.com/jprieton/underscore-webpack/main/enable-webpack.sh | bash\n```\n\n\u003cbr\u003e\n\n## Bug tracker?\n\nHave a bug? Please create an issue on GitHub at https://github.com/jprieton/underscores-webpack/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprieton%2Funderscores-webpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjprieton%2Funderscores-webpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjprieton%2Funderscores-webpack/lists"}