{
  "doc": {
    "id": "app/plugins/plugins-guide",
    "title": "How to Use Cypress Plugins: Install, Register, and Verify",
    "description": "Install Cypress plugins from npm, register them in setupNodeEvents or your support file, and troubleshoot plugin issues. Includes a @cypress/grep example.",
    "section": "app",
    "source_path": "/llm/markdown/app/plugins/plugins-guide.md",
    "version": "e6c8d867c21227247f14714fb5690c7c018983c5",
    "updated_at": "2026-08-08T12:39:37.868Z",
    "headings": [
      {
        "id": "app/plugins/plugins-guide#how-to-use-cypress-plugins",
        "text": "How to Use Cypress Plugins",
        "level": 1
      },
      {
        "id": "app/plugins/plugins-guide#find-a-plugin",
        "text": "Find a plugin",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#where-plugin-code-runs",
        "text": "Where plugin code runs",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#installing-a-plugin",
        "text": "Installing a plugin",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#using-a-plugin",
        "text": "Using a plugin",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#register-in-the-cypress-configuration",
        "text": "Register in the Cypress configuration",
        "level": 3
      },
      {
        "id": "app/plugins/plugins-guide#register-in-the-support-file",
        "text": "Register in the support file",
        "level": 3
      },
      {
        "id": "app/plugins/plugins-guide#example-setting-up-cypress-grep",
        "text": "Example: setting up @cypress/grep",
        "level": 3
      },
      {
        "id": "app/plugins/plugins-guide#troubleshooting",
        "text": "Troubleshooting",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#plugin-issue-or-cypress-issue",
        "text": "Plugin issue or Cypress issue?",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#writing-your-own-plugin",
        "text": "Writing your own plugin",
        "level": 2
      },
      {
        "id": "app/plugins/plugins-guide#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "app/plugins/plugins-guide#find-a-plugin",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Find a plugin",
      "heading_level": 2,
      "content_markdown": "## Find a plugin\n\nBrowse the [list of plugins](/llm/markdown/app/plugins/plugins-list.md) maintained by Cypress. It curates official and community plugins across categories like custom commands, visual testing, network and API helpers, reporters, and CI integrations. Each entry shows its latest version, supported Cypress versions, and how recently it was updated, so you can pick one with confidence.\n",
      "section": "app",
      "anchors": [
        "find-a-plugin"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 73
    },
    {
      "id": "app/plugins/plugins-guide#where-plugin-code-runs",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Where plugin code runs",
      "heading_level": 2,
      "content_markdown": "## Where plugin code runs\n\nCode registered in `setupNodeEvents` runs in Node, where it can access the file system, the network, and environment variables. Code registered in your support file runs in the browser alongside your tests and your application under test.\n\nBeyond that, a plugin is a regular npm dependency, so the habits you already use for other packages apply here too.\n",
      "section": "app",
      "anchors": [
        "where-plugin-code-runs"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 84
    },
    {
      "id": "app/plugins/plugins-guide#installing-a-plugin",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Installing a plugin",
      "heading_level": 2,
      "content_markdown": "## Installing a plugin\n\nInstall the plugin as a dev dependency with your package manager:\n\n*   npm\n*   yarn\n*   pnpm\n*   bun\n\n```\nnpm install <plugin name> --save-dev\n```\n\n```\nyarn add <plugin name> --dev\n```\n\n```\npnpm add --save-dev <plugin name>\n```\n\n```\nbun add --dev <plugin name>\n```\n\nBefore installing, check the plugin's supported Cypress versions, shown as a badge on the [list of plugins](/llm/markdown/app/plugins/plugins-list.md) and usually stated in the plugin's README.\n",
      "section": "app",
      "anchors": [
        "installing-a-plugin"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 100
    },
    {
      "id": "app/plugins/plugins-guide#using-a-plugin",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Using a plugin",
      "heading_level": 2,
      "content_markdown": "## Using a plugin\n\nInstalling the package isn't enough on its own: you also need to register the plugin with Cypress. Where you register it depends on where the plugin's code needs to run, and the plugin's README will tell you which it needs:\n\n*   **In [`setupNodeEvents`](/llm/markdown/app/references/configuration.md#setupNodeEvents) in your Cypress configuration** for plugins that run in Node: preprocessors, browser launch handling, tasks, and anything that touches the file system or test results.\n*   **In your [support file](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file)** for plugins that run in the browser alongside your tests: custom commands, assertion libraries, and overrides of built-in behavior.\n*   **In both**, for plugins with a Node piece and a browser piece.\n\n### Register in the Cypress configuration\n\nNode-side plugins typically export a setup function that you call inside `setupNodeEvents`, passing along `on` and `config` so the plugin can bind to [Node events](/llm/markdown/api/node-events/overview.md):\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const { configurePlugin } = require('my-cypress-plugin')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      configurePlugin(on, config)      // return the config so any changes the plugin makes take effect      return config    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'import { configurePlugin } from 'my-cypress-plugin'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      configurePlugin(on, config)      // return the config so any changes the plugin makes take effect      return config    },  },})\n```\n\n### Register in the support file\n\nBrowser-side plugins are imported (or registered with a function call) in your support file, which loads before every spec:\n\ncypress/support/e2e.js\n\n```\nimport 'my-cypress-plugin'\n```\n\nAny custom commands the plugin adds are then available in all of your tests.\n\n### Example: setting up @cypress/grep\n\n[`@cypress/grep`](https://github.com/cypress-io/cypress/tree/develop/npm/grep) filters which tests run by title or tag, and is a good example of a plugin that registers in both places. Install it:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpm install @cypress/grep --save-dev\n```\n\n```\nyarn add @cypress/grep --dev\n```\n\n```\npnpm add --save-dev @cypress/grep\n```\n\n```\nbun add --dev @cypress/grep\n```\n\nRegister it in your support file so it can filter tests in the browser:\n\ncypress/support/e2e.js\n\n```\nimport { register as registerCypressGrep } from '@cypress/grep'registerCypressGrep()\n```\n\nAdd its Node plugin to your configuration so it can skip loading specs with no matching tests:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const { plugin } = require('@cypress/grep/plugin')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      plugin(config)      return config    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'import { plugin } from '@cypress/grep/plugin'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      plugin(config)      return config    },  },})\n```\n\nThen verify it works by running only tests with \"login\" in the title:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress run --expose grep=login\n```\n\n```\nyarn cypress run --expose grep=login\n```\n\n```\npnpm cypress run --expose grep=login\n```\n\n```\nbunx cypress run --expose grep=login\n```\n",
      "section": "app",
      "anchors": [
        "using-a-plugin"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 696
    },
    {
      "id": "app/plugins/plugins-guide#register-in-the-cypress-configuration",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Register in the Cypress configuration",
      "heading_level": 3,
      "content_markdown": "### Register in the Cypress configuration\n\nNode-side plugins typically export a setup function that you call inside `setupNodeEvents`, passing along `on` and `config` so the plugin can bind to [Node events](/llm/markdown/api/node-events/overview.md):\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const { configurePlugin } = require('my-cypress-plugin')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      configurePlugin(on, config)      // return the config so any changes the plugin makes take effect      return config    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'import { configurePlugin } from 'my-cypress-plugin'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      configurePlugin(on, config)      // return the config so any changes the plugin makes take effect      return config    },  },})\n```\n",
      "section": "app",
      "anchors": [
        "register-in-the-cypress-configuration"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 183
    },
    {
      "id": "app/plugins/plugins-guide#register-in-the-support-file",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Register in the support file",
      "heading_level": 3,
      "content_markdown": "### Register in the support file\n\nBrowser-side plugins are imported (or registered with a function call) in your support file, which loads before every spec:\n\ncypress/support/e2e.js\n\n```\nimport 'my-cypress-plugin'\n```\n\nAny custom commands the plugin adds are then available in all of your tests.\n",
      "section": "app",
      "anchors": [
        "register-in-the-support-file"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 59
    },
    {
      "id": "app/plugins/plugins-guide#example-setting-up-cypress-grep",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Example: setting up @cypress/grep",
      "heading_level": 3,
      "content_markdown": "### Example: setting up @cypress/grep\n\n[`@cypress/grep`](https://github.com/cypress-io/cypress/tree/develop/npm/grep) filters which tests run by title or tag, and is a good example of a plugin that registers in both places. Install it:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpm install @cypress/grep --save-dev\n```\n\n```\nyarn add @cypress/grep --dev\n```\n\n```\npnpm add --save-dev @cypress/grep\n```\n\n```\nbun add --dev @cypress/grep\n```\n\nRegister it in your support file so it can filter tests in the browser:\n\ncypress/support/e2e.js\n\n```\nimport { register as registerCypressGrep } from '@cypress/grep'registerCypressGrep()\n```\n\nAdd its Node plugin to your configuration so it can skip loading specs with no matching tests:\n\n*   cypress.config.js\n*   cypress.config.ts\n\n```\nconst { defineConfig } = require('cypress')const { plugin } = require('@cypress/grep/plugin')module.exports = defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      plugin(config)      return config    },  },})\n```\n\n```\nimport { defineConfig } from 'cypress'import { plugin } from '@cypress/grep/plugin'export default defineConfig({  // setupNodeEvents can be defined in either  // the e2e or component configuration  e2e: {    setupNodeEvents(on, config) {      plugin(config)      return config    },  },})\n```\n\nThen verify it works by running only tests with \"login\" in the title:\n\n*   npm\n*   Yarn\n*   pnpm\n*   Bun\n\n```\nnpx cypress run --expose grep=login\n```\n\n```\nyarn cypress run --expose grep=login\n```\n\n```\npnpm cypress run --expose grep=login\n```\n\n```\nbunx cypress run --expose grep=login\n```\n",
      "section": "app",
      "anchors": [
        "example-setting-up-cypress-grep"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 309
    },
    {
      "id": "app/plugins/plugins-guide#troubleshooting",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Troubleshooting",
      "heading_level": 2,
      "content_markdown": "## Troubleshooting\n\nIf a plugin doesn't seem to do anything, or errors on startup, work through these checks:\n\n*   **Follow the plugin's own README.** Registration details vary between plugins, and some require extra configuration beyond the patterns shown above.\n*   **Confirm you registered it in the right place.** An error like `cy is not defined` inside `setupNodeEvents` means browser-side code is running in Node; move that registration to your support file.\n*   **Return the `config` object** from `setupNodeEvents` if the plugin modifies configuration. Forgetting to return it silently discards the plugin's changes.\n*   **Restart Cypress after configuration changes.** Changes to the Cypress configuration file, including newly registered plugins, require restarting `cypress open`.\n*   **Check version compatibility.** A plugin built for an older Cypress major version may fail on the current one. Compare the supported versions badge on the [list of plugins](/llm/markdown/app/plugins/plugins-list.md) with your installed Cypress version.\n",
      "section": "app",
      "anchors": [
        "troubleshooting"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 195
    },
    {
      "id": "app/plugins/plugins-guide#plugin-issue-or-cypress-issue",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Plugin issue or Cypress issue?",
      "heading_level": 2,
      "content_markdown": "## Plugin issue or Cypress issue?\n\nWhen something breaks in a project that uses plugins, isolate which side owns the problem before reporting it, so your issue lands where it can be fixed:\n\n1.  **Read the error and stack trace.** A stack trace that points into the plugin's package in `node_modules` is a strong signal the plugin is involved.\n2.  **Disable the plugin and run again.** Comment out its registration in `setupNodeEvents` and your support file, then re-run the failing command or test.\n3.  **Report it where it reproduces:**\n    *   If the problem still occurs with the plugin disabled, it isn't caused by the plugin. Work through the [troubleshooting guide](/llm/markdown/app/references/troubleshooting.md), search [existing Cypress issues](https://github.com/cypress-io/cypress/issues), and if it's new, [open an issue against Cypress](https://github.com/cypress-io/cypress/issues/new/choose) with a reproducible example.\n    *   If the problem only occurs with the plugin registered, report it on the plugin's own repository, not the Cypress repository. Search its existing issues first, and include your Cypress version, the plugin version, and a minimal reproduction. The Cypress team doesn't maintain community plugins and can't fix bugs in them.\n\nIf the failure started right after a Cypress upgrade, first check that the plugin supports the new version. A compatibility gap is a plugin issue: the plugin's repository is the right place to report it, even though the Cypress upgrade surfaced it.\n",
      "section": "app",
      "anchors": [
        "plugin-issue-or-cypress-issue"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 293
    },
    {
      "id": "app/plugins/plugins-guide#writing-your-own-plugin",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "Writing your own plugin",
      "heading_level": 2,
      "content_markdown": "## Writing your own plugin\n\nAnyone can create and publish a plugin. If no existing plugin covers your use case, read the [Node Events Overview](/llm/markdown/api/node-events/overview.md) to learn how plugins hook into Cypress, then [submit it to the plugins list](https://github.com/cypress-io/cypress-documentation/blob/master/CONTRIBUTING.md#adding-plugins) so others can find it.\n",
      "section": "app",
      "anchors": [
        "writing-your-own-plugin"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 59
    },
    {
      "id": "app/plugins/plugins-guide#see-also",
      "doc_id": "app/plugins/plugins-guide",
      "heading": "See also",
      "heading_level": 2,
      "content_markdown": "## See also\n\n*   [List of plugins](/llm/markdown/app/plugins/plugins-list.md): browse official and community plugins\n*   [Node Events Overview](/llm/markdown/api/node-events/overview.md): the events available in `setupNodeEvents`\n*   [Configuration](/llm/markdown/app/references/configuration.md#setupNodeEvents): reference for `setupNodeEvents` and other options\n*   [Writing and Organizing Tests](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file): how the support file works\n*   [Troubleshooting](/llm/markdown/app/references/troubleshooting.md): isolate and report problems in Cypress itself\n",
      "section": "app",
      "anchors": [
        "see-also"
      ],
      "path": "/llm/json/chunked/app/plugins/plugins-guide.json",
      "token_estimate": 64
    }
  ]
}