Add an Asset Pipeline to Laravel 4

Nov 04, 2013

Table of contents:

What is an asset pipeline?
Installing an asset pipeline in Laravel 4
Working with the asset pipeline
Using Sass in your Laravel application
Configuration options
Conclusion

It’s no secret that much of Laravel 4 has been inspired by Ruby on Rails. Rails is a mature and well used framework that is used on some of the biggest and most popular websites and applications on the Internet, and so it makes sense that Laravel would be inspired by the best bits of a really great framework.

However, one notable thing that is missing from Laravel 4 is a way of handling your asset pipeline. An asset pipeline is how the framework handles your CSS or Javascript assets so that they are served to the browser in the most efficient way possible.

Laravel 4 might not ship with this out of the box, but we can always install a community package to get the fantastic functionality in our projects.

In this article I’m going to run through why you should use an asset pipeline and how to set one up.

If you are new to the concept of an asset pipeline, don’t worry, you’ll never want to go back after reading this!

What is an asset pipeline?

So before I get into trying to convince you why you should be using an asset pipeline, first I should probably explain what exactly it is.

When you serve a website over the Internet, the browser has to retrieve all of the assets that make up the page. So for each CSS or Javascript file, the browser needs to make a separate request.

Your CSS and Javascript files can also start to become pretty heavy over time, especially if you are working on a big site.

The asset pipeline will automatically combine all of your asset files into a single file and minify the code into one file. This means that the browser only has to make one request, and the size of the file can be greatly reduced. This will have a big impact on the performance of your website.

Many developers these days also write their CSS using a preprocessor like LESS or Sass or they prefer to use CoffeeScript rather than Javascript. Your asset pipeline will automatically compile all your code into regular CSS or Javascript.

And finally, if all those reasons weren’t enough, your asset pipeline will also automatically cache your stylesheets or Javascript files when in the production environment. This means that those files won’t be download each time the page loads if nothing has changed.

So hopefully you can see the many reasons why you should be using an asset pipeline. Even if you don’t want to use a preprocessor or if you just want to use vanilla Javascript, an asset pipeline still has a lot of great benefits.

Installing an asset pipeline in Laravel 4

I’m going to be using this asset pipeline package in Cribbb as it looks to be fairly heavily inspired by what is already available in Rails.

So to install the package, simply add the following line to your composer.json file:

{
    "require": {
        "codesleeve/asset-pipeline": "dev-master"
    }
}

Next, run the following command to update your dependancies and pull in the asset pipeline package:

$ composer update

Next, we need to let Laravel know about the service provider. Add the following line to your app file under app/config:

"Codesleeve\AssetPipeline\AssetPipelineServiceProvider";

Next, the asset pipeline will behave differently depending on what environment it is currently in. In the production environment, all your files will be compressed, concatenated and cached. However, you probably don’t want that to happen when developing locally as it will make debugging problems or refreshing changes difficult.

To ensure that Laravel is set to the correct environment, make sure you have set the ‘local’ environment under bootstrap/start.php:

$env = $app->detectEnvironment([
    "local" => ["localhost"],
]);

Finally, we need to generate our asset files. Run the following command from Terminal:

$ php artisan assets:setup

Working with the asset pipeline

So now that you have the asset pipeline installed and you have run the assets generate command, you should notice that you have some new directory structures in your project.

Under app/ you should see a new folder called assets. In this folder there should be two more folders named stylesheets and javascripts.

If you go into one of those folders you should see a file named application.css or application.js.

These two files are known as your manifest files. You use these files to include all your other asset files so that the output is a single file.

By default this file will automatically include any other files within the same directory.

To include the asset files within your HTML template, you can add the following two tags:

<?= stylesheet_link_tag() ?>
<?= javascript_include_tag() ?>

These tags will automatically generate the correctly link and script tags for your HTML output:

<link
  rel="stylesheet"
  type="text/css"
  href="https://localhost:8000/assets/application.css"
/>
<script src="https://localhost:8000/assets/application.js"></script>

Note: When you are in the local environment, you will notice that all of your asset files will be included individually. This is to make developing easier. Once you are in the production environment, all of your assets will be concatenated into one. You don’t have to make any changes for this behaviour to occur.

Using Sass in your Laravel application

My preprocessor of choice is Sass. If you are unfamiliar with Sass, checkout my introductory tutorial Getting started with Sass.

To use Sass with the asset pipeline, all you have to do is to create a new Sass file under the stylesheets directory. For this example I’m going to be calling my file main.css.scss. Notice how the file has a double extension? This is a Rails convention that this package automatically adopts. You can turn this off in the configuration if you don’t like it.

Next, write some Sass:

body {
  a {
    color: red;
  }
  &:hover {
    color: green;
  }
}

Here I’m simply writing a little bit of Sass that will compile down into regular CSS.

Next, fire up the server and take a look at your stylesheet in the browser, you should see the following output:

body a {
  color: red;
}
body:hover {
  color: green;
}

As you can see, the asset pipeline has automatically included our Sass file and compiled it into regular CSS!

Configuration options

This asset pipeline package also enables you to configure it until your heart is content.

To enable the configuration, run the following command in Terminal:

php artisan config:publish codesleeve/asset-pipeline

This will generate your own project specific configuration file that will allow you to override the default settings. It’s important to configure the package this way so whenever you pull in new updates using Composer, you don’t overwrite your settings.

Now if you look under app/config/packages you will find your config file that you can edit. For a more detailed explanation of each of the configuration options, take a look at the documentation.

Conclusion

Dealing with front-end assets and keeping things organised is a massive part of developing a robust and powerful application. It’s easy to think that all of the server side code is what is important, but in reality, your front-end code is probably going to change a lot more.

Using an asset pipeline is a really good idea because it enables you to structure your front-end assets using a much more “object oriented” approach. Using a preprocessor like Sass allows you to split up your CSS files into individual components that makes maintaining them and working with other developers much easier.

An asset pipeline is something that you set up once and never have to think about again. It will also make your life much easier. If you have never used an asset pipeline in your projects, I would urge you to give it a go.

This is a series of posts on building an entire Open Source application called Cribbb. All of the tutorials will be free to web, and all of the code is available on GitHub.