StaticImage component from gatsby-plugin-image does not work with storybook

[ArmanNisch]

Description

Describe the issue that you're seeing.

I am not able to render Images in storybook if they are using the StaticImage component from gatsby-plugin-image.

I see the following error in the Storybook console:

Image not loaded https://placekitten.com/800/600

index.browser-6ab2b891.js:1 Please ensure that "gatsby-plugin-image" is included in the plugins array in gatsby-config.js, and that your version of gatsby is at least 2.24.78

How can I get gatsby-plugin-image to work within a storybook Environment and/or is it possible to return some sort of default image if the sharp server is not available?

When using gatsby-plugin-image the images are processed via sharp, consequently I am unable to view these images through third-party programs such as Storybook because when storybook is running I don't have access to the sharp server used by gatsby-plugin-image.

Note: The image renders just fine when viewing the image via the Gatsby Development Server and/or when building the static site.

Steps to reproduce

1. Import a component that is making use of gatsby-plugin-image into storybook.
2. Run storybook
3. No image will be displayed

Expected result

1. If gatsby-plugin-image detects that the sharp server is not available, it should return a default image?
2. Something should be shown... no image at all is just not good.

Actual result

1. No image is shown in storybook.

Environment

System:
OS: Linux 5.8 Ubuntu 20.04.2 LTS (Focal Fossa)
CPU: (16) x64 AMD Ryzen 7 4800H with Radeon Graphics
Shell: 5.8 - /usr/bin/zsh
Binaries:
Node: 14.16.0 - ~/.nvm/versions/node/v14.16.0/bin/node
Yarn: 1.22.10 - ~/.nvm/versions/node/v14.16.0/bin/yarn
npm: 7.14.0 - ~/.nvm/versions/node/v14.16.0/bin/npm
Browsers:
Chrome: 91.0.4472.77
Firefox: 88.0.1
npmPackages:
gatsby: 3.6.2 => 3.6.2
gatsby-plugin-image: 1.6.0 => 1.6.0
gatsby-plugin-manifest: 3.6.0 => 3.6.0
gatsby-plugin-mdx: 2.6.0 => 2.6.0
gatsby-plugin-react-helmet: 4.6.0 => 4.6.0
gatsby-plugin-remove-generator: 1.1.0 => 1.1.0
gatsby-plugin-sharp: 3.6.0 => 3.6.0
gatsby-plugin-sitemap: 4.2.0 => 4.2.0
gatsby-plugin-styled-components: 4.6.0 => 4.6.0
gatsby-source-filesystem: 3.6.0 => 3.6.0
gatsby-transformer-remark: 4.3.0 => 4.3.0
gatsby-transformer-sharp: 3.6.0 => 3.6.0

[LekoArts]

You could try these new instructions: #31653
Otherwise I'd suggest asking in the repository of Storybook since this is specific to their platform.

[TeoTN]

Hey, I've just encountered the same issue. These instructions don't touch the problem.
Why do you think it doesn't belong to Gatsby? My impression is that this is a problem in Gatsby because you can't build reusable components based on StaticImage, as they can't be run properly in isolation. (And/or tested visually).

[ArmanNisch]

@TeoTN Precisely

[mosesoak]

@LekoArts This is not in Storybook's corner, sorry. You guys have a docs page that claims compatibility with Storybook. They now officially use Webpack 5, so your team should definitely reopen this as a legit Gatsby issue and help get a solution out.

Unless others are using StaticImage successfully with Storybook -- is that the case? Having just spun up a fresh project and tried, I can vouch that it doesn't work. I get the same error as listed on this discussion, this Stack Overflow post which also is unanswered, and since it was suggested to go bother the community maintainer of the addon, my issue there (not their problem).

Are you claiming that someone has actually checked your current Storybook docs page and tried out the basic Gatsby Image Plugin use cases, and it works? Because it not, closing this prematurely and trying to push it off on others isn't fair at all, nor is it becoming of a $50M funded company.

