RFC: What's best way to expose registerProductCollection for 3PDs?

[imanish003]

Introduction

We are planning to expose __experimentalRegisterProductCollection, which will be called like this:

__experimentalRegisterProductCollection(
	title,
	description,
	icon,
	...,
	preview: {
		handlePreviewState,
		initialState: {
			isPreview: true,
			previewMessage: 'This is in preview mode',
		},
	},
)

At this stage, let's set aside the specifics of the function's parameters. The primary goal here is to facilitate both 3PDs and us in registering new collections. A key consideration now is how best to make this function available to 3PDs. Here are a couple of options:

1. Expose a function like __experimentalRegisterProductCollection

One potential method is using a package similar to how plugins utilize registerCheckoutBlock from the @woocommerce/blocks-checkout package:

import { registerCheckoutBlock } from '@woocommerce/blocks-checkout';

registerCheckoutBlock({
	metadata,
	component: (props) => <Block {...props} />,
});

If we decide on this approach, we need to determine the most appropriate package for distribution or create a new package. Currently, functions related to cart and checkout are packaged under @woocommerce/blocks-checkout. Here are the packages available in the WooCommerce repository as you can see here:

const wcHandleMap = {
	'@woocommerce/blocks-registry': 'wc-blocks-registry',
	'@woocommerce/settings': 'wc-settings',
	'@woocommerce/block-data': 'wc-blocks-data-store',
	'@woocommerce/data': 'wc-store-data',
	'@woocommerce/shared-context': 'wc-blocks-shared-context',
	'@woocommerce/shared-hocs': 'wc-blocks-shared-hocs',
	'@woocommerce/price-format': 'wc-price-format',
	'@woocommerce/blocks-checkout': 'wc-blocks-checkout',
	'@woocommerce/blocks-components': 'wc-blocks-components',
	'@woocommerce/interactivity': 'wc-interactivity',
};

Question: Which package is most suitable for integrating the __experimentalRegisterProductCollection function?

• Maybe we can use @woocommerce/blocks-components to expose __experimentalRegisterProductCollection. AFAIU, It's only used by Cart & Checkout blocks to expose reusable components. Alternatively, @woocommerce/blocks-registry, which houses various register-type functions, might also be suitable (Thanks @xristos3490 for pointing this out). Your insights on this would be greatly valued.
• OR Should we consider creating a new package to be shared by all woo blocks except Cart & Checkout blocks?

Note

It is worth noting that some packages, like @woocommerce/blocks-components, are not published on NPM. They are only accessible to 3PDs through the @woocommerce/dependency-extraction-webpack-plugin in a Webpack configuration.

Pros

• Exposing TypeScript types along with the function can ensure type safety, leading to fewer runtime errors and more robust code.
• This will maintain consistency with C&C blocks as they are also using package to expose such functions.
• By handling collection registration through a dedicated API, it supports scalability by allowing more complex configurations and features to be added in a controlled manner using new arguments.

Cons

• It will require Webpack Configuration by 3PDs through the @woocommerce/dependency-extraction-webpack-plugin. Based on this comment by @xristos3490, this isn't a con. I am updating it just to keep it up to date.

2. Using JS filter

Another approach is to expose a JavaScript filter for 3PDs to add new collections. Here is a quick example:

// Function to add the new collection
function addSeasonalFavoritesCollection(collections) {
  return [
    ...collections,
    seasonalFavoritesCollection,
  ];
}

// Adding the filter
addFilter(
  '__experimentalRegisterProductCollection',
  'my-plugin/seasonal-favorites',
  addSeasonalFavoritesCollection
);

Pros

• This method requires minimal setup from developers, as they can hook into the filter and add new collections.

Cons

• We can't export Typescript types for 3PDs for type safety.
• When 3PDs are given the capability to modify any existing collection through a shared filter, there is a possibility that multiple plugins might attempt to alter the same collection in incompatible ways. This could lead to several issues.
• JavaScript's execution model is asynchronous and single-threaded, meaning that scripts and modules may load and execute in a non-deterministic order unless explicitly managed. This non-deterministic behavior can lead to issues where the order of filter application is unpredictable, potentially causing race conditions or unexpected behaviors.

Need Feedback

