Company

Medusa v1.3.3: BatchJob API, Advanced Next.js Storefront, Feature Flags, and More!

Jul 07, 2022 by

Shahed Nasser

We have released a new version of the Medusa Core, Medusa Admin, an advanced Next.js Starter, and more!

This week we released a new version of Medusa!

Version

Copy to clipboard
1.3.3

brings new features and enhancements including BatchJob API, Import API, Feature Flags, and more!

Along with this new release, we have released a new version of the Medusa Admin, released an advanced Next.js Starter, and further updated and enhanced our documentation.

Keep reading below to learn more about the new features and what upcoming features you can expect from Medusa.

Features

BatchJob API

The addition of the BatchJob API opens the door for new features in this release and future releases.

The purpose of this API is to allow users to upload and export batches of data in Medusa asynchronously. For example, users can export products as CSV files or import products from CSV files.

This feature includes the addition of the necessary services and interfaces to allow a seamless experience while handling batch jobs in your Medusa server.

Depending on the batch job’s type, a strategy is implemented to handle the job. For example, when the user requests to export products, the

Copy to clipboard
ProductExportStrategy

is used to handle it.

These strategies are also extendable and customizable. Developers can override it by creating a file in the Medusa server under

Copy to clipboard
src/strategies

that extends the

Copy to clipboard
AbstractBatchJobStrategy

abstract class.

A BatchJob can be created by sending a

Copy to clipboard
post

request to

Copy to clipboard
/admin/batch-jobs

and setting the

Copy to clipboard
type

in the body of the request. The strategy associated with the

Copy to clipboard
type

will be used.

Import/Export API

Following the implementation of the BatchJob API, the Import/Export API was possible to implement within Medusa. This API would implement the strategies needed to import or export different domains within Medusa.

In this release, two strategies were implemented that allow exporting products and orders. Future releases would allow the import of products, as well as the import and export of different domains within Medusa.

Product Export

Using the new Import/Export API, you can export products into a CSV file. This is done by sending a

Copy to clipboard
POST

request to

Copy to clipboard
/admin/batch-jobs

and in the body of the request set

Copy to clipboard
type

Copy to clipboard
product-export

You can also filter the products you want to export instead of exporting all products. This is an example of a request for a product export with filters:

{
  "type": "product-export",
  "context": {
    "filterable_fields": {
      "title": "Test export product",
    },
  },
}

Order Export

Similarly, you can export orders on your Medusa server into a CSV file. You can do that by sending a

Copy to clipboard
POST

request to

Copy to clipboard
/admin/batch-jobs

and in the body of the request set

Copy to clipboard
type

Copy to clipboard
order-export

You can also filter the orders you want to export instead of exporting all orders. This is an example of a request for an order export with filters:

{
  "type": "order-export",
  "context": {
    "filterable_fields": {
      "email": "test@email.com",
    },
  },
}

Feature Flags

Feature flags are used to disable features that are still under development and testing. This will help us increase the frequency of releases of Medusa’s core as we’ll be able to disable any features that are still not ready for use in a production environment.

Feature flags are files created under

Copy to clipboard
src/loaders/feature-flags/*.ts

. Each feature flag has a key, the name of an environment variable that controls whether the feature is turned on or not, a default value, and a description. For example:

export default {
  key: "key",
  description: "description",
  env_key: "MEDUSA_FF_ENV_KEY",
  default_val: false,
}

Features can be enabled or disabled either by setting the environment variable associated with the feature or setting the flag in the

Copy to clipboard
medusa-config.js

file under

Copy to clipboard
configMudle.featureFlags.<feature_key>

. By default, it will have the value defined in the feature flag file.

To use feature flags, we’ve added helper classes, decorators, and middleware to check whether a feature is enabled or not.

For example, to enable an API endpoint only if a feature is enabled you can use the

Copy to clipboard
featureFlagEnabled

middleware:

app.use("/batch-jobs", featureFlagEnabled("test_flag"), route)

Another example is using the

Copy to clipboard
FlagRouter

in a service to determine whether a feature is enabled or not:

//inject dependency in constructor
constructor({ featureFlagRouter }) {
  this.featureFlagRouter = featureFlagRouter
}

myMethod() {
  if (this.featureFlagRouter.featureIsEnabled("flag_1")) {
    // do flag 1 stuff
  }
}

Feature flags can be used throughout the Medusa server including migrations and models.

Other

In the GitHub repository, we’ve moved from using Lerna to Turborepo as Lerna is no longer actively maintained. This move will improve build and test time locally and in the CI pipeline of the repository.

Additionally, we’ve removed the

Copy to clipboard
mongoose

and

Copy to clipboard
mongodb

dependencies from the core

Copy to clipboard
medusa

package as they are no longer in use.

How to Update Your Medusa Server?

To update your Medusa server, first, update the Medusa packages in your dependencies:

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

Then, run migrations with Medusa’s CLI tool:

medusa migrations run

Medusa Admin New Features

Product/Order Export

Following the addition of the Import/Export API, you can now export products and orders from your Medusa Admin.

You can create a new export by clicking the “Export Products” button on the Products page, or the “Export Orders” button on the Orders page. This creates a new export batch job to export your products or orders into CSV files.

In upcoming releases, we’ll add the UI to filter the products and orders to export.

Activity Drawer

Clicking the notification bell icon in the top right of the navigation bar now opens an Activity Drawer. This Activity Drawer will contain important notifications for the admin user.

In this release, only the list of batch jobs will be available in the Activity Drawer where users can track the status of export jobs they started or download finished batch jobs.

The Activity Drawer uses a new

Copy to clipboard
PollingContext

that listens to everything related to batch jobs including their creation, updates in their status, and more.

How to Update Medusa Admin

You can update your Medusa admin by pulling new changes from the Medusa Admin repository into your Medusa Admin.

New Next.js Storefront

We previously had a starter Next.js storefront with limited functionalities to help developers interested in using Next.js for their storefront get a head start.

This week, we’ve released a new Next.js storefront with advanced features and a sleek, modern design. The new Next.js storefront includes features that were previously implemented including product listing and a checkout flow.

Additionally, this storefront includes full implementation of customer profile, support for payment Stripe and PayPal payment providers, and support for search with either MeiliSearch or Algolia.

Documentation

Since the last release, we’ve improved our documentation to include more helpful guides to assist you while developing with Medusa including:

A new CLI reference that you can refer to when using Medusa’s CLI tool.
Added a “Configure your Server” documentation with a full list of available configurations you can use when configuring your Medusa server.
Improved and updated deployment guides including deploying the server to Heroku, Admin to Netlify, and Gatsby to Netlify. We’ve also added a new “Deploy to Heroku” button that you can use to instantly deploy a Medusa server on Heroku.
Added documentation for the PayPal plugin with details related to the server, admin, and storefront setup.
Added new documentation to learn how to implement the checkout flow in your storefront.

Upcoming Features

Sales Channels API

In the

Copy to clipboard
1.3.1

release newsletter, we mentioned that we are planning the Sales Channel API feature. In this quarter, we kickstart the development of the Sales Channels API.

Sales Channels will allow merchants to sell across multiple channels such as mobile apps or the Amazon marketplace. This will additionally make it possible to differentiate between the channels and ultimately provide rules and conditions specific to each channel.

Product Import

After implementing the export feature for this release, we’ll work on the import feature. This will allow users to import products stored in CSV files into their Medusa server. With both Import and Export functionalities available, migrating data from one Medusa server to another will be much easier.