DEV Community: Oliver Juhl

Designing a Git-Like Flow in Ecommerce APIs

Oliver Juhl — Thu, 26 Jan 2023 12:26:21 +0000

Medusa’s Order API supports order editing capabilities that equip merchants and developers with the tooling necessary to reduce manual work and offer a great customer experience.

Designing this seemingly simple functionality proved to be a complex task that was solved with inspiration from the world's most-used developer tools.

This article covers how we adopted principles from the Git version control system and GitHub in our Order Editing API design. You can read the product announcement here.

Understanding Order Editing

Before going over the design behind this feature, we need to understand its constraints. Let’s dive into what it means to edit an order in Medusa.

When an order is placed, it is in its base state from a customer and store administrator point of view. Generally, the next steps for orders from here are fulfillment, shipping, and payment capturing.

Sometimes a change in the order might be required first. Several scenarios could lead to this; the customer changed their mind about their purchase, the inventory management system was out of sync with the physical stock, or the merchant wants to add a complimentary item due to long processing time.

A naive solution would allow store administrators to modify order items directly. However, this could have serious consequences. Order history is lost or becomes misleading, potential unresolved payment discrepancies arise, and stale order data remain in integrated services, such as analytics providers.

Aside from ensuring data consistency in your underlying dependencies, you also want to offer a good customer experience. Instead of changing things directly, you want to give customers full control and confidence by allowing them to confirm a change before it is completed. Supporting these cases spawns the need to introduce an intermediate pending step for the edits you make to an order.

It should be clear that editing an order is not as straightforward as updating the quantity of a line item. There are many use cases and dependencies to consider to ensure data is consistent across all systems in your stack and that customers get the best experience.

Building an API with git-like flow of events

As we started to plan the feature, it became apparent that we were building a subset of the functionality from a version control system with a pull request-like mechanism for editing an order.

The goal was to allow users to change the original state of their order with an approval-staged flow without losing its history. A Git-like system with the management capabilities offered by GitHub.

We were excited to realize that a developer-centric pattern from our daily work could directly apply to our API design.

We can see the following resemblance between the order-editing flow and a git-like system:

Order placed → Main branch
Store administrator initiates an order edit → Branches out from main
Store administrator makes changes to order edit → Pushes commits to branch
Store administrator submits an order edit → Opens a pull request to main
Customer confirms an order edit → Reviewer approves the pull request

We even extended the capabilities of the API with additional functionality as a result of using the Git + GitHub analogy:

Store administrator force completes an order edit → Core maintainer force merges a pull request
Customer requests an additional item → Reviewer requests changes to the pull request

Our feature had a functional requirement of having an intermediate step between initializing the edit and committing the changes. In this state, you can create multiple edits to the order without applying them. This is similar to pushing commits to a branch while a feature is in work-in-progress, except we only allow one commit for each order edit. More on that later.

Design

Now let’s turn to implementation specifics to see how the analogy took shape in our data layer.

There are two database models worth highlighting: OrderEdit and OrderItemChange:

// order-edit.ts

OrderEdit
- id
- order
- changes
- internal_note
- items

// order-item-change.ts

OrderItemChange
- id
- original_line_item
- line_item
- type (add, remove, update)

Only properties relevant to the Git analogy are included above. If you wish to explore the models more in-depth, you can find them here.

The OrderEdit model holds the modifications you want to make to your order. It references the original order, stores an internal note, and contains a list of edits. When an OrderEdit is created, all items from the Order are copied to the OrderEdit.

The edits are represented as one or more OrderItemChange records. There are three types of changes: Add, Remove and Update. The purpose of each should be clear. When an edit is created, we store a copy of the original item to ensure full visibility of the history when these changes are eventually applied.

You might have already drawn the parallels to Git. The above data modeling is comparable to how branches, staged changes, and commits work. The OrderEdit is your branch diverging from the main one, and the OrderItemChange records are your staged changes ready to be pushed.

Together, they constitute the commit with a message and hold the information capable of showing a diff of the changes.

Limitations to the analogy

