RFC: Vendure Storefront UI / Starter

[HouseinIsProgramming]

Background

We are building a Vendure storefront that is both flexible and developer-friendly.

Our goal is to provide a solid foundation that developers can easily build upon, while drastically reducing the starting friction and the time it takes to go from concept to minimum viable product (MVP).

This would also provide a fully functional demo that can be installed using 1 create command.

But to do that, we need to make the right choices about how we distribute the UI components.

The goal is to ensure we’re building something that works for both developers who want simplicity and provide reasonable flexibility when it comes to customization.

With our current proposals that would have certain trade-offs and ultimately result in either something that is requires less maintenance overhead but is more opinionated and would require more effort while customizing components, or something that will require more maintenance but wouldn’t force you into any “defaults”.

Proposals:

We have two options that we that we would like to propose.

Both of these approaches would include an SDK, similar to the one proposed by @michaelbromley in this issue: #2621

The component distribution is where these 2 approaches differ.

Option 1: NPM Package Distribution

Traditional npm package that developers install and import.

This is the more opinionated and lower maintenance approach.

Pros:

• Familiar workflow - standard npm install
• Automatic updates - bug fixes delivered through package updates
• Smaller bundle size - external dependencies
• Version management with semantic versioning

Cons:

• Less customization - harder to modify internals
• Dependency management overhead
• Breaking changes require migration
• May need separate packages for different frameworks
• Component internals "hidden" from developers

Example Workflow

1. Install the Starter Storefront

Create a new Vite-based storefront that includes the pre-built components and hooks:

npx @vendure/create my-shop --with-vite-storefront
cd my-shop
npm run dev

File structure:

my-shop 
└─ apps
	└─ vendure
	└─ storefront/
		├── package.json       # @vendure/storefront-ui dependency
		├── src/
		│   ├── pages/         # Uses imported components, custom or prebuilt
		│   ├── components/    # Only custom components - made by user
		│   └── lib/
		└── node_modules/
		    └── @vendure/storefront-ui/  # Pre-built components live here

2. Modify Components

Since the components are imported from the NPM package, customization is limited to props or Tailwind classes.

// src/pages/all-products.tsx

const products = // fetch from Vendure
const page = 1

function handlePageChange(page: string) {
  // refetch products with new page
}

// all of the props would have to be "hard-coded" in the NPM component package
<ProductGrid page={page} onPageChange={(page) => handlePageChange(page)}>
  {products.map((product) => (
    <ProductCard product={product} />
  ))}
</ProductGrid>;

3. Update Components

To get the latest updates or bug fixes, update the NPM package:

npm update @vendure/storefront-ui

# or update your package.json

This would require no further maintenance, unless it would be a version with breaking changes.

4. No Internal Modifications

Developers cannot modify the internal logic or structure of the components. They can only use the exposed props and Tailwind classes for customization.

---

Option 2: shadcn Registry Distribution

Components distributed through shadcn-style registry - copies code directly into your project.

This would require more maintenance but offers infinite customizability of already built components.

Pros:

• Full customization - complete source code access
• No external dependencies - components in your codebase
• Framework agnostic - same components work across React-based meta frameworks
• Familiar to developers - shadcn/ui has widespread adoption
• Gradual adoption - install only needed components
• No version conflicts

Cons:

• Manual updates - developers must sync improvements manually
• Maintenance burden on developers
• Code duplication across projects
• Consistency challenges

Example Workflow

1. Install the Starter Storefront

Create a new Vite-based storefront that includes the components copied from the shadcn registry:

npx @vendure/create my-shop --with-vite-storefront
cd my-shop
npm run dev

File structure:

my-shop 
└─ apps
	└─ vendure
	└─ storefront/
			├── package.json             # No vendure *component* dependencies
			└── src/
			    ├── pages/               # Uses local components
			    ├── components/
			    │   └── vendure/         # Vendure components (copied from registry)
			    ├── hooks/               # All hooks (copied from registry)
			    └── lib/

