Forem: Shahed Nasser

Medusa Community Highlights: Strapi Integration, SES Plugin, and More!

Shahed Nasser — Mon, 15 May 2023 11:42:02 +0000

Changing the way commerce is built is no easy undertaking. Therefore, we are incredibly excited about our Medusa community, their support, and their amazing contributions that make it easier for others to move to a more modular way of building commerce.

This article is part of an ongoing series that periodically highlights community plugins, storefront starters, quotes, and more. Join our community of over 5,000 developers on Discord to stay updated with all community-related news and discussions. You can also visit our Plugin Library to browse many community contributions.

Latest community contributions

Medusa and Strapi Integration

Govind Diwakar has created a Strapi monorepository with all the components necessary for you to set up and use Strapi with Medusa. Within this monorepository, you’ll find a Strapi project, a Medusa plugin for Strapi, a Strapi plugin for Medusa, and other components that will make your integration between Medusa and Strapi successful.

By integrating Strapi and Medusa, you can utilize rich CMS features that Strapi provides while using Medusa’s powerful commerce features.

Check out the monorepository for more details about the project and how to set it up.

Medusa SES Plugin

Lacey Pevey created a plugin that allows you to use AWS Simple Email Service (SES) as a notification provider in your Medusa backend. By using this plugin, you can send emails to the customer when an order is placed, a password reset has been requested, a gift card has been created, and more using AWS SES.

The templates used for the emails are stored within your Medusa backend in a data directory, and they’re based on handlebars. So, they’re compatible with SendGrid templates as well.

Check out the Medusa SES Plugin for more details about its features and how to install it.

Medusa SvelteKit Client

We also got a much-requested SvelteKit client that lets you interact with your Medusa backend from a SvelteKit storefront. With this client, you can easily build a SvelteKit storefront or admin for your Medusa backend.

SvelteKit enables you to combine the fluid user experience of client-side reactivity with the ability to handle logic on the server when desired. This keeps your Medusa backend firewall-protected and accessible only to your storefront server, which provides an additional layer of security compared to directly exposing your backend.

Check out the Medusa SvelteKit Client for more details about its features and how to install it. Thanks to Lacey Pevey for another great contribution.

Community Radar

Ante Primorac

@anteprimorac

@sebrindom @medusajs Undoubtedly, the new Modules feature is the most remarkable addition to Medusa. It offers unparalleled customization options for the core functionality and the unique capability of running each module as a standalone service, representing a significant step towards greater… twitter.com/i/web/status/1…

09:44 AM - 25 Apr 2023

Created something cool with Medusa? Let us know!

We would love to hear about all the cool projects you’ve created with Medusa. Whether it’s plugins, storefront starters, your own store built with Medusa, or anything similar, we’d love to see it and hopefully share it in our next Community Highlights!

You can share all your cool projects in the Showcase channel on our Discord. You can also learn how to publish your plugins on our Plugin Library using this guide in our documentation.

Modular building blocks: The case of Amazon

Shahed Nasser — Thu, 04 May 2023 14:07:14 +0000

Amazon Web Services (AWS) is a giant in cloud computing. It provides a variety of services that facilitate managing and hosting infrastructure on the cloud. AWS is used widely by both companies and individuals to build or host any type of computer application. This includes, but not limited to, web servers, serverless applications, file and object storage, and much more.

AWS have become a go-to for both developers and businesses as they’re guaranteed a reliable service for all the computing needs. Although nowadays, there are many clouding hosting services that may provide similar features, it wasn’t the case before Amazon started building AWS.

Building AWS was a remarkable foresight from Amazon that understood what businesses and developers needed to continue innovating without limitations. This article explores the story of how Amazon built AWS.

Early Beginning of AWS

In the early 2000s, Amazon (named Amazon.com back then) was only focused on the retail industry. Although it had a software development team internally that built the Amazon store, it wasn’t considered a technology company and didn’t garner any interest from developers.

In 2002, Tim O’Reilly, a renowned author and founder of O’Reilly Media, visited Jeff Bezos to show him a tool he created called Amarank. This tool automatically opened Amazon’s store every few hours and scanned the ranking of O’Reilly Media books and its competitors’ books on Amazon’s ranking for books. It did this using screen scraping. This tool allowed O’Reilly to keep track of the rankings without having to manually check the Amazon store.

O’Reilly then suggested to Bezos that Amazon exposes its data, such as products or rankings, through APIs. This would allow other companies and developers to build powerful tools on top of Amazon.

“Companies need to think not just what they can get for themselves from new technologies, but how they can enable others” — Tim O’Reilly

After O’Reilly’s visit, Bezos discussed this issue with the top Amazon executives. It was then pointed out that an engineer named Rob Frederick, the founder of a mobile commerce startup called Convergence that Amazon acquired, was working on a similar project inside Amazon. He was creating APIs that would allow mobile devices to access Amazon’s store.

So, Bezos decided to add Frederick to an Associates group with the mission to create APIs that allow developers to build on top of Amazon’s store. These APIs would eventually allow developers to access and perform operations such as publishing products or using payments systems.

After building these APIs, Amazon held its first developer conference, making developers an essential asset to Amazon, similar to customers of the Amazon store. Then, the group that was run by Rob Frederick and the Associates group was named “Amazon Web Services”.

Amazon’s Struggle with Infrastructure

Around the same time Amazon was building the stepping stones of AWS, Amazon was facing troubles with their infrastructure. As their business was growing in traffic, and as they were adding more features into the Amazon store, their monolithic architecture built in the mid 90s was no longer sufficient.

So, Amazon decided to transition their infrastructure to a service-oriented architecture. This allowed them to rebuild their systems into independent but connected components. This transition took 3 years.

During this transition, Amazon teams struggled to access Amazon’s resources and infrastructure while building or testing new features. Although Amazon was moving into a more flexible architecture, its resources were still managed by a single team in the Seattle headquarters.

This problem delayed the roll-out of new features and frustrated both software developers at the company and the top executives, including Jeff Bezos. It was a recurring and visible problem, as teams would often present their new features to the executives, but admit they never got the chance to actually test it out.

Jeff Bezos then got inspired by a book he was reading at the time called Creation by Steve Grand. The book gave him the idea to build the essential building blocks of computing that would allow Amazon’s developers to freely explore, innovate, and be creative. This wouldn’t only solve Amazon’s infrastructure problems, but similar problems other companies and developers were evidently experiencing as well.

“Developers are alchemists and our job is to do everything we can to get them to do their alchemy” — Jeff Bezos

The first steps to building these building blocks was to write down the list of “primitives” of computing. Those included storage, bandwidth, payments, among other primitives. Then, Amazon started putting together teams to develop each of these primitives as services.

Building S3 and EC2

The first two services, which are essential services that developers use now, are Simple Storage Service, or S3, and Elastic Compute Cloud, or EC2.

The team assigned to build S3 worked closely with Jeff Bezos, who was highly interested in the development of these services. Bezos had big ideas and expectations of S3 that the team working on it struggled to keep up with.

While the team looked over details related to service growth and downtime, Bezos insisted that the service needs to be built from the start ready to scale infinitely and with no downtime.

On the other hand, EC2 was built in isolation by a team of two, Chris Pinkham and Chris Brown, working remotely from South Africa. The idea behind building EC2 was to allow developers to build and run their application on Amazon’s servers, regardless of what type of application it was. The plan was to build EC2 on top of an open source tool called Xen which made it possible to run several applications on one physical server.

The Launch of Amazon Web Services

S3 was launched in March 2006. It allowed developers and websites to store files such as photos and documents on Amazon’s servers. Although S3 is a popular service now, at the time it hardly got any traffic and was overlooked by developers and companies.

A few months later, EC2 was in public beta and available for developers to use. Developers rushed to get access to EC2 and start building their applications using Amazon’s servers. This ultimately lead to more traffic and usage of S3 as well.

These services were highly unanticipated by rival companies such as Google and Microsoft. Amazon was the only company dabbling with cloud computing and providing developers with services that allowed them to build with no limitations. As these services rose in popularity, rival companies started noticing what they were missing out on, which lead them to launch their own similar services (Microsoft announced Azure in 2010, and Google announced Compute Engine in 2012).

However, Amazon was already many steps ahead at that point. Other teams at Amazon were already working on and launching other services, such as Flexible Payment Services and Amazon CloudSearch.

The Impact of AWS

AWS transformed both Amazon and software development as we know it. Inside Amazon, teams started relying on AWS and testing it even when services were in early stages. This allowed them to find issues in AWS early on, and facilitated building and rolling out new feature. It solved a huge hurdle that the engineering teams within Amazon were facing.

Companies and startups also started relying heavily on AWS. It removed all restrictions they previously faced with building and creating applications regardless of the sector they worked in. AWS pioneered a new era powering innovation and creativity. Amazon was finally considered a technology company following their launch of AWS.

Amazon’s revolutionary work with AWS spawned from the need for flexibility within its rigid architecture at the time. It limited their innovation and ability to grow as an ecommerce business. Amazon realized something essential, and arguably ahead of its time: monolithic architecture hinders a business’s growth, and modularity facilitates it.

Amazon’s transition in their architecture and motivation behind building AWS was to provide developers, both within the company and globally, with the necessary tooling to build without limitations. As Bezos indicated at the time, trying to guess what a developer would need when building an application was a thing from the past.

Amazon's forward-thinking strategy of empowering developers through APIs and infrastructure services was a game changer for their cloud offering. As we look to the future of ecommerce, the role of developers in shaping the industry is critical.

While there is still progress to be made in optimizing developer experience, at Medusa we aim to follow in Amazon's footsteps by providing ecommerce developers with the necessary building blocks to build, scale, and innovate. With the right primitives in place, we believe that developers can build the Amazons of tomorrow.

Announcing Medusa’s Community Publication

Shahed Nasser — Tue, 02 May 2023 10:18:47 +0000

At Medusa, we’re introducing our new community publication, Medusa Community, hosted on Hashnode. This publication gives writers interested in writing about Medusa a platform where they can be recognized and paid for their work.

Keep reading below to learn more about this publication and how you can join!

Why create a community publication?

Last year, we created a Writers Program at Medusa, where we were able to work with over 200 writers in producing content related to Medusa. This has allowed us to create diverse content of different types and levels based on the different skills the community writers provided.

As the Writers Program continued to grow and gain interest, we realized how important it is to highlight the community’s work and make it easier for more people to contribute and join. The community publication aims to solve a lot of the limitations we had with the Writers Program, while also providing creative and useful content for the community, by the community.

How does it work?