I am leaning towards the first method of exposing the __experimentalRegisterProductCollection function. It would be beneficial to gain a better understanding of the purpose of each existing package and consider establishing a dedicated package for Woo blocks. To date, only cart and checkout blocks have offered these types of extensibility points. Now, it's time to make a decision for other WooCommerce blocks. I look forward to feedback on whether it's advisable to use the existing packages or if we should create a new one for __experimentalRegisterProductCollection function.

[gigitux]

Thanks, @imanish003, for kicking off this discussion! I agree entirely with you and I think that we should follow the first approach.

OR Should we consider creating a new package to be shared by all woo blocks except Cart & Checkout blocks?

IMHO, I think that we should create another package. This package should contain only code that we want to expose to 3rd party developers to avoid any potential risk that we make some APIs/functions public involuntarily.

Also, on long term, it would be great if this package would be full-typed and published on npm. In this way, even if it will be extracted by @woocommerce/dependency-extraction-webpack-plugin, developers will have intelligent code completion.

For example @wordpress/components uses this approach. The package is on npm, in this way, developers can add it to devDependecies in the package.json, so they can take advantage of intelligent completion thanks to the types included, but at the building time, that package will be extracted by @wordpress/dependency-extraction-webpack-plugin

[imanish003]

Thank you, @gigitux for your valulable input 🙏🏻

IMHO, I think that we should create another package. This package should contain only code that we want to expose to 3rd party developers to avoid any potential risk that we make some APIs/functions public involuntarily.

Makes sense. I think my reason behind asking the question was if we wanna share this package with @woocommerce/rubik team. As they already have an existing package, I thought we might consider sharing that.

Also, I started thinking about what could be new package name in case we decide to create a new package. Here are some of initial ideas:

• @woocommerce/blocks-extension: This emphasizes that the package is meant for extending WooCommerce blocks functionalities and could be more inclusive of various kinds of extensions in the future.
• @woocommerce/blocks-utils: This name focuses on the utility aspect, suggesting that the package offers various utilities.
• @woocommerce/blocks-addons: This name clearly indicates that the package is meant to add additional functionalities or features to the existing WooCommerce blocks.

Do you have any other suggestions for naming this new package? What do you think about these suggestions?

Also, on long term, it would be great if this package would be full-typed and published on npm

+1
Once we have all the things we want to expose in the same package/directory, it will be easy to publish them on NPM.

For example @wordpress/components uses this approach. The package is on npm, in this way, developers can add it to devDependecies in the package.json, so they can take advantage of intelligent completion thanks to the types included, but at the building time, that package will be extracted by @wordpress/dependency-extraction-webpack-plugin

Thanks for sharing it. I agree with you that we can also follow a similar approach 💯

[Aljullu]

+1 to exposing a function like __experimentalRegisterProductCollection. It's a more explicit extensibility approach, so I think in the long term it will be easier to use for consumers and allows more flexibility for us in how it's implemented internally. I also agree with all the comments @gigitux made above.

OR Should we consider creating a new package to be shared by all woo blocks except Cart & Checkout blocks?

Something we could evaluate in the future is whether it would make sense to merge these two packages, the new one we create and @woocommerce/blocks-checkout. I think for now it's ok having them in two separate packages, specially considering Cart & Checkout inner blocks are quite different to any other block, but I would keep the door open in case in the future we want to merge both into one single package.

[xristos3490]

I proposed the @woocommerce/blocks-registry here for the sake of maintaining a coherent global organization. However, it might be beneficial to have separate entry points for C&C features due to their unique nature. 🤔

[imanish003]

Thanks for your valuable input @Aljullu 🙏🏻

I also agree with all the comments @gigitux made above.

I just replied to Luigi in case you want to look at my response.

I think for now it's ok having them in two separate packages, specially considering Cart & Checkout inner blocks are quite different to any other block, but I would keep the door open in case in the future we want to merge both into one single package.

That makes sense. As I shared in this comment that my reason behind asking the question was if we wanna share this package with @woocommerce/rubik team. As they already have an existing package, I thought we might consider sharing that. But after reading your comment, I am more inclined towards creating a new package and later we may consider merging both the packages into one.

[xristos3490]

I'm also in favor of option 1.

A few arguments:

• Handling validation within a single entry point (curated extensibility.)
• Avoid accessing existing collections, thus preventing others from removing them.

