Configuration reference
These options control how Chromatic behaves via the CLI, config file and the GitHub Action. Refer to branching docs and diagnosing CLI issues for more context on when to use some of these flags.
Note that the config file only supports a subset of these options. Some options are exclusive to the CLI or the config file. The next section tags each option with the appropriate context.
Glob Types: Where supported, globs are handled via picomatch. To learn more about globs and how to use them, refer to our guide on globs. To verify your glob pattern, use the picomatch-playground.
Options
autoAcceptChanges
Flag:
--auto-accept-changes
Type:
glob | boolean
Default:
false
Example:
"main"
or true
branchName
Flag:
--branch-name
Type:
string
Default:
Example:
"my-branch"
<owner>:<branch>
buildCommand
Flag:
--build-command
Type:
string
Example:
"nx run my-app:build-storybook"
Requires
--output-dir
.buildScriptName
Flag:
--build-script-name
(-b
)Type:
string
Default:
build-storybook
Example:
"build:storybook"
ci
Flag:
--ci
Type:
boolean
Default:
Example:
true
configFile
Flag:
--config.json
Type:
string
Default:
chromatic.config.json
Example:
"config/chromatic.json"
debug
Flag:
--debug
Type:
boolean
Default:
false
Example:
true
interactive: false
diagnosticsFile
Flag:
--diagnostics-file
Type:
string | boolean
Default:
false
Example:
"debug.json"
or true
Defaults to
chromatic-diagnostics.json
dryRun
Flag:
--dry-run
Type:
boolean
Default:
false
Example:
true
exitOnceUploaded
Flag:
--exit-once-uploaded
Type:
glob | boolean
Default:
false
Example:
"my-branch"
or true
0
(OK) once the built version has been published to Chromatic. Only for given branch, if specified.exitZeroOnChanges
Flag:
--exit-zero-on-changes
Type:
glob | boolean
Default:
false
Example:
"!(main)"
or true
0
rather than the usual exit code 1
. Only for given branch, if specified.externals
Flag:
--externals
Type:
string | string[]
(glob)Example:
"my-folder/**"
Requires
onlyChanged
.forceRebuild
Flag:
--force-rebuild
Type:
glob | boolean
Default:
false
Example:
"my-branch"
or true
ignoreLastBuildOnBranch
Flag:
--ignore-last-build-on-branch
Type:
glob
Example:
"my-branch"
interactive: false
Flag:
--no-interactive
Type:
boolean
Default:
Example:
false
true
in non-TTY environments.junitReport
Flag:
--junit-report
Type:
string | boolean
Default:
false
Example:
"report.xml"
or true
Defaults to
chromatic-build-{buildNumber}.xml
where the {buildNumber}
will be replaced with the actual build number.--list
Flag:
--list
Type:
boolean
Default:
false
Example:
true
Useful for debugging and diagnosing issues.
logFile
Flag:
--log-file
Type:
string | boolean
Default:
false
Example:
"logs.txt"
or true
chromatic.log
fileHashing
Flag:
--no-file-hashing
Type:
boolean
Default:
false
Example:
true
onlyChanged
Flag:
--only-changed
Type:
glob | boolean
Default:
false
Example:
true
Runs Chromatic for stories affected by files and dependencies that have changed since the baseline build, including the specified branch if provided.
onlyStoryFiles
Flag:
--only-story-files
Type:
string | string[]
(glob)Example:
"src/ui/**"
onlyStoryNames
Flag:
--only-story-names
Type:
string | string[]
(glob)Example:
"Atoms/Button/*"
outputDir
Flag:
--output-dir
(-o
)Type:
string
Default:
Example:
"storybook-static"
--patch-build
Flag:
--patch-build
Type:
string
Example:
"my-feature...main"
projectId
Type:
string
Example:
"Project:5d67dc0374b2e300209c41e7"
appId
.projectToken
Flag:
--project-token
(-t
)Type:
string
Default:
Example:
"chpt_b2aef0123456789"
CHROMATIC_PROJECT_TOKEN
instead if you can.repositorySlug
Flag:
--repository-slug
Type:
string
Default:
Example:
"owner/repositoryName"
skip
Flag:
--skip
Type:
glob | boolean
Default:
false
Example:
"my-branch"
or true
skipUpdateCheck
Flag:
--skip-update-check
Type:
boolean
Default:
false
Example:
true
storybookBaseDir
Flag:
--storybook-base-dir
Type:
string
Example:
"src/ui"
Use with
onlyChanged
and storybookBuildDir
when your Storybook is located in a subdirectory of your repository.storybookBuildDir
Flag:
--storybook-build-dir
(-d
)Type:
string
Example:
"dist/storybook"
storybookConfigDir
Flag:
--storybook-config-dir
Type:
string
Default:
.storybook
Example:
"storybook-config"
Use with
onlyChanged
and storybookBuildDir
when using a custom --config-dir
flag for Storybook.storybookLogFile
Flag:
--storybook-log-file
Type:
string | boolean
Default:
build-storybook.log
Example:
"sb.txt"
or true
traceChanged
Flag:
--trace-changed
Type:
string | boolean
Default:
false
Example:
"expanded"
or true
Requires
onlyChanged
.workingDir
Flag:
--working-dir
Type:
string
Default:
process.cwd()
Example:
"my-folder"
package.json
if installed in a subdirectory (i.e., monorepos).untraced
Flag:
--untraced
Type:
string | string[]
(glob)Example:
"my-folder/**"
Requires
onlyChanged
.uploadMetadata
Flag:
--upload-metadata
Type:
boolean
Default:
false
Example:
true
diagnosticsFile: true
and logFile: true
zip
Flag:
--zip
Type:
boolean
Default:
false
Example:
true
playwright
Flag:
--playwright
Type:
boolean
Default:
false
Example:
true
cypress
Flag:
--cypress
Type:
boolean
Default:
false
Example:
true
Environment variables
Some options can be configured through environment variables. You will typically only need these when instructed to. Flags take precedence over environment variables. Environment variables are also read from a .env
file if present.
Environment variable | Description |
---|---|
CHROMATIC_PROJECT_TOKEN | Project token, see --project-token |
CHROMATIC_SHA | Git commit hash. See troubleshooting guide for issues |
CHROMATIC_BRANCH | Git branch name. See --branch-name for additional options and troubleshooting guide for issues |
CHROMATIC_SLUG | Git repository slug (e.g., chromaui/chromatic-cli ). See troubleshooting guide for issues |
CHROMATIC_POLL_INTERVAL | Polling interval when waiting for the build to finish (default: 1000 ) |
CHROMATIC_OUTPUT_INTERVAL | Frequency of progress output while polling or uploading (default: 10000 ) |
CHROMATIC_RETRIES | Number of times to retry file upload (default: 5 ) |
CHROMATIC_STORYBOOK_VERSION | Overrides Storybook package/version detection (e.g. @storybook/react@7.0.1-alpha.25 ) |
CHROMATIC_TIMEOUT | Number of ms before giving up on storybook dev (default: 300000 (5 minutes)) |
STORYBOOK_BUILD_TIMEOUT | Number of ms before giving up on storybook build (default: 600000 (10 minutes)) |
CHROMATIC_DNS_SERVERS | Overrides the DNS server IP address(es) used by node-fetch, comma-separated. See troubleshooting guide for issues |
CHROMATIC_DNS_FAILOVER_SERVERS | Fallback DNS server IPs (default: 1.1.1.1 , 8.8.8.8 (Cloudflare, Google)). See troubleshooting guide for issues |
CI | See --ci |
LOG_LEVEL | One of: silent , error , warn , info , debug |
DISABLE_LOGGING | Set to true to disable logging. Equal to LOG_LEVEL=silent |
HTTPS_PROXY or HTTP_PROXY | Used to configure https-proxy-agent. See troubleshooting guide for issues |
CHROMATIC_ARCHIVE_LOCATION | Change the default location for archives generated by Playwright or Cypress tests |
STORYBOOK_NODE_ENV | Specify a different environment for building Storybook in (default is production ). Note that changing this value might slow down your builds or even alter the build behavior. |
Deprecated options
The following options are still supported but will be removed in a future version. If your project still uses them, we encourage you to remove them from your scripts or configuration at your earliest convenience.
CLI flag | |
---|---|
--allow-console-errors | Continue running Chromatic even if Storybook logs errors in the console. |
--app-code <token> | Renamed to --project-token . |
--diagnostics | Replaced by --diagnostics-file . |
--only | Replaced by --only-story-names . |
--preserve-missing | Replaced by --only-* based options.Refer to the following documentation for more information on its deprecation and alternatives. |
Unsupported options
The options listed below are no longer supported by our CLI and will not yield any result if you provide them in your project. We recommend removing them from your scripts and configuration.
CLI flag | |
---|---|
--do-not-start | Don’t attempt to start or build Storybook. Use this if your Storybook is already running, for example, when part of a larger app. Alias: -S |
--exec <command> | Alternatively, a shell command that starts your Storybook. Alias: -e |
--preserve-missing-specs | Preserve missing stories when publishing a partial Storybook. |
--script-name [name] | The npm script that starts your Storybook. Defaults to storybook . Alias: -s |
--storybook-port <port> | What port is your Storybook running on. Auto detected from the npm script when using --script-name . Alias: -p |
--storybook-https | Enable if Storybook runs on HTTPS (locally). Auto detected from the npm script when using --script-name . |
--storybook-cert <path> | Use with --storybook-https . Auto detected from the npm script when using --script-name . |
--storybook-key <path> | Use with --storybook-https . Auto detected from the npm script when using --script-name . |
--storybook-ca <ca> | Use with --storybook-https . Auto detected from the npm script when using --script-name . |
--storybook-url <url> | Run against an online Storybook at some URL. This implies --do-not-start . Alias: -u |