We share all the details about the new publication in our new Write for Us page. To sum it up:

You can join as a writer using this form.
You’ll then receive an email with the details to join the Hashnode publication and any other necessary resources.
That’s it! You can then start writing and submitting content to the community publication.

Important notes

It’s important to sign up again as a writer using the form mentioned above, even if you were previously part of the Writers Program.
Your article must match our writing guidelines.
Articles are not instantly published on the publication, as we might specify a schedule on how and when we decide to post the article.
You’ll receive payment if your article is published or scheduled.
Although you can generally write about anything related to Medusa, we also have guidelines on what topics we are against and some things to keep in mind when writing. You can learn more here.

Benefits of joining the Community Publication

Your content will be recognized by the Medusa community. We’ll also often share articles we find insightful or creative across our channels.
You’ll get paid for your work. We also offer bonus payments if your article gets featured on Hashnode or other publications.

Start writing for Medusa

Interested in the Community Publication? You can join the publication through this form.

Check out the Medusa Community Publication and follow it on Hashnode to stay updated with all community content.

Extending Medusa Example: Build an Open Source Marketplace

Shahed Nasser — Wed, 19 Apr 2023 10:45:46 +0000

Medusa is the set of building blocks that developers can use to create their custom use case. Instead of forcing developers to use a standardized solution, leading them to enforce hacky-workarounds, Medusa embraces customization and extendability.

This tutorial gives an example of that by giving an overview look of how you can create a marketplace with Medusa. While the steps in this tutorial may not lead to a fully-fledged marketplace, they will give you an idea of how it can be implemented by building the foundation. You’ll also find other resources at the end of the tutorial that can guide you through the rest of your marketplace development.

Last year, we wrote a blog about how to create a marketplace with Medusa and Medusa Extender. At the time, Medusa did not provide the necessary functionalities to extend its core, which required developers to use Medusa Extender. With the release of v1.8 of Medusa, the marketplace can now be built with Medusa only. This tutorial illustrates how to do that.

The code of this tutorial is available in this GitHub Repository.

What You’ll be Building

By following along the steps in this tutorial, you’ll be implementing the following logic:

Every time a user is created, a new store associated with that user is created.
When the user retrieves the store’s details, their store’s details will be retrieved.
Every time a product is created, it is associated with the store of the logged-in user.
The user will only be able to retrieve products from their store.

Prerequisites

This article assumes you already have a Medusa backend with v1.8 of Medusa installed. If not, you can learn how to install it here.

Extend the Store Entity

In this section, you’ll extend the Store entity so that you can later add new relations to it. Extending an entity requires extending its repository as well.

You can learn more about extending an entity in our documentation.

Create the file src/models/store.ts with the following content:

import { Entity } from "typeorm"
import {
  Store as MedusaStore,
} from "@medusajs/medusa"

@Entity()
export class Store extends MedusaStore {
  // TODO add relations
}

This imports the Store entity from the Medusa core package as MedusaStore and creates a new Store entity that extends it.

Extend the StoreRepository

Next, create the file src/repositories/store.ts with the following content:

import { Store } from "../models/store"
import { 
  dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
  StoreRepository as MedusaStoreRepository,
} from "@medusajs/medusa/dist/repositories/store"

export const StoreRepository = dataSource
  .getRepository(Store)
  .extend({
    ...Object.assign(
      MedusaStoreRepository, 
      { target: Store }
    ),
  })

export default StoreRepository

This imports the StoreRepository from the Medusa core package as MedusaStoreRepository, then extends the repository to target the new Store entity you created.

Create index.d.ts

Finally, to ensure TypeScript is aware of the new type you’re creating, create the file src/index.d.ts with the following content:

export declare module "@medusajs/medusa/dist/models/store" {
  declare interface Store {
    // TODO add relations
  }
}

You’ll later add relations to the Store interface as you add them to the Store entity. You’ll also be using the same file when extending other entities.

Extend the User Entity

Next, you’ll extend the user entity to add a new column and relation to the Store entity. The steps are the same as the ones described in the previous section.

Start by creating the src/models/user.ts file with the following content:

import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm"
import {
  User as MedusaUser,
} from "@medusajs/medusa"
import { Store } from "./store";

@Entity()
export class User extends MedusaUser {
  @Index("UserStoreId")
  @Column({ nullable: true })
  store_id?: string;

  @ManyToOne(() => Store, (store) => store.members)
  @JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
  store?: Store;
}

This imports the User entity from the Medusa core package as MedusaUser and creates a new entity User that extends it. In the entity, you add a new column store_id and a relation store to the Store entity.

Then, in the Store entity created in src/models/store.ts, add the following relation to the entity:

import { Entity, OneToMany } from "typeorm"
import { User } from "./user";
// other imports...

@Entity()
export class Store extends MedusaStore {
    @OneToMany(() => User, (user) => user?.store)
  members?: User[];
}

You might see some TypeScript errors in your editor now. This can be resolved by replacing the content of the src/index.d.ts with the following content:

export declare module "@medusajs/medusa/dist/models/store" {
  declare interface Store {
    members?: User[];
  }
}

export declare module "@medusajs/medusa/dist/models/user" {
  declare interface User {
    store_id?: string;
    store?: Store;
  }
}

This informs TypeScript that the User entity now has store_id and store properties, and the Store entity has a members property. You can learn more here.

Extend the UserRepository

Next, create the file src/repositories/user.ts with the following content:

import { User } from "../models/user"
import { 
  dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
  UserRepository as MedusaUserRepository,
} from "@medusajs/medusa/dist/repositories/user"

export const UserRepository = dataSource
  .getRepository(User)
  .extend({
    ...Object.assign(
      MedusaUserRepository, 
      { target: User }
    ),
  })

export default UserRepository

This imports the UserRepository from the Medusa core package as MedusaUserRepository and creates a new UserRepository that extends it but targets the new User entity.

Create Migration for the User Entity

Since you’re adding a new column store_id to the User entity, you must add a new migration that reflects that column in your database.

You can learn more about migrations in our documentation.

First, run the following command in the root directory of your backend:

npx typeorm migration:create src/migrations/add-user-store-id

This will create a new file under src/migrations. The file’s name should be of the format <TIMESTAMP>_UserChanged.ts.

In the file, there’s a migration class with two methods: up and down. Replace the methods with the following content:

public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE "user" ADD "store_id" character varying`);
    await queryRunner.query(`CREATE INDEX "UserStoreId" ON "user" ("store_id") `);
}

public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP INDEX "public"."UserStoreId"`);
    await queryRunner.query(`ALTER TABLE "user" DROP COLUMN "store_id"`);
}

Before you run the migrations, run the build command which transpiles the files under the src directory into the dist directory:

npm run build

Then, run the migration command:

medusa migrations run

This will add the new store_id column to the user table.

Create Middleware to Register Logged-In User

To get access to the logged-in user across your services, you need to register it through a middleware. This middleware will run on all endpoints under the /admin path, except for the /admin/auth endpoints.

You can learn more about middlewares in our documentation.

Start by creating the file src/api/middlewares/logged-in-user.ts with the following content:

import { UserService } from "@medusajs/medusa"
import { User } from "../../models/user"

export async function registerLoggedInUser(req, res, next) {
  let loggedInUser: User | null = null

  if (req.user && req.user.userId) {
    const userService = 
      req.scope.resolve("userService") as UserService
    loggedInUser = await userService.retrieve(req.user.userId)
  }

  req.scope.register({
    loggedInUser: {
      resolve: () => loggedInUser,
     },
   })

  next()
}

This retrieves the logged-in user from req.user.userId and, if available, registers it in Medusa’s dependency container under loggedInUser.

You can learn more about the dependency container and injection in our documentation.

Next, create the file src/api/index.ts with the following content:

import { Router } from "express"
import configLoader from "@medusajs/medusa/dist/loaders/config"
import { 
  registerLoggedInUser,
} from "./middlewares/logged-in-user"
import 
  authenticate 
from "@medusajs/medusa/dist/api/middlewares/authenticate"
import * as cors from "cors"

export default function (rootDirectory: string) {
  const router = Router()
  const config = configLoader(rootDirectory)

  const adminCors = {
    origin: config.projectConfig.admin_cors.split(","),
    credentials: true,
  }

  router.use(
    /\/admin\/[^(auth)].*/,
    cors(adminCors),
    authenticate(),
    registerLoggedInUser
  )

  return router
}

This registers the middleware on all paths starting with /admin except for /admin/auth paths. Notice that you also add the authenticate middleware before the registerLoggedInUser middleware. The authenticate middleware authenticates the user and sets req.user. If not added, the registerLoggedInUser middleware will not be able to access the logged-in user.

You’ll see the middleware’s work in action when you start customizing services in the upcoming sections.

Extend Store Service

In this section, you’ll extend the Store service to change the logic behind retrieving a store. In the Medusa core package, it’s assumed there’s one store and so the first store is retrieved. You’ll be changing that to retrieve the store of the logged-in user.

You can learn more about extending services in the documentation.

Create the file src/services/store.ts with the following content:

import { Lifetime } from "awilix"
import { 
  FindConfig,
  StoreService as MedusaStoreService, Store, User,
} from "@medusajs/medusa"

class StoreService extends MedusaStoreService {
  static LIFE_TIME = Lifetime.SCOPED
  protected readonly loggedInUser_: User | null

  constructor(container, options) {
    // @ts-expect-error prefer-rest-params
    super(...arguments)

    try {
      this.loggedInUser_ = container.loggedInUser
    } catch (e) {
      // avoid errors when backend first runs
    }
  }

  async retrieve(config?: FindConfig<Store>): Promise<Store> {
    if (!this.loggedInUser_) {
      return super.retrieve(config);
    }

    return this.retrieveForLoggedInUser(config);
  }

  async retrieveForLoggedInUser (config?: FindConfig<Store>) {
    const storeRepo = this.manager_.withRepository(this.storeRepository_);
    const store = await storeRepo.findOne({
        ...config,
        relations: [
          ...config.relations,
          'members'
        ],
        where: {
          id: this.loggedInUser_.store_id
        },
    });

    if (!store) {
        throw new Error('Unable to find the user store');
    }

    return store
  }
}

export default StoreService

You import the StoreService from the Medusa core package as MedusaStoreService. You then create a new StoreService class that extends MedusaStoreService.

In the class, you set the LIFE_TIME of the service to Lifetime.SCOPED. This is necessary for the service to access the registered loggedInUser. You can learn more about it in the documentation.

You also add a new class attribute loggedInUser_ and set its value in the constructor. Notice that you wrap the initialization of loggedInUser_ in the constructor with a try-catch block to avoid errors when the loggedInUser is not registered in the Medusa container.

