Bootstrap wpackio-scripts to your project

This guide covers in-depth how to get started or incorporate wpack.io tooling into your WordPress project. Install the build tool We have two way to get started with @wpackio/scripts. Bootstrap the files automatically Using this way is recommended. It will not override any of your files and will bootstrap needed files and package.json scripts automatically for you. First cd into project directory. Now run Once done, run OR if using yarn (the cli tool will auto-detect) This will create the following files: wpackio.project.js - Information and entry-points for your project (plugin or theme). wpackio.server.js - Information about your local development server. Make sure to add it to .gitignore file because it may differ for team members. .browserslistrc - For targeting your environment. More info here. It is used by both babel and autoprefixer to make sure your javascript and css files work as expected. postcss.config.js - Additional configuration for your css files. Read more. We have autoprefixer setup by default. NOTE You must use camelCase format when defining appName. Otherwise it will not work. Now you are ready to go. Bootstrap the files manually. Please read here. Mention entry-points Now edit your wpackio.project.js file and at the very least, mention the entry-points. Here you start thinking in terms of ES6 Modules and specify the files, which imports other files. If you have, files src/main.js and src/mobile.js, which are ES6 Modules and runs everything, then you can have your project config something like this. Your src/main.js may look something like this Generate server config for team members It is very much possible that different team members use different types of local server. @wpackio/scripts doesn’t come into you way and forces you to change this. Instead it provides a way to automatically generate server config for each of your team member. The only requirement here is to make sure you have wpackio.server.js in your .gitignore file. Then ask your members to run @wpackio/scripts will realize that the project is already configured and will only ask the user for the URL of the development server. It is usually the URL provided by wamp, mamp, vvv etc. Just enter that and the wpackio.server.js will be automatically created for you. Now we have the node dependencies set. It is time to use PHP dependency to actually enqueue the files. Keep on reading the next part of quick start guide.

Read More

Use PHP API to consume assets

While @wpackio/scripts will generate the assets for you, you still need a way to actually wp_enqueue_script the assets and define dynamic publicPath to make them actually work. wpackio/enqueue is the PHP companion of @wpackio/scripts. It gives you all the APIs you will need to properly consume assets generated from @wpackio/scripts from your WordPress plugins or themes. Installation Using Composer We recommend using composer for using this library. Then in your plugin main file or functions.php file of your theme, load composer auto-loader. Manual If you do not wish to use composer, then download the file Enqueue.php. Remove the namespace line namespace WPackio; and rename the classname from Enqueue to something less generic, like MyPluginEnqueue. This ensures conflict-free loading. Then require the file in your plugin entry-point or functions.php file of your theme. Getting Started Which ever way, you choose to install, you have to make sure to instantiate the class early during the entry-point of your plugin or theme. This ensures that we have necessary javascript in our website frontend and admin-end to make webpack code-splitting and dynamic import work. Consuming assets for project The PHP API must be instantiated in a way that it understands what you have written in your wpackio.project.js file. Say your appName is awesomePlugin and your files entry look like this. The following code shows you how you can consume, i.e, wp_enqueue all of the assets. Why call it early? It is required that you create an instance of the class, before wp_head and admin_head hooks are called. It is needed because WPackio\Enqueue hooks in early to print a small javascript like this: This is single-handedly responsible for making webpack dynamic publicPath work. More information can be found about available methods in PHP API docs.

Read More

Start using development server

Now that we have all dependencies installed, it is time to start the development server. Remember that wpackio-scripts doesn’t provide any WordPress development server. You are free to use any local server, like wamp, mamp, vvv. Let’s start by editing our wpackio.server.js file. Edit wpackio.server.js file Edit the file with your favorite editor and change the proxy, like… If your local WordPress development server is going to produce and URL to the outputPath which is not of the type /wp-content/plugins/<slug>/<outputPath>/ then you can override it with the distPublicPath settings. Say you have local WordPress hosted under http://localhost/wp-one. Then put distPublicPath like This is the only thing you need to start the server. Under the hood, we use browser-sync to proxy the WordPress directory. Start the server Now from a terminal, run npm start This will boot up the development server and open up a browser window. The files will be served from /wp-content/<plugins|themes>/<slug>/<outputDir>/ depending on your configuration. Fine tune some proxy stuff Under the hood, we proxy WordPress server that you have. It will work for 90% of the time. But in some cases, like with REST API or customizer, things might not work at first. Luckily there’s an easy fix. Create a file wpackio-fix.php under wp-contents/mu-plugins and put the following content Remember to use it only under your development server. Also change 192.168.1.144:3000 to your browser-sync URL (the one that opens).

Read More

Creating Production Distribution

Now that you know how to start development server, it’s time to create production build. In most of the cases it is a single command away. But if you want to create distributable .zip file for your WordPress theme or plugin, then we have you covered too. Create production assets From your terminal run npm run build This will create the production assets (.js and .css files along with any image files). Create distributable zip file Now you may want to copy over the dist files, along with your PHP files so that you can create a .zip out of it. It is needed when uploading themes to WordPress too. With wpackio-scripts, it’s just a command away. Mention files you want to copy Edit your wpackio.project.js file to mention the files you want to copy and where you want to copy. The above config will copy the files matching the pattern in packageFiles to package directory. So be sure to add it to your .gitignore file. Run command Now run the command from your terminal npm run archive This will produce the files for you to copy and deploy. Bonus: Deploy from Gitlab CI We use gitlab CI/CD within our workflow. And with wpackio-scripts, deploying a theme or plugin is very easy. Our .gitlab-ci.yml file looks like this.

Read More