Show instructional UI if main.js updating fails

package.json

@@ -62,6 +62,7 @@
     "chromatic": "^6.22.0",
     "date-fns": "^2.30.0",
     "pluralize": "^8.0.0",
+    "ts-dedent": "^2.2.0",
     "urql": "^4.0.3",
     "uuid": "^9.0.0"
   },

src/Panel.tsx

@@ -15,6 +15,7 @@ import {
 } from "./constants";
 import { Authentication } from "./screens/Authentication/Authentication";
 import { LinkedProject } from "./screens/LinkProject/LinkedProject";
+import { LinkingProjectFailed } from "./screens/LinkProject/LinkingProjectFailed";
 import { LinkProject } from "./screens/LinkProject/LinkProject";
 import { VisualTests } from "./screens/VisualTests/VisualTests";
 import { client, Provider, useAccessToken } from "./utils/graphQLClient";
@@ -68,7 +69,15 @@ export const Panel = ({ active }: PanelProps) => {
     },
     [api]
   );
-  const [projectId, updateProject, projectIdChanged, clearProjectIdChanged] = useProjectId();
+  const [
+    projectId,
+    projectToken,
+    configDir,
+    updateProject,
+    updatingProjectFailed,
+    projectIdUpdated,
+    clearProjectIdUpdated,
+  ] = useProjectId();
 
   // Render a hidden element when the addon panel is not active.
   // Storybook's AddonPanel component does the same but it's not styleable so we don't use it.
@@ -84,12 +93,22 @@ export const Panel = ({ active }: PanelProps) => {
       </Provider>
     );
 