2. Modify Components (Full Control)

Since the components are copied directly into the project, developers have full access to the source code and can modify them as needed.

Example: Adding pagination functionality
A developer can open the ProductGrid component file and add new props and UI elements for pagination. This level of direct modification is the key benefit of this approach.

// src/components/vendure/product-grid.tsx
export function ProductGrid({
  children,
  page,
  onPageChange,
}: ProductGridParams) {
  return (
    <div>
      {/* The developer has complete freedom to change the component. */}
      <div className="grid grid-cols-3 gap-6">{children}</div>

      {/* They can add pagination controls directly into the component */}
      <div className="mt-4 flex justify-center gap-2">
        <button onClick={() => onPageChange(page - 1)}>Previous</button>
        <span>Page {page}</span>
        <button onClick={() => onPageChange(page + 1)}>Next</button>
      </div>
    </div>
  );
}

This modified component is then used on the page. The usage looks identical to the NPM example, but the components are now local and not part of the node_modules and fully controlled by the developer.

// src/pages/all-products.tsx
const products = []; // fetch from Vendure
const page = 1

function handlePageChange(page: number) {
  // refetch products with new page
}

<ProductGrid page={page} onPageChange={(page) => handlePageChange(page)}>
  {products.map((product) => (
    <ProductCard product={product} />
  ))}
</ProductGrid>;

3. Manual Updates

To sync updates from the registry, re-install the component:

npx shadcn@latest add http://storefront-registry.vendure.io/r/product-grid.json

This would completely overwrite your components, then you would have to compare the updated components with the git diff of what was overwritten and re-add your custom code.

4. Full-access to customization

Developers have full control over the component internals, including logic, structure, and styling. They can rewrite or extend components as needed.

---

Feedback questions:

1. Which distribution method would you prefer?
   • NPM package for easy installation and updates.
   • shadcn registry for full customization control but a bit more involved updating process.
2. What level of customization do you typically need?
   • Basic theming and styling
   • Component behavior modifications
   • Complete component rewrites
3. How important are automatic updates vs. stability?

[lgoebkes]

In my experience I always preferred the copy and do what you want approaches. Yes it is maybe more work to fit your customization to a newer version, but it is actually also more visible what has changed and you can use git tools to see the differences.

Using SDK's has not really less maintenance in my opinion. Especially the 'what has actually changed to my previous version' question is much harder to answer and dependency hell is also reached much faster. In addition I never had a SDK, that could be modified exactly as my clients wanted it to be, without having to use some nasty hacks.

So for me the shadcn proposal is the one I would prefer.

[tianyingchun]

I suggest using next.js，heroui

[colinpieper]

The shadcn approach sounds more suitable. More often than not, large amounts of customization is needed, or a template like that is used as a starting point, or even just inspiration. I don't think I would use a package variant except to look at the source code and re-use parts that I like.

So:

1: Which distribution method would you prefer?:
Shadcn registry for full customization control but a bit more involved updating process.

2: What level of customization do you typically need?:
Complete component rewrites.

3: How important are automatic updates vs. stability?:
Stability. I rarely find automatic updates in frontend components useful.

[tianyingchun]

Shadcn should not be the best choice, he is too loose and flexible, and the code will be uncontrollable and not very readable. It is recommended to use it.heroui ，All of my own projects come from shadcn Switched to heroui

[mschipperheyn]

I personally would do neither. Given the high level of customization needed in all storefront projects, I would want to do a git checkout and then customize away. I would ideally want a really well structured project aligned with my preference of grouping functionality in modules, using e.g. a contact module that has a

• screens
• forms
• fetchers
• __tests__
• graphql
• components (module related React components)

coupled with a config.ts in the module directory defining front end path and apiPath.

Also, most projects end up using a monorepo structure using various packages. E.g. ui for generic ui building blocks, storefront for the storefront, backend for vendure, etc.

