Building a medusajs starter

Starter templates often focus on simplicity at the expense of style, and sometimes neglecting designers' involvement.

I'm in my 'optimize everything' phase in my developer journey right now, so in order to find the right (most optimized) solution, I tried out all the available DTC starters on the medusa starters page, and I've got some opinions.

TLDR; If you really want to build a storefront with medusa, these starter repos need to be treated as a reference guide and not a "starter".

The best and most efficient way to learn anything is by doing.

Within my short time as a developer and also running a software agency, I've experienced enough to understand the time constraint and pressure that comes with deadlines. It’s the reason why templates ever became a thing; ship fast.

However, I strongly advice a different approach to starters and templates.

Whenever you can, only take the core logic from these repos and build your own starter template. I promise you'll have a better developer experience knowing what the code does. With all the copy paste ui libraries out there recently, you can be done in a week or two on average.

Here are some of my top references for building your own medusa storefront.

Official Medusa Next.js Starter In the lib directory, you’ll find a lot of must-have utilities for data fetching with the official sdk and some lodash utility wrappers for pricing, sorting, and more.
The data and utils directories from the lib directory (any starter repo you like).
The middleware config on the official starter (referenced above).
Email templates from Tinloof's starter.
The authData HOFs from lamda-curry's starter.

Troubleshooting

These are the issues I ran into during this experience and how I resolved them:

SyntaxError: Cannot use import statement outside a module.

This is vite specific issue. To fix this, make the following additions to the vite.config.ts file

javascript

export default defineConfig({
	// ...
  ssr: {
    noExternal: ["@medusajs/js-sdk"],
  },
});

The ssr.noExternal basically tells vite to bundle the medusa sdk during ssr because it uses some ESM features and will cause runtime errors if not bundled.

Error: Unable to decode turbo-stream response from URL

I experienced this using Remix actions. I believe this was caused by Remix v3_preview options, upgrading to react router v7 resolved this automatically.