diff --git a/.gitignore b/.gitignore index 9b24533..039cffa 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ build-storybook.log .DS_Store .env .idea +*.iml diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index 0967ef4..0000000 --- a/.prettierrc +++ /dev/null @@ -1 +0,0 @@ -{} diff --git a/LICENSE b/LICENSE index 6976f81..151a58c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Maxime Malgorn +Copyright (c) 2024 Maxime Malgorn Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index ef1ea02..ad0e3ef 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,82 @@ -# Storybook Addon Branch switcher -Navigate between multiple branches directly from Storybook +# Storybook Branch switcher -### Development scripts +A Storybook addon to navigate between multiple Git branches. \ +Also a command-line tool to automatically generate one instance per branch. -- `npm run start` runs babel in watch mode and starts Storybook -- `npm run build` build and package your addon code +## Installation -### Switch from TypeScript to JavaScript +Install the following module with npm: -Don't want to use TypeScript? We offer a handy eject command: `npm run eject-ts` - -This will convert all code to JS. It is a destructive process, so we recommended running this before you start writing any code. - -## What's included? - -![Demo](https://user-images.githubusercontent.com/42671/107857205-e7044380-6dfa-11eb-8718-ad02e3ba1a3f.gif) - -The addon code lives in `src`. It demonstrates all core addon related concepts. The three [UI paradigms](https://storybook.js.org/docs/react/addons/addon-types#ui-based-addons) - -- `src/Tool.tsx` -- `src/Panel.tsx` -- `src/Tab.tsx` - -Which, along with the addon itself, are registered in `src/manager.ts`. - -Managing State and interacting with a story: - -- `src/withGlobals.ts` & `src/Tool.tsx` demonstrates how to use `useGlobals` to manage global state and modify the contents of a Story. -- `src/withRoundTrip.ts` & `src/Panel.tsx` demonstrates two-way communication using channels. -- `src/Tab.tsx` demonstrates how to use `useParameter` to access the current story's parameters. - -Your addon might use one or more of these patterns. Feel free to delete unused code. Update `src/manager.ts` and `src/preview.ts` accordingly. - -Lastly, configure you addon name in `src/constants.ts`. - -### Bundling - -Addons can interact with a Storybook project in multiple ways. It is recommended to familiarize yourself with [the basics](https://storybook.js.org/docs/react/addons/introduction) before getting started. - -- Manager entries are used to add UI or behavior to the Storybook manager UI. -- Preview entries are used to add UI or behavior to the preview iframe where stories are rendered. -- Presets are used to modify the Storybook configuration, similar to how [users can configure their `main.ts` configurations](https://storybook.js.org/docs/react/api/main-config). - -Since each of these places represents a different environment with different features and modules, it is also recommended to split and build your modules accordingly. This addon-kit comes with a preconfigured [bundling configuration](./tsup.config.ts) that supports this split, and you are free to modify and extend it as needed. - -You can define which modules match which environments in the [`package.json#bundler`](./package.json) property: - -- `exportEntries` is a list of module entries that users can manually import from anywhere they need to. For example, you could have decorators that users need to import into their `preview.ts` file or utility functions that can be used in their `main.ts` files. -- `managerEntries` is a list of module entries meant only for the manager UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly. -- `previewEntries` is a list of module entries meant only for the preview UI. These modules will be bundled to ESM and won't include types since they are mostly loaded by Storybook directly. - -Manager and preview entries are only used in the browser so they only output ESM modules. Export entries could be used both in the browser and in Node depending on their use case, so they both output ESM and CJS modules. - -#### Globalized packages - -Storybook provides a predefined set of packages that are available in the manager UI and the preview UI. In the final bundle of your addon, these packages should not be included. Instead, the imports should stay in place, allowing Storybook to replace those imports with the actual packages during the Storybook build process. - -The list of packages differs between the manager and the preview, which is why there is a slight difference between `managerEntries` and `previewEntries`. Most notably, `react` and `react-dom` are prebundled in the manager but not in the preview. This means that your manager entries can use React to build UI without bundling it or having a direct reference to it. Therefore, it is safe to have React as a `devDependency` even though you are using it in production. _Requiring React as a peer dependency would unnecessarily force your users to install React._ - -An exception to this rule is if you are using React to inject UI into the preview, which does not come prebundled with React. In such cases, you need to move `react` and `react-dom` to a peer dependency. However, we generally advise against this pattern since it would limit the usage of your addon to React-based Storybooks. - -### Metadata - -Storybook addons are listed in the [catalog](https://storybook.js.org/addons) and distributed via npm. The catalog is populated by querying npm's registry for Storybook-specific metadata in `package.json`. This project has been configured with sample data. Learn more about available options in the [Addon metadata docs](https://storybook.js.org/docs/react/addons/addon-catalog#addon-metadata). +```sh +npm i --save-dev storybook-branch-switcher +``` -## Release Management +or with yarn: -### Setup +```sh +yarn add -D storybook-branch-switcher +``` -This project is configured to use [auto](https://github.com/intuit/auto) for release management. It generates a changelog and pushes it to both GitHub and npm. Therefore, you need to configure access to both: +Then, add following content to `.storybook/main.js` -- [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-access-tokens) Create a token with both _Read and Publish_ permissions. -- [`GH_TOKEN`](https://github.com/settings/tokens) Create a token with the `repo` scope. +```js +module.exports = { + addons: ['storybook-branch-switcher'] +}; +``` -Then open your `package.json` and edit the following fields: +## CLI -- `name` -- `author` -- `repository` +### Usage -#### Local +This package exports a script called `sb-branch-switcher` which will automatically generate one Storybook instance per +branch, based on your Git workflow. -To use `auto` locally create a `.env` file at the root of your project and add your tokens to it: +### CLI Configuration -```bash -GH_TOKEN= -NPM_TOKEN= -``` +The CLI needs a configuration file located at `.storybook/.branches.json` by default. But you can create this file in +another location and pass the path to the CLI with the `--config` or `--c` argument. -Lastly, **create labels on GitHub**. You’ll use these labels in the future when making changes to the package. +Example : `sb-branch-switcher --config libs/storybook-host/.storybook/.branches.json` -```bash -npx auto create-labels -``` +Here is the explanation of all available options: -If you check on GitHub, you’ll now see a set of labels that `auto` would like you to use. Use these to tag future pull requests. +| Key | Default | Description | +|----------------|----------------|-----------------------------------------------------------------------| +| from | - | **(mandatory)** Where the Storybook instance is located after a build | +| to | - | **(mandatory)** Where all Storybook instances will be copied | +| directory | current folder | Absolute path where the project belongs | +| default_branch | master | Your default Git branch | +| default_root | true | Copy instance for default branch into root folder | +| provider | - | Configuration to retrieve branches and commits to process | -#### GitHub Actions +### Bitbucket (opened PRs) -This template comes with GitHub actions already set up to publish your addon anytime someone pushes to your repository. +This provider enables you to generate one Storybook instance per opened PR of a Bitbucket repository (supports cloud and +on-premise servers). -Go to `Settings > Secrets`, click `New repository secret`, and add your `NPM_TOKEN`. +| Key | Default | Description | +|------------|-----------------------|------------------------------------------------------------| +| type | - | **(mandatory)** must be **"bitbucket"** | +| project | - | **(mandatory)** name of the Bitbucket project to target | +| repository | - | **(mandatory)** name of the Bitbucket repository to target | +| url | https://bitbucket.org | Bitbucket host to connect to | -### Creating a release +If the Bitbucket instance needs an authorization, you can pass the HTTP token to the Rest API in environment +variable `BITBUCKET_TOKEN`. -To create a release locally you can run the following command, otherwise the GitHub action will make the release for you. +### Configuration file example -```sh -npm run release +```json +{ + "from": "dist/storybook", + "to": "dist/storybook-bundle", + "default_branch": "master", + "default_root": true, + "provider": { + "type": "bitbucket", + "project": "my-project", + "repository": "my-design-system" + } +} ``` - -That will: - -- Build and package the addon code -- Bump the version -- Push a release to GitHub and npm -- Push a changelog to GitHub diff --git a/package-lock.json b/package-lock.json index dfb62b5..eddf383 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "storybook-addon-branch-switcher", + "name": "storybook-branch-switcher", "version": "0.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "storybook-addon-branch-switcher", + "name": "storybook-branch-switcher", "version": "0.0.0", "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 4327ef1..ad76ce7 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "storybook-addon-branch-switcher", + "name": "storybook-branch-switcher", "version": "0.0.0", "description": "Navigate between multiple branches directly from Storybook", "keywords": [ @@ -7,7 +7,7 @@ ], "repository": { "type": "git", - "url": "https://github.com/utarwyn/storybook-addon-branch-switcher" + "url": "https://github.com/utarwyn/storybook-branch-switcher" }, "license": "MIT", "author": "utarwyn ", diff --git a/src/constants.ts b/src/constants.ts index b9fd300..8108bde 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -1,8 +1,6 @@ -import * as process from "process"; - -export const ADDON_ID = "storybook-addon-branch-switcher"; -export const PARAM_KEY = 'branches' as const; -export const GLOBAL_KEY = 'branch' as const; +export const ADDON_ID = "storybook-branch-switcher"; +export const PARAM_KEY = "branches" as const; +export const GLOBAL_KEY = "branch" as const; export const BRANCH_SWITCHER_ID = `${ADDON_ID}/switcher` as const; export interface BranchSwitcherParameters { @@ -14,7 +12,7 @@ export interface BranchSwitcherParameters { export const DEFAULT_ADDON_PARAMETERS: BranchSwitcherParameters = { list: [], - defaultBranch: 'master', - currentBranch: 'master', - hostname: undefined, -} + defaultBranch: "master", + currentBranch: "master", + hostname: undefined +};