Skip to main content

Specify NPM dependencies

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

Though your package.json file might contain many third-party npm packages, not all of these are required for you to successfully run your Cypress tests on BrowserStack.

In this guide, you will learn:

  1. Why you need to specify npm packages?
  2. How to specify required npm dependencies?
  3. How to specify private npm package dependencies?
  4. How BrowserStack manages your npm dependency caching?

Why npm dependencies must be specified?

Your Cypress tests are uploaded to BrowserStack and are further run from the BrowserStack machines. Typically, all external npm packages that your tests need to run are specified in the package.json file under the devDependencies section. For your Cypress tests to run on BrowserStack, we use the browserstack.json file and read your dependencies from this file. The package.json is not used by BrowserStack to identify dependencies. You need to set your npm dependencies in the browserstack.json file because:

  • The package.json file might contain several devDependencies many of which are not essential for running your tests. For example, the eslint package.
  • Installing npm packages in BrowserStack machines is a time intensive task. By installing non-essential packages, we would increase your build time, which can be avoided by skipping such packages.

Based on these benefits, use the information in the following sections to understand which npm packages must be specified in the browserstack.json.

Specify public npm package dependencies

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

Ensure that your are using CLI v1.3.0 or higher to use the 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"
      }
    }
  }
}

If you encounter the Cannot find module 'cypress' error after migrating to Cypress 10, add the cypress dependency under npm_dependencies in the browserstack.json file.

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. For such cases, the following two scenarios exist:

Registry URL is publicly resolvable

Complete the following steps to ensure that your tests run seamlessly on BrowserStack:

  1. Specify the private npm package dependency in your browserstack.json file:
    browserstack.json
    {
      "run_settings": {
        ...
        "npm_dependencies": {
           "your-private-npm-package": "^1.2.1",
       },
      }
    }
    
  2. Create a .npmrc file and enter your private npm registry details as shown in the following sample snippet. Check out what are npmrc files and how to set them for more information.
    .npmrc
    @myscope:registry=https://mycustomregistry.example.org
    

If your private npm registry needs authentication to access it, then follow the steps in the configuring NPM registry authentication section.

Registry URL is only available to your private network

If the NPM registry URL is accessible only in your private network, then complete the following steps to route requests through the BrowserStack Local tunnel connection:

  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. Create a .npmrc file and enter your private npm registry details as shown in the following sample code snippet. Check out what are npmrc files and how to set them for more information.
    .npmrc
    @myscope:registry=https://mycustomregistry.private-staging.com
    
  3. Set "local": true in the "connection_settings" section of your browserstack.json file since the URL is not publicly resolvable.
    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 path in the browserstack.json file as shown in the following code snippet. You can see the sample config file and configure the proxy related parameters accordingly.
    browserstack.json
    ...
    {
      "connection_settings": {
        "local": true,
        "local_config_file": "/path/to/your/config.yml"
      }
    }
    ...
    

If your private npm registry needs authentication to access it, then follow the steps in the configure NPM registry authentication section.

Configure NPM registry authentication

In the earlier sections, we learnt about accessing the npm registry for both when your private npm package registry URL is publicly resolvable or privately resolvable. In this section, we will learn about the steps that you must follow if your npm registry itself needs authentication.

Accessing the npm registry involves creating an npm token, and then setting the token in the .npmrc file.

  1. Create an npm token using npm token create command. Check out Creating an access token to learn about creating access tokens including CIDR-whitelisted tokens.
  2. After the token is created, save it in an environment variable such as NPM_TOKEN in your system.
  3. Configure the browserstack.json file as shown in the following snippet to read the specified environment variable value from your system when you trigger any Cypress test.
    browserstack.json
    ...
    "run_settings": {
      ...
      "system_env_vars": ["NPM_TOKEN", "ANY_OTHER_ENV_VARIABLE_THAT_YOU_WANT_TO_BE_AVAILABLE_AT_OS_LEVEL"]
    }
    

    After you configure the environment variable, the browserstack-cypress CLI will use this variable from your system and set the same in BrowserStack machines, and use them thereafter.

  4. In the .npmrc file, specify the npm token for authentication.
    .npmrc
    @myscope:registry=https://mycustomregistry.example.org:_authToken=${NPM_TOKEN}
    

    Check out NPM documentation for setting authentication for CI/CD runs to learn more.

npm dependency caching

Starting browserstack-cypress-cli version 1.11.0 and higher, BrowserStack will cache your npm dependencies to accelerate your overall build execution time.

BrowserStack would cache all your npm dependencies so that every time you run a build, npm install is not required which used to take up a major part of the total time of your build execution.

Caching dependencies is a default behavior for browserstack-cypress-cli v1.11.0 and higher. Due to this behavior, all your private packages (if any) would also be cached on our servers. If you want to stop BrowserStack from caching your npm dependencies, specify the following configuration option in your browserstack.json file but your build will end up taking much longer to complete.

browserstack.json
{
  "run_settings": {
    ...
    "cache_dependencies": "false"
  }
}

You need to ensure that you are using one of the latest browserstack-cypress CLI versions i.e. v1.11.0 (or above) to be able to see these enhancements. Run npm i -g browserstack-cypress-cli to ensure that the latest version is used.

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
Download Copy