nx/docs/generated/packages/react/generators/cypress-component-configuration.json

{
  "name": "cypress-component-configuration",
  "factory": "./src/generators/cypress-component-configuration/cypress-component-configuration#cypressComponentConfigGenerator",
  "schema": {
    "$schema": "https://json-schema.org/schema",
    "cli": "nx",
    "$id": "NxReactCypressComponentTestConfiguration",
    "title": "Add Cypress component testing",
    "description": "Add a Cypress component testing configuration to an existing project.",
    "type": "object",
    "examples": [
      {
        "command": "nx g @nx/react:cypress-component-configuration --project=my-react-project",
        "description": "Add component testing to your react project"
      },
      {
        "command": "nx g @nx/react:cypress-component-configuration --project=my-react-project --generate-tests",
        "description": "Add component testing to your react project and generate component tests for your existing components"
      }
    ],
    "properties": {
      "project": {
        "type": "string",
        "description": "The name of the project to add cypress component testing configuration to",
        "x-dropdown": "projects",
        "x-prompt": "What project should we add Cypress component testing to?",
        "x-priority": "important"
      },
      "generateTests": {
        "type": "boolean",
        "description": "Generate default component tests for existing components in the project",
        "x-prompt": "Automatically generate tests for components declared in this project?",
        "default": false,
        "x-priority": "important"
      },
      "buildTarget": {
        "type": "string",
        "description": "A build target used to configure Cypress component testing in the format of `project:target[:configuration]`. The build target should be from a React app. If not provided we will try to infer it from your projects usage.",
        "pattern": "^[^:\\s]+:[^:\\s]+(:\\S+)?$"
      },
      "skipFormat": {
        "type": "boolean",
        "description": "Skip formatting files",
        "default": false,
        "x-priority": "internal"
      },
      "bundler": {
        "description": "The bundler to use for Cypress Component Testing.",
        "type": "string",
        "enum": ["vite", "webpack"],
        "hidden": true,
        "x-priority": "internal"
      }
    },
    "required": ["project"],
    "examplesFile": "{% callout type=\"caution\" title=\"Can I use component testing?\" %}\nReact component testing with Nx requires **Cypress version 10.7.0** and up.\n\nYou can migrate with to v11 via the [migrate-to-cypress-11 generator](/nx-api/cypress/generators/migrate-to-cypress-11).\n\nThis generator is for Cypress based component testing.\n\nIf you want to test components via Storybook with Cypress, then check out the [storybook-configuration generator docs](/nx-api/react/generators/storybook-configuration). However, this functionality is deprecated, and will be removed on Nx version 19.\n{% /callout %}\n\nThis generator is designed to get your React project up and running with Cypress Component Testing.\n\n```shell\nnx g @nx/react:cypress-component-configuration --project=my-cool-react-project\n```\n\nRunning this generator, adds the required files to the specified project with a preconfigured `cypress.config.ts` designed for Nx workspaces.\n\nThe following file will be added to projects where the Component Testing build target is using `webpack` for bundling:\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';\n\nexport default defineConfig({\n  component: nxComponentTestingPreset(__filename, {\n    bundler: 'webpack',\n  }),\n});\n```\n\nThe following file will be added to projects where the Component Testing build target is using `vite` for bundling:\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';\n\nexport default defineConfig({\n  component: nxComponentTestingPreset(__filename, {\n    bundler: 'vite',\n  }),\n});\n```\n\nHere is an example on how to add custom options to the configuration\n\n```ts {% fileName=\"cypress.config.ts\" %}\nimport { defineConfig } from 'cypress';\nimport { nxComponentTestingPreset } from '@nx/react/plugins/component-testing';\n\nexport default defineConfig({\n  component: {\n    ...nxComponentTestingPreset(__filename, {\n      bundler: 'webpack',\n    }),\n    // extra options here\n  },\n});\n```\n\n## The `bundler` option\n\nComponent testing supports two different bundlers: `webpack` and `vite`. The Nx generator will pick up the bundler used in the specified project's build target. If the build target is using `@nx/webpack:webpack`, then the generator will use `webpack` as the bundler. If the build target is using `@nx/vite:build`, then the generator will use `vite` as the bundler.\n\nYou can manually set the bundler by passing `--bundler=webpack` or `--bundler=vite` to the generator, but that is not needed since the generator will pick up the correct bundler for you. However, if you want to use a different bundler than the one that is used in the build target, then you can manually set it using that flag.\n\n## Specifying a Build Target\n\nComponent testing requires a _build target_ to correctly run the component test dev server. This option can be manually specified with `--build-target=some-react-app:build`, but Nx will infer this usage from the [project graph](/concepts/mental-model#the-project-graph) if one isn't provided.\n\nFor React projects, the build target needs to be using the `@nx/webpack:webpack` executor.\nThe generator will throw an error if a build target can't be found and suggest passing one in manually.\n\nLetting Nx infer the build target by default\n\n```shell\nnx g @nx/react:cypress-component-configuration --project=my-cool-react-project\n```\n\nManually specifying the build target\n\n```shell\nnx g @nx/react:cypress-component-configuration --project=my-cool-react-project --build-target:some-react-app:build --generate-tests\n```\n\n{% callout type=\"note\" title=\"Build Target with Configuration\" %}\nIf you're wanting to use a build target with a specific configuration. i.e. `my-app:build:production`,\nthen manually providing `--build-target=my-app:build:production` is the best way to do that.\n{% /callout %}\n\n## Auto Generating Tests\n\nYou can optionally use the `--generate-tests` flag to generate a test file for each component in your project.\n\n```shell\nnx g @nx/react:cypress-component-configuration --project=my-cool-react-project --generate-tests\n```\n\n## Running Component Tests\n\nA new `component-test` target will be added to the specified project to run your component tests.\n\n```shell\nnx g component-test my-cool-react-project\n```\n\nHere is an example of the project configuration that is generated. The `--build-target` option is added as the `devServerTarget` which can be changed as needed.\n\n```json {% fileName=\"project.json\" %}\n{\n  \"targets\" {\n    \"component-test\": {\n      \"executor\": \"@nx/cypress:cypress\",\n      \"options\": {\n        \"cypressConfig\": \"<path-to-project-root>/cypress.config.ts\",\n        \"testingType\": \"component\",\n        \"devServerTarget\": \"some-react-app:build\",\n        \"skipServe\": true\n      }\n    }\n  }\n}\n```\n\nNx also supports [Angular component testing](/nx-api/angular/generators/cypress-component-configuration).\n",
    "presets": []
  },
  "description": "Setup Cypress component testing for a React project",
  "hidden": false,
  "implementation": "/packages/react/src/generators/cypress-component-configuration/cypress-component-configuration#cypressComponentConfigGenerator.ts",
  "aliases": [],
  "path": "/packages/react/src/generators/cypress-component-configuration/schema.json",
  "type": "generator"
}