Not all aspects of a traditional version control system apply to our feature. Whereas Git is excellent at facilitating seamless collaboration among an indefinite number of users, our feature is limited to one active order edit at a time. Only one branch aside from the main one.

This is to guard businesses against unwanted situations arising from multiple ongoing edits and outbound payment links. An example would be that customers accidentally pay for the wrong order edit. We built the logic to eliminate potential merge conflicts.

And finally, we don’t offer a way for merchants to roll back the changes when first committed. The changes made to an Order are irreversible. No git revert.

Demo

Enough talking. Let’s see it in action.

Conclusion

Designing our Order Editing API was especially exciting, as it allowed us to apply existing concepts from our daily work to solve a problem for our users. The API we built provides a great developer experience by using familiar concepts while abstracting away the complexity for our merchants in the admin system.

For concrete API examples of the full order editing flow, see our how-to documentations on:

January 2023 - A glimpse into our roadmap

Oliver Juhl — Tue, 17 Jan 2023 14:43:03 +0000

For 2023, our main mission at Medusa is to ensure our platform provides more extensibility and composability. So, our roadmap contains features that push our platform towards these goals.

Although we have many features planned out for 2023, this article focuses on features our team has already started on and are guaranteed to be shipped in the upcoming quarters.

Keep reading to learn about what’s in store for future versions of Medusa.

Planning our Roadmap

At Medusa, we strive to implement high quality and advanced features for ecommerce businesses interested in the platform. We have a broad vision of the features that we want to implement, and the direction we want Medusa to move into.

This is reflected in our Roadmap. We constantly revisit and make additions to our roadmap to match our vision of the platform. The features in this article are only a subset of the features we are planning to implement in Medusa.

Aside from the roadmap, we’re introducing Rewind Weeks at Medusa in 2023. These will allow us to shed light on the features we shipped in a quarter, along with projects and tools that our team has built to further improve Medusa. We’ll share more details on this later.

Select Features From Our 2023 Roadmap

Multi-Warehouse API

As businesses expand into new markets and open physical stores, supply chains and logistics become much more complex. Without the right tools to manage the many moving parts, orders can get lost, and stock issues start to pile up.

Medusa already enables great integrations with OMS and IMS systems. But we are now adding a more sophisticated inventory layer that allows Medusa to support businesses with multiple distribution centers or retail stores natively.

Merchants can manage inventory across locations within Medusa and connect locations to sales channels to control stock availability. Furthermore, we will introduce allocations to ensure safety stock and avoid overselling. This will give merchants a clear picture of their inventory at any given point.

The new feature will enable a wide range of new experiences for customers, such as buy-online-pick-up-in-store or reserve-online-try-in-store flows. Developers will also get an excellent new API that can be used to optimize fulfillment, build POS experiences, and further push the boundaries of what can be done within digital commerce.

Payment Processor API

One of Medusa’s core strengths is its composable architecture, which allows integrating it with the best-in-breed tools that accelerate ecommerce growth.

From the beginning, offering the best payment option to your customers at any time has been a core feature of Medusa. Medusa already allows merchants to attach as many payment processors — such as Stripe, PayPal, and Klarna — as they want and, with powerful multi-regional logic, control which options are shown to the customer at checkout.

With our new Payment Processor API, we will unlock even more capabilities and make it easier for plugin developers to create integrations with payment processors worldwide.

Simultaneously, the new Payment Processor API will enable better support for RMA flows requiring payments. We recently released Order Editing, which allows merchants to modify orders after they have been placed.

Edits can result in discrepancies between the order total and paid total, and with the new Payment Processor API, we are making it simpler to collect payments for differences.

Nested Categories

Medusa currently allows merchants to organize their products by Collections to be used in storefronts or for internal business logic. For example, they can be used for controlling whether discounts can be applied to a group of products.

In the near future, we will introduce an additional way to manage your product hierarchy and create better experiences for your customers. Nested Categories will allow you to define category hierarchies like Women’s > Bottoms > Skirts to better organize product navigation on storefronts.

