Source maps

If you’re not familiar with source maps, they work with any sort of preprocessor to teach your browser’s web inspector which files generated the compiled source you’re inspecting.

By default, Mix will not generate source maps for your files. But you can enable them by chaining the sourceMaps() method after your Mix calls, as you can see in Example 6-3.

let mix = require('laravel-mix');

mix.js('resources/js/app.js', 'public/js')
   .sourceMaps();

Once you configure Mix this way, you’ll see the source maps appear as a .{filename}.map file next to each generated file.

Without source maps, if you use your browser’s development tools to inspect a particular CSS rule or JavaScript action, you’ll just see a big mess of compiled code. With source maps, your browser can pinpoint the exact line of the source file, whether it be Sass or JavaScript or whatever else, that generated the rule you’re inspecting.

Pre- and post-processors

We’ve already covered Sass and Less, but Mix can also handle Stylus (Example 6-4), and you can chain PostCSS onto any other style calls (Example 6-5).

mix.stylus('resources/stylus/app.styl', 'public/css');

mix.sass('resources/sass/app.scss', 'public/css')
   .options({
        postCss: [
            require('postcss-css-variables')()
        ]
   });

Preprocessorless CSS

If you don’t want to deal with a preprocessor, there’s a command for that—it will grab all of your CSS files, concatenate them, and output them to the public/css directory, just as if they had been run through a preprocessor. There are a few options, which you can see in Example 6-6.

// Combines all files from resources/css
mix.styles('resources/css', 'public/css/all.css');

// Combines files from resources/css
mix.styles([
    'resources/css/normalize.css',
    'resources/css/app.css'
], 'public/css/all.css');

Concatenating JavaScript

The options available for working with normal JavaScript files are very similar to those available for normal CSS files. Take a look at Example 6-7.

let mix = require('laravel-mix');

// Combines all files from resources/js
mix.scripts('resources/js', 'public/js/all.js');

// Combines files from resources/js
mix.scripts([
    'resources/js/normalize.js',
    'resources/js/app.js'
], 'public/js/all.js');

Processing JavaScript

If you want to process your JavaScript—for example, to compile your ES6 code into plain JavaScript—Mix makes it easy to use Webpack for this purpose (see Example 6-8).

let mix = require('laravel-mix');

mix.js('resources/js/app.js', 'public/js');

These scripts look for the provided filename in resources/js and output to public/js/app.js.

You can use more complicated aspects of Webpack’s feature set by creating a webpack.config.js file in your project root.

Copying files or directories

To move either a single file or an entire directory, use the copy() method or the copyDirectory() method:

mix.copy('node_modules/pkgname/dist/style.css', 'public/css/pkgname.css');
mix.copyDirectory('source/images', 'public/images');

Versioning

Most of the tips from Steve Souders’s Even Faster Web Sites (O’Reilly) have made their way into our everyday development practices. We move scripts to the footer, reduce the number of HTTP requests, and more, often without even realizing where those ideas originated.

One of Steve’s tips is still very rarely implemented, though, and that is setting a very long cache life on assets (scripts, styles, and images). Doing this means there will be fewer requests to your server to get the latest version of your assets. But it also means that users are extremely likely to have a cached version of your assets, which will make things get outdated, and therefore break, quickly.

The solution to this is versioning. Append a unique hash to each asset’s filename every time you run your build script, and then that unique file will be cached indefinitely—or at least until the next build.

What’s the problem? Well, first you need to get the unique hashes generated and appended to your filenames. But you also will need to update your views on every build to reference the new filenames.

As you can probably guess, Mix handles that for you, and it’s incredibly simple. There are two components: the versioning task in Mix, and the mix() PHP helper. First, you can version your assets by running mix.version() like in Example 6-9.

let mix = require('laravel-mix');

mix.sass('resources/sass/app.scss', 'public/css')
    .version();

The version of the file that’s generated is no different—it’s just named app.css and lives in public/css.

Next, use the PHP mix() helper in your views to refer to that file like in Example 6-10.

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

// Will output something like:

<link rel="stylesheet" href="/css/app.css?id=5ee7141a759a5fb7377a">

