Home Reference Source Repository

npm version Build Status document

Contents

A node.js scripts that help you to compile and deploy the static assets (CSS/JavaScript) of your website. More why here.

Features

JavaScript

Style sheet

Images

Package Features

Tasks

The tasks available at the moment are:

note: -> means in serial, | means in parallel

Configuration

General

Style

JavaScript

Image

note: all the config's path must ends with trailing slash

.Net website and Web.config

Version

If your your website is a .net website (so with a Web.config file) you can add a key to appSetting named swversion. When you run npm run bump or npm run deploy the version inside is upgraded automatically alongside package.json .

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="swversion" value="1.42.2" />
  </appSettings>
</configuration>

In this way you can track project version in your .net website easily (for example alongside error reporting). This is an example of how it could works with Sentry and Raven Client in an MVC website.

server-side:

protected void Application_Error(object sender, EventArgs e) {
    string v = ConfigurationManager.AppSettings["swversion"];
    string sentrykey = ConfigurationManager.AppSettings["sentry.keybackend"];
    var ravenClient = new RavenClient(sentrykey);
    System.Exception exe = Server.GetLastError();
    ravenClient.CaptureException(exe, sentryMessage,SharpRaven.Data.ErrorLevel.Error, new Dictionary<string, string>() { { "scope", "backend" } }, new { Release = v, Environment = enviroment });
    Response.Redirect("/Error/error");
    HttpContext.Current.ClearError();
}

client-side:

<html>
    <head></head>
    <body data-swversion='@ConfigurationManager.AppSettings["swversion"]'>
        <script src="https://cdn.ravenjs.com/3.0.5/raven.min.js"></script>
<script>
    Raven.config('...', {
        release: '@ConfigurationManager.AppSettings["swversion"]',
    }).install();
</script>
    </body>
</html>

Long-Term-Caching

If you want to use long term caching for js e CSS (more there) you can use longTermHash option. When so the build process try to update the relative keys inside Web.config with the hash of single file

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
        <add key="vendors" value="http://YOUR.CDN.DOMAIN/projectname/data/bundles/8f763123f0f046e64dba.js" />
        <add key="main" value="http://YOUR.CDN.DOMAIN/projectname/data/bundles/63ccb10c3a23c226a662.js" />
        <add key="vendors-backoffice" value="http://YOUR.CDN.DOMAIN/projectname/data/bundles/5f015639e77466a19e5d.js" />
        <add key="main-backoffice" value="http://YOUR.CDN.DOMAIN/projectname/data/bundles/5f015639e77466a19e5d.js" />
        <add key="modernizr" value="http://YOUR.CDN.DOMAIN/projectname/data/bundles/modernizr.45f645c83986c0f3e169.js" />
        <add key="main.css" value="http://YOUR.CDN.DOMAIN/projectname/css/38ef2f0c714372f9e033dad37e0cda84.css" />
        <add key="main-admin.css" value="http://YOUR.CDN.DOMAIN/projectname/css/970d7f6a3392de0876e3aa9fbf8e8d2e.css" />
  </appSettings>
</configuration>

and you can change your razor views in this way

<html>
    <head>
    @if (System.Diagnostics.Debugger.IsAttached) {
        <link rel="stylesheet" href="/css/main.css">
    } else {
        <link rel="stylesheet" href="@ConfigurationManager.AppSettings['main.css']">
    }
    </head>
    <body>
        @if (System.Diagnostics.Debugger.IsAttached) {
        <script src="http://localhost:8080/vendors.js" type="text/javascript"></script>
        <script src="http://localhost:8080/main.js" type="text/javascript"></script>
    } else {
        <script src="@ConfigurationManager.AppSettings['vendors']" type="text/javascript"></script>
        <script src="@ConfigurationManager.AppSettings['main']" type="text/javascript"></script>
    }
    </body>
</html>

Getting Started

Setup process of deployment-tools is quite easy - just run

npm install deployment-tools --save-dev

then you must copy the npm scripts that you want to use to your package.json file

{
    "scripts": {
        "lint": "babel-node tools/run lint",
        "clean": "babel-node tools/run clean",
        "buildCss": "cross-env NODE_ENV=production babel-node tools/run buildCss",
        "buildCss": "cross-env NODE_ENV=production babel-node tools/run buildCss",
        "buildJs": "cross-env NODE_ENV=production babel-node tools/run buildJs",
        "build": "cross-env NODE_ENV=production babel-node tools/run build",
        "bump": "babel-node tools/run bump",
        "deploy": "cross-env NODE_ENV=production babel-node tools/run deploy",
        "upload": "babel-node tools/run upload",
        "watch": "babel-node tools/run watch"
    }
}

and the relative confing settings to package.json file

{
    "config": {
        "domain": "http://YOUR.CDN.DOMAIN",
        "projectName": "project",
        "webConfig": "Web.config",
        "packageJson": "/package.json",
        "srcJsPath": "/script/",
        "mainJs": "main.js",
        "mainBackoffileJs": "main-backoffice.js",
        "buildPathJs": "/data/bundles/",
        "srcSassOUT": "/sass/",
        "srcLess": "/less/",
        "mainStyle": "main.less",
        "mainBackoffileStyle": "main-admin.less",
        "buildPathCss": "/data/css/",
        "preserveBuildPathCss": "true",
        "imagesPath": "/data/images/",
        "imagesCdnAlias": "http://your.cdn.domain.alias"
    }
}

Documentation

The documentation of the package can be generated via esDoc

npm run doc

Test

Tests can be run via

 npm test

TODO

License

Copyright (c) 2016 Alessandro Ursino (killanaca)

MIT (http://opensource.org/licenses/mit-license.php)