# Instrument a Front-End App

The SeaLights Node.js agent can be used to instrument the Front-end code as well.

{% hint style="info" %}
See '[Generating an Agent token](https://docs.sealights.io/knowledgebase/settings/token-access-and-management#token-list-and-token-creation-2)' for instructions on how to generate a token prior to executing the commands.

See [Generating a session ID](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md) for instructions on how to generate a session ID
{% endhint %}

## Prerequisites <a href="#scanning-and-instrumentation" id="scanning-and-instrumentation"></a>

* The front-end application was scanned
*

## Instrumentation command <a href="#scanning-and-instrumentation" id="scanning-and-instrumentation"></a>

First, the front-end code must be scanned and instrumented to provide the needed information to the SeaLights server.

{% tabs %}
{% tab title="Unix/Linux" %}
{% code overflow="wrap" %}

```sh
npx slnodejs instrument [--labid <Lab ID>] \
    --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId \
    --workspacepath dist --outputpath sl_dist \
    --splitPreambleIntoFile [--failbuild true]
```

{% endcode %}
{% endtab %}

{% tab title="Windows (CMD)" %}
{% code overflow="wrap" %}

```powershell
call npx slnodejs instrument [--labid <Lab ID>] `
    --tokenfile \path\to\sltoken.txt --buildsessionidfile buildSessionId `
    --workspacepath dist --outputpath sl_dist `
    --splitPreambleIntoFile [--failbuild true]
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="success" %}
After a successful `instrument`command execution, you should expect a new folder in the project directory called `sl_dist` (or the name provided as a value to the `--outputpath` parameter)
{% endhint %}

{% hint style="danger" %}
In case your command execution does not produce the expected results, you can use the `dryRun` command to validate your configuration, see [dryRun Command: Troubleshooting & Validation](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/advanced-features/dryrun-command-troubleshooting-and-validation.md).
{% endhint %}

{% hint style="info" %}

* Most scans should include the following flags:
  * \--failbuild true (if scan fails, then it will throw an error that will allow the pipeline to fail, rather than fail silently)
* In order to ignore specific files or folders during the Scan operation, please refer to [Ignoring Files or Folders](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/ignoring-files-or-folders.md)
  {% endhint %}

This will generate a new folder ('sl\_dist' in the command above) with the instrumented code: a few Sealights-specific API calls will be added to your JS file to report coverage dynamically as illustrated in the picture below.\
**The content of this Sealights' generated folder needs to be deployed instead of your original code** - on the application server - for the client browser to work against during your testing stages, but not in your production environment.

<figure><img src="/files/kBYdsi8ATsgVHSna2YS7" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
For distributed Test Runner & Test Listener, we recommend using the Lab ID parameter in order to link between the two.

* For Front-End instrumented code, this parameter needs to be passed already as part of the the build command.
* If the lab ID is not provided, the session ID will be used as a Lab ID
  {% endhint %}

