Borschik helps with remote static assets

10 March 2014

Last week I met the need to develop a web site which static assets have to be hosted on a different server and respond by different URLs than its HTML. This is the requirement to all the static files: stylesheets and JavaScript linked to the page as well as imges and fonts mentioned in HTML, CSS and JavaScript code. However it is obvious that these resources should be local when developing. Thus, the challenge was to introduce a piece of magic which knows where we aim to host the statics and transforms all the relative paths into absolute ones according to it.

The tools which helped me is called Borschik. The name is funny. Besides it reffers to a famous Russian/Ukranian soup, it also alludes to a word "сборщик" sborschik , and so might be translated as ~~ass~~embler. "Removing the ass part" as one of my friends says. :-)

In the varya/st-deliverer public repository you can find a stub project illustrating the solution.

Project structure

As you will be able to see later borschik is very flexible. So you can use any project structure. In my project I store everything in src folder. When building I get HTML files in dist/html directory. Check out the code and make sure that static files are linked from a different server by their absolute paths.

<html>
  <head>
    <title>Deliver static assets with Borschik</title>
    <link rel="stylesheet" href="http://varya.github.io/stor.../styles.css" />
  </head>
  <body class="page" background="http://varya.github.io/stor.../grungy.jpg">
    ...
  </body>
</html>

Open in your browser to enjoy my visual design and a tom-cat.

Bring borschik to your project

Borschik is an npm package. So, you can install it globally by runing

npm install -g borschik

I personally prefer local project dependencies, so my project has a package.json file:

{
  ...
  "dependencies": {
    "borschik": "0.4.2"
  },
  ...
}

Configuration

Before we start the magic transformation it is needed to instruct borschik what to transform and how to transform. The .borschik configuration file serves for that.

{
  "paths" : {
    "src/img/": "http://varya.github.io/stor.../st-deliverer/img/",
    "src/css/": "http://varya.github.io/stor.../st-deliverer/css/",
    "src/font/": "http://varya.github.io/storage/fonts/"

  }
}

Note that you can tune different replacements for different paths. Here I tried to illustrate with the fonts.

Run the command

Run borschik over a file which contains links to local static assets, and you will get the transformation result. For example,

./node_modules/borschik/bin/borschik \
  --input=src/css/styles.css

Fot the building process you will also need an --output flag to instruct borschik where to place the result.

Borschik knows the syntax of web technologies. It will not touch the links mentioned in text, for example.

Build system

Now you can use borschik in your project build process. I simply wrote a Makefile with a lot of help from @alexeyten (tnx!). There is also a grunt plugin megatolya/grunt-borschik.
Indeed, borschik is included into bem-tools and enb — the two competitive solutions for building the projects with BEM structure.

Result

Check the cat again. Still there?

You also can learn about other features of borschik from the article: http://bem.info/articles/borschik/.