🐛 [Bug]: Image data is overridden when `inlineAssets` is `true`

[leifmarcus]

Package

storyblok-js-client (Client SDK)

Bug Description

When using the storyblok-js-client SDK and setting the option inlineAssets to true, all information of the current image is overridden. This is problematic, when for instance the alt text is different on the image, that is used in the story.

If you look into the implementation, you see, that the whole image object is replaced with the master asset object, which might have different fields, then the image, that is used in the story.

Steps to Reproduce

1. create a Story in Storyblok that has an image included
2. select an image from the Asset Library
3. override the alt text of the image in the story
4. request the story using the storyblok-js-client with inlineAssets: true.
5. See the alt text from the master image instead of the change alt text

Expected Behavior

when inlining assets, only properties, that are not present on the image attached to the story should be merged. For instance, the is_private property is not present on the attached image. Asset fields like the alt text or the caption should not be overridden.

Actual Behavior

Currently, due to the complete override of the image, all information that is changed on the attached image will be overridden from the master image which leads to not translated alt text or captions.

Code Sample

// how it is currently done in your code
if (processedNode.fieldtype === 'asset' && Array.isArray(response.data.assets)) {
  // Replace the assets array with the actual asset objects
  processedNode = {
    ...processedNode,
    // this will completely override all root level fields of the attached asset.
    ...response.data.assets.find((asset: any) => asset.id === processedNode.id),
  };
}

Environment

System:
    OS: macOS 26.0
    CPU: (14) arm64 Apple M4 Pro
    Memory: 1.12 GB / 48.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 22.19.0 - ~/.nvm/versions/node/v22.19.0/bin/node
    npm: 10.9.3 - ~/.nvm/versions/node/v22.19.0/bin/npm
    pnpm: 10.16.1 - ~/Library/pnpm/pnpm
  Browsers:
    Chrome: 140.0.7339.186
    Edge: 140.0.3485.81
    Safari: 26.0
  npmPackages:
    @storyblok/astro: ^7.2.5 => 7.3.0 
    @storyblok/richtext: ^3.7.0 => 3.8.0 
    storyblok: ^4.4.1 => 4.6.2 
    vue: ^3.5.21 => 3.5.21

Error Logs

Additional Context

No response

[leifmarcus]

I would like to open this again, as we are not able to use this version of the fix. It will fail all our current builds, as empty alt text will override alt texts from the root image.

I have another Idea how to solve the issue in a different way. What if, we change the option inlineAsset to be either true or a function. When it is a function, you will use the function to merge the assets. With this every customer could define the merge strategy as needed.

// config object is defined as
interface ISbConfig {
  // ...
  inlineAssets?: boolean | (rootAsset: IAsset, storyAsset: IAsset) => IAsset;
}

// can be used by customers like
const client = new Storyblok({
  inlineAssets: (rootAsset, storyAsset) =>({
     ...storyAsset,
     is_private: rootAsset.is_private,
     alt: storyAsset.alt || rootAsset.alt || '',
  }),
})

// another option is to use an assetResolver function
// which is used, when inlineAsset is set to true
const client = new Storyblok({
  resolveAssets: (rootAsset, storyAsset) =>({
     ...storyAsset,
     is_private: rootAsset.is_private,
     alt: storyAsset.alt || rootAsset.alt || '',
  }),
})

[maoberlehner]

I like the idea, and it would allow us to work around the issue rather elegantly!

We're currently discussing the handling of metadata on a product level internally. Depending on the ETA and the result of the discussions, we'll consider this approach! Yet we'd prefer fixing the issue for real instead of adding a workaround.

[maoberlehner]

@leifmarcus we're a hesitant to implement this in the js-client because we always try to be backwards compatible as much as possible and therefore adding something means maintaining it potentially for a long time.

Currently, the "global" asset metadata basically serves as a default. But as soon as you use an asset in a story, it is decoupled from the global metadata. So you have to update the metadata in stories anyway when you update the global asset metadata.

I see the following use cases:

1. Story created with no global metadata, global asset metadata is updated, you want to use the global asset metadata.
2. Story created with global metadata, global asset metadata is updated, you want to use the updated global asset metadata.
3. Story created with local metadata, global asset metadata is updated, you want to keep the local metadata.

For me, 1. and 2. are basically the same. So the case where the metadata in the story is empty, is basically the same as the metadata in the story is outdated because the global metadata was updated. But at the code level we (and you, when using a resolver) can't know if it is case 2. or 3. and if 1. and 2. are functionally equivalent, we can't solve this in code.

Can you go into more detail what your exact use case is and why updating the assets in the stories with the latest metadata is not an option for you?