diff --git a/404.html b/404.html index 2e18773..4545532 100644 --- a/404.html +++ b/404.html @@ -4,7 +4,7 @@ - + @@ -29,11 +29,11 @@ - + - + - + diff --git a/about/index.html b/about/index.html index 09ba62c..d5c6a07 100644 --- a/about/index.html +++ b/about/index.html @@ -4,7 +4,7 @@ - + @@ -32,11 +32,11 @@ - + - + - + diff --git a/available-options/index.html b/available-options/index.html index e891f46..194895f 100644 --- a/available-options/index.html +++ b/available-options/index.html @@ -4,7 +4,7 @@ - + @@ -32,12 +32,12 @@ - + - + - - + + diff --git a/best-practices/index.html b/best-practices/index.html index 4e96668..dd5a84b 100644 --- a/best-practices/index.html +++ b/best-practices/index.html @@ -4,7 +4,7 @@ - + @@ -34,12 +34,12 @@ - + - + - - + + @@ -300,14 +300,14 @@

You can log into Chromatic and navigate to a build's details to confirm if TurboSnap is enabled for a specific build. If you don't see the "TurboSnap" ribbon on the right side of the screen, it most likely means TurboSnap is not enabled for that project.

✅ Good

- +

🚫 Bad

- +

@@ -330,45 +330,86 @@

Create small, fast-merging PRs for changes that disable TurboSnap

-

Some changes can disable TurboSnap for a build. These changes include:

+

Some changes can disable TurboSnap for a build. It's often the case when a module referenced by ./storybook/preview.ts[x] file is updated or when package dependencies are added/updated/removed.

+

These changes include:

We recommend making these changes in small, focused PRs and merging them as quickly as possible.

-

You can identify builds where TurboSnap is disabled by navigating to the build's details and looking for the "TurboSnap" ribbon on the right. For instance, Chromatic may indicate that a "full build" was triggered due to a change in the .storybook/preview.tsx file, possibly because React providers were updated, localized resources were modified, etc.

+

You can identify builds where TurboSnap is disabled by navigating to the build's details and looking for the "TurboSnap" ribbon on the right. For instance, Chromatic may indicate that a "full build" was triggered due to a change in the .storybook/preview.ts[x] file, possibly because React providers were updated, localized resources were modified, etc.

- +

- +

You can play with the untraced setting of your project's chromatic.config.json file to tell chromatic to ignore some of these files:

+
+
chromatic.config.json
+
{
+    "$schema": "https://www.chromatic.com/config-file.schema.json",
+    "untraced": ["**/package.json"]
+}
+
+

- # - Exclude localization files from Chromatic + # + Avoid importing modules from barrel files

-

Changes to resources.json files often disable TurboSnap and trigger a "full build" because they modify the .storybook/preview.tsx file.

-

To prevent this, add the untraced setting to your project's chromatic.config.json file:

+

Barrel files (**/index.ts[x]) are often problematic and should generally be avoided. This is particularly important when working with chromatic. If a barrel file is referenced in the .storybook/preview.ts[x] file and any module exported by that barrel file is updated, TurboSnap will be disabled, and a "full build" will be triggered.

+ +

+ # + Ignore package.json files +

+ +

Changes to package.json files will disable TurboSnap and trigger a "full build". While this can be useful if the updated package impacts the UI (e.g., Orbiter or Hopper), it is often unnecessary.

+

To avoid this, add the untraced setting to your project's chromatic.config.json file and instruct chromatic to ignore package.json files:

chromatic.config.json
{
     "$schema": "https://www.chromatic.com/config-file.schema.json",
-    "untraced": ["**/resources.json"]
+    "untraced": ["**/package.json"]
 }
-
-

If you're using Chromado, you don't need to manually add the onlyChanged setting, as it's already included by default.

-
-

Additionally, you might want to consider adding the package.json file to the untraced list as well:

+ +

+ # + Ignore localization files +

+ +

Changes to resources.json files often disable TurboSnap and trigger a "full build" because they modify the .storybook/preview.ts[x] file.

+

To prevent this, add the untraced setting to your project's chromatic.config.json file and tell chromatic to ignore resource files:

