Project Configuration with wpackio.project.js

The wpackio.project.js file at the root of your workspace tells wpackio how your project is to be compiled. When you bootstrap this file is created for you. You should commit wpackio.project.js with your VCS. A typical project file looks like this. Let’s dive in deep with different options. appName (string) The name of your application. It should be unique and you have to use the same value with the PHP consumer library. NOTE: This must be camelCase. type (string) Either plugin or theme, depending on your WordPress project. slug (string) The slug of your plugin or theme. This is the name of the directory put under wp-content/{themes,plugins}. This is used only for development purpose and has no significance on production build. bannerConfig (Object) A configuration object for banner put above all minified code. It has the following properties: name (string): Name of application. author (string): Author of application. version (string): Version of application. link (string): Homepage link of application. license (string): License of application. copyrightText (string): Additional copyright text. credit (boolean): Whether to give wpackio a little credit ❤️. files (Array) An array of file object. It defines which files to compile and supports code-splitting with different entry-points. Unlike webpack entry-point it has to be an array of object of a certain shape. First let us see an example. Here we have passed only one file object to the files entry. In most of the cases this is what we’d need. Our main entry will split codes depending on different entry-points and the tooling will handle chunk-splitting, optimization, prevent duplicates etc. More information is found here. Once again, do note that you do not really need to do anything apart from defining entry.property = string[] logically. Just think about which single JS file you will need to run a particular application. Even if you have only one property under entry, then also (if needed) chunk-splitting will be applied. If we were to pass multiple file object, then webpack would run in multi-compiler mode, separating dependency tree from each of the file object. Each file object has two required and three optional properties. Here’s the interface. name (string) required: A unique name of this file entry. If you are using more than one file entry, then make sure to give different names, otherwise the compiler might not work in development mode. entry (object) required: This is the path (relative to project root) of files you would like to compile. As you can see, we only support Object Syntax of webpack entry. The reason is, we do our own little magic (covered in the concepts section) to define dynamic publicPath from WordPress API itself. webpackConfig (Function | Object | undefined) If you’d like to extend webpack configuration, then this is where you’d put your code. It can support both webpack configuration objects or function to get further control. Kindly read the Extending Webpack Config under tutorials. Callback Function The most powerful form is the function. It has the following signature config (webpack.Configuration) The configuration calculated by @wpackio/scripts is passed as the first parameter. merge (webpackMerge) The webpack-merge passed as-is. appDir (string) Directory inside outputPath where all the assets are to be emitted. isDev (boolean) Whether the operation is going for development mode or production build. typeWatchFiles (string[]) Array of glob pattern for which typescript reports are to be notified. hasTypeScript (boolean | undefined) Explicitly disable typescript type assertions. More information about typescript related options can be found here. outputPath (string): Name of the directory (relative) where we would put the bundled and manifest files. Defaults to dist and you should not commit this directory in your VCS. NOTE: This must be a single directory name with alphanumeric camelCase. You can not pass rel/path/to/dist here. hasReact (boolean): Where you need support for react specific presets, like jsx. hasSass (boolean): Where you need support for sass/scss files. You need to install node-sass or dart-sass and your project’s devDependency yourself. hasFlow (boolean): Whether you need support for flowtype. useBabelConfig (boolean) wpackio-scripts knowingly avoids any babel.config.js and .babelrc file from babel-loader. If you wish to avoid this behavior and want to be in control of babel configuration, set this option to true. More information about it can be read here. jsBabelPresetOptions (object) | tsBabelPresetOptions (object) wpackio script uses its own preset for javascript and typescript files. Using this option you can pass in additional config and it will be spread over the default one. jsBabelPresetOptions is applied for js,jsx files and tsBabelPresetOptions is applied for ts.tsx files. jsBabelOverride (Function) | tsBabelOverride (Function) Pass in a callback function to completely override options for babel-loader The signature is Where defaults is the config created by tooling. Here’s an example we used to incorporate react hot loader. jsBabelOverride is applied for js,jsx files and tsBabelOverride is applied for ts.tsx files. externals (Object) Configure webpack external runtime dependency. alias (Object) Configure webpack resolve.alias. errorOverlay (boolean) Whether to show overlay during development mode when some error has occurred. optimizeSplitChunks (boolean) Whether or not to apply built-in optimization presets. Turn it off if you would like to do things manually. We have the default config from webpack optimization split-chunks plugin with only exception of setting chunks to 'all'. We can do it safely because our PHP consumer library handles the enqueue. watch (string) Glob pattern to watch additional files and reload browser on change. Useful for watching .php files. packageFiles (string[]) Array of glob patterns to copy files to the packageDirPath directory. This is used to create the distributable zip file. WordPress allows uploading .zip files to install both theme and plugins. This option provides you a way to create such .zip file with wpackio-scripts pack command. packageDirPath (string) Relative path of directory where we would put the package files. You should add it to your .gitignore file. A subdirectory with name same as slug will always be created inside it. The generated package file will also have name like <slug>.zip. zlibLevel (number) The level of zlib compression to use when creating the zip.