Vue and React

Mix can handle building both Vue (with single-file components) and React components. Mix’s default js() call handles Vue, and you can replace it with a react() call if you want to build React components:

mix.react('resources/js/app.js', 'public/js');

If you take a look at the default Laravel sample app.js and the components it imports (Example 6-11), you’ll see that you don’t have to do anything special to work with Vue components. A simple mix.js() call makes this possible in your app.js.

window.Vue = require('vue');

Vue.component('example-component', require('./components/ExampleComponent.vue'));

const app = new Vue({
    el: '#app'
});

And if you switch to react(), this is all you need to run in your file for your first component:

require('./components/Example');

Both presets also bring in Axios, Lodash, and Popper.js, so you don’t have to spend any time getting your Vue or React ecosystems set up.

Hot Module Replacement

When you’re writing single components with Vue or React, you’re likely used to either refreshing the page every time your build tool recompiles your components or, if you’re using something like Mix, relying on Browsersync to reload it for you.

That’s great, but if you’re working with single-page apps (SPAs), that means you’re booted back to the beginning of the app; that refresh wipes any state you had built up as you navigated through the app.

Hot Module Replacement (HMR, sometimes called hot reloading) solves this problem. It’s not always easy to set up, but Mix comes with it enabled out of the box. HMR works essentially as if you’d taught Browsersync to not reload the entire file that was recompiled, but instead to just reload the bits of code you changed. That means you can get the updated code injected into your browser, but still retain the state you had built up as you got your SPA into just the right spot for testing.

To use HMR, you’ll want to run npm run hot instead of npm run watch. In order for it to work correctly, all of your <script> references have to be pulling the right versions of your JavaScript files. Essentially, Mix is booting up a small Node server at localhost:8080, so if your <script> tag points to a different version of the script, HMR won’t work.

The easiest way to achieve this is to just use the mix() helper to reference your scripts. This helper will handle prepending either localhost:8080 if in HMR mode or your domain if you’re in a normal development mode. Here’s what it looks like inline:

<body>
    <div id="app"></div>

    <script src="{{ mix('js/app.js') }}"></script>
</body>

If you develop your applications on an HTTPS connection—for example, if you run valet secure—all your assets must also be served via an HTTPS connection. This is a little bit trickier, so it’s best to consult the HMR docs.

Vendor extraction

The most common frontend bundling pattern, which Mix also encourages, ends up generating a single CSS file and a single JavaScript file that encompasses both the app-specific code for your project and the code for all its dependencies.

However, this means that vendor file updates require the entire file to be rebuilt and recached, which might introduce an undesirable load time.

Mix makes it easy to extract all of the JavaScript from your app’s dependencies into a separate vendor.js file. Simply supply a list of the vendor’s library names to the extract() method, chained after your js() call. Take a look at Example 6-12 to see how it looks.

mix.js('resources/js/app.js', 'public/js')
    .extract(['vue'])

This outputs your existing app.js and then two new files: manifest.js, which gives instructions to your browser about how to load the dependencies and app code, and vendor.js, which contains the vendor-specific code.

It’s important to load these files in the correct order in your frontend code—first manifest.js, then vendor.js, and finally app.js:

<script src="{{ mix('js/manifest.js') }}"></script>
<script src="{{ mix('js/vendor.js') }}"></script>
<script src="{{ mix('js/app.js') }}"></script>

Environment variables in Mix

As Example 6-13 shows, if you prefix an environment variable (in your .env file) with MIX_, it will become available in your Mix-compiled files with the naming convention process.env.ENV_VAR_NAME.

# In your .env file
MIX_BUGSNAG_KEY=lj12389g08bq1234
MIX_APP_NAME="Your Best App Now"

// In Mix-compiled files
process.env.MIX_BUGSNAG_KEY

// For example, this code:
console.log("Welcome to " + process.env.MIX_APP_NAME);

// Will compile down to this:
console.log("Welcome to " + "Your Best App Now");

You can also access those variables in your Webpack configuration files using Node’s dotenv package, as shown in Example 6-14.