There is certainly much room for improvement in terms of the organization of these packages, but I personally see the @woocommerce/blocks-registry as the most appropriate one to use in this case.

Also

It will require Webpack Configuration by 3PDs through the @woocommerce/dependency-extraction-webpack-plugin .

I don't particularly see this as a con. Using this package, 3PDs can:

• Utilize the Woo globals to minimize their bundle's size effectively.
• Access to libraries that aren't exposed to npm.
• Generally, it is considered a good practice to use this wrapper instead of WordPress's one.

Above all, remember that this should also provide much simpler access to this helper by calling directly

wc.blocksRegistry.__experimentalRegisterProductCollection ({...})

without even the need for Webpack.

See:

[imanish003]

There is certainly much room for improvement in terms of the organization of these packages, but I personally see the @woocommerce/blocks-registry as the most appropriate one to use in this case.

Looks like we are commenting on this discussion at the same time 😅

As you said in this comment, "it might be beneficial to have separate entry points for C&C features due to their unique nature". I am inclining towards Albert's suggested approach, i.e., creating separate packages and merging them into one if required. But I don't have a strong opinion on this and am happy to change my mind. I believe an input from @woocommerce/rubik team will be helpful here 🙂

I don't particularly see this as a con. Using this package, 3PDs can:

Aha! That is very useful info. Thank you for sharing it with me. I have updated it. Thank you again 🙏🏻

[alexflorisca]

I think for now it's ok having them in two separate packages, specially considering Cart & Checkout inner blocks are quite different to any other block, but I would keep the door open in case in the future we want to merge both into one single package.

From my exposure to the broader WC community on slack, I get the feeling there is a steep learning curve transitioning to developing for blocks. So I would consider simplifying the devEX here as much as possible. I would actually propose using this as an opportunity to think through and consolidate our packages a little bit with some more consistent and intuitive naming.

There's a few things that could be improved here

• there is wc.checkout, wc.blocksCheckout and packages beginning with wc.wcBlocksXXX.
• It's not clear what some of the functions like registerInnerBlock that live in wc.wcBlocksRegistry refer to. This would be best placed under the corresponding block (checkout in this case)
• Much of what's under wc.wcBlocksRegistry is to do with checkout, so it would be best moved to that package.
• We could consolidate wcBlocksSharedHocs, wcBlocksSharedContext and wcBlocksMiddleware to a shared package
• Move price-format to a shared package

As blocks grows, I think it's likely other blocks will start to use the wc global more and more so I suggest we have a structure something like

wc = {
  blocks : {
    shared: {},
    checkout: {},
    products: {},
    components: {},
  }
}

There are however implications to changing the structure of the wc global so radically, and we'd have to support existing structure and deprecate gently. But I do think it's worth improving this for developers and making it clearer what's what.

Alternatively, if we decide this is too much, the wcBlocksRegistry seems like a good place to put this function, as it deals with registering some new data for a block.

[xristos3490]

Thanks for this info, @alexflorisca! Improving the developer experience should be at the forefront of our minds as we continue to add more features for 3PDs.

I fully agree with the list you shared and the potential improvements. In addition to those, I want to surface one more related to the UI design system. While WC has been expanding its features in different areas, components have been designed to manage the UI in various places with different components:

• The WC Admin area requires specific UI components from @woocommerce/components.
• The new Product Editor requires UI components from @woocommerce/product-editor.
• Generic UI elements are also available through the @wordpress/components package.
• The C&C blocks (which are different by nature since it's the only area that components may be used in the front-end) use another package named @woocommerce/blocks-components.

As an example, here's what someone needs to know in order to create a text input in specific areas:

• The TextControl from WC Admin package.
• The TextControl from the Product Editor package.
• The TextControl from the WordPress's components package.
• The TextInput and the ValidatedTextInput from the C&C blocks-components package.

With the exception of the C&C blocks case, IMO everything (being in the admin area) could be consolidated into specific abstracted components and have a clear understanding of why each component wraps the generic one from WordPress's packages.

I know this doesn't exactly suggest a solution, but I wanted to surface that it is, most probably, a task requiring collaboration and some challenging decisions. That said, I do agree that we can start by adding the collection helper to the @woocommerce/blocks-registry and continue thinking of how a well-organized package directory can look!