So that's my preference and I will adjust any kind of starter kit to that style before I start implementing. I'm not a fan of too much magic. Monorepo support is crucial in any scenario.

[DanielBiegler]

Which distribution method would you prefer?

Since customization is at the very core of Vendure, going with the ui-kit npm approach seems backward. People choose Vendure because a regular cookie cutter shop framework isnt enough so I vote for the shadcn-copy-into-your-own-repo way.

Potentially breaking the production shop ui due to some new upstream ui package change you dont control can be damaging to the revenue and is entirely unacceptable.

What level of customization do you typically need?

Basic theming and styling

Yes, preferably css variables for colors (primary, secondary, subtle, ..), radii, borders, shadows, .. would enable quick themability.

Component behavior modifications
Complete component rewrites

Yes, people will inevitably add custom fields and other special behavior so again, the copy-into-repo approach solves this.

How important are automatic updates vs. stability?

Stability. Stability. Stability.
Stability. Stability. Stability.
Stability. Stability. Stability.

[martijnvdbrug]

Which distribution method would you prefer?

✨ shadcn registry for full customization control but a bit more involved updating process.
We have tried to build generic components ourselves, but for every shop we ended up copying the component, just to be able to customize something that wasn't thought of before. Maybe it is possible, but I prefer code ownership on the FE.

This feels similar to Tailwind Components: We just copy them, use as base, and modify them later when needed. Everything in our own version control.

What level of customization do you typically need?

✨ Complete component rewrites
At least for our customers: They start small, then grow, and end up requiring very specific features. For example, we start with a basic checkout, but end up with a customized version. Because, maybe, we need surcharges per payment method or something like that.

How important are automatic updates vs. stability?

✨ Stability

What is not fully clear to me yet: This will create a running demo env, but will it then also enforce a frontend framework. Or, will the goal be that this starter is portable to NextJS, Astro or (insert new hip framework here) by the consumer?

[subinpauljoy]

An independently maintained git repository would be the best way in my opinion.

Git clone

And then do all the required customisation. Any project that chose Vendure needs some customized storefront experience.

I have created an end to end react storefront experience and realised that SEO performance of react SPA is not that great.

I thought I'll port it to something like NextJS. But the recent updates in NextJS wasn't very react-like in my experience. So I chose to port it to Astro and with its island architecture, I believe a Vendure ecommerce back end and an Astro + react headless storefront is one of the most dev friendly experience to build a fully featured storefront experience.

My store runs on 2.x.x and storefront uses landing pages built in plasmic visual page builder and plasmic CMS for structured content.

My implementation is specific to my usecase but soon I am planning to spend some time and open-source a storefront starter repo just to give back to the community.

[Draykee]

Just throwing this out there—have we considered using Web Components as a basis for the UI library?

They're framework-agnostic, based on web standards, and work across React, Angular, Vue, Svelte, etc. Could be a great way to make the components more portable and future-proof.

That said, maintaining a Web Component library can be tricky: custom events, isolated styling (Shadow DOM), and cross-framework quirks require careful design and clear documentation. Libraries like Lit or Stencil can help, but it's still some effort. I personally also have zero experience with it yet. I just consumed some libraries so far.

[dlhck]

Just throwing this out there—have we considered using Web Components as a basis for the UI library?

They're framework-agnostic, based on web standards, and work across React, Angular, Vue, Svelte, etc. Could be a great way to make the components more portable and future-proof.

That said, maintaining a Web Component library can be tricky: custom events, isolated styling (Shadow DOM), and cross-framework quirks require careful design and clear documentation. Libraries like Lit or Stencil can help, but it's still some effort. I personally also have zero experience with it yet. I just consumed some libraries so far.

I think web components have a lot of hidden complexity, that makes it even more complicated than it already is. We're also not trying to build a "one size fits all" solution with the storefront. Less scope with top-notch maintenance is worth more imo.