{% hint style="info" %}
Note that if Sealights inline scripts are being blocked by CSP (Content-Security-Policy) headers then our dashboard will need to be whitelisted.\
See [Content-Security-Policy (CSP) Header Quick Reference](https://content-security-policy.com/) as a good resource to how to handle this\
In some cases, its possible to add a meta tag to do this as well, see: [Content-Security-Policy Meta http-equiv Example](https://content-security-policy.com/examples/meta/)
{% endhint %}

## Deploying Sealights instrumented folder

After generating a new folder with the instrumented code of your Front-End application, **the content of this folder needs to be deployed instead of your original code on the server** for the client browser to work against. Below, you’ll find several Best Practices in use among Sealights customers:

{% hint style="warning" %}
In the sample commands below, we refer to your application’s artifact as `dist` folder, as a default.\
Please make sure to update the command according to your specific configuration, and replace the parameter with the path relevant to your project's settings. For example: `apps`, `code`, `js`,…
{% endhint %}

### Deploying the folder containing the instrumented code <a href="#deploying-the-folder-containing-the-instrumented-code" id="deploying-the-folder-containing-the-instrumented-code"></a>

For example, if your original folder was named `'dist'` and the new folder with the instrumented code is '`sl_dist`’, you can follow the steps below:

1. Rename the original folder from ‘`dist`’ to ‘`dist_original`’
2. Use the instrumented folder instead of using one of the following options by renaming the ‘`sl_dist`’ to ‘`dist`’

{% tabs %}
{% tab title="Unix/Linux" %}

```sh
mv dist dist_original
mv sl_dist dist 
```

{% endtab %}

{% tab title="Windows" %}

```powershell
rename dist dist_original
rename sl_dist dist
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
On Unix/Linux system you also have the ability to define a ‘`dist`’ soft link to the ‘`sl_dist`’ folder.

`ln -s sl_dist dist`
{% endhint %}

### Deploying Instrumentation for several environments (Lab IDs) <a href="#deploying-instrumentation-for-several-environments-lab-ids" id="deploying-instrumentation-for-several-environments-lab-ids"></a>

If you need to instrument your front-end application for several environments and provide accordingly different LabIds (resp. to every context), additional commands are required to manage LabID parameters in your deployment steps. We have described below the most common solutions in use

#### Using slnodejs agent <a href="#using-slnodejs-agent" id="using-slnodejs-agent"></a>

You have the ability to split the single `slnodejs scan` command into a build scan command and several “instrumentations only” commands. For example, below, we’ll instrument the application for two different LabIDs (`MyFirstLab` and `My-2nd-Lab`)

{% code overflow="wrap" %}

```sh
#Build Scan without Instrumentation - Unix
npx slnodejs scan --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId --workspacepath dist --scm git --projectRoot /path/to/source/root

#Instrumentation for first environment (i.e. MyFirstLab)
npx slnodejs scan --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId --labid MyFirstLab --instrumentForBrowsers --instrumentationOnly --workspacepath dist --outputpath sl_dist_MyFirstLab 

#Instrumentation for second environment (i.e. My-2nd-Lab)
npx slnodejs scan --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId --labid My-2nd-Lab --instrumentForBrowsers --instrumentationOnly --workspacepath dist --outputpath sl_dist_My-2nd-Lab  
```

{% endcode %}

#### Using a Search and Replace operation <a href="#using-a-search-and-replace-operation" id="using-a-search-and-replace-operation"></a>

Another solution is to execute the `slnodejs scan --instrumentForBrowsers` command with a generic `labid` that is replaced in the JS files (string operation) prior to the artifact deployment in each environment

{% code overflow="wrap" %}

```sh
Unix:
npx slnodejs scan --tokenfile /path/to/sltoken.txt --buildsessionidfile buildSessionId --labid sl_LabId_ReplaceMe --instrumentForBrowsers --workspacepath dist --outputpath sl_dist --scm git --projectRoot /path/to/source/root

#Updating LabID for first environment (i.e. MyFirstLab)
find sl_dist -type f -name "*.js" -exec sed -i 's/sl_LabId_ReplaceMe/MyFirstLab/g' {} +

#Updating LabID for second environemnt (i.e. My-2nd-Lab)
find sl_dist -type f -name "*.js" -exec sed -i 's/sl_LabId_ReplaceMe/My-2nd-Lab/g' {} + 
```

{% endcode %}

## Validating the Instrumentation and build number in the JS source from the Browser <a href="#validating-the-instrumentation-and-build-number-in-the-js-source-from-the-browser" id="validating-the-instrumentation-and-build-number-in-the-js-source-from-the-browser"></a>

In your browser, open the source code of your JS page: is there the Sealights' instrumentation code and the right build number at the beginning of the page ? If Yes, all is set.

<figure><img src="/files/n3OQu5HIoLJqhKwyxYNb" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/instrument-a-front-end-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.