Read More

Server Configuration with wpackio.server.js

The wpackio.server.js file at the root of your workspace tells wpackio how your development server is handled. It is used to proxy an existing development server and run webpack and browsersync on top of it, to give you the ultimate developer experience. You should NOT commit wpackio.server.js with your VCS, if you do not have docker based development. In case of mamp, wamp, vvv, local server generally differs for team members. A typical server file looks like this. Let’s dive in deep with different options. host (string) The IP Address of your local network. An IP is needed because only then can we properly have browser-sync accessible across network and have our service workers work. wpackio will try to determine the best possible IP address from your interfaces and will use that. If you pass a specific value (192.168.1.102), then it will be used instead. proxy (string) The URL of the local WordPress development server where your theme/plugin is installed and being developed upon. Right now, we recommend having a Root WordPress installation (not sub-folder). If you have sub-folder installation, then put the whole URL as proxy like http://localhost/wp-plugin port (number) A port where the development hot server will live. ui (Object) Passed directly to browser-sync. notify (boolean) Whether or not to show notification on browser. open (boolean) Whether to automatically open the local server on your browser. ghostMode (boolean|Object) Passed directly to browser-sync. distPublicPath (string) Absolute URL path (without protocol and host) of the outputPath defined in your project configuration. It is used for development server only and has no effect on the production build. By default wpackio-scripts calculates the URL of the outputPath in this way So this assumes that WordPress proxy server is installed in root and not in sub-directory. The directory structures of plugins, themes are set as default. You have entered the correct slug in your project configuration and it matches with the directory structure of your development server. In case, your development server doesn’t work like this, you can specify your distPublicPath manually. Remember you have to put a forward slash at the end of the value.

Read More

Methods and options of PHP API

