RFC - Overwriting composables

[patzick]

👀 Introduction

We are thinking about allowing a way to override/extend composables generically, to give more control to our users.

💭 Existing way

The simplest way of achieving this result is to allow the auto-import plugin, which is built in into the Nuxt core, to do its magic and replace imports.

Example:
We use useCart in component. We’re not adding import {useCart} from ... as the import is resolved by Nuxt.
So by default we get core composable from the package.
But we can also create useCart composable in composables directory and overwrite/extend.

Let’s try extending, we’ll intercept addProduct method and add console log there.

import { useCart as coreUseCart } from "@shopware-pwa/composables-next";

export function useCart() {
  const coreFunctionality = coreUseCart();

  async function addProduct(params: { id: string; quantity?: number }) {
    console.error("MODIFIED: useCart.addProduct()");
    return await coreFunctionality.addProduct(params);
  }

  return {
    ...coreFunctionality,
    addProduct,
  };
}

⚠️ Potential problem with that solution

It’s all working well, except one case - composables using internally other composables.

Let’s now take useAddToCart composable, it’s using useCart under the hood.

flowchart LR
    component --> useAddToCart --> useCart(useCart core)

		component --> useCartNew(useCart extended)

Loading

Assuming we would use both in component we’d get different results.

✒️ Current way - overwrite only what you can see

Pros

• Ready

  this solution works out of the box

• Traceable overwrites

  You can search of usages for specific composable to make sure you know all the places where it’s use when extending composable. There are no unexpected untraceable behaviours and you don’t need to know internals of all core composables

• Not affected by internal core changes

  If we’re changing internals of the composables, which are not affecting its public API, we do not put this in changelog. We are and will constantly working on improvements for composables. At any time we can remove or add some dependency to another composable for performance reasons. You don’t need to worry about that for yourself, only for the code you actually extend/overwrite.

• Standardised and simple package architecture

  We bundle package in standard module js way. You can expect clear publicly exported API and simple importing like import { useXYZ } from "package-name". We do not rely on aliases or any unstandardised way you need to build or setup your application to make it work. Auto imports plugin is built in in Nuxt, but you can use any other framework and this shouldn’t be a requirement.

Cons

• Might cause confusion

  From a simple point of view of “just understanding” the architecture - this way might be confusing.

  How is this happen if I replaced addProduct method in useCart and adding to cart via useAddToCart is not invoking it, when I see in library internals that this method is used there?

  It could be not clear from the start “what actually is overwritten”?

• Sometimes multiple overwrite is expected

  You replace only composable usages inside your own project. So addressing the example above to reach desired effect of adding console log when new product is added you need to extend both addProduct in useCart and addToCart in useAddToCart. This is clearly more work

🧪 Possible way - overwrite all usages

Pros

• Straightforward overrides

  You know that you’re extending/replacing all usages of specific composable, no matter where it’s used, you know what you’re doing and just want to have the job done

Cons

• Untraceable results

  You’re never sure, without carefully checking core internals, what you’re actually changing. So if you change composable/method API, you might break things

• Complex package importing

  To achieve this goal we’d need to export composables

  • bundled like now
  • every composable with own path with clear reliance on aliases, so end application would have to have more configuration

• Affected by internal core changes

  Every time we’d change that some composable stops or starts using some other composable it could break end app without any warning if you already extended/replaced content

[niklaswolf]

I can see the drawback and possible confusion in the case of composables using other composables.
But I think it's not worth adding too much complexity regarding the imports, I'd rather do it the "nuxt way". Like this it is also much more transparent and discooverable to new developers, because they basically can search for the functionality in the nuxt documentation.

And if you really have a usecase like "composables using other composables": you always have the possibility to not use the default composable at all and add a custom one :)

[quarkus]

Hey.

I actually just ended up with the exact Problem mentioned above which led to reactivity issues and i spend like an hour figuring out what was going in.

What i did:

• extended useCart to overwrite the computed Ref "count" (as i have to apply a custom filter)
• used useAddToCart to add items to the cart which uses the core useCart internally.
• changes where not causing usages of my custom count to rerender.

I would think it would be a good idea to have a global overwrite at least for the internal composable references ...

[patzick]

A non-invasive way of overriding composables is here: #471. Of course still you can break things, but at least overriding specific composables makes it work everywhere, even between existing core composables.