1 | # Storybook Chromatic & Storybook Chroma
|
2 |
|
3 | A CLI to connect your Storybook with Chromatic or Chroma.
|
4 |
|
5 | <img width="100%" src="https://user-images.githubusercontent.com/3070389/63930825-5abe5f00-ca54-11e9-8320-7ee949823458.gif" alt="">
|
6 |
|
7 | ## Install
|
8 |
|
9 | ```sh
|
10 | yarn add storybook-chromatic
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | You can use this package normally, which means installing it and adding a script called `chromatic` to your `package.json`
|
16 |
|
17 | ```
|
18 | "chromatic": "chromatic",
|
19 | ```
|
20 |
|
21 | But alternatively (and this is useful for testing) you can use npx:
|
22 |
|
23 | **Use a git branch**:
|
24 | ```sh
|
25 | npx -p chromaui/chromatic-cli#master chromatic --dev
|
26 | ```
|
27 |
|
28 | **Use a debug version on npm**:
|
29 | ```sh
|
30 | npx -p storybook-chromatic chromatic
|
31 | ```
|
32 |
|
33 | Using npx has pros and cons:
|
34 |
|
35 | - đź‘Ť You'll never be out of date, you'll use the latest version every time, never have to worry about upgrading this.
|
36 | - đź‘Ť You don't need this package as a dependency, and don't need to install it during local development
|
37 | - đź‘Ž This will add a delay when you actually do want to run this, like in your CI, delaying feedback.
|
38 |
|
39 | ### Main options
|
40 |
|
41 | ```
|
42 | --app-code="<your app code>"
|
43 | ```
|
44 |
|
45 | You can also use the environment variable: `CHROMATIC_APP_CODE`
|
46 |
|
47 | ### Storybook options
|
48 |
|
49 | ```
|
50 | --build-script-name [name], -b The npm script that builds your Storybook [build-storybook]
|
51 | --script-name [name], -s The npm script that starts your Storybook [storybook]
|
52 | --exec <command>, -e Alternatively, a full command to run to start your storybook
|
53 | --do-not-start, -S Don't attempt to start or build; use if your Storybook is already running
|
54 |
|
55 | --storybook-port <port>, -p What port is your Storybook running on (auto detected from -s, if set)
|
56 | --storybook-url <url>, -u Storybook is already running at (external) url (implies -S)'
|
57 | --storybook-build-dir, -d <dirname> Provide a directory with your built storybook; use if you've already built your storybook
|
58 | --storybook-https Use if Storybook is running on https (auto detected from -s, if set)
|
59 | --storybook-cert <path> Use if Storybook is running on https (auto detected from -s, if set)
|
60 | --storybook-key <path> Use if Storybook is running on https (auto detected from -s, if set)
|
61 | --storybook-ca <ca> Use if Storybook is running on https (auto detected from -s, if set)
|
62 | ```
|
63 |
|
64 | These options are not required, this CLI is 0-config if you have a `build-storybook` script in your `package.json`.
|
65 |
|
66 | ### Chromatic options
|
67 |
|
68 | ```
|
69 | --auto-accept-changes [branch] Accept any (non-error) changes or new stories for this build [only for <branch> if specified]'
|
70 | --exit-zero-on-changes [branch] Use a 0 exit code if changes are detected (i.e. don't stop the build) [only for <branch> if specified]
|
71 | --ignore-last-build-on-branch [branch] Do not use the last build on this branch as a baseline if it is no longer in history (i.e. branch was rebased) [only for <branch> if specified]'
|
72 | --preserve-missing Treat missing stories as unchanged (as opposed to deleted) when comparing to the baseline'
|
73 | --no-interactive Do not prompt for package.json changes
|
74 | --only <component:story> Only run a single story or a glob-style subset of stories (for debugging purposes
|
75 | ```
|
76 |
|
77 | ### Debug options
|
78 |
|
79 | ```
|
80 | --skip Skip chromatic tests (mark as passing)
|
81 | --list List available stories (for debugging purposes)
|
82 | --ci This build is running on CI, non-interactively (alternatively, pass CI=true)
|
83 | --debug Output more debugging information
|
84 | ```
|
85 |
|
86 | ### Environment variables
|
87 |
|
88 | This package will load any variables from a `.env` file if present
|
89 |
|
90 | ## Contributing
|
91 |
|
92 | Because of the nature of this package: it being a connector between Storybook and a web service, you may need an app code to test this locally. Just send us a message at opensource@hichroma.com or sign up for an account!
|
93 |
|
94 | All contributions are welcome!
|
95 |
|
96 | ## Future plans:
|
97 |
|
98 | - We'd like to unify this so there's just a single package on npm.
|
99 | - Migrate to Typescript
|
100 | - Deprecate all the storybook options in favor of a sane `--config` flag
|
101 |
|
102 | ## Publishing
|
103 |
|
104 | We publish with a script:
|
105 |
|
106 | ```sh
|
107 | ./scripts/publish.js
|
108 | ```
|
109 |
|
110 | You can pass any flags to this you'd normally be able to pass to `npm publish`, such as `--dry-run` or `--tag="alpha"`.
|
111 |
|
112 | Before publishing we check if the current user has permissions and if the version isn't already on npm
|
113 |
|
114 | ## Compatibility & versioning
|
115 |
|
116 | Compatibility is guaranteed between this package and Chromatic like so:
|
117 |
|
118 | - Production Chromatic ensures it’s compatible with what’s on NPM
|
119 | - What's on the master branch is equal to what's published on NPM
|
120 | - This package ensures it’s compatible with production Chromatic
|
121 |
|
122 | To facilitate upgrading in the future, removing and adding features, this is the process:
|
123 |
|
124 | - Any new features will have to be on Chromatic production before they could be used in this package
|
125 | - We can feature flags to be able to test new functionality
|
126 | - Chromatic production can not remove any features this package depends on until after the usage has been removed from this package.
|
127 | Plus a grace period so users have upgraded
|