-  if (projectIdChanged) {
+  if (updatingProjectFailed) {
+    return (
+      <LinkingProjectFailed
+        projectId={projectId}
+        projectToken={projectToken}
+        configDir={configDir}
+      />
+    );
+  }
+
+  if (projectIdUpdated) {
     return (
       <Provider key={PANEL_ID} value={client}>
         <LinkedProject
           projectId={projectId}
-          goToNext={clearProjectIdChanged}
+          goToNext={clearProjectIdUpdated}
           setAccessToken={setAccessToken}
         />
       </Provider>

src/constants.ts

@@ -22,3 +22,7 @@ export type UpdateProjectPayload = {
 };
 
 export const PROJECT_UPDATED = `${ADDON_ID}/projectUpdated`;
+export const PROJECT_UPDATING_FAILED = `${ADDON_ID}/projectUpdatingFailed`;
+export type ProjectUpdatingFailedPayload = {
+  configDir: string;
+};

src/gql/graphql.ts

@@ -382,6 +382,7 @@ export type CompletedBuildTestsArgs = {
   first?: InputMaybe<Scalars['Int']['input']>;
   last?: InputMaybe<Scalars['Int']['input']>;
   orderBy?: InputMaybe<CompletedBuildTestsOrder>;
+  statuses?: InputMaybe<Array<TestStatus>>;
   storyId?: InputMaybe<Scalars['String']['input']>;
 };
 
@@ -556,6 +557,13 @@ export type Image = {
   imageWidth: Scalars['Int']['output'];
 };
 
+export type LocalBuildsSpecifierInput = {
+  /** If set, only return builds with isLocalBuild set to this value */
+  isLocalBuild?: InputMaybe<Scalars['Boolean']['input']>;
+  /** If set, return all global builds, and only local builds from this email hash */
+  localBuildEmailHash?: InputMaybe<Scalars['String']['input']>;
+};
+
 export type Mutation = {
   __typename?: 'Mutation';
   bulkCreateFigmaMetadata: Array<FigmaMetadata>;
@@ -683,6 +691,7 @@ export type PreparedBuildTestsArgs = {
   first?: InputMaybe<Scalars['Int']['input']>;
   last?: InputMaybe<Scalars['Int']['input']>;
   orderBy?: InputMaybe<PreparedBuildTestsOrder>;
+  statuses?: InputMaybe<Array<TestStatus>>;
   storyId?: InputMaybe<Scalars['String']['input']>;
 };
 
@@ -753,6 +762,7 @@ export type ProjectBranchNamesArgs = {
 export type ProjectLastBuildArgs = {
   branches?: InputMaybe<Array<Scalars['String']['input']>>;
   defaultBranch?: InputMaybe<Scalars['Boolean']['input']>;
+  localBuilds?: InputMaybe<LocalBuildsSpecifierInput>;
   results?: InputMaybe<Array<BuildResult>>;
   slug?: InputMaybe<Scalars['String']['input']>;
   statuses?: InputMaybe<Array<BuildStatus>>;
@@ -956,6 +966,7 @@ export type StartedBuildTestsArgs = {
   first?: InputMaybe<Scalars['Int']['input']>;
   last?: InputMaybe<Scalars['Int']['input']>;
   orderBy?: InputMaybe<StartedBuildTestsOrder>;
+  statuses?: InputMaybe<Array<TestStatus>>;
   storyId?: InputMaybe<Scalars['String']['input']>;
 };
 

src/index.ts

@@ -1,20 +1,22 @@
 /* eslint-disable no-console */
 import type { Channel } from "@storybook/channels";
-import { readConfig, writeConfig } from "@storybook/csf-tools";
 // eslint-disable-next-line import/no-unresolved
 import { getGitInfo, GitInfo, run } from "chromatic/node";
+import { relative } from "path";
 
 import {
   BUILD_ANNOUNCED,
   BUILD_STARTED,
-  CHROMATIC_ADDON_NAME,
   CHROMATIC_BASE_URL,
   GIT_INFO,
+  PROJECT_UPDATED,
+  PROJECT_UPDATING_FAILED,
+  ProjectUpdatingFailedPayload,
   START_BUILD,
   UPDATE_PROJECT,
   UpdateProjectPayload,
 } from "./constants";
-import { findConfig } from "./utils/storybook.config.utils";
+import { updateMain } from "./utils/updateMain";
 
 /**
  * to load the built addon in this test Storybook
@@ -46,7 +48,7 @@ const observeGitInfo = async (
 
 async function serverChannel(
   channel: Channel,
-  { projectToken: initialProjectToken }: { projectToken: string }
+  { projectToken: initialProjectToken, configDir }: { projectToken: string; configDir: string }
 ) {
   let projectToken = initialProjectToken;
   channel.on(START_BUILD, async () => {
@@ -81,25 +83,16 @@ async function serverChannel(
     async ({ projectId, projectToken: updatedProjectToken }: UpdateProjectPayload) => {
       projectToken = updatedProjectToken;
 
-      const mainPath = await findConfig("main");
-      const MainConfig = await readConfig(mainPath);
-
-      const addonsConfig = MainConfig.getFieldValue(["addons"]);
-      const updatedAddonsConfig = addonsConfig.map(
-        (addonConfig: string | { name: string; options?: Record<string, string> }) => {
-          const fullConfig = typeof addonConfig === "string" ? { name: addonConfig } : addonConfig;
-          if (fullConfig.name === CHROMATIC_ADDON_NAME) {
-            return {
-              ...fullConfig,
-              options: { projectId, projectToken, ...fullConfig.options },
-            };
-          }
-          return addonConfig;
-        }
-      );
-
-      MainConfig.setFieldValue(["addons"], updatedAddonsConfig);
-      await writeConfig(MainConfig);
+      try {
+        await updateMain({ projectId, projectToken });
+        channel.emit(PROJECT_UPDATED);
+      } catch (err) {
+        console.warn(`Failed to update your main configuration:\n\n ${err}`);
+        const relativeConfigDir = relative(process.cwd(), configDir);
+        channel.emit(PROJECT_UPDATING_FAILED, {
+          configDir: relativeConfigDir,
+        } satisfies ProjectUpdatingFailedPayload);
+      }
     }
   );
 

src/screens/LinkProject/LinkingProjectFailed.stories.ts

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { LinkingProjectFailed } from "./LinkingProjectFailed";
+
+const meta = {
+  component: LinkingProjectFailed,
+  args: {
+    projectId: "Project:abc123",
+    projectToken: "xzy789",
+    configDir: ".storybook",
+  },
+} satisfies Meta<typeof LinkingProjectFailed>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

src/screens/LinkProject/LinkingProjectFailed.tsx

@@ -0,0 +1,62 @@
+import { Code, Link } from "@storybook/components";
+import React from "react";
+import { dedent } from "ts-dedent";
+
+import { Container } from "../../components/Container";
+import { Heading } from "../../components/Heading";
+import { Section, Sections, Text } from "../../components/layout";
+import { Text as CenterText } from "../../components/Text";
+
+type LinkingProjectFailedProps = {
+  projectId: string;
+  projectToken: string;
+  configDir: string;
+};
+
+const addonName = "@chromaui/addon-visual-tests";
+const configureDocsLink = "https://www.chromatic.com/docs/addon-visual-tests#configure";
+
+export function LinkingProjectFailed({
+  projectId,
+  projectToken,
+  configDir,
+}: LinkingProjectFailedProps) {
+  return (
+    <Sections>
+      <Section grow>
+        <Container>
+          <CenterText>
+            <Heading>Add the Project ID to your Storybook config</Heading>
+            The Project ID will be used to reference prior tests. Please commit this change to
+            continue using this addon.
+          </CenterText>
+          <Code>
+            {dedent`
+            // ${configDir}/main.js|ts|tsx
+
+            module.exports = {
+              // ...,
+              addons: [
+                // ...
+                {
+                  name: '${addonName}',
+                  options: {
+                    projectId: '${projectId}',
+                    projectToken: '${projectToken}',
+                  },
+                },
+              ],
+            };
+            `}
+          </Code>
+          <CenterText>
+            What is this for?{" "}
+            <Link target="_new" href={configureDocsLink}>
+              Learn more ≫
+            </Link>
+          </CenterText>
+        </Container>
+      </Section>
+    </Sections>
+  );
+}

src/utils/updateMain.ts

@@ -0,0 +1,32 @@
+import { readConfig, writeConfig } from "@storybook/csf-tools";
+
+import { CHROMATIC_ADDON_NAME } from "../constants";
+import { findConfig } from "./storybook.config.utils";
+
+export async function updateMain({
+  projectId,
+  projectToken,
+}: {
+  projectId: string;
+  projectToken: string;
+}) {
+  const mainPath = await findConfig("main");
+  const MainConfig = await readConfig(mainPath);
+
+  const addonsConfig = MainConfig.getFieldValue(["addons"]);
+  const updatedAddonsConfig = addonsConfig.map(
+    (addonConfig: string | { name: string; options?: Record<string, string> }) => {
+      const fullConfig = typeof addonConfig === "string" ? { name: addonConfig } : addonConfig;
+      if (fullConfig.name === CHROMATIC_ADDON_NAME) {
+        return {
+          ...fullConfig,
+          options: { projectId, projectToken, ...fullConfig.options },
+        };
+      }
+      return addonConfig;
+    }
+  );
+
+  MainConfig.setFieldValue(["addons"], updatedAddonsConfig);
+  await writeConfig(MainConfig);
+}

src/utils/useProjectId.ts

@@ -1,25 +1,54 @@
 import { useChannel } from "@storybook/manager-api";
 import React from "react";
 
-import { UPDATE_PROJECT, UpdateProjectPayload } from "../constants";
+import {
+  PROJECT_UPDATED,
+  PROJECT_UPDATING_FAILED,
+  ProjectUpdatingFailedPayload,
+  UPDATE_PROJECT,
+  UpdateProjectPayload,
+} from "../constants";
 
 const { CHROMATIC_PROJECT_ID } = process.env;
 
 export const useProjectId = (): [
   projectId: string,
+  projectToken: string,
+  configDir: string,
   updateProject: (projectId: string, projectToken?: string) => void,
-  projectIdChanged: boolean,
-  clearProjectIdChanged: () => void
+  projectUpdatingFailed: boolean,
+  projectIdUpdated: boolean,
+  clearProjectIdUpdated: () => void
 ] => {
   const [projectId, setProjectId] = React.useState<string | null>(CHROMATIC_PROJECT_ID);
-  const [projectIdChanged, setProjectIdChanged] = React.useState(false);
+  const [projectToken, setProjectToken] = React.useState<string | null>();
+  const [projectIdUpdated, setProjectIdUpdated] = React.useState(false);
+  const [projectUpdatingFailed, setProjectUpdatingFailed] = React.useState(false);
+  const [configDir, setConfigDir] = React.useState<string | null>();
 
-  const emit = useChannel({});
+  const emit = useChannel({
+    [PROJECT_UPDATED]: () => setProjectIdUpdated(true),
+    [PROJECT_UPDATING_FAILED]: (payload: ProjectUpdatingFailedPayload) => {
+      setProjectUpdatingFailed(true);
+      setConfigDir(payload.configDir);
+    },
+  });
 
-  const updateProject = (newProjectId: string, projectToken: string) => {
-    emit(UPDATE_PROJECT, { projectId: newProjectId, projectToken } as UpdateProjectPayload);
+  const updateProject = (newProjectId: string, newProjectToken: string) => {
+    emit(UPDATE_PROJECT, {
+      projectId: newProjectId,
+      projectToken: newProjectToken,
+    } as UpdateProjectPayload);
     setProjectId(newProjectId);
-    setProjectIdChanged(true);
+    setProjectToken(newProjectToken);
   };
-  return [projectId, updateProject, projectIdChanged, () => setProjectIdChanged(false)];
+  return [
+    projectId,
+    projectToken,
+    configDir,
+    updateProject,
+    projectUpdatingFailed,
+    projectIdUpdated,
+    () => setProjectIdUpdated(false),
+  ];
 };