Furthermore, adding the same product to multiple categories will be possible, enabling better merchandising functionality right within the Medusa dashboard.

As always with Medusa, you own your data and can extend and customize the behavior of our APIs. This is also the case with Nested Categories, enabling developers to create enhanced search and browsing experiences while adding a new, powerful reporting dimension to your product catalog.

EventBus Modules

Medusa emits hundreds of events that plugins use to send transactional emails, automate tedious tasks, and reliably integrate systems in your stack.

The existing event system uses Redis with BullMQ to enable Pub/Sub functionality. Many larger Medusa implementations will, however, already have an event architecture in place.

With the new EventBus Modules, it will be possible to integrate your existing events architecture directly into Medusa.

This will enable new EventBus providers like RabbitMQ, Kafka, or Amazon SQS, and improve Medusa’s compatibility with microservice architectures.

Automated API specs and typing

Medusa’s API reference is automated to ensure that the documentation is always up-to-date with the core API. As part of our dedication to improving our documentation, we are enhancing how we document the API with code and simultaneously creating new automations to generate our client library.

This will remove inconsistencies between server logic, documentation, and client library support.

We will, furthermore, be able to eliminate the current dependency on @medusajs/medusa in our client library, which will help reduce the bundle size of storefront implementations.

Medusa Admin extensibility

One of Medusa’s principles is to build strong defaults that make it quick and easy to get started, and simultaneously offer a fantastic developer experience that enables customizations and extensions to make Medusa your bespoke commerce engine.

We have followed that principle diligently in our backend implementations until now. But our Admin dashboard has long been more locked and harder to customize. We are prioritizing changing that very soon.

Our first step will be to move our admin dashboard to an NPM package that can spin up with your Medusa server. This will improve the developer experience when building with Medusa, as you will no longer have to clone the admin project, merge updates, or start it separately from your Medusa server.

Additionally, we will follow semantic versioning of the admin package to avoid version mismatches between the admin application and the core medusa package.

The next step hereafter will open up extension areas in the admin dashboard to add custom UI elements like buttons, cards, or entire pages. Custom elements can be created in your local project or shipped with plugins to package server and admin functionality easily.

Conclusion

As mentioned earlier, this Roadmap overview includes only the features we started implementing. There are more upcoming features and enhancements in our Roadmap, which you can check out in our GitHub Discussions.

What features are you excited for? And what features do you think we should include in our Roadmap?

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

What's new? - Medusa v1.2

Oliver Juhl — Mon, 28 Feb 2022 17:27:57 +0000

Features and fixes included in the release of v.1.2 of Medusa and Medusa Admin. The larger issues/tickets built in this release will be highlighted with a small detailed description.

For the full changelog see, go here.

Release highlights

Tax API

The Tax API allows you to configure your store to charge taxes from your customers to be in compliance with tax regulations in the markets you operate in. Tax regulations differ a lot across countries so Medusa’s tax system gives you a number of possibilities for configuring your taxes to ensure that you charge your customers the correct amount of tax.

You configure taxes on a region-basis meaning you can use different tax settings based on where customers are shopping from. Each region may use one of two tax modes:

Automatic Taxes
Tax totals are computed automatically on every cart update and retrieval. This is the default tax mode.
Manual Taxes
Tax totals have to be manually computed by calling POST /store/carts/:id/taxes. This mode is more appropriate for tax configurations that use a plugin that calls 3rd party APIs. By using manual tax calculations you avoid 3rd party calls as part of the usual retrieval of carts.

The process for computing the tax total is the same regardless of the mode used. The steps taken are outlined in the figure below

A more elaborate walkthrough of the Tax API will soon be published to our documentation.

Strategies

The new strategy pattern allows you to override core logic in Medusa in cases where such overrides are necessary. For example, if a merchant wants to apply custom logic when generating line items in a cart; a strategy can be overridden to accommodate this. Check out the first two implementations of the strategy pattern:

CustomerGroup