You then override the retrieve method. In that method:

You check if the loggedInUser_ is set. If not, you call the retrieve method of the service from the core package.
If the loggedInUser_ is set, you retrieve the store using a new method retrieveForLoggedInUser. This method retrieves the store using the value of store_id of the loggedInUser_ and expands the members relation.

Before you test out this method, you should create the logic that associate a new user with a new store.

Extend the User Service

In this section, you’ll implement the logic behind creating a store for every new user. To do this, you’ll extend the UserService from the Medusa core to override the create method.

Create the file src/services/user.ts with the following content:

import { Lifetime } from "awilix"
import { UserService as MedusaUserService } from "@medusajs/medusa"
import { User } from "../models/user"
import { CreateUserInput as MedusaCreateUserInput } from "@medusajs/medusa/dist/types/user"
import StoreRepository from "../repositories/store"

type CreateUserInput = {
  store_id?: string
} & MedusaCreateUserInput

class UserService extends MedusaUserService {
  static LIFE_TIME = Lifetime.SCOPED
  protected readonly loggedInUser_: User | null
  protected readonly storeRepository_: typeof StoreRepository;

  constructor(container, options) {
    // @ts-expect-error prefer-rest-params
    super(...arguments)
    this.storeRepository_ = container.storeRepository

    try {
      this.loggedInUser_ = container.loggedInUser
    } catch (e) {
      // avoid errors when backend first runs
    }
  }

  async create(user: CreateUserInput, password: string): Promise<User> {
    if (!user.store_id) {
      const storeRepo = this.manager_.withRepository(this.storeRepository_)
      let newStore = storeRepo.create()
      newStore = await storeRepo.save(newStore)
      user.store_id = newStore.id
    }

    return await super.create(user, password)
  }
}

export default UserService

In this file you:

Extend the core’s UserService which is imported as MedusaUserService.
You change the value of the LIFE_TIME attribute of the service. This is explained in the Extend Store Service section.
You add a new loggedInUser_ attribute and initialize it in the constructor.
You override the create method. In the method, you first check if the user does not have a store_id. This allows you to specifically set the store of the user in other places if necessary. This can be helpful if you’re creating a team of users in one store. If the user doesn’t have store_id set, a new store is created and the store_id property of the user is set to the ID of the new store. The user is saved then using the logic implemented in the core service.

Test Store-User Relation

Time to test everything you’ve implemented so far. To do that, run the build and the start commands in your Medusa backend:

npm run build && npm start

Once your Medusa backend starts, login with any admin user that you have using the User Login endpoint. If you’ve seeded your database with demo data, you should have the following login credentials:

{
    "email": "admin@medusa-test.com",
    "password": "supersecret"
}

Notice that when you log in, the store_id of the user is set to null.

Then, try to get the store’s data using the Get Store Details endpoint. The default store will be returned, which has an empty members array.

Next, try to create a new user using the Create a User endpoint. You should see that the new user has a set store_id.

Now, try to login with your new user, then try to retrieve the store’s data using the Get Store Details endpoint as mentioned earlier. You’ll see now that a different store is retrieved than the first time. This is the store that was created for this new user. It also has the new user as part of its members array.

The user-store relation is now established and ready for use. Next, you’ll be working on the product-store relation.

Extend the Product Entity

In this section, you’ll extend the Product entity to add a new column and relation to the Store. The process will be very similar to that of extending the User entity.

Start by creating the file src/models/product.ts with the following content:

import { Column, Entity, Index, JoinColumn, ManyToOne } from "typeorm"
import {
  Product as MedusaProduct,
} from "@medusajs/medusa"
import { Store } from "./store";

@Entity()
export class Product extends MedusaProduct {
  @Index("ProductStoreId")
  @Column({ nullable: true })
  store_id?: string;

  @ManyToOne(() => Store, (store) => store.products)
  @JoinColumn({ name: 'store_id', referencedColumnName: 'id' })
  store?: Store;
}

This imports the Product entity from the Medusa core package as MedusaProduct and creates a new entity Product that extends it. In the entity, you add a new column store_id and a relation store to the Store entity.

Then, in the Store entity created in src/models/store.ts, add the following relation to the entity:

import { Product } from "./product";
// other imports...

@Entity()
export class Store extends MedusaStore {
    // other relation...

    @OneToMany(() => Product, (product) => product?.store)
  products?: Product[];
}

You might see some TypeScript errors in your editor now. This can be resolved by adding the products relation to the Store interface and adding a new declaration for the Product in index.d.ts:

export declare module "@medusajs/medusa/dist/models/store" {
  declare interface Store {
    members?: User[];
    products?: Product[];
  }
}

// user declaration...

export declare module "@medusajs/medusa/dist/models/product" {
  declare interface Product {
    store_id?: string;
    store?: Store;
  }
}

Extend the ProductRepository

Next, create the file src/repositories/product.ts with the following content:

import { Product } from "../models/product"
import { 
  dataSource,
} from "@medusajs/medusa/dist/loaders/database"
import {
  ProductRepository as MedusaProductRepository,
} from "@medusajs/medusa/dist/repositories/product"

export const ProductRepository = dataSource
  .getRepository(Product)
  .extend({
    ...Object.assign(
      MedusaProductRepository, 
      { target: Product }
    ),
  })

export default ProductRepository

This imports the ProductRepository from the Medusa core package as MedusaProductRepository and creates a new ProductRepository that extends it but targets the new Product entity.

Create Migration for the Product Entity

Since you’re adding a new column store_id to the Product entity, you must add a new migration that reflects that column in your database.

First, run the following command in the root directory of your backend:

npx typeorm migration:create src/migrations/ProductChanged

This will create a new file under src/migrations. The file’s name should be of the format <TIMESTAMP>_ProductChanged.ts.

In the file, there’s a migration class with two methods: up and down. Replace the methods with the following content:

