Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lasso-js/lasso

Advanced JavaScript module bundler, asset pipeline and optimizer
https://github.com/lasso-js/lasso

Last synced: 1 day ago
JSON representation

Advanced JavaScript module bundler, asset pipeline and optimizer

Awesome Lists containing this project

README 

        
Lasso.js

==================



[![Build Status](https://travis-ci.org/lasso-js/lasso.svg?branch=master)](https://travis-ci.org/lasso-js/lasso)

[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/lasso-js/lasso)



Lasso.js is an eBay open source Node.js-style JavaScript module bundler that also provides first-level support for optimally delivering JavaScript, CSS, images and other assets to the browser.



This tool offers many different optimizations such as a bundling, code splitting, lazy loading, conditional dependencies, compression and fingerprinted resource URLs. Plugins are provided to support pre-processors and compilers such as Less, Stylus and [Marko](https://github.com/raptorjs/marko). This developer-friendly tool does not require that you change the way that you already code and can easily be adopted by existing applications.



# Example



Install the command line interface for Lasso.js:



```text

npm install lasso-cli --global

```



Install a helper module from npm:



```text

npm install change-case

```



Create the main Node.js JavaScript module file:



__main.js:__



```javascript

var changeCase = require('change-case');

console.log(changeCase.titleCase('hello world')); // Output: 'Hello World'

```



Create a StyleSheet for the page:



__style.css__



```css

body {

    background-color: #5B83AD;

}

```



Create an HTML page to host the application:



__my-page.html:__



```html



    

    Lasso.js Demo



    
Lasso.js Demo



```



Run the following command:



```bash

lasso style.css \

    --main main.js \

    --inject-into my-page.html

```



Output:



```text

Output for page "my-page":

  Resource bundle files:

    static/my-page-9ac9985e.js

    static/my-page-1ae3e9bf.css

  HTML slots file:

    build/my-page.html.json

  Updated HTML file:

    my-page.html

```



Open up `my-page.html` in your web browser and in the JavaScript console you will see the output of our program running in the browser, as well as a page styled by `style.css`.



As you can see, with Lasso.js you no longer have to struggle with managing complex build scripts. Simply let Lasso.js worry about generating all of the required resource bundles and injecting them into your page so that you can just focus on writing clean and modular code.



There's also a JavaScript API, taglib and a collection of plugins to make your job as a front-end web developer easier. Please read on to learn how you can easily utilize Lasso.js in your application.



# Table of Contents



- [Design Philosophy](#design-philosophy)

- [Features](#features)

- [Another Client-side Bundler?](#another-client-side-bundler)

- [Installation](#installation)

- [Usage](#usage)

	- [Command Line Interface](#command-line-interface)

	- [JSON Configuration File](#json-configuration-file)

	- [Dependencies](#dependencies)

		- [External Dependencies](#external-dependencies)

		- [Dependency Attributes](#dependency-attributes)

		- [Conditional Dependencies](#conditional-dependencies)

		- [Enabling Flags](#enabling-flags)

	- [Asynchronous/Lazy Loading](#asynchronouslazy-loading)

	- [Using the JavaScript API](#using-the-javascript-api)

		- [Configuring the Default Lasso](#configuring-the-default-lasso)

		- [Optimizing a Page](#optimizing-a-page)

		- [Creating a New Lasso](#creating-a-new-lasso)

	- [Lasso.js Taglib](#lassojs-taglib)

		- [Using Lasso.js Taglib with Marko](#using-lassojs-taglib-with-marko)

		- [``](#)

	- [Client/Server Template Rendering](#clientserver-template-rendering)

	- [Runtime Optimization with Express](#runtime-optimization-with-express)

	- [Bundling](#bundling)

	- [Code Splitting](#code-splitting)

- [Configuration](#configuration)

	- [Default Configuration](#default-configuration)

	- [Complete Configuration](#complete-configuration)

- [Node.js-style Module Support](#nodejs-style-module-support)

- [Babel Support](#babel-support)

- [No Conflict Builds](#no-conflict-builds)

- [Custom attributes for Script & Style tags](#custom-attributes-for-script--style-tags)

    - [Use of defer/async with script tags](#use-of-deferasync-with-script-tags)

- [Content Security Policy Support](#content-security-policy-support)

- [Available Plugins](#available-plugins)

- [Extending Lasso.js](#extending-lassojs)

	- [Custom Plugins](#custom-plugins)

	- [Custom Dependency Types](#custom-dependency-types)

		- [Custom JavaScript Dependency Type](#custom-javascript-dependency-type)

		- [Custom CSS Dependency Type](#custom-css-dependency-type)

		- [Custom Package Type](#custom-package-type)

	- [Custom Output Transforms](#custom-output-transforms)

- [JavaScript API](#javascript-api)

- [AMD Compatibility](#amd-compatibility)

- [Sample Projects](#sample-projects)

- [Discuss](#discuss)

- [Maintainers](#maintainers)

- [Contributors](#contributors)

- [Contribute](#contribute)

- [License](#license)



# Design Philosophy



* Dependencies should be **declarative** _or_ discovered via **static code analysis**

* Common **module loading** patterns should be supported

* Must be **extensible** to support all types of resources

* **Maximize productivity** in development

* **Maximize performance** in production

* Must be **easy to adopt** and not change how you write your code

* Can be used at **runtime or build time**

* Must be **configurable**



# Features



* Bundle Client-side Dependencies

    * Supports all types of front-end resources (JavaScript, CSS, images, Less, CoffeeScript, etc.)

    * Asynchronous/lazy loading of JS/CSS

    * Configurable resource bundling

    * Code splitting

    * JavaScript minification

    * CSS minification

    * [Fingerprinted](https://developers.google.com/web/fundamentals/performance/optimizing-content-efficiency/http-caching) resource URLs

    * Prefix resources with CDN host name

    * Optional Base64 image encoding inside CSS files

    * Custom output transforms

    * Declarative browser-side package dependencies using simple `browser.json` files

	* endencies

	* Image minification

    * etc.

* Browser-side Node.js Module Loader

    * Full support for [Isomorphic JavaScript](http://nerds.airbnb.com/isomorphic-javascript-future-web-apps/)

    * Conflict-free CommonJS module loader for the browser

    * Complete compatibility with Node.js

        * Supports `module.exports`, `exports`, `require`, `require.resolve`, `__dirname`, `__filename`, `process`, etc.

    * Supports the [package.json `browser` field](https://gist.github.com/defunctzombie/4339901)

    * Full support for [browserify](http://browserify.org/) shims and transforms

    * Maintains line numbers in wrapped code

* Developer Friendly

    * Generates the HTML markup required to include bundled resources

    * Disable bundling and minification in development

    * Line numbers are maintained for Node.js modules source

    * Extremely fast _incremental builds_!

        * Only modified bundles are written to disk

        * Disk caches are utilized to avoid repeating the same work

* Dependency Compilation

    * Less

    * [Marko](https://github.com/marko-js/marko)

    * Dust

    * etc.

* Extensible

    * Custom dependency compilers

    * Custom code transforms

    * Custom bundle writers

    * Custom plugins

* Configurable

    * Configurable resource bundles

    * Enable/disable transforms

    * Development-mode versus production-mode

    * Enable/disable fingerprints

    * etc.

* Flexible

    * Integrate with build tools

    * Use with Express or any other web development framework

    * JavaScript API, CLI and taglib

* Security

    * Supports the [nonce attribute](https://www.w3.org/TR/CSP2/#script-src-the-nonce-attribute) when using Content Security Policy for extra security.

* _Future_

    * Automatic image sprites



# Another Client-side Bundler?



[Browserify](http://browserify.org/) is an excellent JavaScript module bundler. We are huge supporters of writing Node.js-style modules (i.e. CommonJS), and we also believe [npm](https://www.npmjs.org/) is an excellent package manager. If you are not using a JavaScript module bundler then you are absolutely missing out. Modularity is equally important for client-side code as it is for server-side code, and a JavaScript module bundler should be part of every front-end developer's toolbox.



So why did we create Lasso.js if Browserify is such a great tool? We created Lasso.js because we wanted a top-notch JavaScript module bundler that _also_ provides first-level support for transporting CSS, "plain" JavaScript, images, fonts and other front-end assets to the browser in the most optimal way. In addition, we want to enable developers to easily create web applications that follow [widely accepted rules for creating faster-loading websites](http://stevesouders.com/examples/rules.php) (such as putting StyleSheets at the top, and JavaScript at the bottom). We also want to allow for developers to easily load additional JavaScript and StyleSheets after the initial page load.



While high performance is very important for production systems, we want to also provide a more developer-friendly experience by offering fast, incremental builds, simplifying development and by producing debuggable output code. And, of course, we do not want developers to have to learn how to code their applications in a new way so Lasso.js was built to not change how you already code. You'll even find support for Browserify shims and transforms. Therefore, if you try out Lasso.js and it is not the tool for you, then feel free to switch back to something else (it'll of course be ready if your application's requirements change in the future). eBay and other large companies rely on Lasso.js for delivering high performance websites and are committed to its success. If you try it out and find gaps, please let us know!



# Installation



The following command should be used to install the `lasso` module into your project:



```bash

npm install lasso --save

```



If you would like to use the available command line interface, then you should install the [lasso-cli](https://github.com/lasso-js/lasso-cli) module globally using the following command:



```bash

npm install lasso-cli --global

```



# Usage



## Command Line Interface






[__Sample App:__](https://github.com/lasso-js-samples/lasso-cli) To try out and experiment with the code, please see the following project:
[lasso-js-samples/lasso-cli](https://github.com/lasso-js-samples/lasso-cli)






Install the command line interface for Lasso.js:



```bash

npm install lasso-cli --global

```



In an empty directory, initialize a new Node.js project using the following command:



```bash

mkdir my-app

cd my-app

npm init

```



Install required modules into the new project:



```bash

npm install jquery

npm install lasso-less

```



Create the following files:



__add.js:__



```javascript

module.exports = function(a, b) {

    return a + b;

};

```



__main.js:__



```javascript

var add = require('./add');

var jquery = require('jquery');



jquery(function() {

    $(document.body).append('2+2=' + add(2, 2));

});

```



__style.less:__



```css

@headerColor: #5B83AD;



h1 {

    color: @headerColor;

}

```



__my-page.html:__



```html



    

    Lasso.js Demo



    
Lasso.js Demo



```



Finally, run the following command to generate the resource bundles for the page and to also inject the required `` and `<link>` tags into the HTML page:



```bash

lasso style.less \

    --main main.js \

    --inject-into my-page.html \

    --plugins lasso-less \

    --development

```



If everything worked correctly then you should see output similar to the following:



```text

Output for page "my-page":

  Resource bundle files:

    static/add.js

    static/raptor-modules-meta.js

    static/main.js

    static/node_modules/jquery/dist/jquery.js

    static/raptor-modules-1.0.1/client/lib/raptor-modules-client.js

    static/style.less.css

  HTML slots file:

    build/my-page.html.json

  Updated HTML file:

    my-page.html

```



The updated `my-page.html` file should be similar to the following:



```html

<!doctype html>

<html lang="en">

<head>

    <meta charset="UTF-8">

    <title>Lasso.js Demo</title>

    <!-- <lasso-head> -->

    <link rel="stylesheet" href="static/style.less.css">

    <!-- </lasso-head> -->

</head>

<body>

    <h1>Lasso.js Demo</h1>

    <!-- <lasso-body> -->

    <script src="static/raptor-modules-1.0.1/client/lib/raptor-modules-client.js">

    

    

    

    

    $_mod.ready();

    



    
Lasso.js Demo


    

    

    $_mod.ready();

    

 sections of a page...

    });

```



### Creating a New Lasso



```javascript

var myLasso = lasso.create(config);

myLasso.lassoPage(...);

```



## Lasso.js Taglib






[__Sample App__](https://github.com/lasso-js-samples/lasso-taglib) To try out and experiment with the code, please see the following project:
[lasso-js-samples/lasso-taglib](https://github.com/lasso-js-samples/lasso-taglib)






For the ultimate in usability, a taglib is provided for Marko (and Dust) to automatically lasso a page _and_ inject the required HTML markup to include the JavaScript and CSS bundles.



If you are using [Marko](https://github.com/marko-js/marko) you can utilize the available taglib for Lasso.js to easily lasso page dependencies and embed them into your page.



### Using Lasso.js Taglib with Marko



1. `npm install lasso --save`

2. `npm install marko --save`



You can now add the lasso tags to your page templates. For example:



```marko



    

    Test Page

    



    
Test Page


    



```



You will then need to create an `browser.json` in the same directory as your page template. For example:



_browser.json_:

```json

{

    "dependencies": [

        "./jquery.js",

        "./foo.js",

        "./bar.js",

        "./style.less"

    ]

}

```



Using Marko and Lasso.js taglib, you can simply render the page using code similar to the following:



```javascript

var template = require('marko').load('my-page.marko');

template.render({}, function(err, html) {

    // html will include all of the required  and  tags

});

```



The output of the page rendering will be similar to the following:



```html

<!doctype html>

<html lang="en">

<head>

    <meta charset="UTF-8">

    <title>Test Page</title>

    <link rel="stylesheet" href="/static/my-page-85e3288e.css">

</head>

<body>

    <h1>Test Page</h1>

    <script src="/static/bundle1-6df28666.js">

    

    



        

        

        

            console.log('hello-inline');

        

    

        

    



        

        

            (function() { var run = function() { console.log('hello-inline'); }; if (document.readyState === "loading") { document.addEventListener("DOMContentLoaded", run); } else { run(); } })();