This release introduces a notion of a CustomerGroup, which is the first element of our Promotions API. The feature allows you to group customers together and will play a key part in adding more advanced promotions, since you will be able to define discounts for entire customer groups ultimately allowing you to support VIP segments, wholesale customers, and much more.

CustomerGroup
- id: string
- name: string
- customers: Customer[]

Read our discussion on the Promotions API and feel free to pitch in with feedback and / or input.

Global search

Global search has been added to Medusa Admin meaning that you will be able to search for Discounts, Orders, Customers, and GiftCards from anywhere in your admin system. The feature is the ultimate productivity booster for store managers and customer service by allowing you to navigate to an order with as little as three clicks; 1) open search (with keyboard shortcuts), 2) paste order number, 3) press enter.

Check out a small gif below.

Add error handler in `atomicPhase_` to allow clean up when transactions fail

Introduce a new way of gracefully handling errors in our atomic phases by adding an error handler param to the atomicPhase_. The case to solve for is when work is performed within a transaction, but the transactions fail and cleanup is needed.

Read more about the feature and what is solved for in the pull request.

What’s next?

Introducing customer groups was the first step towards building the Promotions API, and the focus next will be to refactor our discount rules to be much more advanced, such that you can create discounts per product type, tag and collection as well as customer groups.

Additionally, the MoneyAmount entity will be extended to allow for advanced pricelists meaning you will be able to define variant prices per customer, add a MoneyAmount type, and more.

Stay tuned on our Discord or via our webpage!

Building an open-source extendable dashboard in Gatsby

Oliver Juhl — Mon, 20 Dec 2021 17:52:12 +0000

Introduction

At Medusa, we’ve recently started rethinking our admin. We strive to create the best possible developer experience, but when it comes to the admin system, user experience is just as important - and we’ve been slightly neglective of that. This is about to change.

The first cut of the sod towards a better and more user-friendly admin system is a complete design revamp. The revamp will not only include a better and visually enhanced user interface, but also a new styling framework. We’ve started the work last week and expect to release a new and improved Medusa Admin in late January. Let’s have a look at what’s in store.

Facelift
The biggest item on the agenda is undoubtedly a complete makeover of the admin user interface. We’ve recently onboarded our new Head of Design, Ludvig, who’s gonna rebuild the design from scratch. We are gonna keep all current workflows and domain structures intact and only focus on improving the look and feel.

Here’s a small sneak peek:

TailwindCSS
Up until now, we’ve been using the combination of Rebass and Emotion to build and style our components, but this is also about to change. We’ve spent quite some time investigating the many different options out there and have chosen to go with TailwindCSS. This is due to the fact, that Tailwind is a highly adapted framework with a huge community behind it, guaranteeing us future support and opening up for potentially more community contributions to Medusa Admin.

React hooks
As part of the latest release, we introduced medusa-react; a new React library providing a set of hooks (among other things) for interacting seamlessly with a Medusa backend. The hooks currently support our Store API but will very soon include the Admin API as well. We will integrate this set of hooks into the revamped version of Medusa Admin, which will fix a lot of smaller issues in our current API consumption and improve the developer experience by being more intuitive and easy to use.

See WIP here.

Versioning
The current process for having an up-to-date admin system is quite cumbersome. It requires you to pull the upstream changes from our project into your cloned repository. To allow for a more seamless workflow, we will add a new way of versioning your admin system. Going forward, we will ship Medusa Admin as a Gatsby theme, and the admin project that is created for you (unless you choose to clone) will be a barebones Gatsby project with said theme installed. This allows you to incorporate new changes by simply upgrading your Medusa Admin Gatsby theme.

Extendability
As part of shipping Medusa Admin as a Gatsby theme, we are able to provide you with a range of new theming tools to customize and improve your own admin project. One of the more important concepts in the toolbox is Component Shadowing, which allows you to override components in the core admin project thereby making it possible to extend pages and components with custom logic and UI.

See example here.

We are very excited about this new and improved Medusa Admin and are looking forward to presenting it to you all in January - you can sign up for the PH launch of it here. If you have questions or suggestions, you are more than welcome to reach out to us in our community.

