Last updated: September 23rd 2024
Framework versions tested: 2.4.8 ● 4.4.5 ● 5.0.0 ● 6.2.9 ● 7.3.9 ● 7.3.10 ● 10.1.0 ● 17.3.7 ● 18.2.1
Github: Angular repository
Angular is a TypeScript-based open-source front-end web application platform developed by Google. Started with angularJS or 1.x version then a complete rewrite was made known as Angular2 or just Angular. Later it was improved with the 4 version. On November 1, 2017, the 5th version named Angular5 was released introducing even many more improvements to the older versions.
The purpose of this document is to explain how to integrate Jscrambler with Angular2 and above versions. Fortunately, you can use the same process independently of the Angular version.
This document assumes you already have some knowledge of the framework and how to build a project. Still, if you have any doubt please read this official quickstart.
If you haven't tried jscrambler before, please consider reading the getting started guide which will walk you through the steps on how to protect your application. It will also teach you how to configure Jscrambler and use a custom configuration.
To complete the integration with Jscrambler you need a JSON configuration file with your API credentials, application ID, and protection configuration. You may create your transformations recipe using Jscrambler Web application and download a JSON configuration file or use the following example for a quick test. If you choose to try the following example, just make sure to fill the missing information: accessKey, secretKey and applicationId.
{
"keys": {
"accessKey": <ACCESS_KEY>,
"secretKey": <SECRET_KEY>
},
"applicationId": <APPLICATION_ID>,
"filesSrc": [
"./dist/**/*.html",
"./dist/**/*.js",
"./dist/**/*.mjs" // (line of code not needed for angular 18 app)
],
"filesDest": "./",
"params": [
{
"name": "whitespaceRemoval"
},
{
"name": "identifiersRenaming",
"options": {
"mode": "SAFEST"
}
},
{
"name": "dotToBracketNotation"
},
{
"name": "deadCodeInjection"
},
{
"name": "stringConcealing"
},
{
"name": "functionReordering"
},
{
"options": {
"freq": 1,
"features": [
"opaqueFunctions"
]
},
"name": "functionOutlining"
},
{
"name": "propertyKeysObfuscation"
},
{
"name": "regexObfuscation"
},
{
"name": "booleanToAnything"
}
],
"areSubscribersOrdered": false,
"useRecommendedOrder": true,
"sourceMaps": false
}
When using the webpack plugin remove the filesDest and filesSrc fields. The source and the destination are instead defined in the webpack configuration file.
As a final note, please make sure you have the option tolerateBenignPoisoning checked when using Self Defending to protect your Angular app.
Below, you can find three examples of apps that you can use to make quick tests or use as boilerplate.
Integrating Jscrambler in your build process can be accomplished in different ways but for now, we will focus on the Angular CLI and webpack, always using the .jscramblerrc file on the root of your project. This file has the same content as the json configure file we discussed before and can be passed as an argument to the Jscrambler client or be placed in the application root folder with the name .jscramblerrc. Your personal ids will be in this file so make sure you do not upload it to public repositories.
One way to build your angular application is using the Angular CLI.
In this section, we will show all the steps needed to make a simple integration of the Jscrambler client. If you do not have an app, you can check all the steps on the boilerplate apps that have Jscrambler already integrated. You can also create a new angular 5 application through Angular CLI app. If you need more information the Angular quickStart will help you through the process.
To apply your integration, first, make sure you already have the .jscramblerrc file in the root of the project because the Jscrambler client will be looking for it if there's no configuration file passed as an argument.
Second, insert Jscrambler client as a development dependency by running the command: npm i --save-dev jscrambler.
For the final step, we recommend that you create a new entry in the package.json scripts where you call the Angular build process in production mode. The Jscrambler client will process all the files you defined in the configuration file. For example, if you insert this line:
"build:prod" : "ng build && jscrambler"
Every time you need to build your application for production you only need to type:
npm run build:prod
There you go. Jscrambler is now integrated in your build process.
Note: You can also transform your angular-cli process build into a webpack build process using a single command:
ng eject
This will generate webpack.config.js in the root folder of your project and you're free to configure it the way you want. In order to add Jscrambler into webpack config, see the next section.
We also give you the option to integrate Jscrambler in a webpack build process. Integrating Jscrambler in your application can be as simple as including our jscrambler-webpack-plugin in your webpack.config.js file or similar.
Begin by adding our webpack plugin to your development dependencies:
npm i --save-dev jscrambler-webpack-plugin
Then in your production webpack configuration file (e.g. webpack.prod.js) insert the Jscrambler plugin in the build process importing the package with the line:
var JscramblerWebpack = require('jscrambler-webpack-plugin');
and in the plugin array add the following line:
new JscramblerWebpack({
enable: true, // optional, defaults to true
chunks: ['app'] // optional, defaults to all chunks
// and other jscrambler configurations
})
The Jscrambler client will use .jscramblerrc as usual, though it is possible to override specific values using the plugin's configuration.
It is important to note that by default the webpack plugin will protect your entire bundle, including dependencies. Thus we separate them into a different chunk called vendor. Those chunks were defined in the webpack.common.js file, specifically in the entry field if you are using our example angular webpack boilerplate, or in the webpack.config.js file if you used the ng eject command and haven’t created a production webpack file. By doing this, we can enter the chunk that contains only our code into the chunks argument of the jscrambler plugin which will speed up your build times dramatically. If you want to protect some special external library we recommend that you create a different chunk for them or include it in the app chunk.
The final step is running your build process in production mode using the webpack command line with the flag -p or defining the production configuration file. You can also create a script that can call your production build. In the example, we added the following line to the package.json script field.
"build:prod":"webpack --bail --config webpack.prod.js"
With this steps your application will be protected by Jscrambler every time you run the script.
When using the webpack plugin, you can use the NoEmitOnErrorsPlugin option to force webpack to exit its bundling process in case of error. Otherwise, use the --bail option on the jscrambler CLI.
If you’re using the Self Defending transformation, make sure you activate the tolerateBenignPoisoning like in the example below:
{
"name": "selfDefending",
"options": {
"options": [
"tolerateBenignPoisoning"
]
}
}