Installation

On your terminal, run any of the below commands to globally install the latest trakk-js NPM package :
yarn global add trakk-js

or

npm install -g trakk-js
After the installation has been completed, you may check the installed version by running:
trakkjs -v

Configuration

Inside your application's local root folder create a trakk.config.json as shown in the example below:
{
    /* a valid Trakk.js API key */
    "key": "3b2b21f3-9c99-40f4-b7c4-2f358216776c",

    /* 
      * The command you use to start your app locally, 
      * from within your app's root folder
      */
    "start": "react-scripts start",

    /*
      * A list of globs to folders and/or files to trakk
      *
      * This field is optional
      *
      * By default, all .js, .jsx, .ts & .tsx files in your app 
      * will be trakked across all folders
      */
    "include": ['/my-app/**'],

    /*
      * A list of globs to folders and/or files to not trakk
      *
      * This field is optional
      *
      * By default, everything under /node_modules will be ignored, always
      */
    "exclude": ['/dist/**', '/tests/**', '/mirage/factories/**', '/path/to/my-file.js'],

    /*
      * This field is optional
      *
      * Its default value is `false`
      * 
      * Meaning that, by default, when clicking on the Trakk.js toggle button, the Trakk UI Panel
      * will slide-in providing you with a complete UI you can interact with:
      * 
      * - you can view all trakked events in real-time
      * - ignore the ones you are not interested in
      * - view all relevant stats
      * - generate documentation with a single click
      * 
      * However, for large-scale applications, if the events being trakked start to become too many (10000+) at some point, 
      * it is possible that the real-time UI Panel's responsiveness might start to slow down. 
      * 
      * The UI Panel will continue to function as expected but it might take longer for new events to be loaded and rendered in the UI.
      * 
      * If you are interested in only generating documentation automatically,
      * setting this property to true, will load the Trakk.js toggle button on your app,
      * but clicking on it will not load the Trakk.js real-time UI Panel.
      * 
      * Instead it will immediately generate documentation for you and save it locally.
      * 
      */
    "light": true,

    /*
      * This field is optional
      *
      * Its default value is `false`
      * 
      * Meaning that, by default, if your application happens to throw an Error
      * and your application is not set up to catch it, the error will be thrown and
      * your application's flow might break.
      * 
      * The uncaught Error will be trakked and reported under the "Uncaught Errors" section of the Trakk.js UI
      * 
      * If, however, you choose to set `"catchUncaughtErrors": true`,
      * then any unexpected errors thrown by your application, will, instead, be caught by Trakk.js,
      * thus preventing your application from possibly breaking its flow.
      * 
      * The Error will still be trakked and reported under the "Uncaught Errors" section of the Trakk.js UI
      * 
      * Depending on your needs, you might, or might not, desire to set `"catchUncaughtErrors": true`
      * 
      */
    "catchUncaughtErrors": true
}

Fonts


If you would like the Trakk.js UI Panel, that loads on top of your application locally, to use its own fonts, make sure your application's Content Security Policy allows requests to https://*.googleapis.com and https://*.gstatic.com

Attention : Trakk.js API Requests


Allow Requests to https://trakkjs.com

Make sure your application's Content Security Policy allows requests to https://trakkjs.com
Otherwise the Trakk.js UI Panel won't be able to load on your application.

Allow Requests to http://localhost:*/trakk-js-api/*

Make sure your application's Content Security Policy allows requests
either to :
http://localhost:*
or :
http://*/*/local-trakk-js-api/
Otherwise, the Trakk.js UI Panel won't be able to function properly.

How To Use It

* Please read our README for extensive details on how to use the Trakk.js UI and what it offers

Starting Trakk

After you have completed the installation and set up your trakk.config.json , go to your application's local root folder and run:
trakkjs
Once trakk.js has finished preparing your application, your application will then start locally
You can now visit your application on your browser
When you visit your application a  trakk.js  toggle will appear in the middle of the right side of your window. Once you click on it, the Trakk.js UI Panel will slide in and you can then start using it.
Everytime you make a change to your application, Trakk.js will automatically restart

What we trakk

* Please read our README for extensive details on how to use the Trakk.js UI and what it offers

Web Application Frameworks

Trakk.js is framework agnostic
It will run on any application that contains .js , .jsx , .ts or .tsx files
All you need to do is provide Trakk.js with a trakk.config.json file and it will do the rest

Trakking Function Calls

Trakk.js will trakk all function calls found in any .js , .ts, .jsx or .tsx files across the whole of your application, unless you tell it otherwise in your trakk.config.json
All files found inside any /node_modules folders will always be ingored

Trakking Errors

Trakk.js will trakk All Uncaught Errors thrown by your application, that your application failed to catch

Trakking Requests

Trakk.js will trakk all of the following types of requests:
XMLHttpRequest
Fetch
jQuery Ajax
navigator.sendBeacon()
axios
Fake Requests [  performed by Pretender.js or any request whose window.XMLHttpRequest.name is fakerequest (case-insensitive)  ]

Trakking User Interactions

Trakk.js will trakk all of the following user interactions & take screenshots of them:
click events on <a> , <button> & <label> elements
change events on <input> & <select> elements
submit events on <form> elements

FAQ

Does trakk.js modify any of the folders, files or code found on the device where Trakk.js is used?

No, Trakk.js never modifies any of the folders, files or code found on the device where Trakk.js is used.

Does Trakk.js send and/or store any of the files, code or other information found on the device where Trakk.js is used, to a remote server?

No, trakk.js, never sends any of the files, code or other information found on the device where Trakk.js is used, to any remote server.
Trakk.js, will make one call to its remote server, using the key you provided in your trakk.config.json, in order to fetch the script that will load the Trakk UI Panel onto your application.
Trakk.js, will occasionally send anonymous error reports to its remote server in order to improve your user experience. The error reports will include your API key, in order to avoid malicious error reporting, but no other information stored on your device (nor any of your code).