Build Process

[justintadlock]

One thing that we should probably decide early on is what system to use for building compiling assets and so on. This project has minimal CSS and JS, so we could get by without anything. But, I'd rather have a consistent method of handling this in any project that includes CSS/JS that we do.

Personally, I'm a fan of Laravel Mix simply because it's super simple to configure: https://laravel-mix.com/ But, I'm open to anything else if someone with more JS and build experience is willing to tackle setting things up.

Goals

We have two goals:

• Provide raw files that theme authors can import into their own builds if they choose to do so.
• Provide compiled files that theme authors can simply enqueue.

File organization

Here's how I do things in my projects:

// Raw, uncompiled files:

- /resources
    /js
    /scss (or css)

// Compiled resources:

- /public 
    /js
    /css 

[dingo-d]

I could try to provide a basic webpack.config.js file, but it's a bit problematic because people put their assets in different folders, so this config would presume that you use only specific folder structure in your themes. I mean we could say - if you use this, you need to place your dev files here, and your enqueued styles and scripts will have to be enqueued in this fashion.

[justintadlock]

We don't need a build process for themes. We just need something for our own projects. Themes can import the raw JS and SCSS files into their own build process if they want from /resources.

If themes don't want to import, they can simply enqueue the production assets from /public.

Here's a basic webpack.mix.config.js:

// Import required packages.
const mix = require( 'laravel-mix' );

// Set dev path.
const devPath  = 'resources';

// Set public path.
mix.setPublicPath( 'public' );

// Set options.
mix.options( {
    postCss        : [ require( 'postcss-preset-env' )() ],
    processCssUrls : false
} );

// Source maps.
mix.sourceMaps();

// Versioning and cache-busting with `mix-manifest.json`.
mix.version();

// Compile JS.
mix.js( `${devPath}/js/customize-controls.js`, 'js' );

// Sass configuration.
var sassConfig = {
    outputStyle : 'expanded',
    indentType  : 'tab',
    indentWidth : 1
};

// Compile SASS/CSS.
mix.sass( `${devPath}/scss/customize-controls.scss`, 'css', sassConfig );

// Extra Webpack config.
mix.webpackConfig( {
    stats       : 'minimal',
    devtool     : mix.inProduction() ? false : 'source-map',
    performance : { hints  : false    },
    externals   : { jquery : 'jQuery' },
} );

[dingo-d]

I've added the webpack example here: https://github.com/WPTRT/customize-section-button/tree/feature/add-webpack-config

If it's too complicated let me know. I've changed some things (using scss and some minor modifications as well).

[justintadlock]

I've got to admit that I'm not a fan of it, but I'm also not a fan of normal Webpack config anyway. I think it's overly complicated for the vast majority of use cases.

The /public folder seems to be gone from that branch??

---

I added Laravel Mix in https://github.com/WPTRT/customize-section-button/commit/b9945de83dbc316026d4554450e6c33f59225642. I should've done it on a separate branch so that we could test both implementations, but I wasn't thinking.

Commands are:

npm run dev
npm run watch
npm run prod

I also added in cross-env so that commands work on Windows. :)

[dingo-d]

The /public folder seems to be gone from that branch??

Yes, since when you build the resources it will be made with hash added to it (that's why there's manifest.json present). I basically reused a bit of how we build assets in the Theme Sniffer plugin (I need to update that one a bit tho). Also, you can check how my colleague changed the webpack and made it more modular (I'll rewrite the config to look like this in the sniffer) in our boilerplate: https://github.com/infinum/wp-boilerplate/

My branch has the commands

npm run start
npm run build

And there's the precommit script that will be run by husky.

And good catch about the cross-env package, will add it into the branch as well 😄

[aristath]

Just my 2c: For simple projects like this one with minimal JS & CSS, a build process is more annoying than useful. I agree that we should use something consistent in all our projects, but at the same time we should show that there's a right tool for every job... and for this job I doubt this is it. This particular job doesn't need fancy tools.

Another issue is that by introducing this complexity it's no longer a drop-in component. A theme author can't just drop this in their theme and be done with it, they'll have to start cleaning up, removing more than half the files in the repo just to get to a point where they can say "it's now ready to go in my theme". Sure we can add things in a .gitattributes file and just ignore files on export, that will get the package ready for people that will download the package from the repo. But if a theme uses composer for example and they import 5 packages like this one, then they've got a lot of cleaning up to do before they can submit their theme on .org

[justintadlock]

When using Composer, you should use --prefer-dist for production, which will pull from the ZIP and follow the .gitattributes rules. If we need to add anything to .gitattributes, we should definitely do so.

One thing related to this discussion is that I would like to provide the .scss files. This allows theme authors to import into their own theme's customize-controls.scss (or whatever) and not have to enqueue ours directly.

[aristath]

When you put it like that it makes perfect sense :laughing: