Quickstart

Introduction

This is a Python module to interface with the JScrambler javascript transformation service. The Python module offers a trivally simple API to transform you javacsript and html files.

Installation

This module has been tested to work in both Python 2.7 and 3.4. The only non-standard Python dependency is the requests module.

To install jscrambler, simply install the jscrambler package from PyPI. You can use, pip, for instance:

$ pip install jscrambler

Credentials

To use jscrambler, you need to subscribe to the server and obtain access credentials to use the server. Get your API credentials at https://jscrambler.com/en/account/api_access. There you will see two values, Access key and Secret key, which allow you to submit projects.

Configuration file

It is easier if you create a json configuration file, such as this one (let’s call it config.json):

{
    // acess credentials, replace with your own
    "keys": {
        "accessKey": "YOUR_ACCESS_KEY",
        "secretKey": "YOUR_SECRET_KEY"
    },

    // where to find the source .js files
    "filesSrc": ["lib/**/*.js"],

    // directory where to place the modified files
    "filesDest": "build/",

    // parameters that control the transformations available
    "params": {
        "function_outlining": "true",
        "rename_all": "true"
    }
}

Minimal python code

Here’s some sample python code to process some files, assuming that the output build directory is already created:

import jscrambler
import json

# reads the json configuration file
with open("config.json", "rt") as jsonfile:
    config = json.load(jsonfile)

# creates a jscrambler client context
client = jscrambler.Client(config["keys"]["accessKey"],
                           config["keys"]["secretKey"])

# processes the files specified in the configuration
client.process(config)

Django integration

Although jscrambler can be integrated with any web framework in any programming language, the jscrambler python package comes with some support for Django projects out of the box.

If you have a Django project that uses the standard django.contrib.staticfiles application to support static files, then you already know about the STATIC_ROOT django setting. This setting contains the path of a directory to which all the static files will be collected. This is triggered by running the command python manage.py collectstatic when you want to deploy new static files into an HTTP server, such as nginx or apache httpd.

To add jscrambler into the workflow, you begin by adding the djcrambler configuration to the Django project settings (myproject/settings.py):

JSCRAMBLER_CONFIG = { my config }

The JSCRAMBLER_CONFIG setting has to contain dict based structure with the usual jscrambler configuration parameters. If you wish, you can easily load it from an external JSON file, thus:

import json
with open("config.json", "r") as configfile:
    JSCRAMBLER_CONFIG = json.load(configfile)

Another change in the Django settings that you need is to add jscrambler to the INSTALLED_APPS:

INSTALLED_APPS = (
   'django.contrib.staticfiles',
   #...
   'jscrambler', # <--- add this app to your project
)

After these changes, you will get a new Django management command called scramblestatic. This command, which should run after collectstatic, takes all files matching any of the filesSrc patterns from the config, relative to STATIC_ROOT, and replace them in-place with the scrambled versions:

$ python manage.py collectstatic
$ python manage.py scramblestatic

Note

if the config parameter filesSrc is missing, it defaults to **/*.js and **/*.html, which matches all Javascript and HTML files found under STATIC_ROOT.

There is no out-of-the-box support for processing Django templates yet, so you should make sure to write your valuable Javascript code that you wish to protect as clearly separated static files, instead of placing it inside Django templates.

Warning

If you have a setup in which the HTTP server is serving static files directly from STATIC_ROOT, then running the commands collectstatic and scramblestatic while the HTTP server is running will temporarily expose your original sources to the Internet. Therefore, it is recommanded that your STATIC_ROOT points to a temporary directory, which replaces the live one only after the scramblestatic command is finished.