Open-source Node.js commerce engine for Strapi

Oliver Juhl — Mon, 15 Nov 2021 15:04:12 +0000

Use Medusa and Strapi to power your commerce setup for a full open-source headless solution. In recent years, it has become increasingly popular to go with a headless approach when building ecommerce, blogs, portfolios, and the likes. Among many benefits, you get improved performance, more customizability, and support to scale as your business grows.

A headless system is essentially a decoupling of presentational layers and backend. It cuts off the traditional proprietary frontend displaying your content (hence the name), and instead gives you Rest APIs, you can consume from whatever system, client, or service you would like.

Going with the headless approach when building your setup will provide you with a modular system with best-in-breed services within each specific area of your stack; CMS, ecommerce, etc. This is in contrast to how you would traditionally choose a monolithic platform that partly (or hardly) caters to all of your needs.

This article will guide you through setting up a headless ecommerce setup in which content is managed by Strapi and the ecommerce is powered by Medusa - on a 100% open-source stack.

Why Medusa, and why Strapi?

The bottleneck of headless ecommerce systems is most often the amount of resources it requires to both get started and to maintain. You need backend developers to handle your infrastructure and integrations and frontend developers to build the customer experience. This is one of the reasons many existing headless solutions target enterprise businesses. To allow for small to mid-sized businesses to enter the space, one must cater to the developer experience. If the onboarding, setup, and implementation process are all easy to approach, you no longer need a team of ten to build a scalable ecommerce setup.

Strapi and Medusa are two systems built primarily for developers and the combination of the two enables you to build an ecommerce store with a blazingly fast, content-rich frontend and a highly extendable backend.

Both projects are open-source, headless, and built with Node.js. They use a very similar architecture for plugins and customizations, that gives you the ability to extend your commerce and CMS to fit exactly your needs. Let's now dive into the installation and setup of the two.

Installation

The following guide for setting up the plugin assumes, that you are familiar with both Strapi and Medusa. If this is not the case, visit the official Medusa and Strapi documentation.

Setting up Medusa

First, create a Medusa project using your favorite package manager. You can go about this in two ways:

Use npx
npx create-medusa-app will allow you to create a Medusa store engine, a storefront, and Medusa admin in a single command

# using npx
npx create-medusa-app

# using yarn
yarn create medusa-app

When choosing npx you are shown different store engine options as part of the setup. For this Strapi tutorial, you should choose medusa-starter-default. Optionally, pick a storefront.

Use medusa-cli
@medusajs/medusa-cli is our Command Line Tool for creating the Medusa store engine (alongside many other powerful commands). Use it as such:

# using yarn
yarn global add @medusajs/medusa-cli

# using npm
npm install -g @medusajs/medusa-cli

# initialise a Medusa project
medusa new my-medusa-store

Medusa uses Redis for emitting events in the system, so ensure, that this is installed and running

$ redis-cli
127.0.0.1:6379> ping
PONG

And in medusa-config.js you should enable it. Your project config in the bottom of the file should look similar to this:

projectConfig: {
  redis_url: REDIS_URL,
  database_database: "./medusa-db.sql",
  database_type: "sqlite",
  store_cors: STORE_CORS,
  admin_cors: ADMIN_CORS,
},

Additionally, add Strapi to your list of plugins:

{
  resolve: `medusa-plugin-strapi`,
  options: {
    strapi_medusa_user: 'medusa_user',
    strapi_medusa_password: 'medusaPassword1',
    strapi_url: '127.0.0.1',
    strapi_port: '1337'
  }
}

And finally, install the plugin using your package manager:

#using yarn
yarn add medusa-plugin-strapi

# using npm
npm install medusa-plugin-strapi

You've now successfully installed and configured your Medusa store engine. Seed it with data and start it up by running:

# using npm
npm run seed && npm start

# using yarn
yarn seed && yarn start

We'll now turn to the Strapi side of things.

Setting up Strapi

Similar to how you installed Medusa, you can install Strapi using your favorite package manager. Use the strapi-medusa-template to create your project. The template is a custom Strapi implementation required for the two systems to work together.