People are losing a lot of painful time over something (that may be, is it?) wrong in Gatsby's docs. More importantly if you'd shoot this to an engineer to look into as valid or not before just closing it and pushing it down, maybe you'd find that there's a pretty low lift -- just updating the docs a little or something. (And while I'm at it: having to petition unjustly closed issues just to get heard is for the birds.)

[LekoArts]

Fundamentally Gatsby and Storybook work together so I have to disagree on the sentiment that the guide is not working. StaticImage is only a part of Gatsby or more specifically gatsby-plugin-image.

StaticImage is a quite specific component and has some limitations (https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-plugin-image/#restrictions-on-using-staticimage) which you can also understand better when reading the conceptual guide: https://www.gatsbyjs.com/docs/conceptual/image-plugin-architecture/#how-staticimage-works

There's no bug in StaticImage so we wouldn't track this in our issue tracker but in GitHub Discussions. And it might be solvable similar to Static Queries as also a babel plugin handles parts of it, but it also might just not work as Storybook doesn't have all the necessary content. If it would be solvable it probably should go into the Gatsby storybook Addon so that everyone can benefit from it directly.
But realistically this would involve quite a bit of investigation and research into this matter and our priorities are not focused on this right now. It's still a third-party tool and our time is better spent on making Gatsby better for everyone.

If you don't have the time or energy to investigate this further (which is totally understandable/fine) then the guide will have a note for now that this doesn't work: #33127

[ArmanNisch]

The solution would lie in updating StaticImage to respond with an image, even if it does not have access to Sharp (the server-side image processor). This would be similar to how the old StaticImage plugin used to work.

This is not a Storybook issue, as Storybook correctly displays the Gatsby StaticImage component -> it is that the StaticImage component does not return an image if run within Storybook, as it relies on a server-side plugin (sharp) to process and return the image.

@LekoArts, I agree with @mosesoak, the current Gatsby docs do not reflect the reality of what actually is going on. Sure, Gatsby and Storybook work together, but this is clearly a bug on the part of StaticImage needing a server-side component to work properly. This makes StaticImage basically unusable in Storybook.

[mosesoak]

@LekoArts Thank you so much for updating the docs to help others avoid a time sink on this! I understand your points and appreciate your thoughtful reply and action. I'm sorry if my frustration got the better of me in my post. 🌞

For others who are trying to get Gatsby images to work in storybook, my teammate and I have found a solution:

1. Avoid StaticImage obviously, see above. If you just want a static image such as an arrow on a UI, use an img tag instead. Storybook has a static images pointer flag, -s that you can use to have your static images copied to the storybook project.
2. For dynamic images that you're querying using the gatsby graph, use GatsbyImage in presentational components and make them accept a prop like imageData: IGatsbyImageData which would be the result you'd fetch from the graph. Now set your storybook and build-storybook commands to copy your images directory as static like -s src/images. Then use the following hook in your stories:

src/hooks/useImageData.ts

import { IGatsbyImageData, Layout } from 'gatsby-plugin-image';
import { useEffect, useState } from 'react';

/**
 * For use with Storybook: spoofs a gatsby IGatsbyImageData blob by loading image to get w/h.
 *
 * @param filename Assumes src/images as base directory (set in package.json storybook script)
 * @param layout optional override for gatsby layout parameter
 * @returns
 */
export const useImageData = (
  filename: string,
  layout: Layout = 'constrained',
) => {
  // a default is provided so component types can treat it as defined
  const [imageData, setImageData] = useState<IGatsbyImageData>({
    layout: 'constrained',
    images: { fallback: { src: '' } },
    width: 0,
    height: 0,
  });

  useEffect(() => {
    const img = new Image();
    img.onload = () => {
      setImageData({
        layout,
        images: { fallback: { src: filename } },
        width: img.width,
        height: img.height,
      });
    };
    img.src = filename;

    return () => {
      img.onload = null;
    };
  }, [filename, layout]);

  return imageData;
};

PortfolioCard.stories.tsx

const Template: ComponentStory<typeof PortfolioCard> = (args) => {
  const imageData = useImageData('temporary/card-temporary.png');
  return <PortfolioCard {...args} imageData={imageData} />;
};

export const Primary = Template.bind({});
Primary.args = {
  label: 'Virtual and digital rewards',
};

PortfolioCard.tsx (excerpt)

export type PortfolioCardProps = {
  imageData: IGatsbyImageData;
  imageAlt?: string;
  label?: string;
};

export const PortfolioCard: FC<PortfolioCardProps> = ({
  label,
  imageData,
  imageAlt = '',
}) => {
  return (
    <CardContainer>
      <ImageContainer>
        <GatsbyImage image={imageData} alt={imageAlt} />
      </ImageContainer>
      {label && <Label>{label}</Label>}
    </CardContainer>
  );
};

Maybe someday we'll publish this OSS but until then, hope it helps some of you! Happy storybookin'.