in Basset, Laravel, Our Authors

Basset – asset collections for Laravel

Introducing Laravel Basset (which stands for Better Asset Management) is a Gulp asset building system with integration for Laravel PHP framework.

Laravel Basset is inspired by Basset package for Laravel by Jason Lewis.

It comes with Browserify, ES6, SCSS, LESS, CoffeeScript, Autoprefixer, Livereload and Bower support included.

It uses very simple  collections configuration for assets. Collections are sets of JavaScript and stylesheet files that should be combined into one unit. Your website can use many collections like, for example, homepage collection, login collection, admin collection and whatever you need.

Quick start

To quickly start your project via Composer with Laravel and Basset setup, run:

composer create-project thelegacy/laravel your-project-name dev-master

After this just run npm install and your done. You can go ahead and build your application.

Or the longer way ….

Installation

Add gulp and laravel-basset npm package, using command:

npm install gulp laravel-basset --save

This will add gulp and laravel-basset package to your project.

In order to use this with Laravel you should install Laravel integration package with Composer, just run it from Terminal:

composer require thelegacy/basset

This will add PHP package for integration with Laravel. To complete installation with Laravel, go into your config/app.php and add this class to Service Providers:

  'Basset\BassetServiceProvider',

Now, you’re done and you should have everything installed for NodeJS and Laravel.

Usage

Create Gulpfile.js or edit Gulpfile that comes with Laravel 5.

Now you should add loading of collections configuration. You can put collections inline into Gulpfile.js or you can separate collections into collections.json file. Scanning of collections.json file can be added easily, inside Gulp file add this:

var basset = require('laravel-basset');

basset.loadFile('./collections.json');

Now just create a collections.json file and define collections in the collections.json file, for example like this:

{
    "collections": {
        "main": {
            "css": [
                "http://fonts.googleapis.com/css?family=Open+Sans",
                "main/homepage.css",
                "main/products.less"
            ],
            "js": [
                "main/homepage.coffee",
                "main/products.js"
            ]
        },
        "admin": {
            "css": [
                "admin/admin.less",
                "admin/admin-modals.css"
            ]
        }
    }
}

Here you can see two collections defined, the main collection and the admin collection. Also you can see that JavaScripts are put under js key and stylesheets are put under css key under each collection definition. You can also see that you can put external css or js files as well.

Build

To build these collections you just run:

gulp build

And it will build these files into public/builds directory by default. In there you can also see manifest.json file which is used by view helpers to identify which build files are used.

Usage in views

To use these built collections you can use @stylesheets and @javascripts helpers in Blade views, like this:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title></title>
  @stylesheets('main')
</head>
<body>

  ...

  @javascripts('main')
</body>
</html>

Or  use <?php echo basset_javascripts(‘main’) ?> or <?php echo basset_stylesheets(‘main’) ?> in simple PHP view.

This will output script or link tags for javascripts or stylesheets.

You can now see all the files that you included in your collection definition in your browser.

Watch mode

There is also a watch mode included so that whenever you change files build command is run. Watch watches files referenced in your collection definition.

To use Watch Mode, start:

gulp basset:watch

You can run this watch with Laravel Elixir watch, like this:

gulp watch basset:watch

This will start Watch Mode and you can modify files end see them when you reload your browser.

Livereload middleware

Watch Mode uses livereload by default, and to use livereload in your Laravel project you should add our Basset\Livereload middleware. Go into your app/Http/Kernel.php file and add:

  'Basset\Livereload'

To protected $middleware array. This will add Livereload snippet to every html response, but only on local environment.

Now whenever you change watched files, build is being run and your browser will automatically reload.

Build for production

To build collections for production environment run:

gulp production build

This will build collections for production environment and combine and minify all collection files.

This will result with a single css and single js file for every collection. So for the main collection you will get main-{SHA1}.css and a main-{SHA1}.js file with SHA1 hash of contents added to the name of files.

Basset is also Dotenv aware, so if you have APP_ENV=production in your .env file, then Basset will know that it needs to build for production.

Bower support

Basset has Bower support built-in, it can read your bower.json file and wire all your dependencies in. To add bower components you should go into folder of your collection, and install bower component.

In this example, collection name will be admin. You should add to your collections.json :

