mindkomm/theme-lib-mix

A Laravel Mix function for WordPress themes.

Mix

A Laravel Mix function for WordPress themes.

The mix() function is useful if you want to enable cache busting for your theme asset files (CSS, JavaScript, images, icon sprites). Laravel Mix allows you to create a mix-manifest.json file, which might look like this:

{
    "/css/styles.css": "/css/styles.css?id=6ed48b0b831e80bd7549",
    "/js/scripts.js": "/js/scripts.js?id=1bdd07b944e933aa88aa",
}

The ID parameter is a hash of the file contents that changes every time that you make a change to a file. The mix(), mix_child() and mix_any() functions provided in this package allow you to use these hashed URLs for enqueueing your assets in your WordPress theme.

Installation

You can install the package via Composer:

composer require mindkomm/theme-lib-mix

Usage

The mix() function assumes that you have a mix-manifest.json (generated by the version function of Laravel Mix) in the build folder of your theme.

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style(
        'styles',
        mix( 'build/css/styles.css' )
    );
} );

If the mix function can’t find your asset file in the manifest file, it will return the asset URL through get_theme_file_uri as a fallback.

Functions

Name	Return Type	Summary/Returns
mix()	string	Gets the path to a versioned Mix file in a theme. Returns: The versioned file URL.
mix_child()	string	Gets the path to a versioned Mix file in a child theme. Returns: The versioned file URL.
mix_any()	string	Gets the path to a versioned Mix file outside of your theme folders. Returns: The versioned file URL.

mix()

Gets the path to a versioned Mix file in a theme.

Use this function if you want to load theme dependencies. This function will cache the contents of the manifest files for you.

• If you want to use mix in a child theme, use mix_child().
• If you want to use mix outside of your theme folder, you can use mix_any().

since 1.0.0

mix( string $path, array $args = [] )

Returns: string The versioned file URL.

Name	Type	Description
$path	string	The relative path to the file.
$args	array	Optional. An array of arguments for the function. (bool) $is_child – Whether to check the child directory first. Default false. (string) $manifest_directory – Custom relative path to manifest directory. Default build.

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style(
        'styles',
        mix( 'build/css/styles.css' )
    );
} );

mix_child()

Gets the path to a versioned Mix file in a child theme.

Similar to mix(), but tries to load a file from the child theme first.

since 1.2.0

mix_child( string $path, array $args = [] )

add_action( 'wp_enqueue_scripts', function() {
	wp_enqueue_style(
		'theme-styles-child',
		mix_child( 'build/css/styles-child.css' ),
		[],
		null
	);
} );

mix_any()

Gets the path to a versioned Mix file outside of your theme folders.

The difference to the mix() function is that for this function, you need to provide the absolute paths to the file and the manifest directory. The benefit is that it’s more versatile and that you can use it for functionality that might not live in a theme, but in a plugin, vendor packages or in a symlinked package.

since 1.1.0

mix_any( string $path, string $manifest_directory, string $manifest_name = mix-manifest.json )

Returns: string The versioned file URL.

Name	Type	Description
$path	string	The full path to the file.
$manifest_directory	string	The full path to the manifest directory.
$manifest_name	string	Optional. The name of the manifest file in $manifest_directory. Default mix-manifest.json.

---

Support

This is a library that we use at MIND to develop WordPress themes. You’re free to use it, but currently, we don’t provide any support.

theme-lib-mix's Issues

globally/static config eg set default path?

Hi,

it'd be useful to be able to globally set the path to something other than build so it doesn't need to be called every time I call mix

I will probably be using it a lot in my templates, but my files are in dist, so ideally I could configure this in my bootstrap functions

<script src="{{ mix('js/app.js') }}"></script>
<link rel="stylesheet" href="{{ mix('css/app.css')" />

also it would be good if you could namespace your class/methods to Mindkomm maybe?

anyway in the meantime I've done it like this (adding the namespace to your file):

public function add_to_twig( $twig ) {
    $twig->addFunction( new \Timber\Twig_Function( 'mix', [$this, 'mix']));
    return $twig;
}

public function mix($path) {
    return \Mindkomm\mix($path, ['manifest_directory' => 'dist']);
}

hope that's useful to somebody.

Mix() can't find the mix-manifest.json for a Wordpress child theme

Using mix() on a custom theme with laravel mix works great. But noticed it won't find the manifest if the $manifest_directory is in the child-theme.

In line 24 get_theme_file_pathfirst checks get_stylesheet_directory which returns the path to the parent theme before get_template_directory which would be the child-theme.

Nobody should be modifying or adding anything to the parent theme and should compile all assets to the child, or would you recommend leaving the mix-manifest.json outside the theme entirely and pass the $manifest_directory every time?