Specify NPM dependencies

Learn how to run your tests that need third-party or private npm packages.

You will learn the following in this guide:

  1. Why you need to specify npm packages?
  2. How to specify required npm dependencies?
  3. How to specify private npm package dependencies?

Why npm dependencies need to be specified?

Your Cypress tests are uploaded to BrowserStack machines and they are run from there. Now, these tests might need some external npm packages to run that you generally specify in package.json under devDependencies. But we do not read your package.json and need you to specify your dependencies separately in browserstack.json for the following reasons:

  1. Your package.json might contain several devDependencies many of which are not even required for running your tests for e.g. eslint
  2. Installing npm packages in BrowserStack machines is a time intensive task. So, installing unnecessary packages would increase your build time that can be otherwise avoided.
  3. Hence, we require you to specify only those npm packages that are absolutely required to run your tests, in the browserstack.json as explained in the following section.

Specify public npm package dependencies

You can use the following keys in the run_settings option under browserstack.json to specify the npm packages and any options that the packages might need in order for your tests to run successfully.

Note: You’ll need CLI v1.3.0 or later to use package_config_options key.
key value
npm_dependencies A hash of npm packages that are required to run your Cypress tests along with their version numbers.
package_config_options A hash of package options that are required to run your Cypress tests with the packages specified.

For Example:

browserstack.json
{
  "run_settings": {
    ...
    "npm_dependencies": {
      "npm-package-you-need-to-run-tests-1": "^1.2.1",
      "npm-package-you-need-to-run-tests-2": "^7.1.6-beta.13",
    },
    "package_config_options": {
      "npm-package-you-need-to-run-tests-1_options": {
        "option1": true,
        "option2": "some-value"
      }
    }
  }
}

Specify private npm package dependencies

If your dependencies include privately or internally hosted NPM packages, you can resolve them by adding a .npmrc file as part of your project, with authentication if required. Now, there are two scenarios as follows:

Registry URL is publicly resolvable

You can do the following steps to make sure that your tests run seamlessly on BrowserStack:

  1. Specify the private npm package dependency in your browserstack.json:
    browserstack.json
    {
      "run_settings": {
        ...
        "npm_dependencies": {
           "your-private-npm-package": "^1.2.1",
       },
      }
    }
    
  2. Next, you have to create a .npmrc file and put your private npm registry details. You can read more about npmrc files and how to set them up. A short example is shown below:
    .npmrc
    @myscope:registry=https://mycustomregistry.example.org
    
  3. Thats it! The above will work fine if the URL is publicly resolvable. If not, see the next section.
  4. If your private npm registry needs authentication to access then follow the section on configuring NPM registry authentication

Registry URL is only available to your private network

If the NPM registry URL is accessible only in your private network then please follow the following steps:

  1. Specify the private npm package dependency in your browserstack.json:
    browserstack.json
    {
      "run_settings": {
        ...
        "npm_dependencies": {
           "your-private-npm-package-accessible-only-in-your-private-network": "^1.2.1",
       },
      }
    }
    
  2. Next, you have to create a .npmrc file and put your private npm registry details. You can read more about npmrc files and how to set them up. A short example is shown below:
    .npmrc
    @myscope:registry=https://mycustomregistry.private-staging.com
    
  3. As the above URL is not publicly resolvable, you need to set "local": true in "connection_settings" of your browserstack.json as shown below:
    browserstack.json
    ...
    {
      "connection_settings": {
        "local": true
      }
    }
    ...
    
  4. If you are behind a proxy then you need to ensure that you specify the proxy parameters in a local-config.yml file and specify the file path in browserstack.json. You can see the sample config file and configure the proxy related parameters accordingly. The path to the config file needs to be specified as shown below:
    browserstack.json
    ...
    {
      "connection_settings": {
        "local": true,
        "local_config_file": "/path/to/your/config.yml"
      }
    }
    ...
    
  5. Thats it! The private URL will be resolved through the BrowserStack Local tunnel connection.
  6. If your private npm registry needs authentication to access then follow the next section

Configure NPM registry authentication

Doesn’t matter whether the private NPM package’s registry URL is publicly resolvable or privately resolvable, the above two sections deal with accessing the registry. But, if your registry needs authentication then you need to follow the steps in this section in addition to the above sections.

Follow the below steps to generate an authentication token and configure your setup:

  1. Create an npm token using npm token create. For more information on creating access tokens, including CIDR-whitelisted tokens, see “Creating an access token”.
  2. Once the token is created, save it in an environment variable such as NPM_TOKEN in your system.
  3. Configure browserstack.json to read the specified env variable’s value from your system while triggering Cypress tests as shown below:
    browserstack.json
    ...
    "run_settings": {
      ...
      "system_env_vars": ["NPM_TOKEN", "ANY_OTHER_ENV_VARIABLE_THAT_YOU_WANT_TO_BE_AVAILABLE_AT_OS_LEVEL"]
    }
    
  4. The above step will inform the browserstack-cypress CLI to read the specific env variable from your system and set the same in BrowserStack machines that run your test.
  5. In the .npmrc file, you’d need to specify the NPM token for authentication:
    .npmrc
    @myscope:registry=https://mycustomregistry.example.org:_authToken=${NPM_TOKEN}
    
  6. You’re all set! The above steps can also be found in NPM documentation for setting authentication for CI/CD runs.

We're sorry to hear that. Please share your feedback so we can do better







Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better







Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Talk to an Expert