{
    "collections": {
        "admin": {
            "bower": "bower.json",
            "css": [
                "admin/admin.less",
                "admin/admin-modals.css"
            ]
        }
}

You can see that we added where the bower.json file is located, and for admin collection it will be at admin/bower.json location, and bower_components will be at admin/bower_components location.

Now when you add jQuery, or Bootstrap or any Bower component, main files of those components will be added to your collection. So you will never need to worry about including dependencies.

So for jQuery case, bower_component/jquery/dist/jquery.js will automatically be included.

Browserify

To enable Browserify support you need to set “browserify” : true in your collection definition. So for admin its going to look like:

{
    "collections": {
        "admin": {
            "browserify": true,
            "bower": "bower.json",
            "css": [
                "admin/admin.less",
                "admin/admin-modals.css"
            ]
        }
}

This will run browserify for this collection and by default it will look for index.js or main.js or admin.js as the main file for browserify. You can, of course, add your own.

And Watch Mode automatically runs Watchify already setup, so your Browserify builds will run much faster.

ES6

ECMA Script 6 is enabled when your turn on Browserify. It uses Babel (formerly 6to5) transpiler. So go ahead and use Classes, modules, and all the other es6 goodness.

Flowcheck.js

Flowcheck, runtime type checking is included when you use Browserify, so you can use optional types. Also it is only included in development mode.

ng-annotate

For users of AngularJS, by default, ng-annotate is run for production build, so all your dependency injection is properly minified.

Load path

Assets inside colllections by default can be put inside these three directories:

./
public/
assets/
resources/assets/

So when you refer to files inside collections these are the directories where Basset is going to look for files.

Also every collection name can have sub folder load path. So for admin collection load path will be:

./
./admin/
public/
public/admin/
assets/
assets/admin/
resources/assets/
resources/assets/admin/

Incremental builds

Build is run only on files that changed content, so you don’t have to wait for long builds. Whenever you change a single file, in most cases only that single file will be rebuilt.

Hjson

Basset uses Hjson for loading collection.json file, so you can use a more Human JSON like:

{
  collections: {
    blog: {
      browserify: true

      css: [
        type.less
        layout.less
        sidebar.less
      ]
    }
}

Without being annoyed by JSON syntax errors.

Source Code

Laravel Basset has two parts, NodeJS one and PHP one. So:

NodeJS laravel-basset: https://bitbucket.org/thelegacy/laravel-basset

PHP Basset: https://bitbucket.org/thelegacy/basset

Express integration is coming soon. More PHP Frameworks integrations coming soon.

Conclusion

Basset has Browserify, ES6, SCSS, LESS, CoffeeScript. It has separate Bower components dependecies for each collection.

It has Autoprefixer, Livereload, ng-annotate, UglifyJS, and Incremental builds for building and developing.

This is it! This is what we consider the best asset management for your Laravel project.

Follow up

How to use Font Awesome with Basset?

How to pass data to JavaScript with Basset?

Basset – auto .min swapping

Share this ...Tweet about this on TwitterShare on FacebookEmail this to someoneShare on RedditShare on Google+Share on LinkedInPin on Pinterest
  • Pingback: Basset - auto .min swapping - Legacy Blog()

  • Pingback: How to use Font Awesome with Basset? - Legacy Blog()

  • Pingback: How to pass data to JavaScript with Basset? - Legacy Blog()

  • pakuize

    I don’t know this seems like a waste of package, I do not really see anything here that elixir that comes with Laravel 5 can not do out of the box or am I missing something here?

    • Daniel V

      There are some cases where Basset is too much and you can just use Elixir.
      Basset has many features already built in, which work together, but with Elixir you have to setup everything by yourself.
      Basset has collection configuration which Elixir doesn’t have, so your scripts and styles are automatically being referenced by collection name and not by listing all the files in views by yourself.
      Basset has incremental builds which is a must for any big application (like aplications with hundreds of javascripts and stylesheets).
      Basset has isolated Bower dependencies on per collection basis, which is a must for incremental application upgrading.
      Basset has auto-min swapping, which is also a must for big applications.
      Basset knows your environment, so it runs faster builds for development mode and optimized builds for production environment.
      Development is easier with Basset because all your files are concatinated and minified only in production environment but not in development mode.
      There is also much less setup with Basset then Elixir, because Basset, has all the plugins setup for you, but with Elixir you have to figure out how best to combine the Elixir plugins for your application.
      I use both Basset and Elixir both for many applications, and Basset is used in production on several very large scale projects with several big teams working together (and this post is primarily written for them).
      If Elixir fits for you, then by all means use it, its just that for our needs Elixir is not enough.

      • pakuize

        Thank you for the clarification

  • Pingback: How to publish collection files with Basset? - Legacy Blog()

  • Pingback: How to setup Basset in Lumen Application? - Legacy Blog()

  • Pingback: Laravel Basset Status Update - Legacy Blog()

  • Pingback: 85% Faster Gulp Builds with Laravel Basset - Legacy Blog()