# using npx
npx create-strapi-app strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git

# using yarn
yarn create strapi-app strapi-medusa --template https://github.com/Deathwish98/strapi-medusa-template.git

After running the command, you have a full Strapi project configured to synchronize with Medusa. Upon the initial start of the Strapi server, all the required models will be created. They will correlate with models from Medusa to allow for two-way synchronization.

Note: The Strapi template starter uses SQLite as the default database. There is a known bug related to knex.js that comes from multiple write connections. Restarting the Strapi server should make the error disappear.

Synchronization

The power of using Strapi with Medusa comes from two-way synchronization. Strapi allows you to enrich your products with extra fields and data, such that you can perfect the customer experience. But for the products to appear in Strapi, you are required to create them in Medusa. For the commerce logic in your presentational layer to function properly, you need the Medusa IDs of products and variants. This is used for operations like adding to cart and going through the checkout flow.

When products are created in Medusa, the two-way communication ensures that data is kept consistent between the two systems. Though only some fields are synchronized and those are:

Product: title, subtitle, description, handle
Variants: title
Region: name

Further down the road, the support for synchronizing more entities is expected to be introduced

Using Postgres in Medusa (optional)

For Postgres to function, you need to create a local database. One way of doing this would be to use your terminal:

createdb medusa-store

Depending on what system you are on and how your local Postgres is configured, the above command might fail. In that case, please investigate the correct way to create a local database on your pc.

Navigate to your newly created Medusa project (<project name>/backend if you used npx). In medusa-config.js, ensure that you have Redis and Postgres enabled. The project configurations at the bottom of the file should look similar to this:

projectConfig: {
  redis_url: REDIS_URL,
  database_url: DATABASE_URL,
  database_type: "postgres",
  store_cors: STORE_CORS,
  admin_cors: ADMIN_CORS,
},

Note: the DATABASE_URL variable should use the Postgres database created in the previous step

Summary and next steps

You are now provided with the toolbox for creating amazing digital commerce experiences on top of a highly extendable CMS system and ecommerce platform.

To quickly get started, see our starters for:

GatsbyJS (much more feature-rich V2 coming soon)
NextJS

A big thanks to community member Pawan Sharma (Deathwish98) for leading the implementation of this integration with Strapi. If you want to be part of the Medusa community, feel free to join us on our Discord channel.

Composable commerce: Switch parts of your stack in seconds

Oliver Juhl — Fri, 12 Nov 2021 14:27:54 +0000

We recently launched our sophisticated Medusa Search API. It allows you to add a blazingly fast product search to your ecommerce setup, improving the overall customer experience and your conversion rates.

From a developer perspective, the Search API unifies communication between Medusa and search engines thereby allowing you to switch between different engines in seconds with only a couple of lines of code. So far, Medusa has only supported product search using MeiliSearch, but we can now proudly present a plugin for Algolia - one of the giants.

The purpose of this article is to show you how to install and configure Algolia for your Medusa store. Additionally, we'll showcase the powerful Search API by guiding you through changing from one search engine to another.

Installation

Create an account on Algolia and grab your Application ID and Admin API Key from the settings panel.

In your Medusa project, install the plugin using your favourite package manager:

yarn add medusa-plugin-algolia@canary

// or

npm install medusa-plugin-algolia@canary

In your medusa-config.js add the integration to the array of plugins with the following settings:

const plugins = [
  // ...other plugins
  {
    resolve: `medusa-plugin-algolia`,
    options: {
      application_id: "your-application-id",
      admin_api_key: "your-admin-api-key",
      settings: {
        products: {
          searchableAttributes: [
            "title",
            "description",
          ],
          attributesToRetrieve: [
            "id",
            "title",
            "description",
            "handle",
            "thumbnail",
            "variants",
            "variant_sku",
            "options",
            "collection_title",
            "collection_handle",
            "images",
          ],
        },
      },
    },
  },
];

In the above config, you've provided the id and key from Algolia alongside a couple of settings, that define the properties you can search for and the values you'll get in return.