The following are the methods and options for \WPackio\Enqueue class which comes with the composer package. Creating Instance While creating a class instance, you can pass in up-to 5 parameters. $appName (string) It has to be same as you have defined in wpackio.project.js under appName. $outputPath (string) It has to be same as you have defined in wpackio.project.js under outputPath. $version (string) Version of your plugin/theme. $type (string) Either "plugin" or ”theme”, depending on your project. $pluginPath (string|false) Absolute path to the main plugin file. If you are using it for theme, then don’t pass it, or just use false. Instance API: getAssets Get handle and Url of all assets from the entry-point. It doesn’t enqueue anything for you, rather returns an associative array with handles and urls. You should use it to enqueue it on your own. Usage Parameters It accepts three parameters. $name (string) It is the name of files entry defined in your wpackio.project.js. Given the following files in wpackio.project.js The value of $name could be app, foo, reactapp. $entryPoint (string) The key of the entry object as defined in wpackio.project.js file. For the same config, if we choose app as $name, $entryPoint could be main or mobile. $config (array) An associative array of additional configuration. Here are the supported keys: js (boolean) True if we are to include javascript files. css (boolean) True if we are to include stylesheet files. js_dep (array) Additional dependencies for the javascript assets. css_dep (array) Additional dependencies for the stylesheet assets. in_footer (boolean) Whether to print the assets in footer (for js only). media (string) Media attribute for stylesheets (defaults 'all'). defaults to NOTE: The identifier property was removed from $config. We need complete control of the script handle to make sure common chunks, such as, runtime is enqueued only once. Return array It returns an associative array with js and css asset handles and URLs for ready consumption using wp_enqueue API. A return may look like this It doesn’t take care of internal dependencies by itself. The register method does. Instance API: register Register script handles with WordPress for an entrypoint inside a source. It does not enqueue the assets, just calls wp_register_* on the asset. This is useful if just registering script for things like gutenberg. Usage and parameters are same as getAssets. It doesn’t return anything. Example Internal Dependencies All the assets within an $entryPoint has internal dependency upon each other. Let us consider the following manifest.json file generated by @wpackio/scripts. Here the asset app/main.js of main entryPoint depends on both app/vendor~main.js. app/runtime.js. So if we were to enqueue only app/main.js it will not work, it need the two scripts in the page too. Similarly for the asset app/mobile.js, of mobile entryPoint, we have internal dependency of app/vendor~mobile.js. app/runtime.js. Here app/runtime.js is a common dependency for both the entry-points. But we should enqueue it only once. To make sure WordPress properly enqueues the dependencies and doesn’t come up with duplicate scripts, register sets the scripts dependencies for you. So if you do something like this You can be assured that app/vendor~main.js and app/runtime.js will both be enqueued. There isn’t any magic behind it. We just set internal dependencies during call to wp_register_(script|style). Instance API: enqueue Enqueue all the assets for an entry-point inside a source. Usage and parameters are same as getAssets. It returns the same list of assets as getAssets. Example Instance API: getManifest Get an associative array representing the content of manifest.json of a file entry. Usage For the same **wpackio.project.js** as in getAssets, we can use this method to retrieve the manifest file directly. Parameters It accepts only one parameter. $name (string) The name of the file entry as defined in **wpackio.project.js**. The wpackio-scripts internally creates a directory of the same name inside outputPath. wpackio/enqueue uses the same concept and looks for a file manifest.json inside the same directory and returns the content as an associative array (using json_decode). Instance API: getUrl Get public URL of an asset (script or style). It doesn’t check whether the asset actually exists or not. It just calculates the plugin/theme URL from $outputPath. This is meant to be used to get URL from manifest.json files directly. Usage Parameters It accepts only one parameter. $asset (string) The relative path of the asset (with forward / as director separator) for which URL is to be calculated.

Read More

Node.js APIs provided by @wpackio/scripts

While @wpackio/scripts is meant to be used as a CLI tool, it does expose all of the necessary node.js APIs to create your own CLI. For now, the best place to check the exports is the file itself. Since we develop in typescript and ship all .d.ts files, you will get IDE intellisense by default. Here are the documentation for a few APIs which are useful. getBabelPresets Get babel configuration for compiling JavaScript or TypeScript files. This is used internally to create babel config for babel-loader. Usage babel.config.js Parameters presetOptions Options for @wpackio/base. It has the following interface. More information can be found in the source repository. typeChecker Whether to include preset for 'flow' or 'typescript'. Leave undefined to ignore both. Possible values are 'flow', 'typescript' or undefined. getDefaultBabelPresetOptions Get default options for @wpackio/babel-preset-base considering whether project has react and whether it is in development mode. Usage getFileLoaderOptions Get options for file-loader. This takes into account the application directory, development or production mode and public path for file-loader usage from css files. If you want to use file-loader for your own custom asset management, then do use this API for dynamically setting the option. This ensures a few things, like All assets are put inside assets directory. Assets works for CSS files where relative path is necessary. More information can be found in file-loader tutorial. Usage wpackio.project.js Parameters appDir (string) Application directory where we are going to put the asset. isDev (boolean) Whether for development or production build. publicPath (boolean) Whether or not to set publicPath for file-loader, depending on isDev. issuer The API consists a family of webpack issuer utilities. Use them in conjunction with file-loader or url-loader. issuerForNonStyleFiles: Tests if files are not, css, sass and scss. issuerForStyleFiles: Tests if files are one of css, sass or scss. issuerForNonJsTsFiles: Tests if files are not, js, jsx, ts and tsx. issuerForJsTsFiles: Tests if files are one of js, jsx, ts and tsx. Usage wpackio.project.js

Read More