chromatic.config.json
{
     "$schema": "https://www.chromatic.com/config-file.schema.json",
-    "untraced": ["**/resources.json", "package.json"]
+    "untraced": ["**/resources.json"]
 }
+ +

+ # + Avoid large constants or utils files +

+ +

Changes to constants or utils files that are referenced by the .storybook/preview.ts[x] file will disable TurboSnap and trigger a "full build".

+

Examples of such files:

+
    +
  • Feature flags
    • +
  • Environment variables
    • +
  • Routes
    • +
  • Backend constants
    • +
  • Dates utils
    • +
  • Formatting utils
    • +
+

As a general rule, avoid referencing large files with multiple unrelated exports. Instead, aim for smaller and more focused files.

+

If you believe that updates to certain constants or utils files should not refresh the snapshot baseline, add them to the untraced setting of your project's chromatic.config.json file.

# diff --git a/getting-started/index.html b/getting-started/index.html index 0bcff34..21ef853 100644 --- a/getting-started/index.html +++ b/getting-started/index.html @@ -4,7 +4,7 @@ - + @@ -34,12 +34,12 @@ - + - + - - + + diff --git a/index.html b/index.html index e4e8183..82a265f 100644 --- a/index.html +++ b/index.html @@ -4,7 +4,7 @@ - + @@ -30,11 +30,11 @@ - + - + - + diff --git a/resources/js/config.js b/resources/js/config.js index 5554eed..f3ec4dc 100644 --- a/resources/js/config.js +++ b/resources/js/config.js @@ -1 +1 @@ -var __DOCS_CONFIG__ = {"id":"+LQx3sgN4HnzykB41t47AjA2Py9lklnwMb","key":"3LN66xgCyJG6p7sClC+gI8Yzo1tMHu1sMwR3GS+OMqs.lqywhO9VpORfhMJTEtaK+dh1441dX2bPOkARIXm1IHeUYKh2BXAV3OkljFI85sOL+KRxwZ+evA7gECgrlfM6CQ.300099","base":"/wl-chromado/","host":"gsoft-inc.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.6.0.783461401947","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"getting-started","l":"Getting started","s":""},{"n":"best-practices","l":"Best practices","s":""},{"n":"about","l":"About","v":false},{"n":"available-options","l":"Available options","s":""}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; +var __DOCS_CONFIG__ = {"id":"kAwxIH1TakkgqBw915u47wcQez/573CVBZ","key":"gYuyeBCriE9rcGiwtZNdMQ1UVFXYVYPGQpVUetXxK/M.Y1Ck8pgs/TOUosy3LWNiVZYkuErPmiaZwGyNpz0XUAc+aUxnI+vl7hvJsOK0R5dIErBvsMyxVZWMm9OF67ExlA.300110","base":"/wl-chromado/","host":"gsoft-inc.github.io","version":"1.0.0","useRelativePaths":true,"documentName":"index.html","appendDocumentName":false,"trailingSlash":true,"preloadSearch":false,"cacheBustingToken":"3.6.0.784433056123","cacheBustingStrategy":"query","sidebarFilterPlaceholder":"Filter","toolbarFilterPlaceholder":"Filter","showSidebarFilter":true,"filterNotFoundMsg":"No member names found containing the query \"{query}\"","maxHistoryItems":15,"homeIcon":"","access":[{"value":"public","label":"Public"},{"value":"protected","label":"Protected"}],"toolbarLinks":[{"id":"fields","label":"Fields"},{"id":"properties","label":"Properties"},{"id":"methods","label":"Methods"},{"id":"events","label":"Events"}],"sidebar":[{"n":"getting-started","l":"Getting started","s":""},{"n":"best-practices","l":"Best practices","s":""},{"n":"about","l":"About","v":false},{"n":"available-options","l":"Available options","s":""}],"search":{"mode":0,"minChars":2,"maxResults":20,"placeholder":"Search","hotkeys":["k"],"noResultsFoundMsg":"Sorry, no results found.","recognizeLanguages":true,"languages":[0],"preload":false},"resources":{"History_Title_Label":"History","History_ClearLink_Label":"Clear","History_NoHistory_Label":"No history items","API_AccessFilter_Label":"Access","API_ParameterSection_Label":"PARAMETERS","API_SignatureSection_Label":"SIGNATURE","API_CopyHint_Label":"Copy","API_CopyNameHint_Label":"Copy name","API_CopyLinkHint_Label":"Copy link","API_CopiedAckHint_Label":"Copied!","API_MoreOverloads_Label":"more","API_MoreDropdownItems_Label":"More","API_OptionalParameter_Label":"optional","API_DefaultParameterValue_Label":"Default value","API_InheritedFilter_Label":"Inherited","Search_Input_Placeholder":"Search","Toc_Contents_Label":"Contents","Toc_RelatedClasses_Label":"Related Classes","History_JustNowTime_Label":"just now","History_AgoTime_Label":"ago","History_YearTime_Label":"y","History_MonthTime_Label":"mo","History_DayTime_Label":"d","History_HourTime_Label":"h","History_MinuteTime_Label":"m","History_SecondTime_Label":"s"}}; diff --git a/resources/js/search.json b/resources/js/search.json index 53eb98f..88ab241 100644 --- a/resources/js/search.json +++ b/resources/js/search.json @@ -1 +1 @@ -[[{"l":"Getting started","p":["Welcome to the Chromado documentation, a library to seamlessly integrate Chromatic+ Azure Pipelines. On this page, you'll discover how this package can optimize your workflow and learn how to set it up for your environment."]},{"l":"Features","p":["Chromado aims to provide a workflow similar to the native Chromatic GitHub integration. While it's hardly as good, it's a functional workflow until Chromatic offers a native Azure Pipelines integration."]},{"l":"Build notifications","p":["The Chromatic Azure Pipelines documentation explains how to integrate Chromatic within an existing pipeline through its CLI, but it's basically it, it lacks build notifications, it's up to you to figure out this part.","Chromado resolves this by automatically providing build notifications as pull request comments whenever a Chromatic build is completed:","Pull request notification example"]},{"l":"TurboSnap","p":["Chromado is compatible with TurboSnap and will by default trigger Chromatic builds with TurboSnap activated.","If TurboSnap is disabled for your build, the PR message will indicate so. In some cases, such as for a \"rebuild\", this is fine. However, in most cases, you should review the details of your Chromatic build to understand why TurboSnap was disabled:","TurboSnap disabled warning example","Using TurboSnap is important because we pay for every snapshot captured by Chromatic. We still pay for TurnoSnaps, but they cost 1/5th of a regular snapshot."]},{"l":"Squash merge","p":["Chromatic doesn't offer any mechanism to support squash merge on Azure DevOps. This means that when using Azure DevOps as a Git provider, if you wish to keep your Chromatic baselines up-to-date, you would be constrained to merging your pull requests with regular merge commits. Fortunately, Chromado implements a workflow based on Chromatic's auto-accept-changes feature, allowing pull requests to be completed with squash merges.","Here's how it works:","Whenever you create or update a pull request, a Chromatic build will automatically be triggered. If the build fails, the Chromatic pipeline will fail, and the team will need to either accept the changes or fix the issues before completing the pull request. If the changes are accepted, unfortunately the main branch baselines will not be updated.","To update the baselines of the main branch, once the pull request has been merged, a new Chromatic build will be triggered on the main branch. This new build will automatically accept all the changes (which is fine since they have been reviewed in the pull request) and update the main branch baselines."]},{"l":"Setting up your workflow","p":["First, let's create a new Chromatic project, then set up your VSCode project, and finally create an Azure pipeline."]},{"l":"Create a new Chromatic project","p":["Request the owner of the Chromatic gsoft-inc-ado organization to create a new Chromatic project for your application. Ensure that you are added as a \"collaborator\" to the new project.","Once created, login to Chromatic and select your application project from the list.","Save your Chromatic project id. You can find the project id in the project URL under the appId parameter. For example, if your project id is 123, the project URL would be https://www.chromatic.com/manage?appId=123.","Go to Manage> Configure> Project> Setup Chromatic with this project token and save the project token.","With the Chromatic project id and token in hand, proceed to the next sections."]},{"l":"Configure your project","p":["Create a chromatic.config.json file at the root of your VSCode project and paste the following content:","Replace YOUR_CHROMATIC_PROJECT_ID by your Chromatic project id."]},{"l":"Create a new Azure pipeline","p":["First, open your application project and create a new YAML file called chromatic.yml. This file will store the configuration of your Chromatic Azure pipeline.","2.1. If your project already includes a template file to set up your pipelines, then paste the following configuration:","Most of Chromatic CLI options are accepted by the @workleap/chromado script. If an option is not accepted, the script will output an error message.","2.2. If your project doesn't include a template file to set up your pipelines, paste the following configuration:","Create a new Azure pipeline from an existing YAML file. Name this new pipeline \"Chromatic\" or choose a name that best suits your project.","Add the newly created Chromatic pipeline as a required build validation for your main branch. Ensure that the build validation is required. This is crucial as any visual changes detected by Chromatic will automatically be accepted on the main branch.","Integrate the Chromatic project id and token, saved earlier, as pipeline variables of the newly created Chromatic pipeline. These variables should be named CHROMATIC_PROJECT_TOKEN and CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN, respectively. Optionally, you can create the CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN variable as a variable group.","Variable","Permissions","CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN","Pull Request Threads: Read & Write"]},{"l":"Best practices","p":["Be sure to read our best practices page to help Workleap stay within its monthly Chromatic snapshot budget."]},{"i":"try-it","l":"Try it \uD83D\uDE80","p":["To test your new Chromatic pipeline, follow these steps:","Start a Chromatic build locally by opening a terminal at the root of the project and executing the following command: pnpm chromatic --project-token YOUR_CHROMATIC_PROJECT_TOKEN.","Go to the Chromatic application and accept all the changes to create a baseline. This guide assumes that your application already includes a few Storybook stories.","Move to a new Git branch and update an existing component watched by Chromatic to trigger a visual change. Commit the change.","Create a pull request for your new branch in Azure DevOps.","A Chromatic build should automatically trigger for the pull request, and a comment with the visual change should be added to it. The comment should indicate that Chromatic detected at least one visual change.","In the pull request comment, click on the \"Build URL\" link. Accept the changes in the Chromatic application.","Re-queue the Chromatic pipeline by clicking on the \"Re-queue\" button of the pipeline in the pull request.","Once the Chromatic pipeline completes successfully, merge the pull request.","A new Chromatic build should automatically trigger for the main branch. The changes from this new build should be automatically accepted by Chromatic, and the pipeline should complete successfully."]},{"l":"Troubleshoot issues","p":["If you encounter pnpm-lock.yaml [file] (not found) when executing the Chromatic pipeline, ensure that the pipeline point to the exact location of your project package-lock.yaml file. For example, if your package-lock.yaml is nested under a /frontend, update key: 'pnpm | $(Agent.OS) | pnpm-lock.yaml' for key: 'pnpm | $(Agent.OS) | $(System.DefaultWorkingDirectory)/frontend/pnpm-lock.yaml'.","If you encounter any other issues with the Chromatic pipeline, follow these steps:","Try adding the CHROMATIC_DEBUG environment variable to chromatic.yml and review the the pipeline logs for diagnosis:","Verify that the CHROMATIC_PROJECT_TOKEN pipeline variable value is correct. To find your Chromatic project token, log in to Chromatic, select your project in the list, and go to Manage> Configure> Project and look for Setup Chromatic with this project token.","Confirm that the projectId field in your chromatic.config.json file contains the correct project id. You can find the project id in the Chromatic project URL under the appId parameter. For example, if your project id is 123, the project URL would be https://www.chromatic.com/manage?appId=123.","Ensure that the PULL_REQUEST_COMMENT_ACCESS_TOKEN pipeline variable value is a valid, non-expired token.","If issues persist, consider disabling TurboSnap by adding the CHROMATIC_DISABLE_TURBOSNAP environment variable the chromatic.yml:","TurboSnap should be re-enabled promptly as Chromatic snapshots are not cheap. We pay for every snapshot that Chromatic takes."]}],[{"l":"Best practices","p":["To help Workleap stay within its monthly Chromatic snapshot budget, we ask teams to follow these best practices:"]},{"l":"Use TurboSnap","p":["Make sure TurboSnap is enabled, and periodically check how many snapshots were caputred for your builds with and without TurboSnap.","You can log into Chromatic and navigate to a build's details to confirm if TurboSnap is enabled for a specific build. If you don't see the \"TurboSnap\" ribbon on the right side of the screen, it most likely means TurboSnap is not enabled for that project.","✅ Good","\uD83D\uDEAB Bad"]},{"l":"Merge PRs quickly","p":["We often see PRs that stay open for multiple days or weeks with daily commits. Avoid this, as new snapshots (or TurboSnaps, which still cost 1/5th of a regular snapshot) are captured every time a commit is pushed.","As a general rule, once a PR is open and ready for review, there should be no more than 5-10 additional commits.","To help with this, if you need to share a PR that isn't ready for review, you can open it as a draft. The Chromatic CLI \"step\" will not run for PRs marked as \"draft\".","Be sure to either add drafts: false to your pipeline configuration or that your build policies do not run for \"draft\" PRs."]},{"i":"create-small-fast-merging-prs-for-changes-that-disable-turbosnap","l":"Create small, fast-merging PRs for changes that disable TurboSnap","p":["Some changes can disable TurboSnap for a build. These changes include:","Updating React providers in the application (usually in Provider.tsx)","Modifying the package.json file","We recommend making these changes in small, focused PRs and merging them as quickly as possible.","You can identify builds where TurboSnap is disabled by navigating to the build's details and looking for the \"TurboSnap\" ribbon on the right. For instance, Chromatic may indicate that a \"full build\" was triggered due to a change in the .storybook/preview.tsx file, possibly because React providers were updated, localized resources were modified, etc."]},{"l":"Exclude localization files from Chromatic","p":["Changes to resources.json files often disable TurboSnap and trigger a \"full build\" because they modify the .storybook/preview.tsx file.","To prevent this, add the untraced setting to your project's chromatic.config.json file:","If you're using Chromado, you don't need to manually add the onlyChanged setting, as it's already included by default.","Additionally, you might want to consider adding the package.json file to the untraced list as well:"]},{"l":"Only capture snapshots for Chrome","p":["Chromatic can capture snapshots across multiple browsers, which can be useful but also expensive because it multiplies the number of snapshots caputred by the number of browsers enabled.","For example, if both Chrome and Safari are enabled, 2 snapshots(or TurboSnaps) will be captured for every story.","We ask that each team enable Chrome only."]},{"l":"Avoid using Chromatic locally with Storybook","p":["Storybook allows running visual tests locally, but this is costly as it triggers the entire suite of visual tests.","Please do not use this feature. Only run visual tests from a PR."]},{"l":"Ignore PRs from the Renovate bot","p":["We want to optimize our snapshot budget and avoid using it on PRs from the Renovate bot. Although minor or patch updates to dependencies could introduce regressions, we prefer to invest our snapshot budget in detecting regressions from changes we make directly to our codebases.","Be sure to configure your CLI to ignore PRs from the Renovate bot.","Chromado disables PRs matching the renovate/** pattern by default."]}],[{"l":"About","p":["To ask a question or propose an idea, feel free to start a new discussion on Github. If you found a bug, please open an issue on Github."]},{"l":"Contributing","p":["Have a look at the contributor's documentation."]},{"l":"License","p":["See the LICENSE on Github."]}],[{"l":"Available options","p":["Most of Chromatic CLI options are accepted by Chromado. If an option is not accepted, Chromado will output an error message.","Here's how you can specify additional Chromatic CLI options:","In addition to Chromatic CLI options, a few environment variables are accepted \uD83D\uDC47"]},{"l":"CHROMATIC_DEBUG","p":["Add the CHROMATIC_DEBUG environment variable to your chromatic.yml pipeline to start a Chromatic build in \"debug\" mode and to benefit from additional logs from the Chromado:"]},{"l":"CHROMATIC_DISABLE_TURBOSNAP","p":["Add the CHROMATIC_DISABLE_TURBOSNAP environment variable to your chromatic.yml pipeline to start a Chromatic build without TurboSnap:","We strongly encourage using TurboSnap as Chromatic snapshots are not cheap."]}]] \ No newline at end of file +[[{"l":"Getting started","p":["Welcome to the Chromado documentation, a library to seamlessly integrate Chromatic+ Azure Pipelines. On this page, you'll discover how this package can optimize your workflow and learn how to set it up for your environment."]},{"l":"Features","p":["Chromado aims to provide a workflow similar to the native Chromatic GitHub integration. While it's hardly as good, it's a functional workflow until Chromatic offers a native Azure Pipelines integration."]},{"l":"Build notifications","p":["The Chromatic Azure Pipelines documentation explains how to integrate Chromatic within an existing pipeline through its CLI, but it's basically it, it lacks build notifications, it's up to you to figure out this part.","Chromado resolves this by automatically providing build notifications as pull request comments whenever a Chromatic build is completed:","Pull request notification example"]},{"l":"TurboSnap","p":["Chromado is compatible with TurboSnap and will by default trigger Chromatic builds with TurboSnap activated.","If TurboSnap is disabled for your build, the PR message will indicate so. In some cases, such as for a \"rebuild\", this is fine. However, in most cases, you should review the details of your Chromatic build to understand why TurboSnap was disabled:","TurboSnap disabled warning example","Using TurboSnap is important because we pay for every snapshot captured by Chromatic. We still pay for TurnoSnaps, but they cost 1/5th of a regular snapshot."]},{"l":"Squash merge","p":["Chromatic doesn't offer any mechanism to support squash merge on Azure DevOps. This means that when using Azure DevOps as a Git provider, if you wish to keep your Chromatic baselines up-to-date, you would be constrained to merging your pull requests with regular merge commits. Fortunately, Chromado implements a workflow based on Chromatic's auto-accept-changes feature, allowing pull requests to be completed with squash merges.","Here's how it works:","Whenever you create or update a pull request, a Chromatic build will automatically be triggered. If the build fails, the Chromatic pipeline will fail, and the team will need to either accept the changes or fix the issues before completing the pull request. If the changes are accepted, unfortunately the main branch baselines will not be updated.","To update the baselines of the main branch, once the pull request has been merged, a new Chromatic build will be triggered on the main branch. This new build will automatically accept all the changes (which is fine since they have been reviewed in the pull request) and update the main branch baselines."]},{"l":"Setting up your workflow","p":["First, let's create a new Chromatic project, then set up your VSCode project, and finally create an Azure pipeline."]},{"l":"Create a new Chromatic project","p":["Request the owner of the Chromatic gsoft-inc-ado organization to create a new Chromatic project for your application. Ensure that you are added as a \"collaborator\" to the new project.","Once created, login to Chromatic and select your application project from the list.","Save your Chromatic project id. You can find the project id in the project URL under the appId parameter. For example, if your project id is 123, the project URL would be https://www.chromatic.com/manage?appId=123.","Go to Manage> Configure> Project> Setup Chromatic with this project token and save the project token.","With the Chromatic project id and token in hand, proceed to the next sections."]},{"l":"Configure your project","p":["Create a chromatic.config.json file at the root of your VSCode project and paste the following content:","Replace YOUR_CHROMATIC_PROJECT_ID by your Chromatic project id."]},{"l":"Create a new Azure pipeline","p":["First, open your application project and create a new YAML file called chromatic.yml. This file will store the configuration of your Chromatic Azure pipeline.","2.1. If your project already includes a template file to set up your pipelines, then paste the following configuration:","Most of Chromatic CLI options are accepted by the @workleap/chromado script. If an option is not accepted, the script will output an error message.","2.2. If your project doesn't include a template file to set up your pipelines, paste the following configuration:","Create a new Azure pipeline from an existing YAML file. Name this new pipeline \"Chromatic\" or choose a name that best suits your project.","Add the newly created Chromatic pipeline as a required build validation for your main branch. Ensure that the build validation is required. This is crucial as any visual changes detected by Chromatic will automatically be accepted on the main branch.","Integrate the Chromatic project id and token, saved earlier, as pipeline variables of the newly created Chromatic pipeline. These variables should be named CHROMATIC_PROJECT_TOKEN and CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN, respectively. Optionally, you can create the CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN variable as a variable group.","Variable","Permissions","CHROMATIC_PULL_REQUEST_COMMENT_ACCESS_TOKEN","Pull Request Threads: Read & Write"]},{"l":"Best practices","p":["Be sure to read our best practices page to help Workleap stay within its monthly Chromatic snapshot budget."]},{"i":"try-it","l":"Try it \uD83D\uDE80","p":["To test your new Chromatic pipeline, follow these steps:","Start a Chromatic build locally by opening a terminal at the root of the project and executing the following command: pnpm chromatic --project-token YOUR_CHROMATIC_PROJECT_TOKEN.","Go to the Chromatic application and accept all the changes to create a baseline. This guide assumes that your application already includes a few Storybook stories.","Move to a new Git branch and update an existing component watched by Chromatic to trigger a visual change. Commit the change.","Create a pull request for your new branch in Azure DevOps.","A Chromatic build should automatically trigger for the pull request, and a comment with the visual change should be added to it. The comment should indicate that Chromatic detected at least one visual change.","In the pull request comment, click on the \"Build URL\" link. Accept the changes in the Chromatic application.","Re-queue the Chromatic pipeline by clicking on the \"Re-queue\" button of the pipeline in the pull request.","Once the Chromatic pipeline completes successfully, merge the pull request.","A new Chromatic build should automatically trigger for the main branch. The changes from this new build should be automatically accepted by Chromatic, and the pipeline should complete successfully."]},{"l":"Troubleshoot issues","p":["If you encounter pnpm-lock.yaml [file] (not found) when executing the Chromatic pipeline, ensure that the pipeline point to the exact location of your project package-lock.yaml file. For example, if your package-lock.yaml is nested under a /frontend, update key: 'pnpm | $(Agent.OS) | pnpm-lock.yaml' for key: 'pnpm | $(Agent.OS) | $(System.DefaultWorkingDirectory)/frontend/pnpm-lock.yaml'.","If you encounter any other issues with the Chromatic pipeline, follow these steps:","Try adding the CHROMATIC_DEBUG environment variable to chromatic.yml and review the the pipeline logs for diagnosis:","Verify that the CHROMATIC_PROJECT_TOKEN pipeline variable value is correct. To find your Chromatic project token, log in to Chromatic, select your project in the list, and go to Manage> Configure> Project and look for Setup Chromatic with this project token.","Confirm that the projectId field in your chromatic.config.json file contains the correct project id. You can find the project id in the Chromatic project URL under the appId parameter. For example, if your project id is 123, the project URL would be https://www.chromatic.com/manage?appId=123.","Ensure that the PULL_REQUEST_COMMENT_ACCESS_TOKEN pipeline variable value is a valid, non-expired token.","If issues persist, consider disabling TurboSnap by adding the CHROMATIC_DISABLE_TURBOSNAP environment variable the chromatic.yml:","TurboSnap should be re-enabled promptly as Chromatic snapshots are not cheap. We pay for every snapshot that Chromatic takes."]}],[{"l":"Best practices","p":["To help Workleap stay within its monthly Chromatic snapshot budget, we ask teams to follow these best practices:"]},{"l":"Use TurboSnap","p":["Make sure TurboSnap is enabled, and periodically check how many snapshots were caputred for your builds with and without TurboSnap.","You can log into Chromatic and navigate to a build's details to confirm if TurboSnap is enabled for a specific build. If you don't see the \"TurboSnap\" ribbon on the right side of the screen, it most likely means TurboSnap is not enabled for that project.","✅ Good","\uD83D\uDEAB Bad"]},{"l":"Merge PRs quickly","p":["We often see PRs that stay open for multiple days or weeks with daily commits. Avoid this, as new snapshots (or TurboSnaps, which still cost 1/5th of a regular snapshot) are captured every time a commit is pushed.","As a general rule, once a PR is open and ready for review, there should be no more than 5-10 additional commits.","To help with this, if you need to share a PR that isn't ready for review, you can open it as a draft. The Chromatic CLI \"step\" will not run for PRs marked as \"draft\".","Be sure to either add drafts: false to your pipeline configuration or that your build policies do not run for \"draft\" PRs."]},{"i":"create-small-fast-merging-prs-for-changes-that-disable-turbosnap","l":"Create small, fast-merging PRs for changes that disable TurboSnap","p":["Some changes can disable TurboSnap for a build. It's often the case when a module referenced by ./storybook/preview.ts[x] file is updated or when package dependencies are added/updated/removed.","These changes include:","Updating React providers in the application ( Provider.tsx)","Updating localization files (**/resources.json)","Updating environment variables","Updating constants files (including feature flags and routes)","Updating package dependencies (**/package.json)","We recommend making these changes in small, focused PRs and merging them as quickly as possible.","You can identify builds where TurboSnap is disabled by navigating to the build's details and looking for the \"TurboSnap\" ribbon on the right. For instance, Chromatic may indicate that a \"full build\" was triggered due to a change in the .storybook/preview.ts[x] file, possibly because React providers were updated, localized resources were modified, etc.","You can play with the untraced setting of your project's chromatic.config.json file to tell chromatic to ignore some of these files:"]},{"l":"Avoid importing modules from barrel files","p":["Barrel files (**/index.ts[x]) are often problematic and should generally be avoided. This is particularly important when working with chromatic. If a barrel file is referenced in the .storybook/preview.ts[x] file and any module exported by that barrel file is updated, TurboSnap will be disabled, and a \"full build\" will be triggered."]},{"i":"ignore-packagejson-files","l":"Ignore package.json files","p":["Changes to package.json files will disable TurboSnap and trigger a \"full build\". While this can be useful if the updated package impacts the UI (e.g., Orbiter or Hopper), it is often unnecessary.","To avoid this, add the untraced setting to your project's chromatic.config.json file and instruct chromatic to ignore package.json files:"]},{"l":"Ignore localization files","p":["Changes to resources.json files often disable TurboSnap and trigger a \"full build\" because they modify the .storybook/preview.ts[x] file.","To prevent this, add the untraced setting to your project's chromatic.config.json file and tell chromatic to ignore resource files:"]},{"l":"Avoid large constants or utils files","p":["Changes to constants or utils files that are referenced by the .storybook/preview.ts[x] file will disable TurboSnap and trigger a \"full build\".","Examples of such files:","Feature flags","Environment variables","Routes","Backend constants","Dates utils","Formatting utils","As a general rule, avoid referencing large files with multiple unrelated exports. Instead, aim for smaller and more focused files.","If you believe that updates to certain constants or utils files should not refresh the snapshot baseline, add them to the untraced setting of your project's chromatic.config.json file."]},{"l":"Only capture snapshots for Chrome","p":["Chromatic can capture snapshots across multiple browsers, which can be useful but also expensive because it multiplies the number of snapshots caputred by the number of browsers enabled.","For example, if both Chrome and Safari are enabled, 2 snapshots(or TurboSnaps) will be captured for every story.","We ask that each team enable Chrome only."]},{"l":"Avoid using Chromatic locally with Storybook","p":["Storybook allows running visual tests locally, but this is costly as it triggers the entire suite of visual tests.","Please do not use this feature. Only run visual tests from a PR."]},{"l":"Ignore PRs from the Renovate bot","p":["We want to optimize our snapshot budget and avoid using it on PRs from the Renovate bot. Although minor or patch updates to dependencies could introduce regressions, we prefer to invest our snapshot budget in detecting regressions from changes we make directly to our codebases.","Be sure to configure your CLI to ignore PRs from the Renovate bot.","Chromado disables PRs matching the renovate/** pattern by default."]}],[{"l":"About","p":["To ask a question or propose an idea, feel free to start a new discussion on Github. If you found a bug, please open an issue on Github."]},{"l":"Contributing","p":["Have a look at the contributor's documentation."]},{"l":"License","p":["See the LICENSE on Github."]}],[{"l":"Available options","p":["Most of Chromatic CLI options are accepted by Chromado. If an option is not accepted, Chromado will output an error message.","Here's how you can specify additional Chromatic CLI options:","In addition to Chromatic CLI options, a few environment variables are accepted \uD83D\uDC47"]},{"l":"CHROMATIC_DEBUG","p":["Add the CHROMATIC_DEBUG environment variable to your chromatic.yml pipeline to start a Chromatic build in \"debug\" mode and to benefit from additional logs from the Chromado:"]},{"l":"CHROMATIC_DISABLE_TURBOSNAP","p":["Add the CHROMATIC_DISABLE_TURBOSNAP environment variable to your chromatic.yml pipeline to start a Chromatic build without TurboSnap:","We strongly encourage using TurboSnap as Chromatic snapshots are not cheap."]}]] \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index a9a5116..0e2489b 100644 Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