public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE "product" ADD "store_id" character varying`);
    await queryRunner.query(`CREATE INDEX "ProductStoreId" ON "product" ("store_id") `);
}

public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`DROP INDEX "public"."ProductStoreId"`);
    await queryRunner.query(`ALTER TABLE "product" DROP COLUMN "store_id"`);
}

Before you run the migrations, run the build command which transpiles the files under the src directory into the dist directory:

npm run build

Then, run the migration command:

medusa migrations run

This will add the new store_id column to the product table.

Extend the Product Service

In this section, you’ll extend the product service to do two things:

Change the save logic to attach the product to the logged-in user’s store.
Change the methods used to retrieve products including the list, listAndCount, and retrieve methods to retrieve the products only associated with the logged-in user’s store.

Create the file src/services/product.ts with the following content:

import { Lifetime } from "awilix"
import { 
  ProductService as MedusaProductService, Product, User,
} from "@medusajs/medusa"
import { CreateProductInput as MedusaCreateProductInput, FindProductConfig, ProductSelector as MedusaProductSelector } from "@medusajs/medusa/dist/types/product"

type ProductSelector = {
  store_id?: string
} & MedusaProductSelector

type CreateProductInput = {
  store_id?: string
} & MedusaCreateProductInput

class ProductService extends MedusaProductService {
  static LIFE_TIME = Lifetime.SCOPED
  protected readonly loggedInUser_: User | null

  constructor(container, options) {
    // @ts-expect-error prefer-rest-params
    super(...arguments)

    try {
      this.loggedInUser_ = container.loggedInUser
    } catch (e) {
      // avoid errors when backend first runs
    }
  }

  async list(selector: ProductSelector, config?: FindProductConfig): Promise<Product[]> {
    if (!selector.store_id && this.loggedInUser_?.store_id) {
      selector.store_id = this.loggedInUser_.store_id
    }

    config.select?.push('store_id')

    config.relations?.push('store')

    return await super.list(selector, config)
  }

  async listAndCount(selector: ProductSelector, config?: FindProductConfig): Promise<[Product[], number]> {
    if (!selector.store_id && this.loggedInUser_?.store_id) {
      selector.store_id = this.loggedInUser_.store_id
    }

    config.select?.push('store_id')

    config.relations?.push('store')

    return await super.listAndCount(selector, config)
  }

  async retrieve(productId: string, config?: FindProductConfig): Promise<Product> {
    config.relations = [
      ...(config.relations || []),
      'store'
    ]

    const product = await super.retrieve(productId, config);

    if (product.store?.id && this.loggedInUser_?.store_id && product.store.id !== this.loggedInUser_.store_id) {
      // Throw error if you don't want a product to be accessible to other stores
      throw new Error('Product does not exist in store.');
    }

    return product
  }

  async create(productObject: CreateProductInput): Promise<Product> {
    if (!productObject.store_id && this.loggedInUser_?.store_id) {
      productObject.store_id = this.loggedInUser_.store_id
    }

    return await super.create(productObject);
  }
}

export default ProductService

In this file you:

Extend the core’s ProductService which is imported as MedusaProductService.
You change the value of the LIFE_TIME attribute of the service. This is explained in the Extend Store Service section.
You add a new loggedInUser_ attribute and initialize it in the constructor.
You override the list and listAndCount methods to filter the retrieved products by the logged-in user’s store ID. You also ensure that the store_id attribute is retrieved as part of the product and that the store relation is expanded.
You override the retrieve method to check if the retrieved product belongs to the logged-in user’s store. If not, you throw an error that the product does not exist.
You override the create method to check if the logged-in user has a store and, if so, associate the product’s store ID with that store.

Notice that you didn’t implement the save mechanism as part of the repository this time. This is because the repository does not have access to the Medusa container. So, you won’t be able to access the logged-in user in it.

Test the Product-Store Relation

You can now test the relation between the product and the store.

Start by running the build and start commands in the root of your Medusa backend:

npm run build && npm start

Then, log in as a user who has a store as explained in the previous testing section.

After that, retrieve the available products by sending a request to the List Products endpoint. You’ll see that there are no products returned, even if you previously had products in your store. This is because these products are not associated with the user’s store.

Then, try creating a new product using the Create Product endpoint. You’ll see that the created product has a store attribute. The id of that store is the same ID of the user’s store.

If you try retrieving the list of products again, you’ll find your newly-created product in the returned array.

Note About Super-Admin User

So far in your implementation you’ve taken into accoun utsers that don’t have a set store ID. These are considered “super-admin” users. These users would be able to view all products in the store and the default store’s details.

If this logic does not work for you, make sure to change the implementation to require a store ID for a user in the different locations we’ve used it.

What’s Next

In this tutorial, you learned how to implement the foundation of a marketplace: having multiple stores, different users within those stores, and associating products with a store.

A marketplace has a variety of other features, each depending on your use case. Some of them are:

Create order-store relation: This requires a similar implementation as what you’ve done in this tutorial with products and users. You need to extend the Order entity to include a relation to the store. You can learn more about extending entities in the documentation.
List orders by stores: This requires a similar implementation as what you’ve done in this tutorial with products. You need to extend the OrderService to override the methods used to retrieve orders. You can learn more about extending services in the documentation.
Associate an order to a store: This requires listening to the order.created event in a subscriber. The implementation can include creating child orders of an order if in your use case you support have products from multiple stores in one product. In this case, you’d also need to extend the order entity to create a parent-child relation. You can learn more about subscribers in the documentation.
Implement teams within a store: You can implement a team within a store by extending the Invite entity to associate it with a store ID, then associate the user created from the invite with that store ID.

These are just some ideas and direction for your development of the marketplace. For further help in your development, make sure to check out the available guides in our documentation.

The History of Ecommerce: 1979 to 2023

Shahed Nasser — Thu, 09 Mar 2023 11:46:55 +0000

Ecommerce has evolved a lot since its start. It hasn’t always been well-designed stores with extensive features and carefully-planned user experiences. A lot of what is fundamental and basic today was revolutionary when discovered at its time.

This article goes down the memory lane of ecommerce, uncovering some old-but-gold ecommerce websites, and highlighting the main difference from ecommerce today.

1979: Michael Aldrich and the First Attempt at Ecommerce

In 1979, Michael Aldrich invented online shopping through televisions. This was way before the inventions of the Internet and the World Wide Web (WWW). He invented it by connecting a modified domestic TV to a transaction processing computer through a domestic telephone line.

Michael Aldrich believed that Videotex was a revolutionary communication medium that was universally applicable and participative, and the first of its kind since the invention of the telephone.

Following his invention, two businesses used Michael’s invention: Gateshead SIS with Tesco and Bradford Centrepoint with Wm. Morrison. This allowed consumers to open their TV and choose groceries from a local supermarket. The order would then be sent through the phone line to a local Tesco, where the ordered items would be packaged and sent to the consumer.

1984: CompuServe’s Electronic Mall

Image Source

CompuServe was one of the first businesses getting close to an ecommerce experience. It was a popular networking service that provided users with emails, message boards, and more.

In 1984, CompuServe added a service called “Electronic Mall” that allowed users to buy items from over 100 online retailers through a simple CLI interface where customers could browse different vendors, product categories and even insert credit information for later purchases.

You can see a demo of it all here.

1992: Book Stacks Unlimited, the Amazon Predecessor

Image Source

Contrary to popular belief, Amazon was not the first online bookstore. Book Stacks Unlimited was created in 1992, three years before Amazon. It began as a dial-up bulletin board. They then launched the website Books.com in 1994, which was eventually acquired by Barnes & Noble.

Not only did Book Stacks Unlimited offer 500K titles, but they provided features such as editorial book recommendations, book summaries, RealAudio interviews with authors, book search, and more.

1994: NetMarket and the First Sale on the Internet

Image Source

In 1994, Dan Kohn created NetMarket, which would sell a variety of CDs and books. He then marked the first sale of a product over the internet using a credit card: a Ten Summoner’s Tale CD by Sting.

According to the New York Times, which covered the story back then, this was the first retail transaction on the Internet using a readily available version of powerful data encryption software designed to guarantee privacy. Dan Kohn said about the purchase that “even if the N.S.A. was listening in, they couldn't get his credit card number.”

1994-1999: The Launch of Ecommerce Giants

1994: PizzaNet (PizzaHut)

Image Source

In 1994, PizzaHut created PizzaNet, their online ordering service. Not only did it allow customers to order from the menu, but it also allowed them to customize the pizza.

In the skepticism of how the website might be used, the local restaurant would always call the customer to verify the order to minimize the risk of pranksters.

1995: Amazon

Image Source

Amazon launched in 1995 as a book store. Although the design wasn’t too appealing, there were features that were advanced for its time: a virtual shopping cart, secure way of entering credit card details, an internal search engine, product reviews, and more.

In the very beginning, Amazon’s engineers used C to code a lot of the features of the website, and used Berkeley DB to store the website’s data.

1996: eBay

Image Source

eBay (initially Auction Web) was launched in 1996. It was one of its kind, being the first online auction website providing a person-to-person marketplace. Buyers would present their products, and customers bid on the items to eventually purchase it.

eBay was free of charge at the start. However, as their traffic hugely increased, eBay’s founders were informed that they needed to upgrade their hosting account. This led them to take commissions on bids to fund the website.

1997: Apple

Image Source

Steve Jobs returned to Apple in 1997. His first line-of-action was to improve Apple’s presence in the ecommerce world. Apple launched their new-and-improved ecommerce website at the end of 1997 aimed at improving customer experience.

1998-1999: Nike

Image Source

Nike created their first website in 1997. However, it was mainly focused on teaching their consumers more about Nike and their products, rather than selling these products online.

In 1998, the Nike website improved to provide consumers the ability to customize their own Nike shoes. It wasn’t until 1999 that Nike moved from editorial content to an online store.

2000-2005: Dot-Com Crash

In the 1990s, the Internet garnered heavy attention and adoption. Web-based startups gained a lot of funding, and all companies suddenly needed to “move to the internet”. Later followed what is now known as the Dot-Com Crash in March 2000 where the Nasdaq index slipped ~77% over less than three years.

The dot-com crash took down many ecommerce and internet-based companies that gained success during the 1990s. This affected even big companies like Amazon. Still, some companies like eBay thrived despite the headwinds.

SnowDevil and Shopify

In 2004, SnowDevil was launched, which ended up being the spark that ignited Shopify. Tobias Lütke and Scott Lake wanted to sell snowboards online, but couldn’t find a software that would help them do that.

They initially used a variety of tools and services such as Miva, OsCommerce, and Yahoo stores. However, they frequently ran into trouble when trying to bring their vision to life. According to Lütke they had a “great CSS-based layout done with all these new fanged ‘web standards’”. However, the lack of customization capability that Yahoo provided barely allowed him to change the background color of the top frame.

So, Lütke and Lake set out to create a solution that would not only solve their problem, but solve the problems of businesses across the globe. They built Shopify in 2007 and transformed SnowDevil to a Shopify demo store, bringing their vision to life.

Shopify now powers over 4.5 million websites worldwide.

Note on 2000s Designs

When looking back at some of the designs from the early 2000s, you’ll notice that there was a significant advancement from the HTML, almost only text and disarrayed images design that dominated that 1990s.

Image Source

Even though the design was still clunky and crammed, there was a clear usage of layouts and different colors. Ecommerce websites at the time also started using some elements that are now basics to ecommerce, such as a navigation menu and a sidebar for categories.

During that period, tech giants like Amazon and eBay continued to innovate with new features that are now core ecommerce features. Amazon added features like Search Inside the Book, allowing customers to search for words inside books. eBay also added a Live Chat feature to provide support for customers.

Image Source

2006-2010: Rise of Ecommerce Platforms

After the dot-com crash, ecommerce companies and stores steadily regained momentum, and new ecommerce platforms emerged.

In 2007, Magento was created by Varien, and it was later acquired by eBay. In the beginning, Varien were building their platform on osCommerce. However, they found it incapable of accommodating all the features and functionalities they had in mind. So, they decided to build a new open-source solution from scratch.

With the passing years, Magento grew to be one of the top open source ecommerce platforms at its time. In its first year, it was downloaded over 500K times. Magento’s popularity is due to the customizability capabilities it provided, as well as its open source nature. This allowed businesses to break away from proprietary solutions and take full ownership of their store.

Image Source

BigCommerce was launched in 2009, after its founders met in a programming online chat. BigCommerce initially wanted to provide a shopping-cart-only solution called Interspire. However, their consumers found it difficult to manually find, install, and update their software on a server, which lead to the change from Interspire to BigCommerce.

BigCommerce gained popularity among businesses that didn’t want the hassle of handling the technical parts of ecommerce, but still wanted to have the customizability options that allowed them to grow and scale. By 2011, BigCommerce was powering almost 10K stores.

Image Source

2010-2020: The Platform Puzzle

As the 2010s started, ecommerce saw a rapid uptake, and over the decade, global ecommerce sales grew 8-fold.

During this period, ecommerce saw a lot of shifts in user behavior as new platforms emerged, effectively reshaping how users interacted with brands online.

Design Changes

The 2010s show a big improvement in the design and functionalities that ecommerce stores provided. Many of the features that were carefully implemented in the 1990s and early 2000s became fundamentals that every ecommerce store had.

With more businesses moving towards the ecommerce landscape, they each needed to stand out through unique branding and design. Ecommerce platforms that started emerging in the late 2000s provided more customizable options for the storefront.

This also lead to newer technologies, concepts, and approaches rising that would reshape websites in general, including ecommerce storefronts. Concepts like Jamstack, coined by Netlify in 2015, and the launch of static-site generator frameworks like Gatsby or Next.js, allowed businesses to have more control over designing their storefront and provide a better user experience.

Mobile Commerce

The 2010s also marked the rise of mobile commerce. Ecommerce businesses started rolling out mobile apps that allowed their consumers to access the same web functionalities from their smartphones. This went through its own timeline of evolution, starting from a simple design and advancing to more sleek and user-experience tailored design.

This elevated the development of ecommerce stores from only catering to a website to multiple platforms. Developers needed to design and build APIs within their existing systems to cater for mobile development.

Image Source

Social Commerce

In the mid 2010s, social commerce started emerging. In 2015, Pinterest rolled out its first shopping capabilities through Buyable Pins. Users were able to purchase products from Pinterest. Instagram also announced Instagram Shop in 2018 which allows users to browse and purchase products from businesses without leaving Instagram.

With the introduction of social commerce, businesses had now another platform to attract new customers. Businesses invested in social marketing strategies to ensure potential customers can discover their products through these platforms and, in turn, convert to purchasing customers.

Image Source

Stripe and the Emergence of New Ecommerce Infrastructure

While ecommerce platforms evolved, a new type of infrastructure started to emerge to further improve the commerce experience. From analytics and backend-focused tools, to new solutions solving complicated issues related to areas such as payment and distribution.

The brothers Patrick and John Collison founded one of the most notable infrastructure solutions in this new commerce era in 2010. Through their side projects, they found it difficult to accept payment online and wanted to fix that. So, they developed a quick solution in 2 weeks and were able to process their first transaction. After making several iterations over the next few months, they launched Stripe under the name dev/payments.

Image Source

As indicated by its initial name, Stripe was aimed towards developers at first. The founders then realized that Stripe solves problems the entire internet faced. According to Patrick, existing solutions like PayPal and Google Checkout were “these confusing things,” and they wanted to solve what these existing solutions couldn’t.

Stripe reshaped the payment landscape, making it easy for anyone to start selling online, while providing a payment infrastructure that facilitated building custom setups. A lot of startups afterward took it upon themselves to cover other areas of the ecommerce infrastructure with similar developer-first approaches.

2020s and Ecommerce Modularization

The ecommerce landscape has evolved to include not only web as a sales channel, but also mobile apps, social apps, and more. This spawned the need for ecommerce solutions that provide omnichannel support, frontend flexibility, and an extensive feature offering.

To accommodate those needs, the 2020s saw new and existing ecommerce solutions start to adopt headless and composable architectures. As the demands for ecommerce heavily evolved, the previous methods used to create ecommerce applications, which were initially monolithic and tightly coupled, are now limiting. Developers now seek modular solutions that are less rigid and open to customizations. This would remove the restrictions on their businesses and the need for hacky workarounds.

The rise of point solutions that focus on specific domains within ecommerce has enabled this move towards modular solutions. Developers can combine these services and create a modern product stack that meets businesses’ exact requirements without compromising scalability.

As ecommerce, and the technology sector as a whole, is a rapidly growing landscape, new trends will continue to rise and fall. However, one thing remains consistent throughout the years: businesses will continue to strive to exceed their current potential. To ensure they can innovate and build unique experiences, ecommerce solutions must adopt a modular approach ensuring scalability and flexibility.

Discovery Days at Medusa: How I created Cross Post tool from Notion

Shahed Nasser — Thu, 16 Feb 2023 13:44:01 +0000

I’m a technical writer at Medusa. Part of my work includes managing the content on our blog and across platforms. Typically, we publish an article on our blog (which is built with Stackbit), then cross-post that article across platforms such as Dev.to, Hashnode, and Medium.

This process has become tedious and time-consuming. We publish at least 2 articles per week, and each article can take more than 30 minutes to be published across our blog and the 3 mentioned platforms. This includes adding the content in the format that each platform supports, uploading images if there are any, setting meta attributes such as description and meta tags, and more.

So, I decided to build a cross posting tool that would automate this task. cross-post-notion now allows us to publish an article from Notion to a GitHub repository (which holds the content of our main blog), Dev.to, Hashnode, and Medium in less than a minute. I decided to build this tool as part of our Discovery Days at Medusa.

What are Discovery Days?

Every Friday, the Medusa team members can dedicate half or their full day towards doing something different from their typical daily work. You can use this day to learn something new, read a book specific to your field, try out an interesting tool, or build a new tool.

As I realized this tool would heavily reduce the time I spend on publishing content to our blog, I dedicated the past 4 Discovery Days (Fridays) to building this tool.

How it Works

You can use cross-post-notion either as an NPX command, as a global CLI tool, or just by cloning the GitHub repository.

Then, after adding the configurations necessary (more on this later), you can publish to all the different platforms using one command. You can also choose specific platforms to publish to.

Publishing to GitHub

Publishing to GitHub can be useful for any blogging platform that uses Markdown files hosted in a GitHub repository. This includes Stackbit, GitHub Pages, 11ty, Hugo, Docusaurus, etc…

Articles are pushed to GitHub as Markdown files with front matter metadata. The front matter includes by default the title and date of the article. The values of these fields are extracted from your Notion document, and you can specify the properties to extract these fields from.

In addition, you can specify custom front matter fields to add and from which properties to extract them from Notion. You can also specify front matter fields with fixed values. This is helpful if you have front matter fields that you need to always add to your articles.

If an article has images, the images are pushed to the GitHub repository as well. You can specify the path to upload the images to and the prefix to use within the article.

Publishing to Dev.to

You can publish articles to dev.to with this tool, either on your personal account, or in an organization. Similar to posting to GitHub, the values of dev.to fields such as the title, tags, or series can all be extracted from Notion properties.

One limitation to publishing to dev.to is that you can’t upload the images in the article using their APIs. So, you’ll still have to manually go in and upload any images in your article.

Publishing to Hashnode

You can publish articles to Hashnode with this tool, either on your personal blog or in a specific publication. Similar to the other platforms, the values of Hashnode fields are extracted from Notion properties.

One limitation to publishing to Hashnode is that it’s not possible to publish an article as a draft with their APIs. It’s only possible to choose to hide it from Hashnode’s feed. So, the article will automatically be available to your followers.

Publishing to Medium

You can publish articles to Medium with this tool, either on your personal account or in a specific publication. Similar to the other platforms, the values of Medium fields are extracted from Notion properties.

Using this Tool

Requirements

This tool requires an Internal Notion Integration created and installed in your Notion workspace. The integration must have access to the pages you want to publish as well. You can learn more about this in Notion’s documentation.

Install the Tool

There are three ways you can use this tool:

1. With NPX, which does not directly install the tool on your machine:

npx cross-post-notion

2. Install as a global CLI tool with NPM or Yarn:

# using NPM
npm install -g cross-post-notion

# using Yarn
yarn add cross-post-notion global

3. Clone the GitHub repository:

git clone https://github.com/shahednasser/cross-post-notion.git
cd cross-post-notion
npm install
npm start

Set Environment Variables

You need to set the following environment variables before you can use the tool. The requirements of the environment variables depends on which platforms you want to publish to:

Notion:
- NOTION_TOKEN: (required for all platforms) Token on a Notion internal integration
GitHub:
- GH_TOKEN: (required) GitHub personal token
- GH_OWNER: (required) GitHub username
- GH_REPO: (required) GitHub Repository name
- GH_BRANCH: Branch name. Default is master.
Dev.to:
- DEVTO_API_KEY: (required) Your personal dev.to API key. Learn how to retrieve it here.
- DEVTO_ORG_ID: The ID of the organization to publish the article under. You can retrieve it either from the organization dashboard page, where the ID is the last part of the URL (https://dev.to/dashboard/organization/ORG_ID). Alternatively, you can use Dev.to's List Organizations endpoint to find the ID.
Hashnode:
- HASHNODE_TOKEN: (required) Hashnode personal token
- HASHNODE_PUB_ID: The ID of the publication to publish the article under. You can retrieve it either from the publication's dashboard page, where the ID is the second part of the URL (https://hashnode.com/PUB_ID/dashboard).
Medium:
- MEDIUM_TOKEN: (required) Medium Integration Token. Can be retrieved from here.
- MEDIUM_PUB_NAME: The name of the Medium publication. Must be the exact name as it is on Medium.

Add Configurations

Configurations are used to customize how the article is published on the different platforms. They can be used to define what properties to extract data from in Notion, whether the article should be published or added as a draft, and more. You only need to set these configurations the first time you use the tool.

By default, configurations are loaded from the file config/default.json relative to the current directory you’re running the command from. Alternatively, you can pass the path to the config file as an option.

The file can have the following configurations:

{
  "config": {
    "notion": {
      "options": {
        "skip_block_types": [
            "toggle"
        ]
      }
    },
    "github": {
      "options": {
        "image_path": "public",
        "image_prefix": "/",
        "article_path": "content",
        "properties": {
          "title": "Title for Blog",
          "date": "Publishing Date",
          "slug": "Slug"
        },
        "add_default_frontmatter": true,
        "frontmatter_labels": {
          "title": "title",
          "date": "date"
        },
        "extra_frontmatter": {
          "excerpt": "this is description"
        },
        "extra_frontmatter_mapper": {
          "excerpt": "Description"
        }
      }
    },
    "devto": {
      "options": {
        "should_publish": false,
        "properties": {
          "title": "Title for Dev.to"
        }
      }
    },
    "hashnode": {
      "options": {
        "should_publish": true,
        "should_notify_followers": false,
        "properties": {
          "title": "Title for Hashnode"
        }
      }
    },
    "medium": {
      "options": {
        "should_publish": false,
        "should_notify_followers": false,
        "properties": {
          "title": "Title for Medium"
        }
      }
    }
  }
}

You can learn what each of these fields are and what more fields can be accepted in the GitHub repository.

Run Post Command

Grab the URL of a Notion document that includes an article you want to publish. It should be an internal URL which you can obtain from the Notion document by:

Click on Share at the top right.
Click on “Copy link” at the bottom of the pop-up.

Then, run the following command:

# using NPX
npx cross-post-notion post <url>

# using CLI tool
cross-post-notion post <url>

# using cloned repository
npm start post <url>

Where <url> is the URL to the Notion document.

If all environment variables are set correctly, you should see logged in your terminal that the article was published on each of the platforms.

You can also specify which platforms you want to publish the article on using the -p option:

npx cross-post-notion post <url> -p devto hashnode

This would publish the article only on Dev.to and Hashnode.

Learn More about this Tool

You can learn more about this tool and its limitations by checking out the GitHub repository. If you use it, let me know if it helps out! Although I’m mainly focused on using it for publishing articles at Medusa, feel free to open issues and contribute to further improve the tool.

Be sure to check out Medusa, a composable ecommerce platform, on GitHub.

8 Tips to Optimize Internal Search in Ecommerce Websites

Shahed Nasser — Thu, 02 Feb 2023 13:56:24 +0000

While the value of external search optimization (SEO) is widely known, many ecommerce websites overlook the value of the hidden gem that is internal search engines. Only 15% of businesses dedicate resources into perfecting the site search. This is worrying as 68% of customers do not return to an ecommerce website that provided a bad search experience.

When building an internal search engine, businesses should provide a search experience that matches their products and audience. This requires configuring your search engine’s ranking rules, synonyms, faceted search, and more.

When we designed our Search APIs at Medusa, we abstracted the search functionalities to allow developers and businesses to either implement custom logic, or, more commonly, use search services like MeiliSearch or Algolia. These services continuously optimize their search functionalities to ensure that your ecommerce website provides a good search experience.

This article explains some tips for configuring and optimizing your search engine to provide a better search experience for your customers.

What is Medusa? Medusa provides bespoke, modular and open commerce infrastructure for developers. Medusa’s different components and APIs are built in abstract layers, making it easier for developers to customize the core functionalities for different business use cases.

Some Search Statistics

If you’re unsure of the importance of internal search engines, here are some statistics that emphasize their effect on ecommerce sales:

43% of customers on retail ecommerce websites go straight to the internal search engine.
Internal search engines are widely used by the most valuable customers; customers that use the internal search engine are 2.4 times more likely to make a purchase.
Customers that use the internal search engine spend 2.6 more times than those who don’t search.
39% of customers are influenced to make purchase by relevant search results.

Tips to Optimize Internal Search Engines

Ranking Rules

Ranking rules are used to decide which search result shows first. A basic approach would show the results having the same exact words in the name of the product first. Although this is fine, but in a lot of cases you must take into account other attributes such as the category of the product or its stock amount.

You might also want to boost the ranking of some products over others due to a marketing strategy. For example, you might want to show products having a discount higher than those without a discount.

Defining your ranking rules can help customers find exactly what they need and influence them to make a purchase.

Typo Tolerance

Customers often make typos while searching. If a search engine shows them results based on their exact query, they’ll typically land on no results pages, which leads them to making no purchase.

An internal search engine must be optimized to detect and resolve typos, providing the customer with the results they’re looking for. Most search engine services utilize machine learning to ensure typo tolerance and provide a better search experience.

Search Analytics

Search analytics can be a minefield of valuable information about your customers. It can help you understand what are the most searched for items. Coupled with other analytics you have related to purchases, you can figure out which of these items result from search results and, in turn, boost their ranking.

Search analytics can also help you figure out which queries lead to no search results. This can be useful to understand what type of products your customers are looking for in your ecommerce website. You can also utilize this to define related results for these search queries.

Synonyms

Often, multiple words have a similar meaning. For example, some customers might use “shirt” and “t-shirt” interchangeably. This can also be affected by different customer cultures or locations.

A good search engine should provide synonyms that would allow the customers to land on the same search results, despite which synonym they use. Obviously, it would be difficult to cater to every possible synonym. You can utilize here the search analytics mentioned earlier to figure out what synonyms are necessary to define.

Parsing Search Queries

According to Google’s 2022 Year in Review, there’s a +75% year-on-year (YOY) increase in search queries related to saving money, such as “cheap electric cars”. Some customers might use other search queries, such as “shirts under $20”.

Although it might not be highly necessary to account for these search queries, parsing them and showing the customer exactly what they need can show customers that you understand them. Consequently, it can lead to a better search experience.

Faceted Search

Faceted search enables users to narrow down their search queries by providing filters that allow them to be more specific.

For instance, by using this search feature, someone looking for a Batman shirt can filter out books and videos about the superhero and focus the search on the desired product.

Filters can be as basic as showing different available categories, and can extend to adding more advanced choices such as material, brand, colors, sizes, and more.

A/B Testing

A/B testing is the process of comparing the outcome or analytics two different versions of a feature or interfaces. In the context of internal search engines, A/B testing can be used to figure out which configurations drive more sales.

For example, if you have two ranking rules, and you’re unsure which one would be better for your customers, you can use A/B testing to figure that out.

There are many ways to run A/B testing. Algolia provides steps to run an A/B test for search relevance. Search services may provide this functionality differently.

Optimized No-Results Page

Despite all the configurations and optimizations you may put in place to improve your internal search engine, it’s still inevitable that the customer might land on a no-results page. Instead of trying to avoid the reality of a no-results page, you can embrace and utilize it for other opportunities.

A no-results page can be optimized to include the following:

Recommended results: You can show results for a collection of products that drive sales. For example, discounted products or best-selling products.
Suggested queries: You can show queries that are similar to the customer’s query, or queries you’re sure will provide many results.
Personalized suggestions: You can use analytics related to the customer to provide suggestions. For example, you can show results based on the customer’s previous search results. You can also show results that are popular in the customer’s region or location.

Search Metrics to Measure

Search metrics and analytics can be key in optimizing your internal search engine. They can help you better understand your customer and decide on new configurations if necessary.

Some search metrics that you should measure are:

Most Searched Products: this metric can help you understand what your customers look for the most in your website. It can be an opportunity to find new products for your store.
Searched Products Leading to Highest Conversions: just because a product is searched for the most does not mean it’s the product that leads to conversion and revenue. Combining the Most Searched Products metric with the Conversion metric can be useful to decide on ranking rules.
New Searches: new searches wouldn’t rank high in the Most Searched Products metric, but they can provide useful insights to the new and upcoming trends in your industry.
No Result Searches: this metric shows which search queries lead to no-result pages. This can be used to define synonyms or search suggestions.

Conclusion

Optimizing your internal search engine can be a powerful tool to improve your ecommerce sales. By carefully configuring your ranking rules, typo tolerance, synonyms, faceted search, and parsing search queries, you can provide a better search experience for your customers.

Additionally, by measuring search metrics such as Most Searched Products, Searched Products Leading to Highest Conversions, New Searches, and No Result Searches, you can better understand your customer’s needs and optimize your search engine accordingly.

By implementing these tips, you can be sure of providing an improved internal search engine experience for your customers.

Medusa is a composable commerce engine that allows you to integrate whichever search engine you find most suitable for you. If you’re interested in Medusa, check out the quickstart guide.

Medusa v1.7.3: Sales Channels out of Beta, Improvements to events, and more!

Shahed Nasser — Thu, 12 Jan 2023 12:23:09 +0000

Time for another exciting release of Medusa!

Version 1.7.3 moves Sales Channels and Publishable API Keys out of beta, introduces improvements for events system and payment sessions, and more.

Keep reading below to learn more about all the new changes in this release of Medusa!

How to Update Medusa?

Medusa Server

You can update your Medusa server using the following command:

npm install @medusajs/medusa@latest @medusajs/medusa-cli@latest medusa-interfaces@latest

Then, please follow the upgrade guide for additional required steps.

Medusa Admin

You can also update the Medusa Admin by pulling changes from the GitHub repository.

Sales Channels

We first introduced Sales Channels in v1.3.5 of Medusa. However, as this feature was in beta mode, it was guarded by feature flags. As of v1.7.3, it is enabled by default.

If you’re not familiar with what sales channels are, they allow merchants to create separate channels they sell their products in. Then, they can specify which sales channels are available in that sales channel.

Subsequently, this would lead to showing customers only products available in their sales channels.

For example, in a B2B use case, a merchant can create a B2B sales channel with products only available for B2B customers. Other types of customers wouldn’t be able to purchase these products.

Learn more about Sales Channels in this documentation.

Publishable API Keys

Publishable API Keys are used to associate resources with an API key. Then, when that publishable API key is used on the client-side, retrieving or processing data is only performed on the defined scope of resources for this API key.

This can be useful when you have resources that you have to pass as parameters for every or most requests.

An example of this is using sales channels on the storefront. You would need to pass the ID of the sales channel to the list products and the create cart requests, among others. This approach is error-prone and can be a hassle during development.

With Publishable API keys, you can just pass the API key in the header of the request. When using tools like Medusa JS Client or Medusa React, you only need to pass the API key once, and it’ll automatically be added to all requests.

At the moment, publishable API keys can only be associated with sales channels.

Learn more about Publishable API Keys in this documentation.

Improvements in the Events System

Medusa’s events system allows you to subscribe a handler method to certain events. The handler method would perform asynchronous action when the event is triggered.

For example, you can subscribe to the order.placed event so that when it’s triggered, you send the customer an email.

In v1.7.3, we introduce improvements into the events system, the main being the ability to retry failed handler methods. Errors can commonly occur in handler methods, either due to errors in the logic of the method or due to errors with third-party services.

You can now specify a unique ID of a subscribed event handler and specify how many times it should be retried in case it fails. Improvements also include enhanced readability and allowing for horizontal scaling.

Learn more about the events architecture in this documentation.

New Payment Session Flow

In v1.7.3, we refactored our payment session flow to improve its performance. The new change reduces the amount of times Medusa communicated with the third-party payment providers.

This improvement does not require any changes in how you use and implement the checkout flow or any payment-related flow.

Redesigned Admin Sidebar

The admin sidebar is now redesigned for a clearer design. The team and users section is now removed, and the sidebar is only focused on important links such as Orders and Products.

In upcoming versions, we’ll introduce additional redesign changes such as collapsible sidebar, history, improved help center, and more.

Documentation Changes

In our documentation we’ve implemented general fixes and added new documentation pages such as:

Storefront guide on how to implement customer profiles.
Gift cards conceptual guide along with how-to guides for storefronts and admins.
Claim-order flow documentation.
Development guide on how to customize Medusa Admin.

Did you miss out on?

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.

How I built Nike’s Ecommerce Features with Medusa

Shahed Nasser — Tue, 10 Jan 2023 13:06:52 +0000

Nike is the world’s largest supplier and manufacturer of athletic shoes. Part of what makes Nike successful is its ecommerce website. Its net sales has crossed 12 billion USD in 2022. This makes up approximately 65% of Nike’s global direct-to-customer revenue in 2022 (18.73 billion USD).

Nike’s ecommerce website is rich with features that encourage customers to make a purchase. It shows a great understanding of what customers want, and how to convert first-time visitors to loyal customers.

Nike realized early-on that they needed to implement an omnichannel experience to provide their customers with the best user experience. This led them to build their own headless commerce platforms utilizing microservices and cloud technologies.

In this article, you’ll learn how to implement 5 core features Nike offers its customers using Medusa. These are:

Digital Gift Cards
Free shipping for members
Search suggestions and autocomplete
Member-only products
Birthday deals

What is Medusa?

medusajs / medusa

Building blocks for digital commerce

Medusa

Documentation | Website

Building blocks for digital commerce

Getting Started

Visit the Quickstart Guide to set up a server.

Visit the Docs to learn more about our system requirements.

What is Medusa

Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm.

Learn more about Medusa’s architecture and commerce modules in the Docs.

Roadmap, Upgrades & Plugins

You can view the planned, started and completed features in the Roadmap discussion.

Follow the Upgrade Guides to keep your Medusa project up-to-date.

Check out all available Medusa plugins.

Community & Contributions

The community and core team are available in GitHub Discussions, where you…

View on GitHub

Using an open source ecommerce platform gives you many of the benefits of customization that a custom platform like Nike’s has. Medusa is built for developers that wants to build bespoke commerce experiences with a composable commerce platforms in Node.js.

Medusa’s architecture allows businesses and developers to build unique and on-brand experiences. Features such as omnichannel support, scalability, and customizability are at Medusa’s core.

Medusa also provides advanced ecommerce features related to automated RMA flows, sales channels, product and order management, and much more.

Medusa’s integrations system gives businesses more flexibility. You can integrate any third-party service into Medusa for rich CMS functionalities, payment gateways, customer support, and more. You can also create custom integrations specific to your brand.

If you like this article, please give Medusa a 🌟 on GitHub

Feature 1: Digital Gift Cards

Nike allows customers to customize and purchase gift cards. They can be sent as a gift to an email or can be shipped as an actual card to a shipping address.

Medusa allows creating gift cards with custom images, unlimited amounts, description, tags, and more.

Merchants can also specify for a specific denomination or amount the price for different currencies.

Customers that purchase this gift card will have it delivered to their email and can use it during checkout.

You can also customize the experience by allowing customers to deliver the gift card to another person’s email. Gift cards in Medusa (and all entities) have a metadata attribute. This attribute can be used to store custom data.

You can utilize it to store a custom recipient email or shipping address, which would allow customers to send the gift card to their family or friends.

metadata: {
    recipient_email: 'example@gmail.com'
}

Feature 2: Free Shipping for Members

When taking a look at the features Nike provides, you’ll notice that their main focus is converting visitors and one-time customers to registered customers. This builds customer loyalty and increases the possibility of the customer making future purchases.

One way Nike encourages visitors to register and become members is offering free shipping for every order a member places. This makes registering worth the extra steps a customer have to make before placing an order, as they’ll be saving up on current and future orders.

In Medusa, this feature can be implemented with a combination of available features: Customer Groups, Discounts, and Subscribers.

Customer Groups

Customer groups can be used to group together customers that share a similar set of attributes. Then, you can apply a different set of prices, discounts, and rules for customers belonging to that group.

In this use case, you can use customer groups to create the “Members” customer group. You’ll see later how to add customers to that group automatically on registration.

Discounts

Discounts can be used to create discount codes that customers can use to save on their order. Discounts can be in the form of fixed discount amount, percentage discount amount, or free shipping.

Discounts can also have conditions. For example, you can specify which products this discount can be used on or which customer groups.

To implement the Free Shipping for Members feature, you can create a discount that gives customers belonging to the customer group “Members” free shipping on their orders.

Subscribers

The last step required is to automatically:

Add customers to the Members customer group on registration.
Add the free shipping discount to customers of the Members customer group.

In Medusa, important actions trigger an event. Developers can listen or subscribe to events and perform an automated task when an action occurs. They do that using subscribers.

Starting with adding customers to the Members customer group, you need to create a subscriber src/subscribers/members.ts on your Medusa server that subscribes to the customer.created event and adds the customer to the “Members” customer group:

import { CustomerGroupService, CustomerService, EventBusService } from "@medusajs/medusa"

type InjectedProperties = {
  eventBusService: EventBusService
  customerService: CustomerService
  customerGroupService: CustomerGroupService
}

class MembersSubscriber {
  customerService: CustomerService
  customerGroupService: CustomerGroupService

  constructor (container: InjectedProperties) {
    this.customerService = container.customerService
    this.customerGroupService = container.customerGroupService

    container.eventBusService.subscribe('customer.created', this.handleRegistration)
  }

  handleRegistration = async (data) => {
    //get Members customer group
    const membersGroup = await this.customerGroupService.list({
      name: 'Members'
    }, { take: 1 })

    if (!membersGroup.length) {
      //Members group doesn't exist
      return
    }

    //add customer to customer group
    await this.customerGroupService.addCustomers(membersGroup[0].id, data.id)
  }
}

export default MembersSubscriber

Next, you need to create a subscriber that automatically adds the free shipping discount to members. The subscriber should subscribe to the events cart.created and cart.customer_updated. The first event is triggered when a new cart is created, and the second one is triggered whenever the customer associated with the cart is changed.

import { CartService, EventBusService } from "@medusajs/medusa"

type InjectedDependencies = {
  eventBusService: EventBusService
  cartService: CartService
}

class MemberDiscountSubscriber {
  cartService: CartService
  discountCode: string

  constructor (container: InjectedDependencies) {
    this.cartService = container.cartService
    this.discountCode = 'MEMBERSFREESHIP'

    container.eventBusService.subscribe('cart.created', this.handleDiscount)
    container.eventBusService.subscribe('cart.customer_updated', this.handleDiscount)
  }

  handleDiscount = async (data) => {
    const cartId = typeof data === 'string' ? data : data.id

    this.cartService.update(cartId, {
      discounts: [
        {
          code: this.discountCode
        }
      ]
    })
  }
}

export default MemberDiscountSubscriber

Notice that in the code above, the discount code is hardcoded. This behavior can be changed to instead include it as an option or retrieve it in other ways using the DiscountService.

Feature 3: Search Suggestions and Auto Complete

An essential and often overlooked feature that ecommerce websites must perfect is the search functionalities. Customers generally visit an ecommerce website either exactly knowing what they want, or with an idea of what they want.

Nike does a great job at providing results for both types of customers. The moment the customer starts entering a search query, they can see top query suggestions and the best products that match the query.

If the customer knows what they’re looking for, they’ll find the product in the immediate results. If not, they can use the help of the top suggestions.

In Medusa, advanced search functionalities can be implemented by integrating the server to third-party services like Algolia or MeiliSearch. This removes the need to implement these features from scratch, and allows utilizing best-in-brand services in your store.

Both Algolia and MeiliSearch provide advanced features such as instantaneous search results, typo tolerance, search suggestions, autocomplete and more. You can integrate one of them by installing the service’s plugin on the Medusa server. Then, you can customize the UI on the storefront as you see fit for your customers.

Feature 4: Member-only Products

Similar to the free shipping feature, Nike also provides products that are only available for members or registered customers. This further encourages visitors to register and check out exclusive products.

In Medusa, this can be implemented with a combination of features: Customer Groups, Sales Channels, and Subscribers.

Customer Groups

As explained in an earlier section, members can be represented by a Customer Group called “Members”. You would then need to implement automatically assigning the Members customer groups to registered customers, as explained earlier.

Sales Channels

Sales channels allow customizing how and what products you sell for different channels in your store. Channels can be different platforms, such as website or mobile. It can also be different types of customers, such as B2B customers or members.

To implement the Member-only products feature, you need to create a sales channel for Members. Then, you can make only specific products available in that sales channel and not available in the default channel.

Subscribers

The last step is to create two subscribers that handle the following:

Add customers to the Members customer group on registration.
Assign the Members sales channel to members’ carts.

The first one’s implementation was explained earlier, and you can find the code block in a previous section.

As for the second, you need to create a subscriber that subscribes to the cart.created and the cart.customer_updated events. If the customer associated with the cart belongs to the Members customer group, the Members sales channel is associated with the cart. Otherwise, the default channel is associated with the cart.

import { CartService, EventBusService, SalesChannel, SalesChannelService } from "@medusajs/medusa"

type InjectedDependencies = {
  eventBusService: EventBusService
  cartService: CartService
  salesChannelService: SalesChannelService
}

class MemberDiscountSubscriber {
  cartService: CartService
  salesChannelService: SalesChannelService

  constructor (container: InjectedDependencies) {
    this.cartService = container.cartService
    this.salesChannelService = container.salesChannelService

    container.eventBusService.subscribe('cart.created', this.handleCreate)
    container.eventBusService.subscribe('cart.customer_updated', this.handleCreate)
  }

  handleCreate = async (data) => {
    const cartId = typeof data === 'string' ? data : data.id

    //retrieve default sales channel
    const defaultChannel = await this.salesChannelService.retrieveByName('Default Sales Channel') as SalesChannel

    //retrieve sales channel
    const membersChannel = await this.salesChannelService.retrieveByName('Members') as SalesChannel

    if (!membersChannel) {
      //sales channel does not exist
      return
    }

    //retrieve cart
    const cart = await this.cartService.retrieve(cartId, {
      relations: ['customer', 'customer.groups']
    })

    const isMember = cart.customer?.groups.some((group) => group.name === 'Members')

    await this.cartService.update(cartId, {
      sales_channel_id: isMember ? membersChannel.id : defaultChannel.id
    })
  }
}

export default MemberDiscountSubscriber

Feature 5: Birthday Deals

Another member benefit that Nike offers is birthday deals. If a member registers before their birthday, they’ll receive a discount on their birthday. Nike emails them with details about the discount.

This can be implemented in Medusa using a combination of features: Customer Groups, and Scheduled Jobs. The usage of customer groups is as explained in earlier sections.

Scheduled Jobs

Medusa allows developers to schedule a task to run at a specific time using scheduled jobs. In this context, a scheduled job can be used to run every day at midnight. Then, it checks which customers’ birthday is set to today. For those customers, an email is sent with the deal details.

You can make use of the metadata field to store custom fields such as birthday. You’ll need to save it when the customer registers or allow the customer to set their birthday in their profile.

const checkBirthdaysJob = async (container, options) => {
  const jobSchedulerService = container.resolve("jobSchedulerService");
  jobSchedulerService.create("check-birthdays", {}, "0 0 * * *", async () => {
    //job to execute
    const customerService = container.resolve("customerService");
    const customers = await this.customerService.list({
      metadata: {
        birthday: Date.now().toString()
      }
    })

        customers.forEach((customer) => {
            //create discount/gift card
            //and send email
        })
  })
}

export default checkBirthdaysJob;

The deal can be implemented either using Discounts or Custom Gift Cards. For the first option, you create a discount with a random code and send it to the customer. For the second option, you create a custom gift card with an amount, and send the gift card’s code to the customer.

To send the email to the customer, you’ll need to integrate a third-party plugin such as SendGrid.

Do More with Medusa

The features explored in this article aim to provide a better user experience for customers. This is what sets big brands like Nike apart and keep their customers loyal.

Although Nike has developed its own headless commerce platform from scratch, using a platform like Medusa can provide a similar amount of features, extensibility, and scalability.

Check out the documentation for more details on what Medusa is and how to get started.

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.

The 10 Medusa Posts of 2022 that you need to read

Shahed Nasser — Mon, 09 Jan 2023 13:54:40 +0000

At Medusa, we invested more resources and focus into our content in 2022 and achieved some amazing results, including:

+172,000 article reads

+100 articles

+150 community writers

In this article, we want to highlight 10 of the best and most-read articles we put out in 2022. If you want to stay up to date on our newest content and product releases, then sign up to our newsletter.

If you want to become part of our community writer program, then you can read more here.

Why content is important at Medusa

As one of the most used platforms in the OS ecom space, we want to take an active part in educating developers not only about Medusa, but the space in general and the tools available.

We tailor our content towards solving community problems, researching new trends and ideas in the open source and ecommerce realm, and share company-related insights. This allows us to stay connected with the developer community, especially with the help of our community writers.

If you want to know more about Medusa itself, then you can check out our documentation for details on its features and how to get started.

10 Best Medusa Articles in 2022

Announcement: Medusa's $8M USD Seed Round

Read here.

In July of 2022, we announced our $8M USD Seed round led by LocalGlobe and Dawn Capital. The story was also covered by TechCrunch and BusinessWire.

With the seed round, we will continue building amazing features in Medusa, building integrations and plugins for third-party tools, and providing the best developer experience.

9 Best Ecommerce UX Practices From the World's Best Ecommerce Site

Read here.

McMaster-Carr has been crowned the title “best e-commerce site” by HackerNews users. As we are building Medusa with the aim to be the best ecommerce platform, this grew our curiosity which lead us to do a research around this website with the help of a community writer.

We then came up with 9 best user experience (UX) practices we picked up from McMaster-Carr in the hopes of it being helpful for businesses and ecommerce developers everywhere.

Creating a React Native Ecommerce app with Medusa

Read here.

Mobile apps have become an essential requirements for all types of businesses, specifically ecommerce businesses. Medusa’s composable architecture makes it possible to integrate the headless server to any frontend framework or platform.

This tutorial written by one of our community writers help readers interested in developing an ecommerce app for their Medusa server get started using React Native. It has become one of our top viewed articles of all time.

Headless Architecture Explained to a 5-Year-Old

Read here.

In the past couple of years, headless has become a buzz-word used by different types of companies and solutions, including Medusa. You’ve probably heard of headless ecommerce or headless CMS, but what does it really mean?

This article takes the challenge of simplifying the meaning of headless that a 5 year old can understand it.

Medusa vs. Magento: Comparing two open source ecommerce frameworks

Read here.

Both Medusa and Magento are open source platforms with a long list of impressive ecommerce and development features. This article compares both platforms, listing what each has to offer in different domains including multi-currency and region support, payment and shipping providers, installation and deployment, and more.

Top 5 open source ecommerce platforms for B2B: A feature-by-feature review

Read here.

This article was also part of our December B2B launch. We conducted a research along with a community writer to put together a list of features that a B2B platform must have based on general B2B use cases.

We then chose 5 top ecommerce platforms (including Medusa) and checked whether these features exist in those platforms. This will help any business or developer unsure about which platform to choose for their B2B business make a choice.

Case study: How Tekla improved conversion by 70% at record speed using Medusa

Read here.

Tekla is textile brand operating in more than 50 countries around the world. After migrating from WooCommerce to Medusa, their conversion rate increased by 70% and they significantly reduced their customer service response hours, among other achievements.

This article explores Tekla’s challenge with their previous solution, and how they utilized Medusa to bring their vision to life.

What is Composable Commerce?

Read here.

The comparison between Monolithic and Composable architectures have been the talk of the developer community in recent years. This is especially for ecommerce platforms, as we see more adoption of the composable architecture by new and existing tools.

This article dives into the differences between the two architectures, and why we at Medusa believe composable commerce is the future.

Medusa Hackathon Winner Announcement

Read here.

In October of 2022, we hosted a Medusa Hackathon with cool prizes. We got +200 project submissions which exceeded our expectations.

This article highlights the winners and runner up list. Check it out to see what cool projects were built with Medusa!

Case Study: How Palmes built a Global on-brand Store in <6 Weeks with Medusa

Read here.

Palmes is a meanswear brand with roots in tennis culture for wearing on and off court that sells tennis wear and accessories. By creating their ecommerce store with Medusa, they utilized advanced ecommerce features such as selling in over 40 countries and building a fully-tailored user experience in their storefront in less than 6 weeks.

This article explores Palmes story of how they used Medusa to create their ecommerce platform with a unique storefront.

Close contestants

Other popular articles that we believe are worth highlighting:

What language or framework are you planning to learn in 2023?

Shahed Nasser — Fri, 06 Jan 2023 13:15:31 +0000

With a new year come new resolutions! What programming languages or framework are you planning to learn this year?

P.S: If you haven't learned about Medusa yet, maybe you have another new year resolution! Check out our GitHub repository and documentation for more details.

6 ways we improved our documentation in 2022

Shahed Nasser — Tue, 03 Jan 2023 12:00:06 +0000

At Medusa, we strive to provide developers with the best experience. Documentation plays a huge role in it, as it guides developers in their journey with the software at hand.

As a technical writer at Medusa, I am heavily involved in the development of our documentation, especially in writing the content. Throughout 2022, our documentation team have put a lot of effort into not only investing more resources into documentation, but look into different ways to improve it.

In this article, I’ll share with you how we went about improving our documentation at Medusa.

What is Medusa

Before diving into our documentation improvement, it’s important to know what Medusa is and how developers use it.

Medusa is an open-source composable commerce platform. Its architecture is made of three main components:

The server: a headless backend that handles all the business logic and data related to the ecommerce store. It can be connected to any frontend for both the storefront and the admin.
The storefront: this is the interface that customers use to browse the ecommerce store and make their purchase. We provide a Next.js and Gatsby starter storefronts, but developers have the freedom to create their own by connecting to the storefront REST APIs.
The admin: this is the interface that merchants use to manage their ecommerce store’s settings and data. We provide a Medusa admin that provides all necessary and advanced functionalities, but developers are free to create their own by connecting to the admin REST APIs.

You can learn more about Medusa’s features and architecture in the documentation.

Why we decided to improve our documentation

At the beginning of 2022, our documentation provided developers with the basic information they needed to run Medusa. Although this was good enough to get them started, it wasn’t enough to guide them through the entire process of developing an ecommerce store.

There were improvements needed regarding the content, the design, the feedback collected, and more. To provide these improvements, we needed to change how we handle our documentation and add more resources into developing it.

How we improved the documentation

View the documentation as a product

The most essential change that helped us implement all improvements is how we manage the documentation. In most software companies, documentation has less of a priority compared to the software, and it is handled as an afterthought.

At Medusa, we early on came to realize that documentation is what can actually drive further adoption of Medusa.

Developers that are curious would be sufficient with a quickstart guide. However, those who actually want to use Medusa to create an ecommerce store for themselves or for their clients require the documentation to explain different concepts and how to implement them.

By recognizing that the documentation is a product, we were able to:

Recognize priorities for what changes/additions should be made for the documentation. These priorities can be decided on based on company goals, our roadmap, improvements in user experience, and more.
Plan our work in cycles. We now use Linear to manage our documentation cycles, tasks, and backlog.
Involve the design team and other teams to further improve our documentation and the experience we provide.
Be more in sync with the core engineering team to deliver changes to the documentation along with changes in the product. The core engineering team also uses Linear, so both teams can be informed of the work they’re each doing, which allows us to stay in sync.

Refactored our API Reference

Our previous API reference needed serious improvements related to:

Maintaining it to ensure that all the details in it were updated with continuous releases.
Providing a good user experience, as it was slow and provided minimal information.
Offering examples on how to use and run endpoints.

To improve it, we decided that it needed to be fully refactored, both in how it was being generated and in how the website itself was built.

The API reference’s OpenAPI Spec is now generated with every new release, ensuring that it’s never outdated. We also added in the OpenAPI Spec comments in our code (which are used to generate the API reference) examples of running requests with the Medusa JS Client and cURL. In addition, we added examples of expected request or response parameters and of possible errors.

The website was previously built with Gatsby using a custom theme. As part of the refactor, we changed it to run as part of our Docusaurus main documentation and on top of Redocly using the Redocusaurus plugin.

This allowed us to utilize Redocly’s functionalities and features that are tailored towards building API references. This further improves the developer experience.

Completely redesigned the documentation

In the last quarter of 2022, we focused on redesigning the documentation to:

Improve the user and developer experience of our documentation.
Restructure the homepage to guide developers to the essential concepts and guides in Medusa.
Provide a design that is fitting with our brand identity.

Thanks to our design team, we were able to introduce a clean design, a summarized homepage with the essential documentation on how to use Medusa, and improve on existing components used throughout the documentation.

Collect user feedback

An important part of developing any product, including the documentation, is to ensure that your users are actually benefiting from the additions or changes you’re making. We implemented that in different ways.

One way was to include a feedback component at the end of all documentation pages or after certain steps that allows developers to let us know whether they found the content helpful or not, and what could be improved.

This helped us find errors in the documentation that we missed or opportunities to make the documentation clearer.

Furthermore, for each code block, we added a report button. This allows developers to quickly create an issue on GitHub with information on the problem they faced while using that code block.

There’s also a link to report issues in the navigation bar that developers can use at any point while browsing the documentation. This further helps us eliminate issues and errors quickly.

Integrate Vale and ESLint into the Documentation

Style guides are important as it helps maintain a single tone throughout the documentation. It is key to be consistent in how you write the documentation, as developers get used to it while browsing it.

However, it’s one thing to write down a style guide, and another thing to actually apply and enforce it. As humans, we can easily miss certain things, especially for written content. This is especially the case with open source projects, as you have many contributors that look forward to help, but may not know how to follow the style guide.

Similar to how a software has integration or unit tests that are built to make sure changes in the software don’t break the entire system, we implemented tests for our documentation’s style guide using Vale and ESLint.

Vale allows you to define a set of rules for your documentation’s textual content. Then, when ran against your documentation files (such as Markdown files), it shows you any errors in the content based on your rules.

ESLint allows you to check for errors and enforce a programming style for JavaScript. Using plugins, it can be integrated with other languages and formats. Using the eslint-plugin-markdown plugin, we were able to check for errors and inconsistencies in code blocks within the documentation.

We also integrated both tools into our documentation pipeline by ensuring that their tests run on every documentation pull request (PR) in our GitHub repository.

Run User Trials

Collecting user feedback is helpful. However, in order to provide a good developer experience, you need to learn how your developers are actually using your documentation.

The best way to do that is to monitor them using it while performing a task. To do this, we started user trials for our documentation. Every quarter, we’ll run a user trial revolving around a specific task and monitor how participants perform that task.

This is essential when you introduce a new feature into your documentation and want to see how developers use it. Is it actually a good feature? What improvements are needed to make it better?

This is also a good exercise to see what problems developers might run into, how the content or the information architecture can be misleading, and whether we really understand our documentation users or not.

If you’re interested in helping us improve our documentation, learn more about our user trials and how you can become a participant.

What’s next?

Writing this article does not mean we have the best documentation out there, and the journey to improve our documentation doesn’t end here. It’s an ongoing process and collaboration between our different teams and the community behind Medusa. The goal is to ensure that we understand our developers and make the information they need accessible.

What do you think of our improvements on the documentation? And do you have suggestions for further improvements? Let us know below!

Should you have any issues or questions related to Medusa, then feel free to reach out to the Medusa team via Discord.