And that's all! You've now enabled Algolia for your Medusa store engine. The plugin will make sure to synchronize products from Medusa to Algolia upon updating, deleting, or creating new ones. Now all you need to do is to restart your server.

Usage

This article will not go too much into depth about how the search functionality works under the hood when querying the API. We refer to the previous article on MeiliSearch if this is of your interest. In there, you will find a quick showcase using Postman as well as a thorough walkthrough of how you can display the results in your storefront using ReactJS (GatsbyJS).

Instead, to illustrate the power of our Search API and search engine plugins, we'll switch out a MeiliSearch plugin with our new Algolia plugin in a store with existing products. Upon restarting the server with the new configuration, your products will automatically be fed into Algolia and the search functionality in your frontend will remain unchanged.

Next up

As mentioned in our post on MeiliSearch, we'll soon publish an article with a thorough walkthrough of our Search API. Until then, you should consider adding blazingly fast product search with one of our plugins to allow for your commerce business to grow to the next level.

Many thanks to community member Rolwin for building the plugin. If you want to be part of the Medusa community, feel free to join us on our Discord channel.

Good first issues for Hacktoberfest

Oliver Juhl — Thu, 07 Oct 2021 16:37:14 +0000

As mentioned in our previous article, Medusa is participating in Hacktoberfest for the first time this year and the excitement is high.

Getting started

There are loads of issues out there for developers to pick up, but it's not always easy to figure out where to start. We've made a series of good first issues that includes both a video tutorial and a checklist, such that you can easily get started building in public.

API fixture generation

The issues chosen for the series deal with API fixture generation. Currently, our fixtures are all stored within the same file, which is suboptimal due to 1) loading large files on the client (our API reference) is bad for performance and user experience and 2) referencing a single fixture in such a large file requires us to look for a needle in a haystack.

The goal is to split each fixture into their own dedicated file making them lightweight and easy to reference.

The issues can be found filtering on label api-fixture, or use this link for easy access.

How-to

To easily get started use the following checklist:

checkout docs/api
branch out to docs/api-[ns]-[endpoint]
if necessary clear dist and run yarn bootstrap
cd integration-tests/docs
yarn && yarn build
medusa-dev --scan-once
Open __tests__/[ns].js
Import from ../test-input/[ns]/[endpoint]
Add test to the toTest array
yarn test --watch __tests__/[ns].js -t [operationId]
Make changes
Make sure that snapshots are correctly defined so that tests pass across two runs
Only add the fixtures and test changes related to your generated fixtures
Push and open PR against docs/api

Additionally, you can watch this video tutorial
explaining the hows and whys narrated by co-founder Sebastian.

If you encounter issues, reach out to the community on Discord or submit them to our Github issue board.

Deploying Medusa on Qovery for a 100% open-source ecommerce stack

Oliver Juhl — Wed, 06 Oct 2021 14:03:24 +0000

This is a guide for deploying a Medusa project to Qovery. Qovery is a Continuous Deployment Platform, that provides you with the developer experience of Heroku on top of your cloud provider (e.g. AWS, DigitalOcean).

It is assumed, that you are currently running a local instance of Medusa. If not, check out our Quickstart or use npx create-medusa-app to set up your application in a matter of minutes. For the latter, see this guide for a small walkthrough.

1. Qovery Console

Create an account on Qovery on their free community plan and jump into the console.

2. Setup

Create a project and an environment.

3. Add your Medusa app

Add a new app to your Qovery environment and connect the Git repository that holds your Medusa project. In your application settings, set the port to 9000 unless something else is specified in your setup.

If you used our npx starter, your repository will most likely hold all components; storefront, admin and backend. Ensure that Root application path in Qovery is pointing to your Medusa project (/backend).

4. Add a database

Navigate to your environment overview and add the databases required by Medusa.

Add Postgres database version 10, 11 or 12
Add Redis database version 5 or 6

5. Configure Medusa

Our Medusa project needs a bit of configuration to fit the needs of Qovery.

