nx/docs/generated/packages/storybook/generators/migrate-7.json

{
  "name": "migrate-7",
  "factory": "./src/generators/migrate-7/migrate-7",
  "schema": {
    "cli": "nx",
    "title": "Migrate Storybook to version 7.",
    "description": "Migrate Storybook to version 7.",
    "$id": "migrate-7",
    "type": "object",
    "properties": {
      "autoAcceptAllPrompts": {
        "type": "boolean",
        "description": "Say yes to all the prompts from the Storybook CLI migration scripts.",
        "default": false
      },
      "onlyShowListOfCommands": {
        "type": "boolean",
        "description": "Only show the steps that you need to follow in order to migrate. This does NOT make any changes to your code.",
        "default": false
      },
      "noUpgrade": {
        "type": "boolean",
        "description": "Skip upgrading Storybook packages. Only use this option if you are already on version 7, and you do not want the latest beta.",
        "default": false
      },
      "onlyPrepare": {
        "type": "boolean",
        "description": "Only run the Nx scripts that will prepare your Storybook configuration files for the Storybook CLI automigration.",
        "default": false
      },
      "afterMigration": {
        "type": "boolean",
        "description": "Only run the Nx post-migration scripts that make the final adjustments to your workspace.",
        "default": false
      }
    },
    "examplesFile": "---\ntitle: Storybook 7 Migration Generator Examples\ndescription: This page contains examples for the @nx/storybook:migrate-7 generator.\n---\n\n{% callout type=\"info\" title=\"Setting up Storybook 7 in a new workspace\" %}\nFor setting up Storybook version 7 in a new Nx workspace, or a workspace that does NOT already have Storybook configured already, please refer to our [Storybook 7 setup guide](/technologies/test-tools/storybook/recipes/best-practices).\n{% /callout %}\n\nStorybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7.0.0 release article](https://storybook.js.org/blog/storybook-7-0/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7.0.0 migration guide](https://storybook.js.org/docs/react/migration-guide).\n\nYou can now migrate your existing Nx workspace with Storybook configuration to use Storybook version 7. To help you, Nx offers the `@nx/storybook:migrate-7` generator. This generator will help you migrate your existing Storybook setup to version 7.\n\n## How to use it\n\nJust call:\n\n```bash\nnpx nx g @nx/storybook:migrate-7\n```\n\n{% callout type=\"warning\" title=\"Commit your changes\" %}\nIt is advised that you start with a clean git history before running this generator, since it is going to be making lots of changes to your workspace.\n{% /callout %}\n\nYou can run this generator using the above command, without passing any options. This will start the migration process for all your projects that have Storybook configured. The logs will explain what is happening in every step, and the logs are mixed Nx and Storybook CLI logs. During the process you will be prompted by the Storybook CLI to accept the automigration scripts. You can read more about that in the next section.\n\nWhen the generator finishes, you will see a summary of the changes that were made to your workspace, and it will also create a new file, called `storybook-migration-summary.md` at the root of your project, which will contain a list of all the changes that were made to your workspace.\n\n### Accept the automigration prompts\n\nThe Storybook CLI (running through our generator) will prompt you to run some code generators and modifiers.\n\nYou can say `yes` to these prompts, which are usually the following (there may be more or less, depending on your setup,\nand depending on the latest versions of the Storybook CLI - this code is NOT managed by Nx, but by Storybook):\n\n- `mainjsFramework`: It will try to add the `framework` field in your project's `.storybook/main.js|ts` file.\n- `eslintPlugin`: installs the `eslint-plugin-storybook`\n- `newFrameworks`: removes unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`)\n- `autodocsTrue`: adds `autodocs: true` to your project's `.storybook/main.js|ts` file\n\n### Check the result\n\nOnce the generator finishes, and the Storybook CLI automigration scripts have run, you should check the result. Examples of migrated `.storybook/main.js|ts` files would look like this:\n\n#### Full example for Angular projects\n\nHere is an example of a project-level `.storybook/main.js|ts` file for an Angular project that has been migrated to Storybook version 7:\n\n```ts {% fileName=\"apps/my-angular-app/.storybook/main.js\" %}\nconst config = {\n  stories: ['../src/app/**/*.stories.@(js|jsx|ts|tsx|mdx)'],\n  addons: ['@storybook/addon-essentials'],\n  framework: {\n    name: '@storybook/angular',\n    options: {},\n  },\n};\n\nexport default config;\n```\n\n#### Full example for React projects with Vite\n\nHere is an example of a project-level `.storybook/main.js|ts` file for a React project using Vite that has been migrated to Storybook version 7:\n\n```ts {% fileName=\"apps/my-react-app/.storybook/main.js\" %}\nconst config = {\n  stories: ['../src/app/**/*.stories.@(js|jsx|ts|tsx|mdx)'],\n  addons: ['@storybook/addon-essentials'],\n  framework: {\n    name: '@storybook/react-vite',\n    options: {\n      builder: {\n        viteConfigPath: 'apps/rv1/vite.config.ts',\n      },\n    },\n  },\n};\n\nexport default config;\n```\n\n### Make sure that all works by running Storybook\n\nYou can now use Storybook 7! 🎉\n\n```bash\nnpx nx build-storybook PROJECT_NAME\n```\n\nand\n\n```bash\nnpx nx storybook PROJECT_NAME\n```\n\n## Run the generator by automatically accepting the Storybook CLI prompts\n\nYou can run the generator with the `--autoAcceptAllPrompts` flag, which will automatically accept all the Storybook CLI prompts. This is useful if you want to run the generator in a CI environment, or if you want to run the generator in a script. Or if you are sure that you want to accept all the prompts!\n\n```bash\nnpx nx g @nx/storybook:migrate-7 --autoAcceptAllPrompts\n```\n\nThe Storybook CLI may still ask you about some things, but mostly it should just run the whole migration suite uninterrupted.\n\n## Run the migration manually\n\nNx gives you the ability to run all the migration steps one by one, manually, but still with the help of our migrator. To help you out with the commands that you need to run, Nx will print out the instructions if you run the generator with the `--onlyShowListOfCommands` flag, like this:\n\n```bash\nnpx nx g @nx/storybook:migrate-7 --onlyShowListOfCommands\n```\n\nEssentially, the way to run the migration manually is the following:\n\n1. Call the Nx generator to show you the list of commands:\n   `npx nx g @nx/storybook:migrate-7 --onlyShowListOfCommands`\n2. Call the Storybook upgrade script:\n   `npx storybook@latest upgrade`\n3. Call the Nx generator to prepare your files for migration. The steps are explained in [Step 02](#step-02) above.\n   `nx g @nx/storybook:migrate-7 --onlyPrepare`\n4. Call the Storybook automigrate scripts for each one of the projects using Storybook (the `@nx/storybook:migrate-7` will give you the list of all the commands)\n5. Call the Nx generator to finish the migration. The steps are explained in [Step 04](#step-04) above.\n   `nx g @nx/storybook:migrate-7 --afterMigration`\n\n## How the generator works under the hood\n\nNow let's see how the `@nx/storybook:migrate-7` generator works under the hood. It essentially does the following things:\n\n### Step 01\n\nIt calls the Storybook CLI upgrade script:\n\n```bash\nnpx storybook@latest upgrade\n```\n\nThis script will upgrade your Storybook dependencies to the latest version, as explained in the [Storybook documentation](https://storybook.js.org/docs/7.0/react/configure/upgrading).\n\n### Step 02\n\nIt prepares all your project-level `.storybook/main.js|ts` files, so that\nthe Storybook automigration scripts can run successfully. This means that it makes the following adjustments to your files:\n\n- Remove the \"`as StorybookConfig`\" typecast from the `.storybook/main.ts` files, if you have any `.storybook/main.ts` files with typecast, since it is not needed any more\n- Remove the \"`path.resolve`\" calls from the Next.js Storybook configuration in project-level `.storybook/main.js|ts` files, if it exists, since it breaks the Storybook automigration scripts\n\n### Step 03\n\nIt calls the Storybook CLI automigrate script, for each one of your projects that have Storybook configured. It does that by passing the `--config-dir` flag and the `--renderer` flag, for each one of your projects that has Storybook configured. An example command would look like this:\n\n```bash\nnpx storybook@latest automigrate --config-dir apps/my-react-app/.storybook --renderer @storybook/react\n```\n\nThis script will make changes to your Storybook configuration files, and other changes to your repository, to make it work for Storybook 7, as explained in the [Storybook documentation](https://storybook.js.org/docs/7.0/react/configure/upgrading).\n\n### Step 04\n\nAfter the Storybook CLI automigrate scripts have run, some additional adjustments are made to your workspace, to make sure that everything is working as expected. These adjustments are as follows:\n\n- Remove the \"`vite-tsconfig-paths`\" plugin from the Storybook configuration files for Vite projects, since it's no longer needed in v7\n- Add the \"`viteConfigPath`\" option to the Storybook builder options for Vite projects, since now Storybook needs the path to the Vite config file\n- Change the import package for the `StorybookConfig` type to be framework specific (e.g. from `@storybook/common` to `@storybook/react-vite` for React projects using Vite)\n- Add the \"`lit`\" package to your workspace, if you are using Web Components\n- Remove the \"`uiFramework`\" option from your project's Storybook targets\n\nOur generator is based on the guide to migration using the Storybook CLI, sp please refer to the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937) for more information.\n\n## I am not on Nx 15.9.0 yet but I still want to migrate to Storybook 7\n\nYou can migrate to Storybook 7 by just using the [Storybook `upgrade` and `automigrate` scripts](https://storybook.js.org/docs/7.0/react/configure/upgrading), but you will have to manually point the `automigrate` script to each one of your projects using Storybook, explained in [Step 03](#step-03) above.\n\nFirst, you would have to run the `npx storybook@latest upgrade` to get the latest versions of all the `@storybook/*` packages. Then, for each one of your projects that use Storybook, you would have to run `npx storybook@latest automigrate --config-dir <MY-PROJECT>/.storybook --renderer @storybook/<react|angular|etc>`.\n\nThe `@nx/storybook:migrate-7` generator helps you by figuring out all the project paths and the renderers that need to be passed in the `automigrate` script, and also by performing a number of adjustments to your code to make sure the migration scripts run smoothly, so it is recommended to use the generator instead of running the scripts manually.\n\n## Report any issues and bugs\n\nPlease report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose).\n",
    "presets": []
  },
  "description": "Migrate to Storybook version 7.",
  "hidden": false,
  "implementation": "/packages/storybook/src/generators/migrate-7/migrate-7.ts",
  "aliases": [],
  "path": "/packages/storybook/src/generators/migrate-7/schema.json",
  "type": "generator"
}