// webpack.mix.js
let mix = require('laravel-mix');
require('dotenv').config();

let isProduction = process.env.MIX_ENV === "production";

Third-party frontend presets

If you’re interested in creating your own preset, or using one created by another community member, that’s also possible with the frontend preset system. There’s a GitHub organization designed to make it easy to find great third-party frontend presets, and they’re easy to install. For most, the steps are as follows:

1. Install the package (e.g., composer require laravel-frontend-presets/tailwindcss).

2. Install the preset (e.g., php artisan preset tailwindcss).

3. Just like with the built-in presets, run npm install and npm run dev.

If you want to create a preset of your own, the same organization has a skeleton repository you can fork to make it easier.

Basic localization

So, how do we call for a translated string? There’s a helper function, __($key), that will pull the string for the current locale for the passed key or, if it doesn’t exist, grab it from the default locale. In Blade you can also use the @lang() directive. Example 6-20 demonstrates how a basic translation works. We’ll use the example of a “back to the dashboard” link at the top of a detail page.

// Normal PHP
<?php echo __('navigation.back'); ?>

// Blade
{{ __('navigation.back') }}

// Blade directive
@lang('navigation.back')

Let’s assume we are using the es locale right now. Laravel will look for a file in resources/lang/es/navigation.php, which it will expect to return an array. It’ll look for a back key on that array, and if it exists, it’ll return its value. Take a look at Example 6-21 for a sample.

// resources/lang/es/navigation.php
return [
    'back' => 'Volver al panel',
];

// routes/web.php
Route::get('/es/contacts/show/{id}', function () {
    // Setting it manually, for this example, instead of in a service provider
    App::setLocale('es');
    return view('contacts.show');
});

// resources/views/contacts/show.blade.php
<a href="/contacts">{{ __('navigation.back') }}</a>

Parameters in localization

The preceding example was relatively simple. Let’s dig into some that are more complex. What if we want to define which dashboard we’re returning to? Take a look at Example 6-22.

// resources/lang/en/navigation.php
return [
    'back' => 'Back to :section dashboard',
];

// resources/views/contacts/show.blade.php
{{ __('navigation.back', ['section' => 'contacts']) }}

As you can see, prepending a word with a colon (:section) marks it as a placeholder that can be replaced. The second, optional, parameter of __() is an array of values to replace the placeholders with.

Pluralization in localization

We already covered pluralization, so now just imagine you’re defining your own pluralization rules. There are two ways to do it; we’ll start with the simplest, as shown in Example 6-23.

// resources/lang/en/messages.php
return [
    'task-deletion' => 'You have deleted a task|You have successfully deleted tasks',
];

// resources/views/dashboard.blade.php
@if ($numTasksDeleted > 0)
    {{ trans_choice('messages.task-deletion', $numTasksDeleted) }}
@endif

As you can see, we have a trans_choice() method, which takes the count of items affected as its second parameter; from this it will determine which string to use.

You can also use any translation definitions that are compatible with Symfony’s much more complex Translation component; see Example 6-24 for an example.

// resources/lang/es/messages.php
return [
    'task-deletion' => "{0} You didn't manage to delete any tasks.|" .
        "[1,4] You deleted a few tasks.|" .
        "[5,Inf] You deleted a whole ton of tasks.",
];

Storing the default string as the key with JSON

One common difficulty with localization is that it’s hard to ensure there’s a good system for defining key namespacing—for example, remembering a key nested three or four levels deep or being unsure which key a phrase used twice in the site should use.

An alternative to the slug key/string value pair system is to store your translations using your primary language string as the key, instead of a made-up slug. You can indicate to Laravel that you’re working this way by storing your translation files as JSON in the resources/lang directory, with the filename reflecting the locale (Example 6-25).

// In Blade
{{ __('View friends list') }}

// resources/lang/es.json
{
  'View friends list': 'Ver lista de amigos'
}

This is taking advantage of the fact that the __() translation helper, if it can’t find a matching key for the current language, will just display the key. If your key is the string in your app’s default language, that’s a much more reasonable fallback than, for example, widgets.friends.title.