Update `medusa-config.js`

First, add the Postgres and Redis database url to your medusa-config.js. In Qovery, click on your Medusa app in the environment overview. Navigate to environment variables in the sidebar on the left. Among the secret variables you should find your database urls. They should look something like this:

QOVERY_REDIS_123456789_DATABASE_URL
QOVERY_POSTGRESQL_123456789_DATABASE_URL

Add these to your medusa-config.js.

const DATABASE_URL = process.env.QOVERY_POSTGRESQL_123456789_DATABASE_URL
const REDIS_URL= process.env.QOVERY_REDIS_123456789_DATABASE_URL

Furthermore, update module.exports to include the following:

module.exports = {
  projectConfig: {
    redis_url: REDIS_URL,
    database_url: DATABASE_URL,
    database_type: "postgres",
    store_cors: STORE_CORS,
    admin_cors: ADMIN_CORS,
    database_extra: { }
  },
  plugins,
};

IMPORTANT: We are using the Qovery community plan, that does not allow SSL connections for the database, so this is disabled.

In a production environment, you would need the following in the config:
database_extra: { ssl: { rejectUnauthorized: false } }

Add some extra variables

We need to add a couple of more environment variables in Qovery. Add the following variables in your Console with an application scope:

JTW_SECRET=something_secret_jwt
COOKIE_SECRET=something_secret_cookie

Make sure to use actual secrets in a production environment.

Update `package.json`

Update scripts to the following:

"scripts": {
    "serve": "medusa start",
    "start": "medusa migrations run && medusa start",
    "prepare": "npm run build",
    "build": "babel src -d dist --extensions \".ts,.js\""
  },

6. Deploy Medusa

Finally, deploy your Redis and Postgres followed by your Medusa application.

Deploy databases

In your environment overview in Qovery, deploy your databases one after the other. Only when these are deployed, proceed to next step.

Push changes to your repository

To initialise your first build Qovery, simply commit and push your changes.

git add .
git commit -m "chore: Qovery setup"
git push origin main

6. Try it out!

In Qovery, click on your Medusa app in the environment overview. In the top right you are able to open up your application. Navigate to /health to ensure, that the app is running.

What's next?

You now have an application running on Qovery. This can be scaled and configured to fit your business needs. As mentioned, we used the community plan, so this should be upgraded when moving to production.

Furthermore, you can deploy Medusa Admin for your application, such that you can start managing your store from an interface.

Deploy Admin on Netlify
Deploy Admin on Gatsby Cloud (Coming soon)

Explore our Github or join our community

DEV Community: Oliver Juhl

Designing a Git-Like Flow in Ecommerce APIs

Understanding Order Editing

Building an API with git-like flow of events

Design

Limitations to the analogy

Demo

Conclusion

January 2023 - A glimpse into our roadmap

Planning our Roadmap

Select Features From Our 2023 Roadmap

Multi-Warehouse API

Payment Processor API

Nested Categories

EventBus Modules

Automated API specs and typing

Medusa Admin extensibility

Conclusion

What's new? - Medusa v1.2

Release highlights

Tax API

Strategies

CustomerGroup

Global search

Add error handler in atomicPhase_ to allow clean up when transactions fail

What’s next?

Building an open-source extendable dashboard in Gatsby

Introduction

Open-source Node.js commerce engine for Strapi

Why Medusa, and why Strapi?

Installation

Setting up Medusa

Setting up Strapi

Summary and next steps

Composable commerce: Switch parts of your stack in seconds

Good first issues for Hacktoberfest

Getting started

API fixture generation

How-to

Deploying Medusa on Qovery for a 100% open-source ecommerce stack

1. Qovery Console

2. Setup

3. Add your Medusa app

4. Add a database

5. Configure Medusa

Update medusa-config.js

Add some extra variables

Update package.json

6. Deploy Medusa

Deploy databases

Push changes to your repository

6. Try it out!

What's next?

Add error handler in `atomicPhase_` to allow clean up when transactions fail

Update `medusa-config.js`

Update `package.json`