Add a globs guide

chromaui · Aug 2, 2024 · fc7e62a · fc7e62a
1 parent 2a59cd0
commit fc7e62a
Show file tree

Hide file tree

Showing 12 changed files with 141 additions and 42 deletions.
diff --git a/src/components/ConfigurationOptions/FilterableConfigOptions.tsx b/src/components/ConfigurationOptions/FilterableConfigOptions.tsx
@@ -43,7 +43,7 @@ export const FilterableConfigOptions = ({
         <DropdownMenu
           label={
             <>
-              Filter based on platform
+              Filter by platform
               <Icon name="filter" aria-hidden size={12} />
             </>
           }

diff --git a/src/content/ci/azure-pipelines.mdx b/src/content/ci/azure-pipelines.mdx
@@ -23,10 +23,10 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
 
     trigger:
       - main
-    
+
     pool:
       vmImage: 'ubuntu-latest'
-    
+
     stages:
       - stage: UI_Tests
         displayName: "UI Tests"
@@ -57,18 +57,18 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
                   script: npx chromatic
                 env:
                   CHROMATIC_PROJECT_TOKEN: $(CHROMATIC_PROJECT_TOKEN)
-    ```   
+    ```
   </Fragment>
   <Fragment slot="playwright">
     ```yml
     # azure-pipelines.yml
 
     trigger:
       - main
-    
+
     pool:
       vmImage: 'ubuntu-latest'
-    
+
     stages:
       - stage: UI_Tests
         displayName: "UI Tests"
@@ -101,8 +101,8 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
                   CI: "true"
               - task: PublishPipelineArtifact@1
                 inputs:
-                  # Chromatic automatically defaults to the test-results directory. 
-                  # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly. 
+                  # Chromatic automatically defaults to the test-results directory.
+                  # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly.
                   targetPath: test-results
                   artifact: test-results
                   publishLocation: "pipeline"
@@ -141,18 +141,18 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
                 env:
                   CHROMATIC_PROJECT_TOKEN: $(CHROMATIC_PROJECT_TOKEN)
                   CHROMATIC_ARCHIVE_LOCATION: "test-results"
-    ```   
+    ```
   </Fragment>
   <Fragment slot="cypress">
     ```yml
     # azure-pipelines.yml
-    
+
     trigger:
       - main
-    
+
     pool:
       vmImage: 'ubuntu-latest'
-    
+
     stages:
       - stage: UI_Tests
         displayName: "UI Tests"
@@ -189,8 +189,8 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
                   ELECTRON_EXTRA_LAUNCH_ARGS: --remote-debugging-port=9222
               - task: PublishPipelineArtifact@1
                 inputs:
-                  # Chromatic automatically defaults to the cypress/downloads directory. 
-                  # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly. 
+                  # Chromatic automatically defaults to the cypress/downloads directory.
+                  # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly.
                   targetPath: cypress/downloads
                   artifact: test-results
                   publishLocation: "pipeline"
@@ -229,7 +229,7 @@ To integrate Chromatic with your existing pipeline, you'll need to add the follo
                 env:
                   CHROMATIC_PROJECT_TOKEN: $(CHROMATIC_PROJECT_TOKEN)
                   CHROMATIC_ARCHIVE_LOCATION: "cypress/downloads"
-    ```   
+    ```
   </Fragment>
 </IntegrationSnippets>
 
@@ -587,10 +587,10 @@ Read our [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|your-custom-branch/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/bitbucket-pipelines.mdx b/src/content/ci/bitbucket-pipelines.mdx
@@ -453,10 +453,10 @@ Read our [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|your-custom-branch/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/circleci.mdx b/src/content/ci/circleci.mdx
@@ -477,10 +477,10 @@ Read our [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|dependabot/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/custom-ci-provider.mdx b/src/content/ci/custom-ci-provider.mdx
@@ -284,10 +284,10 @@ Read our official [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|dependabot/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/github-actions.mdx b/src/content/ci/github-actions.mdx
@@ -67,7 +67,7 @@ In your `.github/workflows` directory, create a new file called `chromatic.yml`
               fetch-depth: 0
           - uses: actions/setup-node@v4
             with:
-              node-version: 20    
+              node-version: 20
           - name: Install dependencies
             # ⚠️ See your package manager's documentation for the correct command to install dependencies in a CI environment.
             run: npm ci
@@ -78,8 +78,8 @@ In your `.github/workflows` directory, create a new file called `chromatic.yml`
           - uses: actions/upload-artifact@v4
             if: always()
             with:
-              # Chromatic automatically defaults to the test-results directory. 
-              # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly. 
+              # Chromatic automatically defaults to the test-results directory.
+              # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly.
               name: test-results
               path: ./test-results
               retention-days: 30
@@ -142,11 +142,11 @@ In your `.github/workflows` directory, create a new file called `chromatic.yml`
             uses: cypress-io/github-action@v6
             env:
               ELECTRON_EXTRA_LAUNCH_ARGS: "--remote-debugging-port=9222"
-            with: 
+            with:
               start: npm run dev
           - uses: actions/upload-artifact@v4
             with:
-              # Chromatic automatically defaults to the cypress/downloads directory. 
+              # Chromatic automatically defaults to the cypress/downloads directory.
               # Replace with the path to your custom directory and adjust the CHROMATIC_ARCHIVE_LOCATION environment variable accordingly.
               name: test-results
               path: ./cypress/downloads
@@ -433,7 +433,7 @@ Multiple file patterns can also be provided as follows:
 
 <div class="aside">
 
-The `externals` option also accept additional glob patterns defined via [picomatch].
+The `externals` option also accept additional glob patterns defined via [picomatch](https://github.com/micromatch/picomatch?tab=readme-ov-file#globbing-features). See the [globs guide] for more info.
 
 </div>
 
@@ -630,7 +630,7 @@ jobs:
           skip: "dependabot/**" # 👈 Option to skip Chromatic for certain branches
 ```
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```yml
 skip: "@(renovate/**|dependabot/**)"
@@ -642,7 +642,7 @@ Read our official [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
 [TurboSnap]: /docs/turbosnap
 
 #### Skip Chromatic in a Monorepo when no UI files have changed

diff --git a/src/content/ci/gitlab.mdx b/src/content/ci/gitlab.mdx
@@ -455,10 +455,10 @@ Read our official [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|your-custom-branch/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/jenkins.mdx b/src/content/ci/jenkins.mdx
@@ -530,10 +530,10 @@ Read our official [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|dependabot/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/src/content/ci/travisci.mdx b/src/content/ci/travisci.mdx
@@ -412,10 +412,10 @@ Read our [CLI documentation](/docs/cli#configuration-options).
 
 </div>
 
-To apply this to multiple branches, use an "extended glob". See [picomatch] for details.
+To apply this to multiple branches, use an "extended glob". See the [globs guide] for details.
 
 ```shell
 npx chromatic --skip '@(renovate/**|dependabot/**)'
 ```
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
diff --git a/...configuration/configuration-reference.mdx → src/content/configuration/configure.mdx b/...configuration/configuration-reference.mdx → src/content/configuration/configure.mdx
@@ -15,8 +15,10 @@ Note that the config file only supports a subset of these options. Some of the o
 file. The next section tags each option with the appropriate context.
 
 <div class="aside">
-  **Glob Types**: Where supported, globs are handled via [picomatch]. You can
-  verify your glob pattern using the
+  **Glob Types**: Where supported, globs are handled via
+  [picomatch](https://www.npmjs.com/package/picomatch#globbing-features). To
+  learn refer to our [guide on globs](/docs/globs) and to verify your glob
+  pattern use the
   [picomatch-playground](https://picomatch-playground-ebjlxm.csb.app/).
 </div>
 
@@ -78,5 +80,4 @@ The options listed below are no longer supported by our CLI and will not yield a
 | `--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`                                                       |
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
 [https-proxy-agent]: https://www.npmjs.com/package/https-proxy-agent
diff --git a/src/content/guides/globs.md b/src/content/guides/globs.md
@@ -0,0 +1,98 @@
+---
+layout: "../../layouts/Layout.astro"
+title: Globs
+description: Learn how to use Storybook parameters to configure Chromatic features at the project, component, and story level
+sidebar: { order: 9 }
+---
+
+# Globs
+
+Chromatic options like `onlyStoryFiles` and `externals` allow you to include or exclude specific files or directories. You can specify a single file, a list using an array or by passing the CLI flag multiple times. Additionally, you can use wildcard characters known as [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns) to define sets of files or directories.
+
+Chromatic handles globs using [picomatch](https://www.npmjs.com/package/picomatch). Refer to the [picomatch documentation](https://github.com/micromatch/picomatch?tab=readme-ov-file#globbing-features) for a complete overview of the syntax.
+
+## How to verify your glob pattern
+
+[Picomatch playground](https://picomatch-playground-ebjlxm.csb.app/) is a handy tool for testing your glob patterns. Let's look at some examples to understand how to use globs with Chromatic.
+
+Imagine we have a project with the following list of files. Copy and paste it into the `File structure` text box of the [Picomatch playground](https://picomatch-playground-ebjlxm.csb.app/).
+
+```
+.stories/preview.jsx
+.stories/config/backgrounds.ts
+.stories/config/msw-default-handlers.ts
+.stories/decorators/auth-wrapper.tsx
+.stories/decorators/redux-wrapper.tsx
+src/core/show-metrics/toggle-show-metrics-banner.tsx
+.stories/decorators/language-wrapper.tsx
+src/core/pdf-preview/pdf-preview-test-story.tsx
+src/i18n.js
+src/core/api/program-api/program-api-fixtures.ts
+.stories/config/msw-handlers/msw-sales-workflow-preferences-api.ts
+.stories/config/msw-handlers/msw-organization-handlers.ts
+.stories/config/msw-handlers/msw-validate-credit-token-api-handlers.ts
+.stories/config/msw-handlers/msw-credit-application-api-handlers.ts
+.stories/config/msw-handlers/msw-document-api-handlers.ts
+.stories/config/msw-handlers/msw-features-handlers.ts
+.stories/config/msw-handlers/msw-live-proposal-api-handlers.ts
+.stories/config/msw-handlers/msw-utility-api-handlers.ts
+.stories/config/msw-handlers/msw-site-api.handlers.ts
+.stories/config/msw-handlers/msw-metrics-handlers.ts
+.stories/config/msw-handlers/msw-quote-api-handlers.ts
+src/core/api/assignment-api/assignment-fixtures.ts
+.stories/config/msw-handlers/msw-contact-api.ts
+.stories/config/msw-handlers/msw-address-api-handlers.ts
+.stories/config/msw-handlers/msw-product-handlers.ts
+.stories/config/msw-handlers/msw-quote-template-api-handlers.ts
+.stories/config/msw-handlers/msw-design-desk-template-api-handlers.ts
+.stories/config/msw-handlers/msw-deal-tracker-dashboard-api-handlers.ts
+.stories/config/msw-handlers/msw-report-definition-api-handlers.ts
+src/core/show-metrics/toggle-show-metrics-banner.styl
+src/translations/proposal/en.ts
+src/translations/credit-application/en.ts
+src/translations/proposal/es.ts
+src/translations/credit-application/es.ts
+src/translations/project/en.ts
+src/translations/project/es.ts
+src/core/api/organization-testimonial-api/organization-testimonial-api-fixtures.ts
+public/test-files/test-pdf.pdf
+public/test-files/test-pdf-spanish.pdf
+src/core/api/features/features-api-fixtures.ts
+src/core/api/utility-api/utility-api-fixtures.ts
+src/core/edit-usage/edit-usage-table-fixtures.ts
+src/components/settings/settings-quote/quote-templates/quote-templates-react/quote-templates-fixtures.ts
+src/core/api/design-desk-template-api/design-desk-template-api-fixtures/design-desk-template-detail-fixture.ts
+src/core/api/report-definition-api/report-definition-api-fixtures.ts
+```
+
+Below are different scenarios that demonstrate how to use globs to include or exclude files or directories. Try copy and pasting the examples into the `Glob string` text box of the playground to see the results.
+
+### Scenario 1: Exclude all files in the `.stories` directory
+
+```
+.stories/**
+```
+
+### Scenario 2: Exclude all TypeScript files and TypeScript files with React components
+
+```
+**/*.ts|**/*.tsx|**/*.js.  # Use | to divide
+```
+
+### Scenario 3: Exclude specific MSW handlers
+
+```
+.stories/config/msw-handlers/**
+```
+
+### Scenario 4: Exclude translation files
+
+```
+src/translations/**
+```
+
+### Scenario 5: Exclude everything but a specific file
+
+```
+!(.stories/config/msw-handlers/msw-quote-api-handlers.ts)
+```
diff --git a/src/content/turbosnap/setup-turbosnap.mdx b/src/content/turbosnap/setup-turbosnap.mdx
@@ -216,7 +216,7 @@ Similar to source code changes, the `--untraced` flag can also be used to ignore
 
 ### Enable or disable for specific branches
 
-To enable TurboSnap for specific branches, pass a glob to `--only-changed` (e.g., `chromatic --only-changed "feature/*"`). Use a negating glob (e.g. `chromatic --only-changed "!(main)"`) to enable all but certain branches. See [picomatch] for details.
+To enable TurboSnap for specific branches, pass a glob to `--only-changed` (e.g., `chromatic --only-changed "feature/*"`). Use a negating glob (e.g. `chromatic --only-changed "!(main)"`) to enable all but certain branches. See the [globs guide] for details.
 
 ### Using TurboSnap in a monorepo
 
@@ -271,7 +271,7 @@ Learn more about using [onlyStoryFiles](/docs/monorepos/#with-onlystoryfiles) an
 
 </div>
 
-[picomatch]: https://www.npmjs.com/package/picomatch#globbing-features
+[globs guide]: /docs/globs
 
 ---