DEV Community: Carlos Padilla

Efficient File Naming Systems for Better File Management

Carlos Padilla — Tue, 06 Jun 2023 14:59:46 +0000

Introduction

We have all encountered this situation: you need to find the latest version of a document. Upon accessing the shared directory, you cannot identify the correct document version for review. You open the folder and discover a file list resembling the following:

Brochure-season2022-George-edits-finalfinal.doc
Brochure-season2022-final-Helen_edits_v4.doc
FINAL_brochure_december2023_cap-updated.doc

In today's fast-paced world, we often struggle to locate the most recent version of a document amidst a sea of poorly named files.

This common issue highlights the importance of maintaining a well-structured filing system for various file types and the challenges and frustrations of an unorganized file system.

By adhering to proper file naming conventions, we can significantly enhance the efficiency and effectiveness of any workflow.

tl;dr

Efficient file naming systems improve file organization and retrieval using descriptive names, metadata, and consistent conventions. To create an effective system, determine its purpose, choose an approach, and follow standard patterns like using information blocks, abbreviating repetitive parameters, formatting dates, and implementing version control. Document the system and train team members to ensure consistent usage.

What is a file naming system?

A file-naming system (FNS) is a framework with guidelines employed to consistently and systematically name and organize files. Its main goal is to help users to manage, identify and locate files in a computer system or storage device easily and quickly.

A well-designed FNS typically includes elements such as descriptive names, metadata, dates, or other information blocks that follow a consistent convention.

FNS can and should be customized to meet specific requirements, depending on the type of users or teams utilizing them. For instance, a file naming system for personal file management will significantly differ from one designed for a business project organization or a university research department.

Why an efficient file naming systems matters

The following are some of the benefits you get by using an effective file naming system:

An efficient file naming system enables swift retrieval by leveraging names or relevant keywords.
A descriptive file name provides helpful information about the content or purpose of the file without opening it.
A practical file naming system implements consistent methodologies and structures for designating files. This uniformity fosters coherence across various projects or within an organization, facilitating comprehension and adherence to the system for everyone involved.

What is an information block in a file naming system?

File naming systems use information blocks to establish the structure of file names and folders.

An information block or parameter is a word or phrase that provides sufficient information to describe a file based on that information. For instance, take the following file name:

20230131-FinanceReportIncome-histogram.png

From it, we could say it has four information blocks:

20230131 -> date
FinanceReportIncome -> type of document
histogram -> content type
.png -> file extension

With these parameters, we can infer the file is an image with a histogram representing the finance report income from the first month of 2023.

Designing an efficient file naming system

Designing an effective file naming system requires time and effort. This task can be easy or complex, depending on the primary purpose of the FNS.

For instance, designing an FNS to manage all the images of a photoshoot could be considered easier than defining an FNS to manage all the project files on a design agency.

In the first example, one person can quickly develop an efficient file naming system, resulting in a straightforward and understandable naming structure.

On the other hand, a more elaborate system is necessary for a design agency, necessitating all employees' collaboration to ensure everyone understands and adheres to the established conventions.

The subsequent recommendations guide establishing rules and conventions within your FNS.

It is important to note that not all suggestions may apply to every scenario. Therefore, the FNS designer must exercise discretion in determining which guidelines to implement and which to skip or modify to fit its use case.

What is the file naming system for?

The first thing to do before initiating the design of an FNS is to define its intended purpose. Establishing a clear objective for the FNS will significantly facilitate determining and implementing appropriate rules and conventions.

Answering the following questions can help you to define the FNS purpose:

How will you look for and order the files? When searching for a file, the keywords entered in the search field will differ based on the specific file type you are looking for. For example, one might search using the project's name to locate a file related to a particular project. On the other hand, if the objective is to retrieve a financial report from the previous month, it would be more appropriate to input a date in the search field followed by the "finance report" words.
Which files include the file set that you will work with? This question is connected to the previous one, as the types of files within the set will determine the most effective search method or file organization strategy. For instance, a collection of files from an academic institution's research department may benefit from being organized by the research department rather than chronologically. In such cases, searching for the project's researcher could facilitate retrieving a specific file.
Which information, such as categories and metadata, can be inferred from the file set? These pieces of information help understand the type of files included in the set and assist in determining which parameters should consist of the file names.

What approach should we use?

Once the goal of the FNS is clear, the next step is to define which approach we should use. When it comes to techniques, we could limit two of them.

One method is to define de FNS based on a folder structure. This approach has the following benefits:

It can keep file names short because each directory in the folder structure gets its name from a parameter.
Files can be separated or grouped by categories.
If the file set is too big, we can divide the categories into subcategories or use metadata to group files.

This approach also comes with some drawbacks:

If a file is shared with someone else by email, all the file context delegated to the folders where it belongs is lost.
Managing folders can get very complex and tricky quickly.
Deleting a folder by accident will result in losing all its files.

The other way is to use file name patterns by using well-defined blocks of information. With this approach, we get some advantages:

We avoid the drawbacks of the folder structure approach. For instance, we don't need to deal with many folders; accidentally deleting one file won't be that bad.
Searching by metadata will filter all the files belonging to the keywords used so we get the related files in the same search.

The downside of this will be that, at some point, using many parameters to name files will result in lengthy and difficult-to-read file names.

Standard and general conventions to follow

The subsequent recommendations outline essential guidelines that every FNS should stick to. These principles have significantly contributed to the organization and efficiency of multiple files and folders in daily operations.

Identify and define the information blocks

Ensure the inclusion of adequate metadata to facilitate seamless identification and retrieval of each file, customized to meet the unique demands for efficient access. Consider incorporating the following information blocks as foundational elements:

Name of the business, institution, or project
Document Type
Date or period
Document language
Content Category
Location
Initials for the author, reviewer, editor, or any person working with the file
Version
Document state (draft, reviewing, editing, publish)

It is crucial to balance providing sufficient parameters for effortless identification and retrieval while avoiding excessive complexity.

Determine the sequence of the metadata

As computers organize files alphabetically by name, it is essential to prioritize the most critical information. For example, if you access invoices by the date they were issued, it will make more sense for the date to be the first piece of metadata.

Ensure all the information blocks offer enough information for easy identification. You can also consider ordering the parameters by putting first general information blocks and then parameters with more specific information.

For instance, a sequence of metadata for a photographer may include the following parameters in the given order:

[YYYYMMDD]_[Place]_[Subject of image]_[unique number].[file extension]

Abbreviate repetitive and lengthy parameters

It's common to find FNS that use information blocks repetitively along the system. Sometimes the block is short enough that you can't reduce the file length.

However, there are cases where these blocks are long or are composed of several words. You could make codes or define acronyms to identify those blocks in such cases.

Try to keep these codes short, with three or four letters at most, and remember to write these abbreviations so anyone using the system can know what each parameter means.

Use underscores or hyphens to delimit metadata

Underscores and hyphens are visually ergonomic and widely accepted on file names for delimiting words.

Avoid spaces, as some computer systems may not function properly with them, and desist from using special characters such as "! # $ % & ' @ ^ ` ~, +; = ( ) [ ] { }" that could cause visual confusion or awkwardness.

Alternatively, you can write the information blocks as CamelCase; this is an efficient way of differentiating words but offers less readability.

Format dates to follow a chronological order

Dates should follow a standard date format such as year-month-day, for example, YYYYMMDD or YYMMDD, to guarantee the appropriate chronological arrangement of files.

In rare cases, we must include the time as part of the file name, so the pattern to use is hour-minutes-seconds (HHMMSS).

Include version control for documents

If you know in advance that the file system will have many version documents, which will be updated or modified over time, it will be worth considering a parameter for file versioning.

An information block for version control should start with "v" followed by two digits with a leading zero to ensure that files sort correctly. The "v" helps to denote that the block corresponds to a version number. As you create files with a new version, keep the same file name but change the version number.

Sometimes file naming systems require to include as part of the file name the state of working files. For these cases, you should add at the end of the file name prefixes for words like "Final," "Draft," "Review," or "Editing."

Implement sequential numbering when needed

In some cases, the file set is a collection of files where all can have and share the same name except for a unique identifier, usually a sequential numbering parameter.

It is recommended to use leading left zeros to keep files organized. For instance, if there are up to 999 files, we should start the sequence like this "001", "002", "003," etc. If there are more than 1000 but less than 10 000 files, then we should start with "0001", "0002", "0003," etc.

Document your file naming system

The FNS should be documented so people can follow the rules and conventions. One way to achieve this is to write a text file at the folder's root. This file must include all the rules, conventions, abbreviations, and some examples of how the system works so that users can stay consistent in its use.

In addition to text files, if people inside a company or a work team will be using the FNS, then conducting a training session may be beneficial to elucidate the significance of adhering to the new system and its functionality.

It is important to note that an FNS may not be perfect from the beginning. As such, it is essential to periodically review the established rules, conventions, and abbreviations to identify areas that may require improvement or modification. The constant update and refinement of the system will improve its overall efficiency and effectiveness.

This ongoing process of evaluation and adaptation will contribute to the long-term success of the FNS, ultimately promoting a more organized and streamlined working environment.

Conclusion

In conclusion, implementing an efficient file naming system is crucial for better file management and organization. By adhering to proper conventions and guidelines, users can quickly locate and identify documents, enhancing workflow efficiency. Regularly reviewing and updating the system ensures its effectiveness and relevance, facilitating a more organized and streamlined working environment.

Explained: The Design and Types of Ecommerce Architecture

Carlos Padilla — Tue, 28 Feb 2023 12:56:23 +0000

An ecommerce architecture refers to the overall technical design and infrastructure of an ecommerce online store, including the hardware and software components, such as servers, databases, and programming languages.

Systems architectures also include the flow of data between different components and how the website or application is built to handle traffic and perform functions such as processing payments and managing inventory.

Ecommerce architectures can vary greatly depending on the business's size, complexity, and specific requirements. Choosing a particular ecommerce architecture is a fundamental decision. It will impact several critical aspects of the business, like scalability, maintenance, upgradeability, cost security, and performance.

Ecommerce Architecture Types

There are several common ecommerce architecture patterns, including monolithic architecture, microservices, two or three tiers architecture, composable, headless, serverless, or cloud-based architectures.

Architectures have different trade-offs, and the best one depends on the specific needs of the business and the resources available.

Monolith Vs. Microservices Ecommerce Architecture

Monolith Architecture

The monolithic architecture model is a unified system that includes all features in a large codebase. In this type of architecture, the ecommerce solution connects to a database. It contains components such as a user interface, data access layer, and business logic layer.

While monolithic architecture is a traditional method of software development, it has some benefits and drawbacks.

Pros of a Monolithic Architecture

It's simple to implement and maintain as all the functionality is contained in one place.
There are fewer external components and less probability of things going wrong because everything is integrated.
Developing and testing new features is quicker because all the functionality is in one place.
Less expensive to set up and maintain than more complex architectures.

Cons of a Monolithic Architecture

As the business and traffic grow, scaling can become challenging and may lead to bottlenecks.
Inflexible and demanding to change, making it hard to adapt to new business requirements or integrate with other systems.
Updating, testing, or replacing one system piece can be difficult and risky because all the functionality is combined.
A failure in one component can affect the entire system, which makes it hard to isolate and fix the problem.

Microservice Architecture

A microservice architecture involves breaking down the ecommerce system into small and independent services that communicate with each other through APIs. The main advantage of this approach is that each microservice operates as a subsystem with its specific business logic. This architecture allows for greater scalability and flexibility.

Pros of a Microservice Architecture

Easier to scale individual services as needed without affecting the entire system.
More flexibility regarding technology choices and distribution of tasks among development teams.
Microservices can be developed, deployed, and scaled independently.
The failure of one service does not affect the entire system allowing for a more fault-tolerant system.
Better integration with other systems complementing a commerce website, such as CRM, CMS, or payment gateways. Businesses benefit from best-in-breed solutions without the need to reinvent the wheel.

Cons of a Microservice Architecture

More complex to implement and maintain, especially for teams with less experience.
There is increased communication overhead, which can slow down the system and increase the risk of errors.
Development, deployment, and maintenance can be more expensive than a monolithic one. It requires more infrastructure and specialized skill sets.

Two- Vs. Three-tier Ecommerce Architecture

Two-tier and three-tier architectures are different ways of organizing the components of an ecommerce system. The three-tier architecture has an extra layer between the client and server, allowing for more scalability and new features.

Two-tier Architecture

A two-tier architecture is where the client (interface layer) communicates directly with the ecommerce platform's data layer. This architecture is straightforward but can become limiting as the business grows. It makes it challenging to add new functionality or scale the system.

Pros of a Two-tier Architecture

Easy to understand and work with because all the functionality is contained in the client. It's quicker to develop, add and test new features.
Reduces network traffic and improves data processing efficiency by optimizing input-output and using buffering techniques.
The server uses transaction control to prevent concurrent modifications to the same records.
Less expensive to set up and maintain than more complex architectures.

Cons of a Two-tier Architecture

Challenging to scale and may lead to bottlenecks as the business and traffic grow.
Inflexible and challenging to change, making it hard to adapt to new business requirements.
The business logic and data presentation may be the same for multiple client applications, increasing the need for resources.
It doesn't provide an additional layer for protection and validation, making it more vulnerable to attacks.

Three-tier Architecture

A three-tier architecture contains an additional "middle tier" between the client and the server. This middle tier typically manages the client and server data flow. It can also handle authentication, security, and data validation functions.

Pros of a Three-tier Architecture

Each layer can be developed by a separate development team, which gives more flexibility regarding technology choices.t
Components can be reused across different platform parts, allowing for cost savings and faster development.
It provides an additional layer for security and validation, improving data integrity as the client lacks direct access to the database.

Cons of a Three-tier Architecture

Different layers may only be able to handle an increase in traffic or data volume with significant modifications. It makes it difficult to scale
A three-tier architecture's development, deployment, and maintenance can be more expensive than a two-tier one.
Maintenance and upgrades can be more complex and time-consuming, as changes must be made to multiple layers and components.
More steps are involved in processing a request, which can lead to increased latency and slower response times for customers.

Composable and Headless Ecommerce Architecture

Headless Architecture

In a headless ecommerce architecture, the front-end presentation layer of the ecommerce platform is separated from the back-end functionality.

The front-end (head) displays the user interface and handles user interactions. On the other hand, the back-end (body) handles specific functionality such as inventory management, order processing, and payment processing.

Pros of a Headless Architecture

Greater flexibility in terms of the technologies used for the front-end and back-end.
Better integration with other systems, such as CMS, CRM, or payment gateways.
Better separation of concerns can improve performance, making it easier to optimize the front-end for a faster and better customer experience and the back end for better scalability and security.
Future-proofing for more straightforward adaptation to new technologies and emerging trends, such as Progressive Web Applications (PWAs) and voice assistants.

Cons of a Headless Architecture

More complex to implement and maintain, especially for small businesses with a limited developer team.
Increased communication overhead can slow down the system and increase the risk of errors.
Development, deployment, and maintenance can be more expensive than traditional commerces.
Requires a different set of skills, expertise, and more robust integration between the front-end and back-end.

Composable Architecture

A composable commerce architecture is an approach where the ecommerce platform comprises small and independent services. They can be combined and configured differently to meet specific business needs.

These services can be developed and deployed independently. Also, they can be composed to create a customized composable commerce solution that can be easily scaled and adapted to business requirements.

Pros of a Composable Architecture

Different services can be swapped in and out as needed.
New services can be added to the platform without affecting the existing functionality.
Services can be scaled independently, depending on the usage.
More control over the ecommerce platform to optimize it for specific business needs.
Code and functionality can be reused across different services, resulting in cost savings and faster development.

Cons of a Composable Architecture

More complex implementation and maintenance, especially for teams with less experience.
The system can slow down and increase the risk of errors because services communicate through APIs.
Higher operational costs because it requires more infrastructure and specialized skill sets.

What Ecommerce Architecture to Choose

A well-designed architecture can improve the platform's performance, scalability, and security, making it easier to adapt to new business requirements. On the other hand, a poorly-designed architecture can limit the growth and success of the business.

Consider your Current Architecture

When evaluating the current architecture of an ecommerce platform, it's essential to consider the following factors:

Scalability: Can the current architecture handle large quantities of users and transactions? Will it be able to drive future growth?
Flexibility: Can the current architecture adapt to new business requirements and changing technologies? Can ecommerce be easily integrated with other systems?
Performance: Is the current architecture optimized for fast load times and responsive user interactions?
Security: Can the current architecture protect sensitive customer data and transactions from potential security threats?
Reusability: Is the current architecture designed to allow code and functionality to be reused across different platform parts?
Cost-effective: Is the current architecture cost-effective for development, deployment, and maintenance?

Once you have assessed the current architecture against these factors, you should clearly understand whether it fits your business's needs. If the present architecture works, keep using it. If not, look for an alternative that better fits your business needs.

Find the Architecture that Best Fits your Future Ecommerce Needs

Knowing your business's future requirements allows you to make an informed decision about the architecture and features of your ecommerce platform. This ensures your business's growth and success.

The ecommerce landscape constantly evolves, and new technologies and trends are always emerging. Ensure your platform is up-to-date with trends and tech to keep growing and succeeding.

For example, ecommerce businesses looking for a simpler and cheaper solution can use a monolithic or two-tier architecture. However, companies that need to scale and customize their business quickly may benefit from microservices, headless, or composable architectures.

Modern ecommerce systems could choose three-tier or composable architectures if they need security, performance, and integrations with other systems.

Medusa’s Ecommerce Architecture

Medusa is an open-source ecommerce building blocks that provide developers with the opportunity of using it as-is, or pick-and-choice how they assemble their ecommerce system. It allows businesses to benefit from scalability and flexibility. The modular architecture will enable enterprises to quickly scale up or down specific parts, depending on their needs.

This can lead to cost savings, better performance, and better customer experience, which are vital factors for the success of an ecommerce business.

Different services are independent and can be combined differently. Businesses can add or remove features as needed and easily integrate them with other systems. This allows companies to improve the performance of their ecommerce store and adapt to new technologies and emerging trends.

Medusa allows developers to build and customize ecommerce functionality using pre-built services and APIs rather than starting from scratch. This approach allows for faster development, improved scalability and flexibility, and better integration with other systems.

Medusa is composed of three components:

The Medusa backend is the core server that holds all the logic and data of the store. It comes with a headless architecture and developers interact with the back-end through REST APIs.
The admin dashboard provides a lot of functionalities to manage the store, including order management, product management, user management, and more.
The Ecommerce storefront. Medusa provides two starter storefronts to view products and make orders, one built with Next.js and one with Gatsby. Developers can also create their own using the REST APIs.

In addition, Medusa's plugin system allows developers to add new functionality to the ecommerce platform without modifying the core codebase. This system will enable developers to create custom plugins that can be used to add new features or extend existing ones. It allows the platform to be customized to meet the specific needs of a business by completing requirements quickly and easily.

Conclusion

Choosing the correct architecture for a business ecommerce can be overwhelming for developers. They must compare each architecture's advantages and disadvantages before selecting an option that could fit the business's necessities.

Medusa is a good alternative for businesses seeking a modular and open source ecommerce architecture. Its modular architecture allows different services to be combined and configured to meet the business's specific needs.

Using Medusa results in cost savings and faster development, particularly for companies with high levels of customization. It has improved integration with other systems and a supportive developer community for assistance with customization and maintenance.

If you’re interested in Medusa, you can get started by following the quickstart guide.

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

Implement Single Sign On in Medusa

Carlos Padilla — Thu, 02 Feb 2023 14:34:17 +0000

Introduction

Medusa is an open source headless commerce that offers out-of-the-box functionalities needed to build an ecommerce platform. An important feature Medusa provides is its flexibility in adapting functionalities according to your needs.

Medusa allows users to authenticate on the platform using email and password or with a bearer token. However, the authentication flow can be customized due to Medusa's flexibility.

This tutorial will guide you through the process of customizing the auth flow of your Medusa server. To achieve that, you will allow your customers to log in with a magic link received in their email.

You can find the final code for this tutorial in this GitHub repository.

What is Medusa?

Medusa is a composable engine that combines an amazing developer experience with endless customizations. You can add additional endpoints to perform custom actions or add new services to implement business logic; for example, to modify the authentication flow. You can also use subscriptions to build automation; for example, to send an email using a notification provider when a specific event happens.

Prerequisites

To follow along with this tutorial, you need the following:

A working Medusa server application: You can follow the quickstart guide to getting started.
Your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the Configure your Server documentation guide to learn how to do that.
An email service to send emails to implement passwordless login: You can follow this guide to enable the Sendgrid plugin available on the Medusa ecosystem.
A Next.js starter to test the new authentication flow added to the Medusa server. However, you can still follow along using a different storefront framework.
yarn package manager: you can follow these instructions to install it. You can also use npm as an alternative.

Passwordless Login

A passwordless login is a strategy to verify a user's identity without a password. Several alternatives to achieve this include possession factors such as one-time passwords [OTPs] or registered smartphone numbers, biometrics using fingerprint or retina scans, and magic links sent by email to the user.

For this tutorial, you will focus on implementing the magic link strategy. See the flow below:

Customers visit the Medusa store, write their email, and click the Enter button.
The Medusa store requests the auth endpoint on the Medusa server, which sends an email to the customer with a magic link.
Customers click on the magic link.
The Medusa server validates the link, logs users in, sets a session cookie, and redirects customers to the Storefront.

Add Passwordless Service

The first step is creating a service that will emit an event to send emails with the magic link to customers and verify tokens from those magic links.

Start by installing the jsonwebtoken package that will be used to sign in and verify the tokens:

yarn add jsonwebtoken

Next, create the file src/services/password-less.ts with the following content:

import { CustomerService, EventBusService, TransactionBaseService } from '@medusajs/medusa'
import { MedusaError } from 'medusa-core-utils'
import { EntityManager } from 'typeorm'
import jwt from 'jsonwebtoken'

class PasswordLessService extends TransactionBaseService {
  protected manager_: EntityManager
  protected transactionManager_: EntityManager
  private readonly customerService_: CustomerService
  private readonly eventBus_: EventBusService
  private readonly configModule_: any;
  private readonly jwt_secret: any;

  constructor(container) {
    super(container)
    this.eventBus_ = container.eventBusService
    this.customerService_ = container.customerService
    this.configModule_ = container.configModule

    const { projectConfig: { jwt_secret } } = this.configModule_
    this.jwt_secret = jwt_secret
  }

  async sendMagicLink(email, isSignUp) {
    const token = jwt.sign({ email }, this.jwt_secret, { expiresIn: '8h' })

    try {
      return await this.eventBus_.withTransaction(this.manager_)
        .emit('passwordless.login', { email, isSignUp, token })
    } catch (error) {
      throw new MedusaError(MedusaError.Types.UNEXPECTED_STATE, `There was an error sending the email.`)
    }
  }

  async validateMagicLink(token) {
    let decoded
    const { projectConfig: { jwt_secret } } = this.configModule_

    try {
      decoded = jwt.verify(token, jwt_secret)
    } catch (err) {
      throw new MedusaError(MedusaError.Types.INVALID_DATA, `Invalid auth credentials.`)
    }

    if (!decoded.hasOwnProperty('email') || !decoded.hasOwnProperty('exp')) {
      throw new MedusaError(MedusaError.Types.INVALID_DATA, `Invalid auth credentials.`)
    }

    const customer = await this.customerService_.retrieveRegisteredByEmail(decoded.email).catch(() => null)

    if (!customer) {
      throw new MedusaError(MedusaError.Types.NOT_FOUND, `There isn't a customer with email ${decoded.email}.`)
    }

    return customer
  }
}

export default PasswordLessService

The first method, sendMagicLink, creates and signs a token with the customer's email received as a parameter and an expiration of one hour. Then, it emits the passwordles.login event using the eventBus, so the PasswordLessSubscriber, which you will create later, can execute its handler to send the email.

The validateMagicLink method verifies there is a token and that it is valid, that is, that it has not been manipulated by a third party or that it has not expired. Lastly, it tries to get the customer using the customerService, and if it’s successful, it returns the retrieved customer.

Add Passwordless Endpoints

The next step is to add custom endpoints, so you can use the strategy from the storefront.

Create the file src/api/index.ts with the following content:

import { Router, json } from 'express'
import cors from 'cors'
import jwt from 'jsonwebtoken'
import { projectConfig } from '../../medusa-config'

const corsOptions = {
  origin: projectConfig.store_cors.split(','),
  credentials: true
}

const route = Router()

export default () => {
  const app = Router()
  app.use(cors(corsOptions))
  app.use(json());

  app.use('/auth', route)

  route.post('/passwordless/sent', async (req, res) => {
    const manager = req.scope.resolve('manager')
    const customerService = req.scope.resolve('customerService')
    const { email, isSignUp } = req.body

    let customer = await customerService.retrieveRegisteredByEmail(email).catch(() => null)

    if (!customer && !isSignUp) {
      res.status(404).json({ message: `Customer with ${email} was not found. Please sign up instead.` })
    }

    if (!customer && isSignUp) {
      customer = await customerService.withTransaction(manager).create({
        email,
        first_name: '--',
        last_name: '--',
        has_account: true
      })
    }

    const passwordLessService = req.scope.resolve('passwordLessService')

    try {
      await passwordLessService.sendMagicLink(customer.email, isSignUp)
      return res.status(204).json({ message: 'Email sent' })
    } catch (error) {
      return res.status(404).json({ message: `There was an error sending the email.` })
    }
  })

  route.get('/passwordless/validate', async (req, res) => {
    const { token } = req.query
    const { projectConfig } = req.scope.resolve('configModule')

    if (!token) {
      return res.status(403).json({ message: 'The user cannot be verified' })
    }

    const passwordLessService = req.scope.resolve('passwordLessService')

    try {
      const loggedCustomer = await passwordLessService.validateMagicLink(token)

      req.session.jwt_store = jwt.sign(
        { customer_id: loggedCustomer.id },
        projectConfig.jwt_secret!,
        { expiresIn: '30d' }
      )

      return res.status(200).json({ ...loggedCustomer })
    } catch (error) {
      return res.status(403).json({ message: 'The user cannot be verified' })
    }
  })

  return app
}

In this file, the /passwordless/sent endpoint does some validations before calling the passwordLessService to emit the event.

The validations include checking if there is a registered customer with that email. If not, it returns a response asking the customer to sign up first. If there is no registered customer, but the request is a signUp, it creates a new customer on the database.

Lastly, when the customer is already retrieved or created, it calls the sendMagicLink method on the passwordLessService to send the email.

The /passwordless/validate endpoint verifies the existence of a token in the query string and validates it with the validateMagicLink method on the passwordLessService. If the token is valid, the service will fetch and return the customer details so the endpoint can set a session and send a response to the storefront.

Add Passwordless Subscriber

The last step is creating a subscriber with a handler function to send emails with a magic link whenever a passwordless.login event is emitted.

To send the emails, this tutorial uses SendGrid as a notification provider, but you can use the email provider of your choice as the flow would be very similar. Create the file src/subscribers/password-less.ts with the following content:

class PasswordLessSubscriber {
  protected sendGridService: any;
  constructor({ eventBusService, sendgridService }) {
    this.sendGridService = sendgridService;
    eventBusService.subscribe('passwordless.login', this.handlePasswordlessLogin);
  }

  handlePasswordlessLogin = async (data) => {
    await this.sendGridService.sendEmail({
      to: data.email,
      from: process.env.SENDGRID_FROM,
      templateId: data.isSignUp ? process.env.SENGRID_REGISTER_TEMPLATE_ID : process.env.SENGRID_LOGIN_TEMPLATE_ID,
      dynamic_template_data: {
        token: data.token
      },
    })
  }
}

export default PasswordLessSubscriber;

The handler, handlePasswordlessLogin, uses the SendGrid service with a dynamic template to send the magic link that customers will click to log in. This email includes a storefront URL with a token passed as query string. Customers can click or copy the URL to log in, there’s no need to type a password.

Be sure to have two templates on Sendgrid: one for signup and another for login. Also, remember to get their IDs and add those values to your .env file. These IDs will be retrieved by your PasswordLessSubscriber when sending an email.

SENGRID_LOGIN_TEMPLATE_ID=d-750a..........................
SENGRID_REGISTER_TEMPLATE_ID=d-03b........................

Set up New Auth Flow on the Storefront

This section will test the new authentication strategy added to your Medusa server. For this tutorial, the Next.js starter Storefront is used as an example, but you can use any other framework, and the process would be very similar.

Login Page

Open the src/modules/account/components/login/index.tsx file and replace its content with the following code:

import { LOGIN_VIEW, useAccount } from "@lib/context/account-context"
import Button from "@modules/common/components/button"
import Input from "@modules/common/components/input"
import React, { useState } from "react"
import { FieldValues, useForm } from "react-hook-form"

interface SignInCredentials extends FieldValues {
  email: string
}

const Login = () => {
  const { loginView } = useAccount()
  const [_, setCurrentView] = loginView
  const [authError, setAuthError] = useState<string | undefined>(undefined)
  const [linkSent, setLinkSent] = useState<string | undefined>(undefined)

  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<SignInCredentials>()

  const onSubmit = handleSubmit(async (credentials) => {
    const response = await fetch("http://localhost:9000/auth/passwordless/sent", {
        method: "POST",
        body: JSON.stringify(credentials),
        headers: { "Content-Type": "application/json" },
      },
    )

    if (!response.ok) response.json().then((data) => setAuthError(data.message))

    if (response.ok) setLinkSent("Check your email for a login link.")
  })

  return (
    <div className="max-w-sm w-full flex flex-col items-center">
      {!linkSent && (
        <>
          <h1 className="text-large-semi uppercase mb-6">Welcome back</h1>
          <p className="text-center text-base-regular text-gray-700 mb-8">
            Sign in to access an enhanced shopping experience.
          </p>
          <form className="w-full" onSubmit={onSubmit}>

            <div className="flex flex-col w-full gap-y-2">
              <Input
                label="Email"
                {...register("email", { required: "Email is required" })}
                autoComplete="email"
                errors={errors}
              />
            </div>

            {authError && !linkSent && (
              <div className="text-rose-500 w-full text-small-regular mt-2">
                {authError}
              </div>
            )}
            <Button className="mt-6">Enter</Button>
          </form>

          <span className="text-center text-gray-700 text-small-regular mt-6">
            Not a member?{" "}
            <button
              onClick={() => setCurrentView(LOGIN_VIEW.REGISTER)}
              className="underline"
            >
          Join us
        </button>.</span>
        </>
      )}

      {linkSent && (
        <>
          <h1 className="text-large-semi uppercase mb-6">Login link sent!</h1>
          <div className="bg-green-100 text-green-500 p-4 my-4 w-full">
            <span>{linkSent}</span>
          </div>
        </>
      )}
    </div>
  )
}

export default Login

The main changes that can be observed are:

The update of the handleSubmit function to request the endpoint /auth/passwordless/sent to send an email with a magic link to the customer.
The removal of the password field.
A div element to show a successful notification if the email was sent correctly.

Registration Page

Open the src/modules/account/components/register/index.tsx file and replace its content with the following:

import { LOGIN_VIEW, useAccount } from "@lib/context/account-context"
import Button from "@modules/common/components/button"
import Input from "@modules/common/components/input"
import Link from "next/link"
import { useState } from "react"
import { FieldValues, useForm } from "react-hook-form"

interface RegisterCredentials extends FieldValues {
  email: string
}

const Register = () => {
  const { loginView } = useAccount()
  const [_, setCurrentView] = loginView
  const [authError, setAuthError] = useState<string | undefined>(undefined)
  const [linkSent, setLinkSent] = useState<string | undefined>(undefined)

  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<RegisterCredentials>()

  const onSubmit = handleSubmit(async (credentials) => {
    credentials.isSignUp = true
    const response = await fetch("http://localhost:9000/auth/passwordless/sent", {
        method: "POST",
        body: JSON.stringify(credentials),
        headers: { "Content-Type": "application/json" },
      },
    )

    if (!response.ok) response.json().then((data) => setAuthError(data.message))

    if (response.ok) setLinkSent("Check your email to activate your account.")
  })

  return (
    <div className="max-w-sm flex flex-col items-center mt-12">
      {!linkSent && (
        <>

          <h1 className="text-large-semi uppercase mb-6">Become a Acme Member</h1>
          <p className="text-center text-base-regular text-gray-700 mb-4">
            Create your Acme Member profile, and get access to an enhanced shopping
            experience.
          </p>
          <form className="w-full flex flex-col" onSubmit={onSubmit}>
            <div className="flex flex-col w-full gap-y-2">
              <Input
                label="Email"
                {...register("email", { required: "Email is required" })}
                autoComplete="email"
                errors={errors}
              />
            </div>
            {authError && (
              <div>
            <span className="text-rose-500 w-full text-small-regular">
              {authError}
            </span>
              </div>
            )}
            <span className="text-center text-gray-700 text-small-regular mt-6">
          By creating an account, you agree to Acme&apos;s{" "}
              <Link href="/content/privacy-policy">
            <a className="underline">Privacy Policy</a>
          </Link>{" "}
              and{" "}
              <Link href="/content/terms-of-use">
            <a className="underline">Terms of Use</a>
          </Link>
          .
        </span>
            <Button className="mt-6">Join</Button>
          </form>
          <span className="text-center text-gray-700 text-small-regular mt-6">
        Already a member?{" "}
            <button
              onClick={() => setCurrentView(LOGIN_VIEW.SIGN_IN)}
              className="underline"
            >
          Sign in
        </button>
        .
      </span></>
      )}

      {linkSent && (
        <>
          <h1 className="text-large-semi uppercase mb-6">Registration complete!</h1>
          <div className="bg-green-100 text-green-500 p-4 my-4 w-full">
            <span>{linkSent}</span>
          </div>
        </>
      )}
    </div>
  )
}

export default Register

The changes that you can watch there are:

The update of the handle function to request the endpoint /auth/passwordless/sent to send an email with a magic link to the customer after registration.
The removal of the first name, last name, password and phone fields on the registration form.
A div element to show a successful notification if the email was sent successfully.

Validation Page

Create the new page src/pages/account/validate.tsx with the following content:

import Layout from "@modules/layout/templates"
import React, { ReactElement, useEffect, useState } from "react"
import { useRouter } from "next/router"
import { useAccount } from "@lib/context/account-context"
import Spinner from "@modules/common/icons/spinner"

const Validate = () => {
  const { refetchCustomer, retrievingCustomer, customer } = useAccount()
  const [authError, setAuthError] = useState<string | undefined>(undefined)

  const router = useRouter()

  useEffect(() => {
    const token = router.query.token
    if (token) {
      fetch(`http://localhost:9000/auth/passwordless/validate?token=${token}`,
        { credentials: "include" })
        .then((response) => {
          if (!response.ok) {
            response.json().then((data) => setAuthError(data.message))
          }
          refetchCustomer()
        })
    }
  }, [refetchCustomer, retrievingCustomer, router])

  if (authError) {
    return (
      <div className="flex items-center justify-center w-full min-h-[640px] h-full text-red-600">
        The link to login is invalid or has expired.
      </div>
    )
  }

  if (retrievingCustomer || !customer) {
    return (
      <div className="flex items-center justify-center w-full min-h-[640px] h-full text-gray-900">
        <Spinner size={36} />
      </div>
    )
  }

  if (!retrievingCustomer && customer) {
    router.push("/account")
  }

  return <div></div>
}

Validate.getLayout = (page: ReactElement) => {
  return (
    <Layout>
      {page}
    </Layout>
  )
}

export default Validate

When users click on the magic link received on their email, they will be redirected to the /account/validate page on the storefront. This page will send a request to the Medusa server to check if the token, passed as a query parameter in the magic link, is valid. If the token is valid, users will be logged in and redirected to the account page, if not an error message will be shown.

The storefront page URL where the user is redirected from the magic link has to match the URL added to the SendGrid templates.

Test Passwordless Strategy

To test out the passwordless strategy, first in your terminal, run the following commands to transpile the TypeScript files to JavaScript files on your Medusa server:

yarn run build

Next, start your Medusa server running the next command

yarn start

and start the Next.js Storefront:

yarn run dev

Then, go to the URL http://localhost:8000. Click on the Account link on the navbar, and you should get this page.

You can't log in right now because you need to register first. Click on the Join us link below the Enter button, and you should get the registration page.

Fill out the form with your email and click on the Join button. You should see a notification that says the registration was completed.

Now, check your inbox email, and you should see a new email with the template you configured previously in Sendgrid.

Click on the Activate account button. A new tab in your browser will be open on the URL http://localhost:8000/account/validate, if your magic link is valid you will be redirected to the profile page:

Log out of your account, go to the login page and ask for a new magic link to log in. You should receive a new mail with the login template from Sendgrid with a new magic link. Click the Login button, and you will be logged in again without writing any password.

What's Next?

As you can see, it is straightforward to customize the authentication flow on your Medusa server. From now on, you can:

Extend the passwordless strategy to send one-time passwords (OTP) by email or SMS.
Add social methods such as Facebook, Twitter, or GitHub using the Medusa Auth plugin.
Implement multifactor authentication (MFA) for administrators.

You can also check out the following resources to dive more into Medusa's core:

Learn how to extract your authentication functionality into a Medusa plugin.
Learn how to create a Subscriber.
Learn how to send notifications when an event occurs.

If you have any issues or questions about Medusa, feel free to contact the Medusa team via Discord.

How to Deploy Your Medusa Server to Railway’s Free Hosting

Carlos Padilla — Mon, 24 Oct 2022 13:02:08 +0000

Medusa is an Open Source headless commerce that allows you to build digital commerce through its API with just a few commands. You can host Medusa’s server on any of your preferred hosting choices, and one way to host it is using Railway.

Railway is a deployment platform where you can provide infrastructure, develop that infrastructure locally, and then deploy it to the cloud.

This guide will teach you how to pull your Medusa server code from a GitHub repository and automatically deploy it to Railway. You also will learn how to set up Postgres and Redis databases for your Medusa server.

Why Railway?

Railway helps you ship quickly by removing common developer hurdles. With it, you can deploy a Medusa server to production without hassle. Their tool extends your app with plugins; if you need a database, create a new service, and you are good to go.

Railway also offers a way to have several environments to test your apps before going to production. It scales apps to meet user demand automatically, based on load. You also get an automatic pipeline to make new deployments each time your repositories are updated.

Lastly, their user-friendly interface is easy to use, so you can do everything in the web app without touching your terminal. Railway makes it easy for developers to deploy their applications and go to production quickly.

Prerequisites

To follow along with this tutorial, you need a working Medusa server application. You can follow the quickstart guide to getting started.

Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the Configure your Server documentation to learn how to do that.

You also need a GitHub account that needs to be linked with a Railway account, so you can pull your code to make the deployments.

Setting up a Project on Railway

Let’s begin by setting up the project on Railway.

Create the Postgres Database

The first step is to create a project on Railway with a PostgreSQL database. Later on, you will connect that database with the Medusa server.

You will be redirected to the new project page. Once you are there, on the dropdown, choose the Provision PostgreSQL option*.*

By choosing that option, a new database will be created and after a few seconds, you will be redirected to the project page where you will see the newly-created database. You will see a sidebar with some database options if you click on the database card.

Go to the Connect tab you’ll find the Postgres connection URL. You’ll need to use this in the next section.

Create the Redis Database

The second step is to add a Redis database to handle the event queues of your Medusa server.

On to the project view, click on the New button, then choose the Database option, and choose Add Redis.

After a few seconds, you should see a new Redis database added to the project view. Click on it to open the database sidebar.

Then, go to the Connect tab to get the Redis Connection URL. You’ll need the URL in the next section.

Deploy Medusa Server

The next step is to prepare the Medusa server to be deployed. Go to your Medusa server directory and open your medusa-config.js file. Be sure you’ve set your database to use PostgreSQL. In medusa-config.js; make the following changes in the exported object:



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

Next, delete the Dockerfile file. By default, Railway will look for it in the root of your repository. If there is one, it will try to deploy your server using it, However, for this tutorial, the deployment won’t be using docker.

Commit your changes and push them to your remote repository on GitHub. Once the repository is ready on GitHub, the next step is to connect it to Railway to be able to deploy it.

Go back to the project view on Railway and click on the New button, then choose the GitHub Repo option.

Choose the Configure GitHub App option to permit Railway to read and pull your code from GitHub.

Once you give the necessary permissions, go back to Railway, and you should see your repository displayed on the dropdown.

If the GitHub repositories are stuck on loading and not showing, you might need to delete the project and start over. This only happens before you configure your account with GitHub.

By selecting your Medusa server repo, a new app will be deployed, and after a couple of minutes,

you should see a successful deployment. Click on the repo app card to check it.

Until this point, you have a Medusa server, and a Postgres and Redis databases deployed, but the app is not public yet and the server is not connected to the databases. That is what you will do in the next section.

Add Environment Variables

On the app info sidebar, go to the Variables tab and add the following properties:



PORT=9000
JWT_SECRET=something
COOKIE_SECRET=something
DATABASE_URL=<<DATABASE_URL>>
REDIS_URL=<<REDIS_URL>>

It’s recommended to use other values for JWT_SECRET and COOKIE_SECRET than something for better security.

The last properties are the URLs to connect to the databases. There, you need to add the database URLs that you got when you created the Postgres and Redis databases earlier.

Note: Each time you add a new environment variable, a new redeploy is scheduled. You can cancel it for the first variables to avoid unnecessary redeploys and only leave it for the last one.

Change Start Command

Next, scroll down on the Settings tab until you get to the Service section. On the Start Command field, write the next command.



medusa migrations run && medusa develop

With this, you are instructing Railway that each time a new redeploy happens, first, it should run the migrations, and then it should start the server on port 9000 and bind it to the host 0.0.0.0. This last thing is a Railway requirement to be able to expose the app.

Expose the App to the Internet

The next step is to make the app available over the internet. Go to the Settings tab and click on the Generate Domain button to get a public domain that you can visit to test the app.

Test it

Make sure you seed the database before trying to make requests to any endpoint on your Medusa server.

To check that your Medusa server is working, on the app sidebar, go to the Deployments tab and click on the app URL.

At end of the URL, add /store/products, so the URL would be something like this:

[https://medusa-server-railway.up.railway.app/store/products](https://medusa-server-railway.up.railway.app/store/products)

You should get a response with a list of the products on your database. If that is the case, you have successfully deployed your Medusa server into Railway.

Make sure to change the URL in your Medusa storefront or admin based on the URL of your server.
Also, add your Admin and storefront URLs to the environment variables on your Medusa server.

Troubleshooting

If you run into any issues or a problem with your deployed server, you can check the logs in your Railway container instance by clicking on Logs in the Deployment tab.

Conclusion

Deploying a Medusa server on Railway is super easy and quick. Once you’re done, you can focus on adding new functionalities to your Medusa server, such as custom endpoints, services, or plugins.

To push the changes to your server, push them to your GitHub repository. Railway will detect changes and start a new deployment. Your application will then be updated with the new features.

To learn more about how to customize your store or how you can connect a storefront to your store, be sure to check out Medusa’s documentation.

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

Customize Medusa and Gatsby to Implement Wishlist Functionality

Carlos Padilla — Tue, 09 Aug 2022 11:51:58 +0000

Medusa is an open source headless commerce that allows you to quickly build an ecommerce platform through its API with just a few commands. In addition to its core that holds all the features an ecommerce requires, Medusa also offers out of the box a ready-made Gatsby storefront that you can use to get your ecommerce store up and running.

This tutorial will guide you through the process of adding wishlist functionality to your Medusa server and then using it to implement a Wishlist flow on a Gatsby storefront.

You can find the final code for this tutorial in this GitHub repository for the Medusa server and this one for the Gatsby storefront.

What you’ll be Creating

Medusa Server

In this article, you’ll learn how to set up your medusa server so that you can have a wishlist functionality. In a nutshell, to achieve that, you need to do the following:

Add two new tables to your database and the entities that represent them to store customers’ wishlists and wishlist items.
Add a wishlist service with helper methods to perform actions related to the wishlist and wishlist items.
Add custom endpoints to fetch and create wishlists, and add and remove wishlist items.

Gatsby Storefront

Once your Medusa server has the wishlist functionality, the next step is to implement the wishlist flow on your Gatsby storefront; this includes the following:

A wishlist popover that gives customers a quick view of what is in their wishlist.
Add or remove products to the wishlist from the product detail page.
A wishlist page to list the products saved in their wishlist and remove them.

Prerequisites

Before you follow along with this tutorial, make sure you have:

A Medusa server with some dummy data to work with. If you don’t, please follow the QuickStart guide to set up a Medusa server first.
As you’ll use migrations in one of the steps, you need to install PostgreSQL and configure it with your Medusa Server.
This tutorial uses the Gatsby starter to test the wishlist functionality added to the Medusa server. However, you can still follow along using a different storefront framework.

Setting up Medusa server

Add the Wishlist Entity

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

import {
  BeforeInsert,
  Column,
  Entity,
  Index,
  JoinColumn,
  ManyToOne,
  OneToMany,
} from "typeorm"

import { Customer } from "@medusajs/medusa/dist/models/customer"
import { Region } from "@medusajs/medusa/dist/models/region"
import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"

@Entity()
export class Wishlist extends BaseEntity {
  readonly object = "wishlist"

  @Index()
  @Column()
  region_id: string

  @ManyToOne(() => Region)
  @JoinColumn({name: "region_id"})
  region: Region

  @Index()
  @Column({nullable: true})
  customer_id: string

  @ManyToOne(() => Customer)
  @JoinColumn({name: "customer_id"})
  customer: Customer

  // TODO add wishlish item relation

  @BeforeInsert()
  private beforeInsert(): void {
    this.id = generateEntityId(this.id, "wish")
  }
}

This uses the decorator @Entity imported from Typeorm to create the Wishlist entity. Then, you create a Wishlist class that extends Medusa's BaseEntity.

A Wishlist can have many wishlist items, so, later on, you'll edit this entity to add the relation between them.

Add Wishlist Repository

To access and modify entity data, you need to create a repository for this entity. Create the file src/repositories/wishlist.ts with the following content:

import { EntityRepository, Repository } from "typeorm"
import { Wishlist } from "../models/wishlist"

@EntityRepository(Wishlist)
export class WishlistRepository extends Repository<Wishlist> { }

Add Wishlist Item Entity

The WishlistItem entity is a pivot table in the database that indirectly relates a product with a wishlist.

Create the file src/models/wishlist-item.ts with the following content:

import { BeforeInsert, Column, Entity, JoinColumn, ManyToOne, Unique } from "typeorm"
import { BaseEntity } from "@medusajs/medusa"
import { generateEntityId } from "@medusajs/medusa/dist/utils"
import { Product } from '@medusajs/medusa/dist/models/product'
import { Wishlist } from './wishlist';

@Entity()
@Unique(["wishlist_id", "product_id"])
export class WishlistItem extends BaseEntity {
  @Column()
  wishlist_id: string

  @ManyToOne(() => Wishlist, (wishlist) => wishlist.items)
  @JoinColumn({name: "wishlist_id"})
  wishlist: Wishlist

  @Column()
  product_id: string

  @ManyToOne(() => Product)
  @JoinColumn({name: "product_id"})
  product: Product

  @BeforeInsert()
  private beforeInsert(): void {
    this.id = generateEntityId(this.id, "item")
  }
}

This entity has two relationships, one with the wishlist and the other one with the product. The product relation allows fetching the wishlist item along with the product information.

You also need to add the relation between the Wishlist and the WishlistItem entities. In src/models/wishlist.ts, replace the //TODO with the following:

@OneToMany(() => WishlistItem, (wishlistItem) => wishlistItem.wishlist, {
  onDelete: "CASCADE"
})
items: WishlistItem[]

Make sure to import the WishlistItem entity at the beginning of the file:

import { WishlistItem } from './wishlist-item'

Add Wishlist Item Repository

Next, create the file src/repositories/wishlist-item.ts with the following content:

import { EntityRepository, Repository } from "typeorm"
import { WishlistItem } from '../models/wishlist-item';

@EntityRepository(WishlistItem)
export class WishlistItemRepository extends Repository<WishlistItem> { }

Create migrations

Migrations update the database schema with new tables or make changes to existing tables. You must create a migration for your Wishlist and WishlistItem entities to reflect them in the database schema.

Create the file src/migrations/wishlist.ts with the following content:

import { MigrationInterface, QueryRunner } from "typeorm";

export class wishlist1655952820403 implements MigrationInterface {

  public async up(queryRunner: QueryRunner): Promise<void> {
    // Tables
    await queryRunner.query(`CREATE TABLE "wishlist" ( "id" character varying NOT NULL, "region_id" character varying NOT NULL, "customer_id" character varying, "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "deleted_at" TIMESTAMP WITH TIME ZONE, CONSTRAINT "PK_gknmp6lnikxobwv1rhv1dgs982" PRIMARY KEY ("id") )`);
    await queryRunner.query(`CREATE TABLE "wishlist_item" ( "id" character varying NOT NULL, "wishlist_id" character varying, "product_id" character varying, "created_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updated_at" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "deleted_at" TIMESTAMP WITH TIME ZONE, CONSTRAINT "PK_7p8joiapu4u0dxbsatkm5n1qs2" PRIMARY KEY ("wishlist_id", "product_id") )`);

    // Foreign key constraints
    await queryRunner.query(`ALTER TABLE "wishlist" ADD CONSTRAINT "FK_auvt4ec8rnokwoadgpxqf9bf66" FOREIGN KEY ("region_id") REFERENCES "region"("id") ON DELETE NO ACTION ON UPDATE NO ACTION`);
    await queryRunner.query(`ALTER TABLE "wishlist" ADD CONSTRAINT "FK_5ix0u284wt3tmrlpb56ppzmxi7" FOREIGN KEY ("customer_id") REFERENCES "customer"("id") ON DELETE NO ACTION ON UPDATE NO ACTION`);
    await queryRunner.query(`ALTER TABLE "wishlist_item" ADD CONSTRAINT "FK_vovw0ddpagwehc13uw0q8lrw2o" FOREIGN KEY ("wishlist_id") REFERENCES "wishlist"("id") ON DELETE CASCADE ON UPDATE NO ACTION`);
    await queryRunner.query(`ALTER TABLE "wishlist_item" ADD CONSTRAINT "FK_1cvf31byyh136a7744qmdt03yh" FOREIGN KEY ("product_id") REFERENCES "product"("id") ON DELETE CASCADE ON UPDATE NO ACTION`);
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE "wishlist" DROP CONSTRAINT "FK_auvt4ec8rnokwoadgpxqf9bf66"`);
    await queryRunner.query(`ALTER TABLE "wishlist" DROP CONSTRAINT "FK_5ix0u284wt3tmrlpb56ppzmxi7"`);
    await queryRunner.query(`ALTER TABLE "wishlist_item" DROP CONSTRAINT "FK_vovw0ddpagwehc13uw0q8lrw2o"`);
    await queryRunner.query(`ALTER TABLE "wishlist_item" DROP CONSTRAINT "FK_1cvf31byyh136a7744qmdt03yh"`);
    await queryRunner.query(`DROP TABLE "wishlist"`);
    await queryRunner.query(`DROP TABLE "wishlist_item"`);
  }

}

Here, the up method runs if the migration hasn't been run before. It creates the wishlist and wishlist_item tables and adds some foreign keys.

Add Wishlist Service

Once your entities are ready, the next step is to create the service that allows you to perform actions related to the wishlist and wishlist items.

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

import { BaseService } from 'medusa-interfaces'
import { MedusaError } from 'medusa-core-utils'

class WishlistService extends BaseService {
  constructor({ manager, wishlistRepository, wishlistItemRepository }) {
    super()
    this.manager_ = manager
    this.wishlistRepository_ = wishlistRepository
    this.wishlistItemRepository_ = wishlistItemRepository
  }

    async create(payload) {
    return await this.atomicPhase_(async (transactionManager) => {

      if (!payload.region_id) {
        throw new MedusaError(MedusaError.Types.INVALID_DATA, `A region_id must be provided when creating a wishlist`)
      }

      const wishlistRepository = transactionManager.getCustomRepository(this.wishlistRepository_)
      const createdWishlist = wishlistRepository.create(payload)
      const { id } = await wishlistRepository.save(createdWishlist)

      const [wishlist] = await wishlistRepository.find({
        where: { id },
        relations: ['items', 'items.product']
      })

      return wishlist
    })
  }

  async retrieve(id) {
    return await this.atomicPhase_(async (transactionManager) => {
      const wishlistRepository = transactionManager.getCustomRepository(this.wishlistRepository_)
            const [wishlist] = await wishlistRepository.find({ 
                    where: { id }, 
                    relations: ['items', 'items.product'] 
            })

      if (!wishlist) {
        throw new MedusaError(MedusaError.Types.NOT_FOUND, `Wishlist with ${id} was not found`)
      }

      return wishlist
    })
  }

  async addWishItem(wishlist_id, product_id) {
    return await this.atomicPhase_(async (transactionManager) => {
      const wishlistItemRepository = transactionManager.getCustomRepository(this.wishlistItemRepository_)
      const wishlistRepository = transactionManager.getCustomRepository(this.wishlistRepository_)

      const [item] = await wishlistItemRepository.find({ where: { wishlist_id, product_id } })

      if (!item) {
        const createdItem = wishlistItemRepository.create({ wishlist_id, product_id })
        await wishlistItemRepository.save(createdItem)
      }

            const [wishlist] = await wishlistRepository.find({
        where: { id: wishlist_id },
        relations: ['items', 'items.product']
      })

      return wishlist
    })
  }

  async removeWishItem(id) {
    return await this.atomicPhase_(async (transactionManager) => {
      const wishlistItemRepository = transactionManager.getCustomRepository(this.wishlistItemRepository_)
      const wishlistRepository = transactionManager.getCustomRepository(this.wishlistRepository_)
      const [item] = await wishlistItemRepository.find({ where: { id } })
      const wishlist_id = item.wishlist_id

      if (item) {
        await wishlistItemRepository.remove(item)
      }

            const [wishlist] = await wishlistRepository.find({
        where: { id: wishlist_id },
        relations: ['items', 'items.product']
      })

      return wishlist
    })
  }
}

export default WishlistService

In the WishlistService, you implement four methods:

The create method creates a new wishlist.
The retrieve method retrieves a wishlist and wishlist items associated with it using the wishlist’s ID.
The addWishItem method adds a new wishlist item to the wishlist.
The removeWishItem method deletes a wishlist item from a wishlist using the item’s ID.

Add Wishlist Endpoints

The last step to finish the Medusa server setup is adding custom endpoints so you can use the wishlist functionality from the Storefront.

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

import { json, Router } from 'express'

const route = Router()

export default (app) => {
  app.use('/store/wishlist', route)
  route.use(json())

  // Wishlist
  route.get('/:id', async (req, res) => {
    const wishlistService = req.scope.resolve('wishlistService')
    const wishlist = await wishlistService.retrieve(req.params.id)
    res.json(wishlist)
  })

    route.post('/', async (req, res) => {
    const wishlistService = req.scope.resolve('wishlistService')
    const payload = {region_id: req.body.region_id, customer_id: null}

    if (req.user && req.user.customer_id) {
      const customerService = req.scope.resolve("customerService")
      const customer = await customerService.retrieve(req.user.customer_id)
      payload.customer_id = customer.id
    }

    const wishlist = await wishlistService.create(payload)
    res.json(wishlist)
  })

  // Wishlist items
  route.post('/:id/wish-item', async (req, res) => {
    const wishlistService = req.scope.resolve('wishlistService')
    const wishlist = await wishlistService.addWishItem(req.params.id, req.body.product_id)
    res.json(wishlist)
  })

  route.delete('/:id/wish-item/:item_id', async (req, res) => {
    const wishlistService = req.scope.resolve('wishlistService')
    const wishlist = await wishlistService.removeWishItem(req.params.item_id)
    res.json(wishlist)
  })

  return app
}

You map each endpoint to a method in the WishlistService. All endpoints return a wishlist object with its wishlist items.

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

import { Router, json } from 'express'
import cors from 'cors'
import { projectConfig } from '../../medusa-config'
import wishlist from './wishlist'

const corsOptions = {
  origin: projectConfig.store_cors.split(','),
  credentials: true
}

export default () => {
  const app = Router()
  app.use(cors(corsOptions))

  wishlist(app)

  return app
}

You import your wishlist routes to inject them into Medusa's router. Also, you use the cors library with Medusa’s CORS options. This allows you to use these endpoints on the Storefront.

Running Migrations

In this section, you’ll run the migrations to add the necessary tables for the wishlist functionality to the database.

In your terminal, run the following commands to transpile the TypeScript files to JavaScript files then run the migrations:

yarn run build && medusa migrations run

Test Wishlist Functionality

Start by running your server:

yarn start

This starts your server on port 9000.

To run the following tests, you need to use a tool like Postman to easily send requests to your server.

Test Creating a Wishlist

To create a wishlist you need to associate it with a region ID. So, send a GET request to localhost:9000/store/regions to get the available regions on your Medusa server and copy the first region's id.

Then, send a POST request to localhost:9000/store/wishlist and in the body pass the region_id you copied. For example:

{
  "region_id": "reg_01G6MFABCQ6GWK1DZWZJ8P35JM"
}

The request returns a wishlist object like this one:

{
  "object": "wishlist",
  "region_id": "reg_01G6MFABCQ6GWK1DZWZJ8P35JM",
  "customer_id": null,
  "id": "wish_01G6MGYVABK9ZXNCP5KM2Y9NFS",
    "items": [],
  "created_at": "2022-06-28T06:46:09.482Z",
  "updated_at": "2022-06-28T06:46:09.482Z"
}

Test Add Items to Wishlist

Wishlist items are associated with products. So, you need to retrieve a product ID first.

Send a GET request to localhost:9000/store/products to get the list of products, then, choose one of them and copy its id.

Next, send a POST request to localhost:9000/store/wishlist/YOUR_WISHLIST_ID/wish-item where YOUR_WISHLIST_ID is the id you got in the previous step. In the body, pass the product_id you copied. For example:

{
    "product_id": "prod_01G6MFABJ7QP3W3R8ZSWYDTNVG"
}

The request returns a wishlist object with one item attached to it:

{
    "object": "wishlist",
    "items": [
        {
            "wishlist_id": "wish_01G6MGYVABK9ZXNCP5KM2Y9NFS",
            "product_id": "prod_01G6MFABJ7QP3W3R8ZSWYDTNVG",
            "product": {
                "id": "prod_01G6MFABJ7QP3W3R8ZSWYDTNVG",
                "created_at": "2022-06-28T06:17:29.187Z",
                "updated_at": "2022-06-28T06:17:29.187Z",
                "deleted_at": null,
                "title": "Medusa T-Shirt",
                "subtitle": null,
                "description": "Reimagine the feeling of a classic T-shirt. With our cotton T-shirts, everyday essentials no longer have to be ordinary.",
                ...
            },
            "id": "item_01G6MKY3KZVQF7GQ72Z6GZ1JAQ",
            "created_at": "2022-06-28T07:38:10.937Z",
            "updated_at": "2022-06-28T07:38:10.937Z"
        }
    ],
    "region_id": "reg_01G6MFABCQ6GWK1DZWZJ8P35JM",
    "customer_id": null,
    "id": "wish_01G6MGYVABK9ZXNCP5KM2Y9NFS",
    "created_at": "2022-06-28T06:46:09.482Z",
    "updated_at": "2022-06-28T06:46:09.482Z"
}

If everything works as expected, you can go to the next section, where you implement this wishlist functionality in the Gatsby storefront.

Set up Storefront

In this section, you'll learn how to integrate the wishlist feature you just added to your Medusa server on a Gatsby Storefront.

Add Wishlist Popover

Start by adding the icon that represents the wishlist in the header. Create the file src/icons/wishlist.jsx with the following content:

import React from "react"

const WishlistIcon = ({ props, fill }) => {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="1.5rem"
      height="1.5rem"
      viewBox="0 0 256 256"
      {...props}
    >
      {!fill ? (
        <path
          fill="currentColor"
          d="M128 220.2a13.6 13.6 0 0 1-9.9-4.1L35 133a58 58 0 0 1 2.2-84.2a56.5 56.5 0 0 1 41.6-14a62.8 62.8 0 0 1 40.3 18.3L128 62l11-11a57.9 57.9 0 0 1 84.1 2.2a56.2 56.2 0 0 1 14.1 41.6a62.8 62.8 0 0 1-18.3 40.3l-81 81a13.6 13.6 0 0 1-9.9 4.1Zm5.6-8.3ZM75 46.7a44 44 0 0 0-29.7 11.1a45.8 45.8 0 0 0-1.8 66.7l83.1 83.1a1.9 1.9 0 0 0 2.8 0l81-81c18.2-18.2 19.9-47.5 3.8-65.3a45.8 45.8 0 0 0-66.7-1.8l-15.3 15.2a6.1 6.1 0 0 1-8.5 0l-13.1-13.1A50.3 50.3 0 0 0 75 46.7Z"
        ></path>
      ) : (
        <path
          fill="currentColor"
          d="m220.3 136.5l-81 81a15.9 15.9 0 0 1-22.6 0l-83.1-83.1a59.9 59.9 0 0 1 2.3-87c23.3-21.1 61.3-19.1 84.6 4.3l7.5 7.4l9.6-9.5A60.4 60.4 0 0 1 181.5 32a59.8 59.8 0 0 1 43.1 19.9c21 23.3 19.1 61.3-4.3 84.6Z"
        ></path>
      )}
    </svg>
  )
}

export default WishlistIcon

Next, create the file src/components/header/wishlist-popover-item.jsx with the following content:


import React from "react"
import RegionalLink from '../utility/regional-link'

const WishlistPopoverItem = ({ item }) => {
  return (
    <RegionalLink to={item.handle} className="font-normal">
      <div className="flex hover:bg-gray-100">
        <div className="overflow-hidden rounded-md mr-4">
          <img className="w-16 h-auto" src={item.thumbnail} alt={item.title} />
        </div>
        <div className="flex items-center">
          <div>
            <p className="font-medium text-sm">{item.title}</p>
          </div>
        </div>
      </div>
    </RegionalLink>
  )
}

export default WishlistPopoverItem

This component renders the wishlist items inside the wishlist popover. It only shows the product's title and thumbnail, and it's wrapped with a RegionalLink component that allows visiting the product detail page.

The next step is to add a WishlistContext to keep the wishlist in sync across the Storefront. It would be best if you had a useWishlist hook to access the Medusa context.

Create the file src/hooks/use-wishlist.js with the following content:

import { useContext } from "react"
import WishlistContext from '../context/wishlist-context'

export const useWishlist = () => {
  const context = useContext(WishlistContext)

  if (!context) {
    throw new Error(
      "useWishlist hook was used but a WishlistContext. Provider was not found in the parent tree. Make sure this is used in a component that is a child of WishlistProvider"
    )
  }

  return context
}

Next, create the file src/context/wishlist-context.js with the following content:

import React, { createContext, useEffect, useState } from "react"
import { useRegion } from "../hooks/use-region"
import { useMedusa } from "../hooks/use-medusa"

const defaultWishlistContext = {
  wishlist: {
    items: [],
  },
  loading: false,
  actions: {
    addItem: async () => {},
    removeItem: async () => {},
  },
}

const WishlistContext = createContext(defaultWishlistContext)
export default WishlistContext

const WISHLIST_ID = "wishlist_id"
const isBrowser = typeof window !== "undefined"

export const WishlistProvider = props => {
  const [wishlist, setWishlist] = useState(defaultWishlistContext.wishlist)
  const [loading, setLoading] = useState(defaultWishlistContext.loading)
  const { region } = useRegion()
  const { client } = useMedusa()

  const setWishlistItem = wishlist => {
    if (isBrowser) {
      localStorage.setItem(WISHLIST_ID, wishlist.id)
    }
    setWishlist(wishlist)
  }

  useEffect(() => {
    const initializeWishlist = async () => {
      const existingWishlistId = isBrowser
        ? localStorage.getItem(WISHLIST_ID)
        : null

      if (existingWishlistId && existingWishlistId !== "undefined") {
        try {
          const { data } = await client.axiosClient.get(
            `/store/wishlist/${existingWishlistId}`
          )

          if (data) {
            setWishlistItem(data)
            return
          }
        } catch (e) {
          localStorage.setItem(WISHLIST_ID, null)
        }
      }

      if (region) {
        try {
          const { data } = await client.axiosClient.post("/store/wishlist", {
            region_id: region.id,
          })

          setWishlistItem(data)
          setLoading(false)
        } catch (e) {
          console.log(e)
        }
      }
    }

    initializeWishlist()
  }, [client, region])

  const addWishItem = async product_id => {
    setLoading(true)
    try {
      const { data } = await client.axiosClient.post(
        `/store/wishlist/${wishlist.id}/wish-item`,
        { product_id }
      )
      setWishlistItem(data)
      setLoading(false)
    } catch (e) {
      console.log(e)
    }
  }

  const removeWishItem = async id => {
    setLoading(true)
    try {
      const { data } = await client.axiosClient.delete(
        `/store/wishlist/${wishlist.id}/wish-item/${id}`
      )
      setWishlistItem(data)
      setLoading(false)
    } catch (e) {
      console.log(e)
    }
  }

  return (
    <WishlistContext.Provider
      {...props}
      value={{
        ...defaultWishlistContext,
        loading,
        wishlist,
        actions: {
          addWishItem,
          removeWishItem,
        },
      }}
    />
  )
}

First, you define a default wishlist context with some default properties and create a WishlistContext. Then, you create a WishlistProvider that initializes the wishlist and exposes some methods to add and remove wishlist items from the created Wishlist.

You need to add the WishlistContext to the MedusaProvider to be able to use it.

Open the file src/context/medusa-context.js, import the WishlistProvider at the beginning of the file, and in the returned JSX in MedusaProvider wrap the CartProvider with the WishlistProvider :

import { WishlistProvider } from "./wishlist-context"

export const MedusaProvider = ({ children, client }) => {
  return (
    //...
          <WishlistProvider>
            <CartProvider>{children}</CartProvider>
          </WishlistProvider>
    //...
  )
}

Next, create the file src/components/header/wishlist-popover.jsx with the following content:

import { Menu } from "@headlessui/react"
import { Link } from "gatsby"
import React from "react"
import PopoverTransition from "../popover-transition"
import WishlistIcon from "../../icons/wishlist"
import WishlistPopoverItem from "./wishlist-popover-item"
import { useWishlist } from "../../hooks/use-wishlist"

const WishlistPopover = () => {
  const { wishlist } = useWishlist()
  const iconStyle = { className: "mr-1" }

  return (
    <Menu as="div" className="relative inline-block text-left mr-2">
      <div>
        <Menu.Button className="inline-flex items-center justify-center w-full rounded p-2 text-sm font-medium hover:opacity-1/2">
          <WishlistIcon props={iconStyle} />
          <span>Wish List</span>
        </Menu.Button>
      </div>

      <PopoverTransition>
        <Menu.Items className="origin-top-right absolute right-0 mt-2 w-96 px-6 py-4 rounded-md shadow-lg bg-white ring-1 ring-black ring-opacity-5 focus:outline-none">
          <div className="py-1">
            {wishlist.items < 1 ? (
              <div className="flex justify-center">
                <p>Your wish list is empty</p>
              </div>
            ) : (
              <>
                {wishlist.items?.map((item, i) => {
                  return (
                    <div className="py-2 first:pt-0" key={i}>
                      <Menu.Item>
                        {() => (
                          <WishlistPopoverItem
                            item={item.product}
                            currencyCode="usd"
                          />
                        )}
                      </Menu.Item>
                    </div>
                  )
                })}
                <div className="flex flex-col mt-4">
                  <Menu.Item>
                    <Link to="/wishlist">
                      <button className="text-ui-dark py-2 text-sm w-full border px-3 py-1.5 rounded hover:text-black hover:bg-gray-100">
                        View Wish List
                      </button>
                    </Link>
                  </Menu.Item>
                </div>
              </>
            )}
          </div>
        </Menu.Items>
      </PopoverTransition>
    </Menu>
  )
}

export default WishlistPopover

Here you use the WishlistIcon and WishlistPopoverItem components that you created previously. Also, you use the useWishlist hook to get the wishlist items from the wishlist context and render them in the wishlist popover component.

Finally, to show the WishlistPopover in the storefront’s header open the file src/components/header/index.jsx and import the component at the beginning of the file:

import WishlistPopover from "./wishlist-popover"

Then, update the mockData object by adding the wishlist property at the end with some demo data:


const mockData = {
  customer: {...},
  cart: {...},
  regions: [...],
  wishlist: {
    items: [
      {
        id: "1",
        title: "Medusa Tote",
        thumbnail:
          "https://medusa-public-images.s3.eu-west-1.amazonaws.com/tshirt.png",
      },
    ],
  },
}

Lastly, add the WishlistPopover just before the CartPopover in the returned JSX:

//...
<WishlistPopover wishlist={mockData.wishlist} />
<CartPopover cart={mockData.cart} />
//...

Test Wishlist Popover

To test out the Wishlist Popover make sure your Medusa server is running and start your Gatsby storefront:

yarn start

Then, go to the URL http://localhost:8000. You should see the wishlist icon in the header on the left of the cart icon. Click on the heart icon and the wishlist popover will be shown.

Add a wishlist button on the product detail page

You will implement the functionality to add or remove items to or from the Wishlist in the product detail page.

Open the file src/templates/product.js and at the beginning of the Product function add the following snippet just after the useCart hook:

const {
  wishlist,
  actions: { addWishItem, removeWishItem },
} = useWishlist()

You get access to the wishlist object in the wishlist context and the methods to add and remove wishlist items.

Next, after the handleAddToCart function, add a state variable to track whether the product is already on the wishlist or not:

const [onWishlist, setOnWishlist] = useState(() =>
  wishlist.items.some(i => i.product_id === product.id)
)

Don’t forget to import the useWishlist and useState hooks at the start of the file

import React, { useEffect, useState } from "react"
import { useWishlist } from "../hooks/use-wishlist"

Then, add the toggleWishlist function to add or remove the item from the Wishlist after the onWishlist state variable:

const toggleWishlist = async () => {
  if (!onWishlist) {
    await addWishItem(product.id)
    setOnWishlist(true)
  } else {
    const [item] = wishlist.items.filter(i => i.product_id === product.id)
    await removeWishItem(item.id)
    setOnWishlist(false)
  }
}

This function is where you use the wishlist actions from the wishlist context. If the item is not on the wishlist, you call the addWishItem action. Otherwise, you call the removeWishItem action.

To use this function, find the <h1> HTML element that renders the product's title and replaces it with the following code:

// Replace this line
<!-- <h1 className="font-semibold text-3xl">{product.title}</h1> -->

// with this 
<div className="flex justify-between items-center">
  <h1 className="font-semibold text-3xl">{product.title}</h1>
  <button onClick={toggleWishlist}>
    <WishlistIcon fill={onWishlist} />
  </button>
</div>

You use the WishlistIcon to let customers know if that product is on the Wishlist or not. If the heart icon is outlined, that means the product is not on the Wishlist. Otherwise, if the icon is filled then the product is on the Wishlist.

Remember to import the WishlistIcon component at the beginning

import WishlistIcon from "../icons/wishlist"

Test Wishlist Button

Run your Gatsby Storefront if it’s not running and visit any product detail page. You should see the heart icon on the top-right of the product's info.

If you click on it, the addWishItem action is triggered, then the icon will change to black. In the wishlist popover, you should see the newly added item.

If you click on it again the removeWishItem action is called and the item is deleted from the wishlist.

Add Wishlist Listing Page

The last thing to do is to implement the wishlist page to see all the items added to the Wishlist and remove them from it.

Create the file src/components/wishlist/wishlist-item.jsx with the following content:

import React from "react"
import WishlistIcon from "../../icons/wishlist"
import { useWishlist } from "../../hooks/use-wishlist"
import RegionalLink from "../utility/regional-link"

const WishlistItem = ({ item }) => {
  const {
    actions: { removeWishItem },
  } = useWishlist()
  const { product } = item

  return (
    <div className="flex mb-6 last:mb-0">
      <div className="bg-ui rounded-md overflow-hidden mr-4 max-w-1/4">
        <img
          className="h-auto w-full object-cover"
          src={product.thumbnail}
          alt={product.title}
        />
      </div>
      <div className="flex text-sm flex-grow py-2 justify-between space-x-8">
        <RegionalLink to={product.handle} className="w-full">
          <div className="flex flex-col justify-between w-full hover:text-green-400">
            <div className="flex flex-col">
              <p className="font-semibold mb-4">{product.title}</p>
              <p>{product.description}</p>
            </div>
          </div>
        </RegionalLink>

        <div className="flex flex-col justify-between">
          <div className="flex justify-end w-full">
            <button onClick={async () => await removeWishItem(item.id)}>
              <WishlistIcon fill={true} />
            </button>
          </div>
        </div>
      </div>
    </div>
  )
}

export default WishlistItem

This component is responsible for rendering each wishlist item on the wishlist page. It shows the product's image, title, and description. It also has a button with the WishlistIcon component to call the removeWishItem action.

Next, create the file src/pages/wishlist.js with the following content:

import React from "react"
import SearchEngineOptimization from "../components/utility/seo"
import { useWishlist } from '../hooks/use-wishlist'
import WishlistItem from '../components/wishlist/wishlist-item'

const Wishlist = () => {
  const { wishlist } = useWishlist()

  return (
    <div className="layout-base">
      <SearchEngineOptimization title="Wishlist" />
      <div className="flex relative flex-col-reverse lg:flex-row mb-24">
        <div className="flex flex-col">
          <div className="mb-8">
            <h1 className="font-semibold text-4xl">Wish list</h1>
          </div>
          <div className="w-full grid grid-cols-2 gap-16">
            {wishlist.items.map(item => {
              return (
                <WishlistItem
                  key={item.id}
                  item={item}
                  currencyCode={wishlist.region?.currency_code || 'usd'}
                />
              )
            })}
          </div>
        </div>
      </div>
    </div>
  )
}

export default Wishlist

This page is straightforward. it gets the wishlist items from the wishlist object retrieved using the useWishlist hook and renders them on the page.

Test Wishlist Listing Page

Re-run your Gatsby Storefront and try adding some products to the Wishlist. Once you have some products added, open the wishlist popover and then click on the View Wish List button.

You’ll then be redirected to the wishlist page where you can view all items in the wishlist.

If you click on the heart icon next to any of the products, the product gets removed from the wishlist. The wishlist popover will also be updated.

What’s next

There are more functionalities you can implement related to the wishlist:

Allow moving items from the wishlist to the cart and vice versa.
Allow logged-in customers to have multiple wishlists and update or delete them.
Add notes to wishlist items.

You can also check out the following resources to dive more into Medusa's core:

Learn how to add a subscriber in your Medusa server that listens to events to perform an action.
Learn how to send notifications when an event occurs.
Learn how to extract your wishlist functionality into a medusa plugin.

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

Medusa + Nuxt.js + Stripe - How to Create a Nuxt.js Ecommerce Storefront from Scratch Using Medusa Part 3

Carlos Padilla — Tue, 28 Jun 2022 11:05:30 +0000

Introduction

Medusa is an open source headless commerce that allows you to build online stores through its APIs with just a few commands. One of its key features is the ease to integrate different payment providers to accept payments when customers place their orders.

In the second part of this series, you added the cart functionality to your Nuxt.js storefront. Following from there, in this guide you will learn how to integrate and use Stripe as a payment provider to allow customers to make payments and place orders.

You can find the code of this tutorial at this GitHub repository.

Prerequisites

To follow along with this tutorial you need the following:

A Medusa server with some dummy data to work with. If you don’t have one, you can follow the QuickStart guide to install one.
An admin dashboard to manage your ecommerce store. Medusa provides an intuitively designed admin dashboard that you can use.
The Nuxt.js storefront from the second part of the series. You can clone the part-02/cart-flow branch of this GitHub repository and continue on from there.
A Stripe account to retrieve the API Keys and secrets to connect your Medusa server with Stripe. The account should be in sandbox mode to test out the integration.

Medusa Server Setup

This section guides you over the steps necessary to add Stripe as a payment provider to your Medusa server.

Install Stripe Plugin

Go to your Medusa server directory with cd medusa-server and in the root of the project install the Stripe plugin with the following command:



yarn add medusa-payment-stripe

Stripe Plugin Configuration

Once the plugin is installed, you need to add configurations for it.

Open your medusa-config.js file and look for the plugins section. Then, add the following object to the plugins array:



const plugins = [
  //...,
  {
    resolve: `medusa-payment-stripe`,
    options: {
      api_key: process.env.STRIPE_API_KEY,
      webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
    },
  },
];

Where STRIPE_API_KEY is the Secret key from Stripe. you can retrieve it from Stripe’s dashboard by click on the Developers link at the top right then choosing API Keys from the left sidebar and copying the Secret key.

Next, you need to add the secret key to your environment variables. In your Medusa server, open your .env file and add the Stripe key:



STRIPE_API_KEY=sk_test_KALKSD313LKKMKCDJNJ...

⚠️ Later on you will come back to stripe’s dashboard to copy the Publishable key and add it to the Nuxt.js storefront.

Admin Dashboard Setup

To use Stripe as a payment provider in your storefront, you must add it as a payment provider in a region first.

This section guides you in how to do that using Medusa’s Admin Dashboard.

Add Stripe to a Region

Make sure your Medusa server is running. Then, start your admin panel with yarn run develop. It should run on localhost:7000 by default.

Open the Admin dashboard in your browser, log in, and click on Settings in the sidebar. Then, choose Regions.

Next, for every region you want to add Stripe as a payment provider in, scroll down the form on the right to Payment Providers and choose Stripe. Then, click Save.

⚠️ This set up is very important. If the region doesn’t have Stripe as a payment provider, it will not be available on the storefront.

Storefront Set Up

In this section you’ll learn more about Medusa’s checkout flow and how to integrate Stripe as a payment provider.

Workflow Overview

In a nutshell, the workflow the Nuxt.js storefront has to follow to implement a full checkout workflow:

When the user visits the website, an empty cart is created on the Medusa server with a default region and country code.
During checkout, the user fills up a form with their email and shipping address.
The user chooses a fulfillment provider for the shipping method.
The user chooses a payment provider and fills any necessary information such as credit card details.
If the payment is processed successfully, the order is placed.

At each of these steps, the cart is updated on the server with new information based on what the user chooses.

Install Nuxt.js Stripe Module

Before you start the stripe implementation, you need to install a Nuxt.js module to help you with that. You’ll be using Nuxt-stripe-module to handle the payment confirmation with stripe.

In the directory of your Nuxt.js storefront, run the following command:



yarn add nuxt-stripe-module

After the installation is complete, open nuxt-config.js and add nuxt-stripe-module to the modules section with the publishable key passed as an option:



modules: [
  ...
  ['nuxt-stripe-module', {
    publishableKey: process.env.PUBLISHABLE_KEY
  }]
],

Next, go back to the Stripe developer dashboard and copy the publishable key from the API keys page.

Then, create a .env file in the root directory of the project if it doesn’t already exist and add the publishable key:



PUBLISHABLE_KEY=<YOUR_PUBLISHABLE_KEY>

Where <YOUR_PUBLISHABLE_KEY> is the key you copied.

Add Checkout Page

Once the Stripe module is added to the Nuxt.js storefront, the next step is to add the checkout page and its components to actually be able to use it.

Create the file pages/checkout/index.vue with the following content:



<template>
  <div class="bg-ui ">
    <div class="container mx-auto p-8 relative">
      <div class="layout-base">
        <div class="flex flex-col-reverse lg:flex-row">
          <div class="lg:w-1/2">
            <checkout-flow />
          </div>
          <div class="lg:w-1/2 lg:pl-16">
            <checkout-summary />
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script>
export default {
  name: 'Checkout'
}
</script>

This is the Checkout page. It loads the <checkout-flow /> component that is in charge of all the checkout process. It also loads the <checkout-summary /> component that shows to the user a cart’s summary with the products in it and the totals of their cart including shipping and taxes amounts.

Add Checkout Components

Create the file components/Totals.vue with the following content:



<template>
  <div class="my-4 border-t bt-gray-100">
    <div class="font-light text-sm space-y-3 mt-3">
      <div class="flex items-center justify-between mb-2">
        <p>Subtotal</p>
        <p class="font-medium">
          {{ formatPrice(item.subtotal, currencyCode ) }}
        </p>
      </div>

      <div v-if="item.shipping_total" class="flex items-center justify-between mb-2">
        <p>Shipping</p>
        <p class="font-medium">
          {{ formatPrice(item.shipping_total, currencyCode) }}
        </p>
      </div>

      <div class="flex items-center justify-between mb-2">
        <p>Taxes</p>
        <p class="font-medium">
          {{ formatPrice(item.tax_total, currencyCode) }}
        </p>
      </div>

      <div class="h-px w-full bg-ui-medium mb-2" />

      <div class="flex items-center justify-between">
        <p>Total</p>
        <p class="font-medium">
          {{ formatPrice(item.total, currencyCode) }}
        </p>
      </div>
    </div>
  </div>
</template>

<script>
import { formatPrice } from '@/utils/format-price'

export default {
  name: 'Totals',
  props: {
    item: {
      type: Object,
      default () { return {} }
    }
  },
  computed: {
    currencyCode () {
      return this.item.currency_code || this.$store.getters['cart/cartCurrencyCode']
    }
  },
  methods: {
    formatPrice
  }
}
</script>

This component is used to display the totals for the customer. It can be used in multiple places such as the checkout or order summary pages.

Next, create the file components/Checkout/Item.vue with the following content:



<template>
  <div class="flex">
    <div class="bg-ui rounded-md overflow-hidden mr-4 max-w-1/4">
      <img
        class="h-auto w-full object-cover"
        :src="item.thumbnail"
        :alt="item.title"
      >
    </div>
    <div class="flex justify-between w-full text-sm py-2">
      <div class="flex flex-col justify-between">
        <div>
          <p class="font-semibold mb-2">
            {{ item.title }}
          </p>
          <p>Variant: {{ item.description }}</p>
        </div>
        <div>
          <p class="mb-2">
            Quantity: {{ item.quantity }}
          </p>
          <p class="font-medium">
            Total: {{ formatPrice(item.unit_price, cartCurrencyCode, item.quantity) }}
          </p>
        </div>
      </div>
      <div>
        <p class="font-medium">
          {{ formatPrice(item.unit_price, cartCurrencyCode, 1) }}
        </p>
      </div>
    </div>
  </div>
</template>

<script>
import { mapGetters } from 'vuex'
import { formatPrice } from '@/utils/format-price'

export default {
  name: 'CartItem',
  props: {
    item: {
      type: Object,
      default () {
        return {}
      }
    }
  },
  computed: {
    ...mapGetters({ cartCurrencyCode: 'cart/cartCurrencyCode' })
  },
  methods: {
    formatPrice
  }
}
</script>

This component is used to render each product that is added to the cart. It shows basic information as the product’s title, description, quantity, and price.

Next, create the file components/Checkout/Summary.vue with the following content:



<template>
  <div class="flex w-full flex-col lg:relative bg-white mb-4 lg:mb-0 rounded-lg shadow py-6 px-8 max-h-review overflow-hidden">
    <div class="flex-grow overflow-y-scroll">
      <checkout-item
        v-for="item in items"
        :key="item.id"
        :item="item"
        class="mb-4 last:mb-0"
      />
    </div>

        <totals :item="$store.state.cart.cart" />  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  name: 'CheckoutSummary',
  computed: {
    ...mapGetters({ items: 'cart/items' })
  }
}
</script>

The <checkout-summary /> component uses the two previous components to show the items in the cart and the cart totals.

For the <checkout-flow> component, you’ll create a placeholder component for now. Create the file components/Checkout/Flow.vue with the following content:



<template>
  <div class="flex flex-col">
    Section for checkout flow
  </div>
</template>

<script>
export default {
  name: 'CheckoutFlow',
}
</script>

Next, open the components/Dropdowns/CartPopover.vue and replace the “Checkout” button with the following content:



<nuxt-link to="/checkout">
  <button class="btn-ui font-medium px-4 py-2 mb-2 text-sm w-full">
    Checkout
  </button>
</nuxt-link>

Now, when the customer clicks on the “Checkout” button in the cart popover they are taken to the Checkout page.

Test it Out

Make sure your Medusa server is running. Then, run your Nuxt.js storefront:



yarn run dev

Once the storefront is running, go to the products page on http://localhost:3333/products, and add a few products to your cart. Then, at the top-right click on the bag icon to see the cart popover.

Click on the “Checkout” button. You’ll be taken to the checkout page which shows the Summary and Flow components you created earlier.

Set Up Checkout Flow

In this part, you will go through the steps needed to implement the checkout flow in your Nuxt.js storefront including the step related to adding a custom payment provider.

To complete the checkout, the customer has to follow and complete four main steps:

Give their email address.
Fill up a form with their shipping address.
Choose a shipping option.
Choose a payment method to complete their purchase.

Each of these steps will become a component of their own and they will be rendered in the checkout-flow component.

Wrapper Components

Create the file components/Checkout/Step.vue with the following content:



<template>
  <div class="text-left mb-4 last:mb-0 w-full">
    <div class="bg-white rounded-lg p-8 shadow">
      <div class="w-full">
        <div class="flex items-center justify-between w-full">
          <h3 class="font-bold">
            {{ title }}
          </h3>
          <checkout-check-icon v-if="showSuccessIcon" class="bg-green-400" />
        </div>
      </div>

      <slot />
    </div>
  </div>
</template>

<script>
export default {
  name: 'CheckoutStep',
  props: {
    showSuccessIcon: {
      type: Boolean,
      default: false
    },
    title: {
      type: String,
      default: 'Title'
    }
  }
}
</script>

This component is the wrapper component for each of the components specific in each step. It has only two props; one for the title and the other one to show a success icon once that step has been completed.

Next, create the file components/Checkout/CheckIcon.vue with the following content:



<template>
  <span
    class="rounded-3xl flex bg-green-400 items-center justify-center"
    :class="`w-${size} h-${size}`"
  >
    <svg
      :class="`w-${size/2} h-${size/2}`"
      fill="#ffffff"
      version="1.1"
      xmlns="http://www.w3.org/2000/svg"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      viewBox="0 0 64 64"
      xml:space="preserve"
    >
      <path
        d="M62.3,12.7c-0.7-0.7-1.8-0.7-2.5,0L23.3,48.1c-0.3,0.3-0.7,0.3-1,0L4.2,30.5c-0.7-0.7-1.8-0.7-2.5,0c-0.7,0.7-0.7,1.8,0,2.5l18.1,17.6c0.8,0.8,1.9,1.2,2.9,1.2c1.1,0,2.1-0.4,2.9-1.2l36.5-35.4C62.9,14.5,62.9,13.4,62.3,12.7z"
      />
    </svg>
  </span>
</template>

<script>
export default {
  name: 'CheckIcon',
  props: {
    size: {
      type: Number,
      default: 8
    }
  }
}
</script>

This component just displays a check SVG icon.

Form Input Components

Before you create the components for each of the steps, you need to install a package to help you manage form inputs.

Run the following command to install the vue-formulate package:



yarn add @braid/vue-formulate

Then, update the build modules property in your nuxt.confg.js file to include the package:



export default {
    ...

  buildModules: [
        ...
    '@braid/vue-formulate/nuxt'
  ],

    ...
}

You also need to install sass to override some style for the form inputs that you will use later. So, run the following command to install it:



yarn add --dev sass sass-loader@10

Contact Component

This component is the simplest of the four. Here, the customer has to write their email address. Then, the email will be validated and, if everything is valid, the customer can go to the next step.

First, you have to add a new state and a new mutation to the cart store. Open the store/cart.js file and update the state function and the mutations as the following:



export const state = () => ({
  cart: {...},

  email: null
})

export const mutations = {
  SET_CART (state, cart) {...},

  SET_CART_EMAIL (state, email) {
    state.email = email
  }
}

You can now save the customer’s email to the store and retrieve it later whenever necessary.

Next, create the file components/Checkout/Steps/Contact.vue with the following content:



<template>
  <checkout-step title="Contact" :show-success-icon="isCompleted">
    <FormulateForm
      v-show="isOpen"
      v-slot="{ hasErrors }"
      class="mt-4"
      @submit="submitHandler"
    >
      <FormulateInput
        type="email"
        label="Email"
        name="email"
        class="w-full"
        validation="bail|required|email"
      />
      <div class="flex items-center justify-end mt-6">
        <FormulateInput
          type="submit"
          label="Next"
          :disabled="hasErrors"
          input-class="btn-ui"
        />
      </div>
    </FormulateForm>
  </checkout-step>
</template>

<script>
export default {
  name: 'Contact',
  props: {
    isCompleted: {
      type: Boolean,
      default: false
    },
    isOpen: {
      type: Boolean,
      default: true
    },
    step: {
      type: Number,
      default: 1
    }
  },
  methods: {
    submitHandler (data) {
      this.$store.commit('cart/SET_CART_EMAIL', data.email)
      this.$emit('updateSteps', this.step)
    }
  }
}
</script>

You use the checkout-step component created previously. Inside it there is a short form with only one input field to validate the email and a submit button.

If the form is valid, it will call the submitHandler method which will commit the cart/SET_CART_EMAIL mutation to update the customer email on the cart store.

Later on the email will be sent to the Medusa server to associate it with the cart. This method also emits an event to call a function on the parent component (<checkout-flow />) to update the visibility for the current component and the next one. This component will also be marked as completed.

Address Component

This component includes the form where the customer enters their shipping info.

Create the file components/Checkout/Steps/Address.vue with the following content:



<template>
  <checkout-step title="Address" :show-success-icon="isCompleted">
    <FormulateForm
      v-show="isOpen"
      v-slot="{ hasErrors }"
      name="formAddress"
      class="space-y-4"
      :keep-model-data="true"
      @submit="submitHandler"
    >
      <div class="flex space-x-8">
        <FormulateInput
          name="first_name"
          label="First name*"
          validation="required"
          class="w-1/2"
        />

        <FormulateInput
          name="last_name"
          label="Last name*"
          validation="required"
          class="w-1/2"
        />
      </div>

      <FormulateInput
        name="company"
        label="Company"
        class="w-full"
      />

      <FormulateInput
        name="address_1"
        label="Address*"
        validation="required"
        class="w-full"
      />

      <FormulateInput
        name="address_2"
        label="Apartment, suite, etc"
        class="w-full"
      />

      <div class="flex space-x-8">
        <FormulateInput
          type="select"
          name="country_code"
          label="Country*"
          validation="required"
          class="w-1/2"
          :options="countries"
        />

        <FormulateInput
          name="city"
          label="City*"
          validation="required"
          class="w-1/2"
        />
      </div>

      <div class="flex space-x-8">
        <FormulateInput
          name="province"
          label="Province"
          class="w-1/2"
        />

        <FormulateInput
          name="postal_code"
          label="ZIP / Postal Code*"
          validation="required|number"
          class="w-1/2"
        />
      </div>

      <FormulateInput
        name="phone"
        label="Phone"
        class="w-full"
      />

      <div class="flex items-center justify-between mt-4">
        <div
          class="text-gray-500 flex items-center text-sm transform transition cursor-pointer"
          hover="text-black -translate-x-2"
          @click="$emit('updateSteps', step, false)"
        >
          <span class="w-2.5 h-2.5 mr-1">
            <svg
              fill="#000000"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
              viewBox="0 0 64 64"
            >
              <g>
                <path
                  d="M45,62.8c-0.5,0-0.9-0.2-1.3-0.6L18.6,35.4c-1.7-1.9-1.7-4.9,0-6.7L43.7,1.8c0.7-0.7,1.8-0.7,2.5-0.1 c0.7,0.7,0.7,1.8,0.1,2.5L21.1,31c-0.5,0.5-0.5,1.4,0,2l25.2,26.8c0.7,0.7,0.6,1.8-0.1,2.5C45.9,62.6,45.4,62.8,45,62.8z"
                />
              </g>
            </svg>
          </span>

          <span>Go back</span>
        </div>

        <FormulateInput
          type="submit"
          label="Next"
          :disabled="hasErrors"
          input-class="btn-ui"
          class="mt-4"
        />
      </div>
    </FormulateForm>
  </checkout-step>
</template>

<script>
export default {
  name: 'Address',
  props: {
    isCompleted: {
      type: Boolean,
      default: false
    },
    isOpen: {
      type: Boolean,
      default: true
    },
    step: {
      type: Number,
      default: 1
    }
  },
  computed: {
    countries () {
      return this.$store.state.region.countries.map(country => ({ label: country.display_name, value: country.iso_2 }))
    }
  },
  methods: {
    submitHandler (data) {
      this.$store.dispatch('cart/updateCart', {
        shipping_address: data,
        email: this.$store.state.cart.email
      })
      this.$emit('updateSteps', this.step)
    }
  }
}
</script>

Similarly, here you use the checkout-step component, but this time inside you will find a long form with several form inputs that will allow you to get the info to fill up the shipping address object needed to update the cart on the Medusa server.

If the form is submitted and valid, it will call the submitHandler method which will dispatch the next action to the cart store defined in store/cart.js.

In that action, you are sending a POST request to the endpoint /store/carts/:cartId with the customer’s email and shipping address. On the Medusa server, a new address will be created and associated with the customer’s cart.

Then, when the response from the server is received, a mutation is committed to update the cart info in the store.

Lastly, the submitHandler function will emit an event to update the visibility for the address component and mark it as completed.

Delivery Component

After the cart is updated with the customer’s address, you should display the shipping options to the customers so they can choose their preferred option.

To be able to do that, add the next state, mutation and action to the cart store in store/cart.js:



export const state = () => ({
    //...
  shippingOptions: []
})

export const mutations = {
  //...
  SET_SHIPPING_OPTIONS (state, shippingOptions) {
    state.shippingOptions = shippingOptions
  },
}

export const actions = {
    //...
    async getCartShippingOptions ({ state, commit }) {
    const { data: { shipping_options: options } } = await this.$axios(`/shipping-options/${state.cart.id}`)
    commit('SET_SHIPPING_OPTIONS', options)
  },
}

In this action you are sending a GET request to the endpoint /store/shipping-options/:cartId that responds with an updated list of shipping options. Then, when the response is received, a mutation is committed to update the shipping options in the store.

These shipping options are rendered in the component you’ll create next to allow the customer to choose one.

Create the file components/Checkout/Steps/Delivery.vue with the following content:



<template>
  <checkout-step title="Delivery method" :show-success-icon="isCompleted">
    <div v-show="isOpen" class="my-6">
      <div class="text-gray-700 text-xs flex items-center mb-4">
        <div class="bg-gray-400 text-white w-4 h-4 rounded-lg text-center mr-2">
          !
        </div>
        <p>Taxes may apply, and will be added upon continuation to the next step.</p>
      </div>

      <div class="space-y-4">
        <div
          v-for="option in shippingOptions"
          :key="option.id"
          class="shadow rounded-md p-4 w-full border-transparent flex justify-between items-center cursor-pointer"
          @click="$store.dispatch('cart/addShippingMethod', option.id)"
        >
          <div>
            <div class="font-semibold text-sm">
              {{ option.name }}
            </div>
            <div class="text-xs text-gray-500 mt-2">
              {{ formatPrice(option.amount, cartCurrencyCode) }}
            </div>
          </div>
          <checkout-check-icon
            v-if="shippingMethod === option.id"
          />
        </div>
      </div>

      <div class="w-full flex items-center justify-between mt-4">
        <button
          class="text-gray-500 flex items-center text-sm transform transition"
          hover="text-black -translate-x-2"
          @click="$emit('updateSteps', step, false)"
        >
          <span class="w-2.5 h-2.5 mr-1">
            <svg
              fill="#000000"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
              viewBox="0 0 64 64"
            >
              <g>
                <path
                  d="M45,62.8c-0.5,0-0.9-0.2-1.3-0.6L18.6,35.4c-1.7-1.9-1.7-4.9,0-6.7L43.7,1.8c0.7-0.7,1.8-0.7,2.5-0.1 c0.7,0.7,0.7,1.8,0.1,2.5L21.1,31c-0.5,0.5-0.5,1.4,0,2l25.2,26.8c0.7,0.7,0.6,1.8-0.1,2.5C45.9,62.6,45.4,62.8,45,62.8z"
                />
              </g>
            </svg>
          </span>

          <span>Go back</span>
        </button>

        <FormulateInput
          type="button"
          label="Next"
          input-class="btn-ui"
          @click="$emit('updateSteps', step, true)"
        />
      </div>
    </div>
  </checkout-step>
</template>

<script>
import { mapGetters } from 'vuex'
import { formatPrice } from '@/utils/format-price'

export default {
  name: 'Delivery',
  props: {
    isCompleted: {
      type: Boolean,
      default: false
    },
    isOpen: {
      type: Boolean,
      default: true
    },
    step: {
      type: Number,
      default: 1
    }
  },
  computed: {
    ...mapGetters({
      shippingOptions: 'cart/shippingOptions',
      cartCurrencyCode: 'cart/cartCurrencyCode',
      shippingMethod: 'cart/shippingMethod'
    })
  },
    created () {
    this.$store.dispatch('cart/getCartShippingOptions')
  },
  methods: {
    formatPrice
  }
}
</script>

When this component is created, it dispatches the getCartShippingOptions action to fetch all the shipping options. Then, you loop the shippingOptions array to show the list to the customer.

When the list is rendered and the customer clicks on one of the available options, an action is dispatched on the cart’s store to add that option as a shipping method to the current cart.

Finally, the form input button emits an event to update the visibility of the delivery component and mark it as completed.

Next, add the next action in the cart’s store located in store/cart.js:



export const actions = {
    //...
    async addShippingMethod ({ state, commit }, optionId) {
      const { cart } = await this.$axios.$post(`/carts/${state.cart.id}/shipping-methods`, { option_id: optionId })
      commit('SET_CART', cart)
    },
}

You send a POST request to the endpoint /store/carts/:cartId/shipping-methods that creates a shipping method based on the shipping option chosen and associates it with the customer’s cart.

Then, add the shippingOptions and shippingMethod getters in store/cart.js to retrieve that info in an easy way:



export const getters = {
  //...
  shippingOptions: state => state.shippingOptions,
  shippingMethod: state => state.cart.shipping_methods[0]?.shipping_option_id,
}

Payment Component with Stripe

This component is the last thing to implement in the checkout workflow. In this step, you first show a list of available payment providers so customers can choose one.

Once the payment provider is selected you need to initialize a payment session so you can process the payment.

Create the file components/Checkout/Steps/Payment.vue with the following content:



<template>
  <checkout-step title="Payment" :show-success-icon="isCompleted">
    <div v-show="isOpen">
      <div class="flex space-x-4 my-8 uppercase">
        <div
          v-for="{provider_id, id} in providers"
          :key="id"
          class="w-full px-4 py-2 border border-gray-300 rounded flex p-1 items-center justify-between cursor-pointer"
          :class="provider === provider_id ? 'border-green-500' : ''"
          @click="provider = provider_id"
        >
          <div>{{ provider_id }}</div>
          <checkout-check-icon v-if="provider === provider_id" class="ml-2" />
        </div>
      </div>

            <div v-show="provider === 'stripe'">
        <div
          id="stripe_container"
          class="bg-white rounded-md p-6 shadow mt-4"
          :class="errors ? 'border border-red-600' : ''"
        />
        <div v-if="errors" class="text-red-600 text-sm mt-2">
          {{ errors }}
        </div>
      </div>

      <div class="flex items-center justify-between mt-4">
        <button
          class="text-gray-500 flex items-center text-sm transform transition"
          hover="text-black -translate-x-2"
          @click="$emit('updateSteps', step, false)"
        >
          <span class="w-2.5 h-2.5 mr-1">
            <svg
              fill="#000000"
              version="1.1"
              xmlns="http://www.w3.org/2000/svg"
              viewBox="0 0 64 64"
            >
              <g>
                <path
                  d="M45,62.8c-0.5,0-0.9-0.2-1.3-0.6L18.6,35.4c-1.7-1.9-1.7-4.9,0-6.7L43.7,1.8c0.7-0.7,1.8-0.7,2.5-0.1 c0.7,0.7,0.7,1.8,0.1,2.5L21.1,31c-0.5,0.5-0.5,1.4,0,2l25.2,26.8c0.7,0.7,0.6,1.8-0.1,2.5C45.9,62.6,45.4,62.8,45,62.8z"
                />
              </g>
            </svg>
          </span>

          <span>Go back</span>
        </button>

        <FormulateInput
          type="button"
          label="Pay"
          input-class="btn-ui"
          @click="processPayment"
        />
      </div>
    </div>
  </checkout-step>
</template>

<script>
export default {
  name: 'Payment',
  props: {
    isCompleted: {
      type: Boolean,
      default: false
    },
    isOpen: {
      type: Boolean,
      default: true
    },
    step: {
      type: Number,
      default: 1
    }
  },
  data () {
    return {
      provider: null,
      card: null,
      errors: null
    }
  },
  computed: {
    providers () {
      return this.$store.getters['cart/paymentProviders']
    }
  },
  watch: {
        async isOpen (val) {
      if (val && !this.providers.length) {
        await this.$store.dispatch('cart/createPaymentSession')
        await this.$store.dispatch('cart/setPaymentSession', this.providers[0].provider_id)
      }
    },
    // TODO watch for changes on the selected provider 
  },
  methods: {
    // TODO add show UI provider and process payment methods
  }
}
</script>

The providers computed property is used to fetch the providers and render them in the template section.

The watcher function isOpen is in charge of dispatching the cart/createPaymentSession and cart/setPaymentSession actions.

For this to actually work, you need to add the cart/paymentProviders getter and the ****cart/createPaymentSession and cart/setPaymentSession actions in store/cart.js:



export const getters = {
    //...
    paymentProviders: state => state.cart.payment_sessions || [],
}

export const actions = {
    //...
    async createPaymentSession ({ state, commit }) {
    const { cart } = await this.$axios.$post(`/carts/${state.cart.id}/payment-sessions`)
    commit('SET_CART', cart)
  },

  async setPaymentSession ({ state, commit }, providerId) {
    const { cart } = await this.$axios.$post(`/carts/${state.cart.id}/payment-session`, { provider_id: providerId })
    commit('SET_CART', cart)
  }
}

The paymentProviders getter is to quickly retrieve the payment_sessions array from the cart’s store.

The createPaymentSession action sends a POST request to the endpoint /store/carts/:cartId/payment-sessions. This initializes the payment_sessions array in the cart object received.

The setPaymentSession action sends a POST request to the endpoint /store/carts/:cartId/payment-session to set the payment_session property in the cart if there isn’t one already set or if the customer changes payment providers.

You will now use the Stripe provider module that you installed previously for this Nuxt.js storefront. This is where the actual integration with Stripe happens. So, when customers choose a payment provider, the @click event sets the provider prop to that value.

If the provider is stripe, you create a card element that the customer uses to enter their card information.

To achieve that, replace the TODO comment in watch with the following:



provider (val) {
  if (val === 'stripe') {
    this.showStripeCard()
  }
}

Then, add this function to the methods property:



methods: {
  showStripeCard () {
    const elements = this.$stripe.elements()
    const card = elements.create('card')
    card.mount('#stripe_container')
    this.card = card
  }
}

You watch for changes in the provider prop. If its value is stripe, you run the showStripeCard method that uses the Stripe module to create an elements object. Then, you create a card element to be mounted on a div container.

Finally, you assign the created card to the card prop. You will use it later to make the payment and complete the cart.

Next, you need to add the function that will be called by the form input to process the payment.

Inside the methods property add the following method:



async processPayment () {
  if (this.provider === 'stripe') {
    await this.$store.dispatch('cart/setPaymentSession', this.provider)

    const { error } = await this.$stripe.confirmCardPayment(this.$store.getters['cart/clientSecret'], {
      payment_method: {
        card: this.card,
        billing_details: {
          email: this.email
        }
      }
    })

    if (error) { this.errors = error.message }

    if (!error) {
      const { id } = await this.$store.dispatch('cart/completeCart')
      this.$router.push(`order-summary/${id}`)
    }
  }
}

Here the setPaymentSession action updates the payment_session object in the cart object to include data related to Stripe. This includes the payment intent and client secret.

Finally, the line this.$router.push(order-summary/${id}) function redirects the customer to an order summary page where they see the order details for the completed cart.

To get the client secret quickly from the cart, add a clientSecret getter to the getters object in store/cart.js:



export const getters = {
    //...
  clientSecret: state => state.cart.payment_session?.data.client_secret || null
}

To confirm a card payment, you use this.$stripe.confirmCardPayment(). This method requires two parameters: the first one is the client secret that you can get from the customer’s cart, and the second one is the payment method object that includes the card element and the billing details object with at least the customer’s email.

When that method is executed, you can receive a successful response or an error. If you get an error, you need to update the errors variable to show the message to the customer. Otherwise, the remaining dispatch actions will be dispatched.

The ****cart/completeCart action is run if the payment is confirmed successfully, so, to complete the cart add the following action in store/cart.js:



export const actions = {
    //...
    async completeCart ({ state, commit }) {
      const { type, data: order } = await this.$axios.$post(`/carts/${state.cart.id}/complete`)

      if (type === 'order') {       
            const { cart } = await this.$axios.$post('/carts')
        commit('SET_CART', cart)

            return order
      }
    }
}

The action sends a POST request to the endpoint /store/carts/:cartId/complete to complete the cart and place the order.

Your Medusa server will try to authorize the payment first, then it will place the order if the authorization is successful. If the type property in the received data is order, you make a post request to the endpoint /store/carts to create a new cart then commit the SET_CART mutation.

Finally, replace the content of components/Checkout/Flow.vue with the following:



<template>
  <div class="flex flex-col">
    <component
      :is="step.component"
      v-for="(step, stepIndex) in checkoutSteps"
      :key="step.component"
      :is-open="step.isOpen"
      :is-completed="step.isCompleted"
      :step="stepIndex"
      @updateSteps="updateSteps"
    />
  </div>
</template>

<script>
import { formatPrice } from '@/utils/format-price'

export default {
  name: 'CheckoutFlow',
  data () {
    return {
      checkoutSteps: [
        {
          component: 'checkout-steps-contact',
          isCompleted: false,
          isOpen: true,
        },
        {
          component: 'checkout-steps-address',
          isCompleted: false,
          isOpen: false,
        },
        {
          component: 'checkout-steps-delivery',
          isCompleted: false,
          isOpen: false,
        },
        {
          component: 'checkout-steps-payment',
          isCompleted: false,
          isOpen: false,
        }
      ]
    }
  },
  methods: {
    formatPrice,
    updateSteps (current, forward = true) {
      this.checkoutSteps[current].isOpen = false
      this.checkoutSteps[current].isCompleted = forward

      const nextOrBefore = forward ? current + 1 : current - 1
      this.checkoutSteps[nextOrBefore].isOpen = true

      if (!forward && nextOrBefore === 0) {
        this.checkoutSteps[nextOrBefore].isCompleted = false
      }
    }
  }
}
</script>

<style lang="scss">
.formulate-input {

  &-label {
    @apply font-semibold text-sm mb-3 block
  }

  &-element > input {
    @apply shadow rounded-md px-4 py-2 text-xs w-full border-transparent
  }

  &-element > select {
    @apply shadow rounded-md px-4 py-2 text-xs w-full border-transparent bg-white
  }

  &-element > select > option {
    @apply bg-gray-100
  }

  &-error {
    @apply text-red-500 text-xs mt-2;
  }
}
</style>

In the template section you use dynamic components to load the four components needed in the checkout flow (contact, address, delivery and payment).

For this to work, you set up in the script section the initial state of the <checkout-flow /> component. The checkoutSteps array contains the props for each step. The updateSteps method is in charge to update the visibility and completion of each step.

Lastly, in the style section you add some classes to style all the form inputs used in the contact and address steps.

Order Summary

After the customers places their order successfully, they need to be redirected to a summary page where they can see an overview of their order.

Create the file pages/order-summary/_id.vue with the following content:



<template>
  <div class="container mx-auto p-8">
    <div v-if="order" class="layout-base flex justify-center pb-16">
      <div class="max-w-xl">
        <span class="text-xs font-medium mb-2">THANK YOU</span>
        <h1 class="text-2xl font-bold">
          Order Confirmed
        </h1>
        <p class="text-md font-light mt-3">
          Your order <span class="font-semibold">#{{ order.display_id }}</span> was successfully processed. You will
          receive an email with the tracking number of your parcel once it’s
          available.
        </p>
        <div class="my-8">
          <!-- Start items section -->
          <order-item
            v-for="item in order.items"
            :key="item.id"
            :item="item"
            :currency="order.currency_code"
          />
        </div>

        <div>
          <totals :item="order" />
        </div>
      </div>
    </div>
    <div v-else>
      "We couldn't find your order, it might have gone through but we can't seem to find it at the moment. Please check your email for an order confirmation."
    </div>
  </div>
</template>

<script>
export default {
  name: 'OrderSummary',
  data () {
    return {
      order: null
    }
  },
  async beforeMount () {
    const { data: { order } } = await this.$axios(`/orders/${this.$route.params.id}`)
    this.order = order
  }
}
</script>

This page loads the <order-item /> component that is used to loop and display all the products that were purchased. The <totals /> component shows the order subtotal, shipping costs, taxes and total amount.

In the beforeMount() function, you make a request to your Medusa server to retrieve the order. For that you need the order ID which you can get from the route parameter with this.$route.params.id.

All that is left is to create the <order-item /> component.

Create the file components/Order/Item.vue with the following content:



<template>
  <div class="flex mb-6 last:mb-0">
    <div class="bg-ui rounded-md overflow-hidden mr-4 max-w-1/4">
      <img
        class="h-auto w-full object-cover"
        :src="item.thumbnail"
        :alt="item.title"
      >
    </div>
    <div class="flex text-sm flex-grow py-2">
      <div class="flex flex-col justify-between w-full flex-grow">
        <div class="flex flex-col">
          <p class="font-semibold mb-2">
            {{ item.title }}
          </p>
          <p>
            <span class="text-ui-dark">Variant:</span> {{ item.description }}
          </p>
        </div>
        <div class="flex space-x-4 text-gray-400 font-light">
          <p class="border-r pr-4 border-gray-500">
            Quantity
            <span class="text-gray-700 font-semibold">
              {{ item.quantity }}
            </span>
          </p>
          <p>
            Price
            <span class="text-gray-700 font-semibold">
              {{ formatPrice(item.unit_price, currency, item.quantity) }}
            </span>
          </p>
        </div>
      </div>
    </div>
  </div>
</template>

<script>
import { formatPrice } from '~/utils/format-price'

export default {
  name: 'CartItem',
  props: {
    item: {
      type: Object,
      default () {
        return {}
      }
    },
    currency: {
      type: String,
      default: 'USD'
    }
  },
  methods: {
    formatPrice
  }
}
</script>

This component receives the product information and renders it on the page. It shows the product’s title, variant, quantity and price.

Testing the Checkout Flow

Start both your Medusa server and Nuxt.js website if they aren’t running.

Then, go to your storefront URL http://localhost:3333 and add some products to the cart. When you are done adding products click on the bag icon at the top-right to see the cart popover and click on the Checkout button.

If all the components for the checkout flow are working as expected you should get the following page:

As you can see, the <checkout-summary /> component shows the info related to the products you added to the cart and gives you the total you have to pay. On the other hand, the <checkout-flow /> shows four card with one of the steps you have to follow to complete the checkout.

Fill up the email input and click on the Next button. The contact form closes and the address component opens. Then, fill up the form with the shipping address and click on the Next button.

If the validation passes, the delivery component will open next with the available shipping options rendered. Choose one option and click Next.

You then will get the payment component with the available payment providers. For this tutorial Stripe is the only provider, but if you add more providers they will be displayed here as well.

Choose stripe as payment provider and write you payment information before clicking on the pay button.

Stripe offers several test cards to simulate payments to test your integration. You can choose one of them here.

Once you’re done click on Pay. The payment will be simulated and if everything is successful you will be redirected to the Order summary page.

You can check if the payment was actually successful on the Stripe Dashboard. Go to your Stripe dashboard and click on the Payments link at the top left. You should see the payment with a status of uncaptured. This means that Stripe was able to process the payment, but it needs further action to be captured and to actually charge the customer.

To capture the payment, start your Medusa admin with yarn run develop. Then, go to the Medusa admin website and click on Orders in the left sidebar. You should see that one order was created.

Click on it to go to the order details page. On this page, scroll down to the payment section. You will see that the status of the payment is Awaiting. Next to it is Capture payment button.

If you click on it the payment will be captured through Stripe. To confirm that the payment was captured, go back to your stripe dashboard. You should see the status for the payment that was already there changed to Succeeded.

Conclusion

In this tutorial, you learned how to set up a basic checkout process to allow your customers to place orders and perform payment with Stripe.

Going forward, you can focus on developing or adding new functionalities to your Nuxt.js storefront including:

Add customer login and profile to give customers a way of managing their information, view their orders, and save payment details.
Integrate other payment providers such as PayPal.
Implement swap feature to allow customers to exchange products after purchase.
Use a notification system such as SendGrid to send the customer emails based on different events.

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

How to Create a Nuxt.js Ecommerce Storefront from Scratch Using Medusa Part 2: Adding Cart Functionality

Carlos Padilla — Tue, 14 Jun 2022 11:07:51 +0000

Introduction

An ecommerce shopping cart is something essential when you are building a storefront. It allows customers to add items to their cart so that they can later purchase it. Customers can also edit items in their cart at any point.

Medusa is an open source headless commerce platform that allows you to build digital commerce through its API with just a few commands. It gives you the flexibility you need to implement your own storefront from scratch using the frontend framework of your choice.

This tutorial is part of a series that revolves around creating a Nuxt.js ecommerce storefront using Medusa from scratch. The first part explains how to set up a starter storefront with Nuxt.js, link it with a Medusa server, and add products and product details pages.

In this guide, you will learn how to set up a cart flow for your Nuxt.js storefront. More specifically, it includes the following:

A dropdown to allow the users to select their region.
A popover cart to give the users a quick view of what is in the cart.
Add products to the cart from the product detail page.
A cart page to list the product in the cart with editing features.

You can find the final code for this part in this GitHub repository.

Prerequisites

This tutorial assumes you already followed along with part 1 of the series. If you haven’t, you can clone the GitHub repository with the first part branch and continue along from there.

Set Up Region Selection

The first thing you need to do is to set up the dropdown that allows choosing a region. When the customer selects a region, their cart will be updated to show the product prices with the currency that is set up for that region.

By default, the Medusa server comes with two regions, therefore two currencies (USD and EUR).

To have all your data’s storefront in sync, you will use a store to manage the application state. Luckily, Nuxt offers a store out-of-the-box. To activate it, go to the root of your storefront project and create a new folder called store if it doesn’t already exist.

Then, create the file store/index.js with the following content:

const REGION = 'medusa_region'
const COUNTRY = 'medusa_country'

export const state = () => ({
  country: undefined,
  region: undefined,
  regions: []
})

export const mutations = {
  UPDATE_REGION (state, payload) {
    state.region = payload.region
    state.country = payload.country || payload.region.countries[0]
    localStorage.setItem(REGION, JSON.stringify(state.region))
    localStorage.setItem(COUNTRY, JSON.stringify(state.country))
  },
  SET_REGIONS (state, regions) {
    state.regions = regions
  }
}

export const actions = {
  async initializeRegions ({ commit }) {
    const { data: { regions } } = await this.$axios('/regions')
    commit('SET_REGIONS', regions)

    if (localStorage) {
      const regionJSON = localStorage.getItem(REGION)
      const countryJSON = localStorage.getItem(COUNTRY)

      if (regionJSON && countryJSON) {
        const region = JSON.parse(regionJSON)
        const country = JSON.parse(countryJSON)
        commit('UPDATE_REGION', {
          region,
          country
        })
      } else {
        commit('UPDATE_REGION', { region: regions[0] })
      }
    }
  },

    updateRegion ({ state, commit, dispatch }, payload) {
      commit('UPDATE_REGION', payload)
    }
}

⚠️ To use axios in this form: this.$axios('/regions') you need to update your axios base URL in nuxt.config.js to http://localhost:9000/store, with this update you won’t need to prepend /store each time you need to make a request to your Medusa server.

In this file, you set up the initial state for the application. Within the state function you define variables to store the country and the region the customer chooses, and a regions array that you will use later on to display all the available regions in a dropdown.

The mutations object is in charge of updating the application state. So, whenever you need to update something, you commit a mutation that under the hood updates the state.

Finally, you have the actions object, it allows you to make some logic, for example, retrieve some data from an API, then commit a mutation to update the state with the data retrieved from the API.

In the initializeRegions action, you make a request to the Medusa server to retrieve all regions available for your storefront, then you commit the SET_REGIONS mutation to update the regions state.

Next, you check if the local storage contains the customer’s country and region to commit the UPDATE_REGION mutation with that data. Otherwise, you commit the mutation with the first region from the regions array.

Create Regions Dropdown Component

The next step is to add the component that displays the regions in the navigation bar.

Create the file components/Dropdowns/Regions.vue with the following content:

<template>
  <div class="relative text-left">
    <div v-if="$store.state.region">
      <button
        class="inline-flex justify-center w-full px-4 py-2 bg-white text-sm font-medium text-gray-700 hover:text-gray-600 flex items-center"
        @click="showRegionsMenu = !showRegionsMenu"
      >
        <span class="mr-1">{{ $store.state.country.display_name }} / {{ $store.state.region.currency_code.toUpperCase() }}</span>
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="20"
          height="20"
          viewBox="0 0 24 24"
        ><path fill="currentColor" d="m12 13.172l4.95-4.95l1.414 1.414L12 16L5.636 9.636L7.05 8.222z" /></svg>
      </button>
    </div>

    <div
      v-if="$store.state.regions.length > 0 && showRegionsMenu"
      class="origin-top-right absolute right-0 mt-2 w-56 px-6 py-2 rounded-md shadow-lg bg-white ring-1 ring-black ring-opacity-5 focus:outline-none"
    >
      <ul class="border-b border-ui last:border-b-0">
        <li v-for="(region) in $store.state.regions" :key="region.id" class="not-last:border-b border-gray-300">
          <button
            v-for="country in region.countries"
            :key="country.id"
            class="block py-3 text-sm w-full text-left text-gray-500 hover:text-black not-last:border-b border-gray-300"
            @click="$store.dispatch('updateRegion', {region: region, country: country})"
          >
            {{ country.display_name }} / {{ region.currency_code.toUpperCase() }}
          </button>
        </li>
      </ul>
    </div>
  </div>
</template>

<script>
export default {
  name: 'RegionsPopOver',
  data () {
    return {
      showRegionsMenu: false
    }
  }
}
</script>

In this component, you have a button with the showRegionsMenu prop to toggle the dropdown regions visibility. Then, you access all the regions available in the store with $store.state.regions and loop through them to make a list with all the regions’ countries.

Finally, for each country you have a button that dispatches the action $store.dispatch('updateRegion', {region: region, country: country}) every time the customer clicks on it, thus updating the customer region.

To actually use this component, open the file under components/App/Navbar.vue and replace the div container of the button “USA / USD” with the following:

<div class="hidden lg:flex">
    <!-- THIS IS THE NEW COMPONENT -->
  <dropdowns-regions />

    <!-- ADD BEFORE THIS -->
    <div class="relative inline-block text-left">
    <div>
      <button
        class="inline-flex justify-center w-full px-4 py-2 text-sm font-medium text-gray-700 hover:text-gray-600"
        type="button"
      >
        Account
      </button>
    </div>
  </div>
</div>

To see the dropdown in action, you need to create a Nuxt plugin that calls the initializeRegions action every time your storefront is visited or when the customer refreshes the page.

Go to the root of your storefront project and create the file plugins/nuxtInit.client.js with the following content:

export default async function (context) {
  await context.store.dispatch('initializeRegions', context)
}

Next, open your nuxt.config.js and update the plugins property with the following:

plugins: [
  { src: '~/plugins/nuxtInit.client.js', mode: 'client' }
],

Test the Regions Dropdown

Make sure your Medusa server is running. Then, start your Nuxt.js server with the following command:

yarn dev

Go to the URL http://localhost:3333. You should find in the navigation bar next to “Account” a region specified in the form of “country/currency”. Click on it and you’ll see a dropdown with different countries and currencies to select from.

Whatever item you choose from the dropdown, the region is immediately updated on the storefront. However, if you check the price on the products at the bottom of the home page, you will see that right now the currency is not in sync with the region selected in the dropdown. That will be fixed once you implement the cart in the next section.

Implement Cart flow

In this section, you will implement all the features related to the cart flow. This includes setting up a store to manage the cart, the components to add or remove products from the cart, a cart popover component to show a quick summary of products in the cart, and a cart page where the customer can have a detailed overview of items in the cart and cart totals.

Initialize a cart

Similar to what you did with the regions, you first need an initializer that allows you to retrieve a cart ID from local storage if it exists. Otherwise, you make a request to your Medusa server to create a new cart for the customer.

Open store/index.js and add the following at the beginning of the file:

const CART_ID = 'cart_id'

then in the actions object add the initializeCart function:

export const actions = {
  ...,

  async initializeCart ({ state, commit }) {
    const existingCartId = localStorage ? localStorage.getItem(CART_ID) : undefined

    if (existingCartId) {
      try {
        const { data: { cart } } = await this.$axios(`/carts/${existingCartId}`)

        if (!cart.completed_at) {
          commit('cart/SET_CART', cart)
        }
      } catch (e) {
        localStorage.removeItem(CART_ID)
      }
    } else {
      const { cart } = await this.$axios.$post('/carts', { region_id: state.region.id, country_code: state.country.country_code })
      commit('cart/SET_CART', cart)
    }
  },
}

This action first checks if there is a cart_id saved in the localStorage. If so, it will retrieve the cart from the Medusa server and if the cart isn’t completed yet it will commit the SET_CART mutation to load it to the state of the storefront.

If there isn’t any cart stored in the local storage, then it will create a new one and will commit the SET_CART mutation to set the cart in the current storefront state.

Next, you need to create a namespaced module to manage the cart state, getters, mutations, and actions.

Create the file store/cart.js with the following content:

export const state = () => ({
  cart: {
    items: []
  }
})

export const getters = {
  items: state => state.cart.items,
  cartCurrencyCode: state => state.cart.region.currency_code
}

export const mutations = {
  SET_CART (state, cart) {
    state.cart = cart
    localStorage.setItem('cart_id', cart.id)
  }
}

export const actions = {
  async updateCart ({ state, commit }, payload) {
    const { cart } = await this.$axios.$post(`/carts/${state.cart.id}`, { ...payload })
    commit('SET_CART', cart)
  },

  async addItem ({ state, commit }, item) {
    let cartId = state.cart.id

    if (!cartId) {
      const { cart: newCart } = await this.$axios.$post('/carts')
      commit('SET_CART', newCart)
      cartId = newCart.id
    }

    const { cart: updateCart } = await this.$axios.$post(`/carts/${cartId}/line-items`, { ...item })
    commit('SET_CART', updateCart)
  },

  async removeItem ({ state, commit }, itemId) {
    const { cart } = await this.$axios.$delete(`/carts/${state.cart.id}/line-items/${itemId}`)
    commit('SET_CART', cart)
  },

  async updateQuantity ({ state, commit }, item) {
    const { cart } = await this.$axios.$post(`/carts/${state.cart.id}/line-items/${item.id}`, { quantity: item.quantity })
    commit('SET_CART', cart)
  }
}

In the state function, you set up an initial state for the cart within an empty array of items to avoid errors when rendering the storefront pages. Later on, when the cart is initialized or retrieved from the Medusa server, the state will be updated with the response from the cart endpoint.

In the getters object you set two getters to get some nested properties from the cart state. You can see this as a shortcut to get a specific property in an object in the state.

Next comes the mutations object that only has the mutation in charge of updating the state within the cart.

Finally, there is the actions object with four functions: the first one is to update the cart properties; the second is to add items to the cart; the third is to remove items from the cart; the fourth is to update items quantity in the cart. All those functions make a request to a specific endpoint on your Medusa server.

The last step to get the cart store working is to update the plugins/nuxtInit.client.js file with the following content:

export default async function (context) {
  await context.store.dispatch('initializeRegions', context)
  await context.store.dispatch('initializeCart', context)
}

With this update, you dispatch the initializCart action that runs whenever a customer visits the storefront or the storefront page is refreshed.

Go to your storefront home page and refresh the page. Then, open the web inspector and click on the Storage tab. You should see under Local Storage the cart_id key with an ID as a value.

Implement Add Items to Cart

The next step is to add the components responsible to add products to the cart.

Create the file components/QuantitySelector.vue with the following content:

<template>
  <div class="flex items-center rounded-md px-4 py-2 shadow">
    <button @click="$emit('decrement', quantity - 1)">
      –
    </button>
    <span class="w-8 text-center">{{ quantity }}</span>
    <button @click="$emit('increment', quantity + 1)">
      +
    </button>
  </div>
</template>

<script>
export default {
  name: 'QuantitySelector',
  props: {
    quantity: {
      type: Number,
      default: 1
    }
  }
}
</script>

This component receives only one prop with the current quantity and it has two buttons in charge of emitting events to its parent container to call the functions to increase or decrease the quantity of the current item.

Next, open the pages/products/_id.vue file. and add these three properties in the data object:

data () {
  return {
    ...
    quantity: 1,
    variant_id: null,
    lowestPrice: {}
  }
},

The quantity property is used to store the product quantity; the variant_id is used to set the id of the variant chosen by the customer and the lowestPrice, as the name suggests, is to get the lowest price for that product.

Then, import mapActions right after the open script tag:

<script>
import { mapActions } from 'vuex'

//...

And replace everything after the data property with the following:

async fetch () {
  try {
    const { product } = await this.$axios.$get(`/products/${this.$route.params.id}`)
    this.product = product
    this.imageToShow = this.product.images[0].id
    this.filterLowestPrice()
  } catch (e) {
    // eslint-disable-next-line no-console
    console.log('The server is not responding')
  }
},

computed: {
  currencyCode () {
    return this.$store.state.region.currency_code || 'usd'
  }
},
watch: {
  currencyCode () {
    this.filterLowestPrice()
  }
},
methods: {
  ...mapActions({
    addItem: 'cart/addItem'
  }),
    increment () {
    this.quantity += 1
  },
  decrement () {
    if (this.quantity > 1) { this.quantity -= 1 }
  },
  updateSelectedOptions (value) {
    const variant = this.product.variants.reduce((acc, cur) => {
      return [...acc, {
        variantId: cur.id,
        options: cur.options.map(o => o.value)
      }]
    }, []).filter((variant) => {
      return Object.values(value).sort().join('__') === variant.options.sort().join('__')
    })

    this.variant_id = variant[0].variantId
  },
  filterLowestPrice () {
    this.lowestPrice = this.product.variants
      .reduce((prices, cur) => {
        return [...prices, ...cur.prices.filter(price => price.currency_code === this.currencyCode)]
      }, [])
      .sort((a, b) => a.amount - b.amount)[0]
  }
}

First, the computed property currencyCode is used to retrieve the current currency code from the store that matches the region selected by the customer.

Next, you have a watcher in charge of tracking any update that the currency code could have. For example, if the customer selects other regions, the watcher detects this change and runs the filterLowestPrice() function to set the lowestPrice in the data property that you add earlier.

In the methods object, you can find the mapActions helper. This lets you use the action addItem created on the cart store but within a component. What this action does is send a request to your Medusa server to add an item to the cart.

The increase and decrease functions are responsible to update the quantity property added earlier.

The updateSelectedOptions function is used to set the specific variant_id chosen for that product by the customer.

Lastly, the filterLowestPrice function filters the product prices to get the lowest price based on the selected currency code.

Next, you need to add a utility function that formats the product prices. Create the file utils/format-price.js with the following content:

export const formatPrice = (amount, currencyCode, quantity = 1) => {
  return (amount / 100 * quantity).toFixed(2) +
    ' ' +
    currencyCode.toUpperCase()
}

This function takes three parameters: the amount, the currency code, and the quantity; then, it calculates the total amount based on the quantity and returns a formatted string with the currency code.

Go back to pages/products/_id.vue and replace the quantity component that was below the “Add to bag” button with the quantity-selector component:

<div class="inline-flex mt-12">
  <button class="btn-ui mr-2 px-12" @click="addItem({variant_id, quantity})">
    Add to bag
  </button>

    <!-- THIS IS THE NEW COMPONENT -->
  <quantity-selector
    :quantity="quantity"
    @increment="increment"
    @decrement="decrement"
  />
</div>

Also, replace the part displaying the price with the following:

<p v-if="lowestPrice.currency_code" class="text-lg mt-2 mb-4">
  {{ formatPrice(lowestPrice.amount, lowestPrice.currency_code) }}
</p>

Make sure to import formatPrice in the script section and add the method in the methods property:

<script>
import { formatPrice } from '~/utils/format-price'

export default {
  ...

  methods: {
        ...
    formatPrice // <--------------------------- ADD HERE
  }
}
</script>

Next, you need to create a new component that shows the product options available to the customer to choose from.

Create the file components/Products/Options.vue with the following content:

<template>
  <div>
    <div v-for="option in filteredOptions" :key="option.id" class="mt-6">
      <div class="text-sm">
        <p class="font-medium mb-2">
          {{ option.title }}
        </p>
        <div>
          <button
            v-for="value in option.values"
            :key="value.id"
            :class="value.value === currentOptions[option.id] ? 'bg-gray-500 text-white' : 'bg-gray-200 text-black'"
            class="inline-flex items-center justify-center rounded-sm text-xs h-12 w-12 mr-2 last:mr-0 hover:bg-gray-500 hover:text-white"
            @click="updateOption(option.id, value.value )"
          >
            {{ value.value }}
          </button>
        </div>
      </div>
    </div>
  </div>
</template>,

<script>
export default {
  name: 'ProductOptions',
  props: {
    options: {
      type: Array,
      default () { return [] }
    }
  },
  data () {
    return {
      currentOptions: { }
    }
  },
  computed: {
    filteredOptions () {
      return this.options.map((option) => {
        option.values = option.values.reduce((acc, curr) => {
          if (!acc.find(val => val.value === curr.value)) {
            return [...acc, { ...curr }]
          }
          return acc
        }, [])

        return option
      })
    }
  },
  watch: {
    options (val) {
      this.currentOptions = val.reduce((acc, curr) => {
        return { ...acc, [curr.id]: curr.values[0].value }
      }, {})
      this.$emit('updateSelectedOptions', this.currentOptions)
    }
  },
  methods: {
    updateOption (optionId, value) {
      this.currentOptions[optionId] = value
      this.$emit('updateSelectedOptions', this.currentOptions)
    }
  }
}
</script>

This component renders all the options available for a specific product. It receives a prop with all the options. It also has a data property to store the currently selected option.

Additionally, it has a computed property filteredOptions that filters the options to avoid duplicates. The watcher is used to update the currentOptions property when the component is rendered the first time.

The updateOption function sets the selected option to the currentOptions property, then emits the updateSelectedOptions event to its parent container with the value of the current option.

Now, go back to pages/products/_id.vue and search for the div where you were looping the options before. It should be below the product description.

Replace it with the Options component that you just created:

<p class="font-light">
  {{ product.description }}
</p>

<!-- THIS IS THE NEW COMPONENT -->
<products-options
  :options="product.options"
  @updateSelectedOptions="updateSelectedOptions"
/>

The last thing to do to finish the add items to cart functionality is to update the “Add to bag” button in pages/products/_id.vue. Replace the button with the following:

<button class="btn-ui mr-2 px-12" @click="addItem({variant_id, quantity})">
  Add to bag
</button>

You run the addItem function whenever the customer clicks on the button.

Test Add to Cart Functionality

To test it out, go to your storefront products page, then click on a product. You should see the products details page.

Try changing to another region from the regions dropdown and you should see the product price and currency code updated immediately matching the selected region.

Also, if you click on the plus quantity button you should see how the quantity increases. On the other hand, if you click on the minus quantity button the quantity decreases.

Finally, if you click on the Add to bag button, based on the example shown above, a Medusa Sweatshirt Size S will be added to the cart.

You will be able to see the product added to the cart once the cart popover is implemented in the upcoming sections.

Update ProductCart component

Before you add the cart popover, you should update the ProductCard component to use the newly created format-price utility function.

Move the file components/ProductCard.vue to the components/Products directory and rename it to Card.vue. The full path should now be components/Products/Card.vue.

Then, open the Card.vue component and replace the p element that renders the price with the following:

<p class="text-sm font-semibold text-gray-900">
  from {{ formatPrice(lowestPrice.amount, lowestPrice.currency_code) }}
</p>

Remember to import the function at the start of the script tag and add it to the methods object:

<script>
import { formatPrice } from '~/utils/format-price'

export default {
  ...

  methods: {
        ...
    formatPrice // <--------------------------- ADD HERE
  }
}
</script>

Finally, replace the computed lowestPrice property to get the currency code from the cart store:

computed: {
  lowestPrice () {
    return this.item.variants
      .reduce((prices, cur) => {
        return [...prices, ...cur.prices.filter(price => price.currency_code === this.$store.getters['cart/cartCurrencyCode'])]
      }, [])
      .sort((a, b) => a.amount - b.amount)[0] || { amount: 1, currency_code: 'usd' }
  }
},

Next, open store/index.js and update the updateRegion action to the following:

export const actions = {
  ...
  updateRegion ({ state, commit, dispatch }, payload) {
    commit('UPDATE_REGION', payload)
    dispatch('cart/updateCart', {
      region_id: state.region.id
    })
  }
}

With this code, you dispatch the cart/updateCart action whenever the customer changes their region.

Now, you need to update the ProductCard that was previously used to use the updated Card component.

Open pages/index.vue and replace the <ProductCard /> component with the new <products-card/> component:

<div class="grid grid-cols-4 gap-8 ">
    <!--- before this component was ProductCard --->
  <products-card
    v-for="product in products"
    :key="product.id"
    :item="product"
  />
</div>

Similarly, open pages/products/index.vue and replace the <ProductCard /> component with the new <products-card/> component:

<div
  v-if="products.length"
  class="grid grid-cols-4 gap-8 "
>
    <!--- before this component was ProductCard --->
  <products-card
    v-for="product in products"
    :key="product.id"
    :item="product"
  />
</div>

To test it out, go to your products page and select a different country with a different currency from the region’s dropdown. You should see the product prices get updated instantly.

Add Cart Popover

To allow customers to see what is in their cart, you’ll implement a cart popover that shows a quick summary of the list of products in the cart.

Create a new file components/Dropdowns/CartPopoverItem.vue with the following content:

<template>
  <li class="flex">
    <div class="overflow-hidden rounded-md mr-4 bg-gray-100">
      <img class="w-16 h-auto" :src="item.thumbnail" :alt="item.title">
    </div>
    <div class="flex flex-col justify-between py-2 space-y-2">
      <div>
        <p class="font-medium text-sm">
          {{ item.title }}
        </p>
        <p class="text-xs mt-2">
          <span class="text-gray-500">Variant:</span> {{ item.description }}
        </p>
      </div>
      <div class="flex items-center font-light text-xs">
        <p>
          <span class="text-gray-500">Quantity</span>
          <span>{{ item.quantity }}</span>
        </p>
        <div class="w-px h-4 bg-ui-dark mx-3" />
        <p>
          <span class="text-gray-500">Price</span>
          <span>
            {{ formatPrice(item.unit_price, cartCurrencyCode, item.quantity) }}
          </span>
        </p>
      </div>
    </div>
  </li>
</template>

<script>
import { formatPrice } from '@/utils/format-price'

export default {
  name: 'CartPopoverItem',
  props: {
    item: {
      type: Object,
      default () {
        return {
          title: 'Item added',
          description: 'Description item',
          quantity: 1,
          unit_price: 9.5,
          thumbnail: ''
        }
      }
    }
  },
  computed: {
    cartCurrencyCode () {
      return this.$store.state.cart.cart.region.currency_code
    }
  },
  methods: {
    formatPrice
  }

}
</script>

This component is used to display each cart item. It receives a product as a prop and renders it in the dropdown showing the product’s title, the variant is chosen, the quantity, and the total amount.

Next, create the file components/Dropdowns/CartPopover.vue with the following content:

<template>
  <div class="relative inline-block text-left">
    <div id="cartButton">
      <button
        class="inline-flex items-center justify-center w-full py-2 bg-white text-sm font-medium hover:opacity-1/2"
        @click="showCart = !showCart"
      >
        <svg width="40" height="41" viewBox="0 0 40 41" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path
            fill-rule="evenodd"
            clip-rule="evenodd"
            d="M14.9968 16.2273C14.9921 16.1189 14.9888 16.0004 14.9877 15.8734C14.9826 15.2497 15.0333 14.4053 15.2648 13.551C15.4962 12.6975 15.9164 11.8043 16.6719 11.123C17.4366 10.4333 18.5016 10 19.9419 10C21.3822 10 22.4472 10.4333 23.212 11.123C23.9674 11.8043 24.3877 12.6975 24.619 13.551C24.8506 14.4053 24.9012 15.2497 24.8961 15.8734C24.8951 16.0004 24.8917 16.1189 24.887 16.2273H27.8836C29.0776 16.2273 30.0056 17.2667 29.8708 18.4531L28.7344 28.4531C28.6196 29.4638 27.7644 30.2273 26.7472 30.2273H13.1366C12.1194 30.2273 11.2643 29.4638 11.1494 28.4531L10.013 18.4531C9.87822 17.2667 10.8062 16.2273 12.0002 16.2273H14.9968ZM23.8859 16.2273C23.8912 16.1186 23.8951 15.9971 23.8962 15.8652C23.9008 15.2957 23.8535 14.5493 23.6538 13.8126C23.454 13.0752 23.1098 12.3775 22.5422 11.8656C21.984 11.3622 21.1673 11 19.9419 11C18.7165 11 17.8999 11.3622 17.3416 11.8656C16.774 12.3775 16.4299 13.0752 16.23 13.8126C16.0303 14.5493 15.983 15.2957 15.9877 15.8652C15.9888 15.9971 15.9926 16.1186 15.9979 16.2273H23.8859ZM12.0002 17.2273H27.8836C28.4806 17.2273 28.9446 17.747 28.8772 18.3402L27.7408 28.3402C27.6834 28.8455 27.2558 29.2273 26.7472 29.2273H13.1366C12.628 29.2273 12.2004 28.8455 12.143 28.3402L11.0066 18.3402C10.9392 17.747 11.4032 17.2273 12.0002 17.2273ZM15.4874 20.0455C15.8388 20.0455 16.1237 19.7605 16.1237 19.4091C16.1237 19.0576 15.8388 18.7727 15.4874 18.7727C15.1359 18.7727 14.851 19.0576 14.851 19.4091C14.851 19.7605 15.1359 20.0455 15.4874 20.0455ZM25.0328 19.4091C25.0328 19.7605 24.7479 20.0455 24.3965 20.0455C24.045 20.0455 23.7601 19.7605 23.7601 19.4091C23.7601 19.0576 24.045 18.7727 24.3965 18.7727C24.7479 18.7727 25.0328 19.0576 25.0328 19.4091Z"
            fill="black"
          /></svg>
        <span>{{ countItems }}</span>
      </button>
    </div>

    <div
      v-if="showCart"
      id="cartPopover"
      class="origin-top-right absolute right-0 mt-2 w-96 px-6 py-4 rounded-md shadow-lg bg-white ring-1 ring-black ring-opacity-5 focus:outline-none"
    >
      <div class="py-1">
        <div v-if="items.length === 0" class="flex justify-center">
          <p>Your cart is empty </p>
        </div>

        <div v-else>
          <ul class="py-2 first:pt-0 space-y-3">
            <dropdowns-cart-popover-item v-for="item in items" :key="item.id" :item="item" />
          </ul>

          <div class="flex flex-col mt-4">
            <div>
              <div>
                <button class="btn-ui font-medium px-4 py-2 mb-2 text-sm w-full">
                  Checkout
                </button>
              </div>
            </div>
            <div>
              <nuxt-link to="/shopping-bag">
                <button class="text-ui-dark py-2 text-sm w-full">
                  View Shopping Bag
                </button>
              </nuxt-link>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  name: 'CartPopover',
  data () {
    return {
      showCart: false
    }
  },
  computed: {
    ...mapGetters({ items: 'cart/items' }),
    countItems () {
      return this.items.reduce((sum, i) => sum + i.quantity, 0)
    }
  }
}
</script>

Within this component, you show how many products there are in the cart. When the customer clicks on the bag icon in the navigation bar, a summary of products in the cart is rendered using the CartPopoverItem component.

Also, 2 buttons View Shopping Bag and Checkout are rendered.

The list of items is retrieved using the mapGetters helper that maps to the cart/items getter created in the cart store.

To see both components in action you need to add them to the Navigation bar.

Open components/App/Navbar.vue and replace the current static shopping bag button with the <dropdowns-cart-popover /> just after the account button:

<div class="flex items-center justify-end">
  <div class="hidden lg:flex">
    <dropdowns-regions />

    <div class="relative inline-block text-left">
      <div>
        <button
          class="inline-flex justify-center w-full px-4 py-2 text-sm font-medium text-gray-700 hover:text-gray-600"
          type="button"
        >
          Account
        </button>
      </div>
    </div>
  </div>

    <!-- ADD HERE -->
  <dropdowns-cart-popover />
</div>

Test the Cart Popover

To test the cart popover, go back to your storefront and try clicking on the bag icon in the navigation bar. You should see the products that are currently in the cart.

In the next section you will implement the cart page that will allow you to modify the items’ quantities or remove items from the cart.

Cart page

This page has two components on it. The first one is the products list and the second is a summary of the cart totals.

To implement the first component, create the file components/ShoppingBag/CartItem.vue with the following content:

<template>
  <div class="flex mb-6 last:mb-0">
    <div class="bg-ui rounded-md overflow-hidden mr-4 max-w-1/4">
      <img
        class="h-auto w-full object-cover"
        :src="item.thumbnail"
        :alt="item.title"
      >
    </div>
    <div class="flex text-sm flex-grow py-2">
      <div class="flex flex-col justify-between w-full flex-grow">
        <div class="flex flex-col">
          <p class="font-semibold mb-2">
            {{ item.title }}
          </p>
          <p class="lg:block mb-4 hidden font-light">
            {{ item.variant.product.description }}
          </p>
          <p>
            <span class="text-ui-dark">Variant:</span> {{ item.description }}
          </p>
        </div>
        <p class="font-semibold">
          {{ formatPrice(item.unit_price, cartCurrencyCode, item.quantity) }}
        </p>
      </div>
      <div class="flex flex-col justify-between">
        <div class="flex justify-end w-full">
          <button @click="deleteItem">
            &times;
          </button>
        </div>
        <quantity-selector
          :quantity="item.quantity"
          @increment="updateQuantity"
          @decrement="updateQuantity"
        />
      </div>
    </div>
  </div>
</template>

<script>
import { formatPrice } from '~/utils/format-price'

export default {
  name: 'CartItem',
  props: {
    item: {
      type: Object,
      default () {
        return {}
      }
    }
  },
  computed: {
    cartCurrencyCode () {
      return this.$store.state.cart.cart.region.currency_code
    }
  },
  methods: {
    formatPrice,
    updateQuantity (quantity) {
      this.$store.dispatch('cart/updateQuantity', { id: this.item.id, quantity })
    },
    deleteItem () {
      this.$store.dispatch('cart/removeItem', this.item.id)
    }
  }
}
</script>

Using this component you can render all the products in the cart.

The <quantity-selector /> component is responsible for updating the product’s quantity. It calls the updateQuantity function which dispatches the cart/updateQuantity action in the cart store. Then, this action sends a request to your Medusa server to update the item quantity.

The delete button removes the item from the cart.

To implement the cart totals component, create the file components/ShoppingBag/CartReview.vue with the following content:

<template>
  <div class="bg-white rounded-md shadow px-8 py-6 w-full sticky top-28">
    <h3 class="font-semibold mb-4">
      Order Summary
    </h3>

    <div class="my-4 border-t bt-gray-100">
      <div class="font-light text-sm space-y-3 mt-3">
        <div class="flex items-center justify-between mb-2">
          <p>Subtotal</p>
          <p class="font-medium">
            {{ formatPrice(cart.subtotal, currencyCode ) }}
          </p>
        </div>

        <div v-if="shippingTotal" class="flex items-center justify-between mb-2">
          <p>Shipping</p>
          <p class="font-medium">
            {{ formatPrice(shippingTotal, currencyCode) }}
          </p>
        </div>

        <div class="flex items-center justify-between mb-2">
          <p>Taxes</p>
          <p class="font-medium">
            {{ formatPrice(cart.tax_total, currencyCode) }}
          </p>
        </div>

        <div class="h-px w-full bg-ui-medium mb-2" />

        <div class="flex items-center justify-between">
          <p>Total</p>
          <p class="font-medium">
            {{ formatPrice(cart.total, currencyCode) }}
          </p>
        </div>
      </div>
    </div>

    <div>
      <button class="btn-ui w-full">
        Checkout
      </button>
    </div>
  </div>
</template>

<script>
import { formatPrice } from '@/utils/format-price'

export default {
  computed: {
    cart () {
      return this.$store.state.cart.cart
    },
    currencyCode () {
      return this.cart.region.currency_code
    },
    shippingTotal () {
      return this.cart.shipping_total || 0
    }
  },
  methods: {
    formatPrice
  }
}
</script>

This component shows the cart’s totals including the subtotal, the shipping total (if the cart has this info), the taxes amount, and the total for all the products on the cart.

Now that you are done with the components you can create the Cart page.

Create the file pages/shopping-bag/index.vue with the following content:

<template>
  <div class="container mx-auto p-8">
    <div class="flex relative flex-col-reverse lg:flex-row">
      <div class="flex flex-col lg:mr-12 lg:w-3/5">
        <div class="mb-8">
          <h1 class="font-semibold">
            Shopping Bag
          </h1>
        </div>
        <div class="w-full">
          <shopping-bag-cart-item
            v-for="item in items"
            :key="item.id"
            :item="item"
          />
        </div>
      </div>
      <div class="relative w-full mb-8 lg:mb-0 lg:w-2/5">
        <shopping-bag-cart-review />
      </div>
    </div>
  </div>
</template>

<script>
import { mapGetters } from 'vuex'

export default {
  name: 'ShoppingBag',
  computed: {
    ...mapGetters({ items: 'cart/items' })
  }
}
</script>

The heaviest work was already implemented in the components created previously, so on this page you are just using them.

You retrieve the items in the cart using the mapGetters helper. Then, the <shopping-bag-cart-item /> component loops through all the items and renders them.

The <shopping-bag-cart-review /> component shows a review of the cart totals.

Test Cart Page

Go to your storefront product page and click on the bag icon in the navigation bar. Then, click on the View shopping bag button. You will be redirected to the cart page.

As you can see the prices on the card items are in sync with the totals in the cart totals summary.

Try testing the different functionalities you added including changing the quantity or deleting an item. It all should work as expected.

What’s Next?

The next part of this series covers adding the checkout flow to place an order. It also covers adding Stripe as a payment method.

You can refer to the following resources to implement additional features in your Nuxt.js ecommerce storefront:

Set up Stripe as a payment method using the Stripe Plugin.
Add customer login and profile to give customers a way to manage their data.
Add a product search engine to your storefront using the Algolia plugin.

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

How to Use a Monorepo to Deploy Your Gatsby Ecommerce Storefront and Admin

Carlos Padilla — Thu, 12 May 2022 11:26:29 +0000

Introduction

A Monorepo is a codebase that contains several projects, often using multiple and different frameworks but unified in a single repository.

Medusa is an open source headless commerce that allows you to build an ecommerce platform through its API with just a few commands in a short amount of time. In addition to its core that holds all extensive ecommerce features, Medusa also has ready-made Gatsby storefront and admin websites that you can use to amplify your ecommerce business.

By default, the storefront, admin, and Medusa server are all distributed as separate projects. This separation gives developers the freedom to shape their ecommerce stack as they see fit to their use case. However, it’s easier to manage the different components that shape your ecommerce stack from one repository rather than different ones.

In this tutorial, you will learn how to set up and deploy the entirety of the frontend of your ecommerce stack in a monorepo with two projects, one for the admin panel and the other for the storefront.

Prerequisites

To follow along with this tutorial you need the following:

A Medusa server with a working storage plugin. If not, you can follow this tutorial to get a server deployed on Amazon Web Services (AWS), and you can follow this documentation to use S3 for your storage.

The server needs to have its API ready to be consumed over HTTPS. This is because once you deploy your apps to Vercel, they will have by default a domain with an SSL certificate. If you try to make requests from them to a server without an SSL certificate, then you will get a mixed-content warning in your browser and you won’t be able to fetch data from the API.

A GitHub account and a newly created repository to be the monorepo.
A Vercel account.
Optionally you can install and use Yarn to follow along with this tutorial. You’ll still be able to follow along with this tutorial if you prefer using NPM.

Set Up a Monorepo

The first step is to create the Monorepo that will hold the storefront and admin.

Open your terminal and run the following command:

mkdir medusa-monorepo && cd medusa-monorepo && git init

With this command you are doing three things:

Creating a new folder for the monorepo, which is called medusa-monorepo.
Change to the monorepo directory.
Initialize a git repository to have a control version system.

Add Admin Website to The Monorepo

The first project you’ll add to the monorepo is the admin. Medusa provides an intuitively designed admin panel that includes all features to manage your ecommerce store.

To add Medusa’s Admin to the monorepo, inside the medusa-monorepo folder run the following command:

git clone https://github.com/medusajs/admin admin

This will clone the admin’s GitHub repository inside your monorepo into a new directory called admin.

Make sure there is no .git folder inside medusa-monorepo/admin. If not, the admin project will be a sub-module of the monorepo rather than managed by the monorepo itself.

The next step is to install the dependencies for the admin app. Run the following command to change to the admin directory and install the dependencies:

cd admin
yarn install

Let’s test the admin app locally. For that, you need to have a local Medusa server installed and running. Then, run the following command inside the admin folder:

yarn develop

You can view the admin in the browser by going to the URL http://localhost:7000.

If you get a CORS error, please check this guide to resolve it.

Add Storefront Website to the Monorepo

Medusa provides great flexibility in your choice of the storefront. You can use one of the ready-made starters, or you can create a storefront using a framework of your choice from scratch.

In this tutorial, you’ll be using Medusa’s Gatsby starter for your ecommerce storefront.

To add the Gatsby Storefront to the monorepo, clone the repository inside the medusa-monorepo directory with the following command:

git clone https://github.com/medusajs/gatsby-starter-medusa.git storefront

This will create a new directory storefront inside medusa-monorepo which will hold the code for your storefront.

As explained earlier, make sure there’s no .git folder inside the medusa-monorepo/storefront folder. If there is a .git folder then delete it.

The next step is to install the dependencies of the storefront app. Use the following command to change to the storefront directory and install the dependencies:

cd storefront
yarn install

Let’s test the storefront locally. You also need a Medusa server installed and running locally first.

Then, run the following command inside the storefront folder:

yarn develop

You can check the storefront in your browser by going to localhost:8000.

If you get a CORS error, please check this guide to resolve it.

Push Changes to the Monorepo

Now that both the storefront and the admin are working locally, the last step before deploying them is pushing the changes to the monorepo you created on your GitHub account.

Deploy to Vercel

One of the advantages of using Vercel for deployment is that it allows you to deploy multiple apps separately from a monorepo. Additionally, you get out-of-the-box CI/CD. So, every time you push new commits to GitHub, Vercel will trigger a new deployment with those changes and your apps will be updated.

Log in with your Vercel account and go to your dashboard. Here you will create two projects, one for the admin app and another for the storefront app.

Deploy the Admin Website

First, you’ll create the admin project. Click on the New Project button and you will be redirected to the new project screen. Then, you need to import your repository from GitHub. If you don’t have your GitHub account already linked to Vercel, click on Add GitHub Account and give the necessary permissions to Vercel so it can read your repositories.

Once Vercel can access your monorepo you should be able to import it. Click on Import.

On the next page, you’ll be asked to configure the project:

Give a name to your project. For example, medusa-admin.
For the Framework Preset choose Gatsby.js.
For the root directory, click on edit and a popup will be shown with the folder structure of the monorepo. Choose the admin folder and click on continue.

Lastly, open Environment Variables and add an environment variable with the URL of your Medusa server:

GATSBY_MEDUSA_BACKEND_URL=<YOUR_MEDUSA_SERVER_URL>

Your configuration setup should look like this:

Once you’re done, click on Deploy. The deployment could take a while as Vercel will install all the dependencies, run the build command, and finally assign a new random domain for your app with an SSL certificate included.

Once your app is deployed you will be redirected to the overview page of the project you just created for your admin app. There, you can find the URL of your admin.

Copy the admin’s URL and go to your Medusa server. You need to add or change the CORS environment variable to allow your admin app to consume the API of your Medusa server:

ADMIN_CORS=<YOUR_ADMIN_URL>

Once the changes are saved and reflected on the Medusa server, you can go to the admin panel URL and you should see the login page.

Try to log in with your admin user credentials and you should be redirected to your admin dashboard.

If you seeded your server with dummy data on installation, you can use the email admin@medusa-test.com and password supersecret.

Deploy Storefront Website

The process to deploy the storefront app is a little different than the Admin. This is because the storefront is configured to render as a static site generator (SSG). To do that, the storefront needs to make some requests to the Medusa server during build time. As the domain name for the storefront is still not set up or added as an environment variable on the Medusa server at this point, a CORS error will be thrown during build time.

So, you’ll first create a project with general configurations and, when you obtain the URL of your storefront, update those configurations to something more specific and redeploy your app.

On your Vercel dashboard, click on the New Project button and you will be redirected to the new project screen. On that page, click on the Import button of the same medusa-monorepo repository.

For the project configurations:

You need to give a name to the project, in this case, it will be medusa-storefront.
For Framework preset choose Other. Later on, you will update this setting to Gatsby.js.
Open Environment Variables and add the following environment variable with the URL of your Medusa server as its value:

GATSBY_MEDUSA_BACKEND_URL=<YOUR_MEDUSA_SERVER_URL>

At this point, you don’t have to choose any directory because you only need an app deployed on Vercel to get the storefront URL, as explained at the start of this section.

The configuration should be something like this:

Once you’re done, click on Deploy. Vercel will start a new deployment, but in this case, it will not install or build anything, and in the end, it will assign a random URL to the newly created app.

When the deployment is done, you will get a congratulations screen, click on Go to Dashboard.

On your project’s dashboard, you can see the info related to the deployment. Copy the URL of your storefront.

Then, go to your Medusa server again and change or add the environment variable STORE_CORS so the storefront can make requests to it without CORS errors:

STORE_CORS=<YOUR_STOREFRONT_URL>

Once you’ve saved the new environment variable and the change is reflected on your server, the next thing to do is update the configurations of the storefront project with configurations specific to it.

On your project’s dashboard, go to the Settings tab

In the Build & Development Settings section, change the Framework preset to Gatsby.js and click on Save.

In the Root directory section, change the value to storefront. This is the path of the storefront in the monorepo. Then, click on Save.

Your settings should look something like this:

The last step is to trigger a new deployment with the new configurations. Go to the Deployments tab

You should then see a previously finished deployment. Click on the 3 dots on the right side of that deployment and click on Redeploy.

A new deployment will start. This time Vercel will change to the storefront directory, install the dependencies, and build the app. Once the new deployment is completed, you will see the overview screen.

Now you can go to your app’s URL and you should see the newly deployed storefront app with the products and data from your Medusa server.

Test Deployed Apps

To test both apps, you can try to sign up as a new user on the storefront app:

Then, go to your admin dashboard and you should see your newly created user.

To test the CI/CD you can go back to your monorepo code and make some changes, then commit and push them to GitHub, Vercel will detect there is a new commit on your monorepo and it will start a new deployment for all your apps.

Conclusion

Medusa’s flexible architecture makes it easy to deploy different parts of your ecommerce stack separately or together.

By using a monorepo, you can utilize features from hosting platforms like Vercel such as out-of-the-box CI/CD and a secure domain to visit your apps.

Going forward, you can focus on developing or adding new functionalities for your ecommerce store including:

Set up Stripe as a payment method using the Stripe Plugin.
Add a product search engine to your storefront using the Algolia plugin to improve your customer’s experience.
Add an email notifications system using the SendGrid plugin to send emails to your customers and admin users.

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

Set up Open source Ecommerce in the cloud

Carlos Padilla — Thu, 31 Mar 2022 12:02:08 +0000

Introduction

Medusa is an open source headless commerce that allows you to build digital commerce through its API with just a few commands and in a matter of time. You can host Medusa’s server on any of your preferred hosting choices, and one way to host it is using AWS Elastic Beanstalk.

AWS Elastic Beanstalk is a service for deploying and scaling web applications and services developed with many programming languages and frameworks including Node.js.

Through this guide, you will learn how to create a simple pipeline with AWS CodePipeline that pulls your Medusa’s server code from a GitHub repository and automatically deploy it to AWS Elastic Beanstalk.

Why Elastic Beanstalk?

Using Elastic Beanstalk you will be able to deploy a Medusa server application within the AWS Cloud. You just deploy your application and Elastic Beanstalk mechanically handles the main points of capability provisioning, load equalization, scaling and application health observance.

Once you deploy your application, Elastic Beanstalk builds the chosen supported platform version and provisions all the AWS resources like AmazonEC2 instances or Databases that your application needs to run.

So, in a nut shell, AWS Elastic Beanstalk makes it easy for developers to deploy their applications and share them with the world.

Prerequisites

To follow along with this tutorial you need the following:

A working Medusa server application. You can follow the quickstart guide to get started.
A GitHub account.
An AWS Account with an IAM user, you can check here how to create one. Be sure your IAM user has the sufficient permissions to interact with Elastic Beanstalk, you can check more info about that here.

Set up a Node environment on Elastic Beanstalk

The first step is to create a Node.js environment on Elastic Beanstalk with a sample application. Later on you’ll replace the sample app with the Medusa server.

Go to AWS sign in page and login with your IAM user. You’ll be redirected to the Console Home page.

Once you are here, go to the top search bar and write Elastic Beanstalk; in the results choose the first option.

That will lead you to AWS Elastic Beanstalk Dashboard page, where you will have to click on the Create application button.

You can use “Create Web app” console wizard to create your sample application.

Specify your Elastic Beanstalk application name information, for this tutorial the name is aws-medusa-server.
Click on Platform drop-down and select the Node.js platform. At the time this article was written, the platform branch selected was Node.js 16 running on 64bit Amazon Linux 2, and the platform version was 5.5.0.
Select the Sample Application as application code.
Click on Configure more options and go to the Capacity section. Once you are there click on edit.
On the Modify capacity page go to instances types and choose t2.small and t2.medium, then click on save.

⚠️ This step is very important because by default the instances type are t2.micro and t2.small, however the micro instance has only 1 Gb of RAM. This is enough for testing and development, but we recommend going with a larger instance for a production environment.

Back in the Configure more options page, go to the Database section and click on edit. Here you are going to set up the PostgreSQL database needed for the medusa server. The suggested configuration is to choose postgres as engine with version 10, 11 or 12. You’ll also need to enter a username and password. Make sure to save those for later as you’ll use them. Once you’re done, click on Save.
Last, click on “Create App“ button. It will take few minutes to launch your application.

Once the environment is created you can go to the overview page and check Environment Health, application running version and application platform version where application is running on.

On top of this page you will see the environment’s URL below the environment name, click on this URL to get to the sample application’s congratulations page.

Until this point you should have a Node environment running on AWS Elastic Beanstalk with a sample application, the next step is to prepare the medusa server to be deploy on this environment.

Preparing Medusa server

To create the pipeline for CI/CD you need to do some changes on your medusa server repository and push them to GitHub.

First, in your Medusa server, open your package.json file and add the following property at the end

"engines": {
  "node": ">=16.0.0"
}

Be careful: the node version must match the version that you set when creating the environment. AWS Elastic Beanstalk will search for this before deploying your app with AWS CodePipeline, so, if you don’t do this, then the deployment will fail.

In this file, you also need to change the start command to the following:

"start": "medusa migrations run && medusa develop -p=8080",

Basically, what you are doing is changing the port on which the medusa server run by default, so, instead of running on port 9000 it will run on port 8080. The main reason to do this is because by default AWS Beanstalk run ngix as reverse proxy to redirect all the incoming traffic from the internet on port 80 to port 8080.

Also, it is necessary to run migrations on the server before running the Medusa server.

The next step is to add a Procfile to the root of your project with the next line of code

web: npm run start

This instructs AWS Beanstalk on how to run your application once all the dependencies are installed with npm install, first it will run the medusa migrations, and then it will start the app.

The last thing you need to do is make sure you’ve set your Database to use PostgreSQL. In medusa-config.js, make the following changes in the exported object:

database_url: DATABASE_URL,
atabase_type: "postgres",
// database_database: "./medusa-db.sql",
// database_type: "sqlite",

When all these changes are done, commit and push them to your remote repository on GitHub.

Once the repository is ready on GitHub, the next step is to create an AWS CodePipeline.

Add environment properties

To create the pipeline, you need to set some environment variables on your node environment on AWS Beanstalk. This is because when you finish setting up the code pipeline, it will be triggered immediately and it will do the first deployment. So, to get an OK status all the env variables needed by the Medusa server need to be set in advance.

On the overview page of AWS Beanstalk, go to the left pane and search for the configuration menu of your node environment and click on it.

Then click on the Edit button next to Software.

In the Modify software page go to the last section called *Environment properties* and add the following properties

NPM_USE_PRODUCTION=false
JWT_SECRET=something
COOKIE_SECRET=something
DATABASE_URL=postgres://<<USERNAME>>:<<PASSWORD>>@<<DATABASE_URL>>:5432/<<DB_NAME>>

Pay special attention to the first and last properties. The first property is to allow AWS Beanstalk to install the dependencies (babel) needed to run the command medusa develop.

The last one is the URL to connect to the database. Here, you need to change <<USERNAME> and <<PASSWORD>> with the ones you set when creating the node environment.

As for <<DB_NAME>> and <<DB_URL>> you can find those by searching for “RDS” in your AWS Console. Then click on Databases in the sidebar. You should see a PostgreSQL database.

Click on the DB identifier and scroll down to Connectivity & Security. The URL under Endpoint is your <<DB_URL>>. As for <<DB_NAME>> , you can find it under the Configuration tab. By default, it’s ebdb.

After adding the environment variables, click on Apply and wait until the environment is updated with this changes. Once the update is complete, you can now go on and create the CodePipeline.

Set up AWS CodePipeline

The goal of the pipeline is to listen for changes or commits on the main branch of your Medusa server’s repository on GitHub. When this happen the pipeline will be triggered and it will starts a new deployment to update your application on AWS Beanstalk.

Make sure that before continuing with this step you’ve created a repository for your Medusa server.

Go to the top search bar and write CodePipeline in the results choose the first option

On CodePipeline dashboard page click on the button “Create Pipeline”.

⚠️ Make sure that your are in the same region where is your node environment.

On the Choose pipeline settings page, give a name to the pipeline and leave everything as it is and click on the Next button. For this tutorial, the name will be aws-medusa-server-pipeline.

On the Add source stage page, under Source Provider dropdown choose GitHub (Version 2). Then, If you have not created a GitHub connection, click on “Connect to GitHub” button to grant permission to AWS CodePipeline to access your Medusa server repository on GitHub. This will help AWS Code Pipeline to upload your committed changes from GitHub to AWS CodePipeline.

Once you’ve connected GitHub, choose your repository and the branch from where you will be pulling your application.

Check the option that says Start the pipeline on source code change and for the Output artifact format option choose “CodePipeline default”. Click on the Next button.

On the Add build stage page, you will click on the Skip build stage button.

On the Add deploy stage page, under Deploy provider dropdown, select “AWS Elastic Beanstalk”, then choose the region your node environment is in and the application and environment you created earlier (in the case of this tutorial these are aws-medusa-server and Awsmedusaserver-env respectively) Once you’re done, click on the Next button.

On the Review page, check that everything is fine. Then, click on the Create pipeline button.

You will see a success message banner displayed, and the pipeline actions will be running until they are completed. If everything went fine, both stages will be marked with a checkmark success.

Test it Out

To check that your Medusa server is working, go back to the Elastic Beanstalk dashboard and search for the environment’s URL below the environment name, then do the following:

Copy the URL.
Open a new tab in your browser, paste the URL and add at the final /health, so the URL would something like this:

http://awsmedusaserver-env.eba-kkrjvcxb.us-west-2.elasticbeanstalk.com/health

You should get an OK message, if that is the case, then you have successfully deployed your Medusa server into AWS Elastic Beanstalk.

💡 Make sure to change the URL in your Medusa storefront or admin based on the URL of your server.

Troubleshooting

If you run into any issues or there’s a problem with your deployed server, you can check the logs in your Elastic Beanstalk instance by clicking on Logs in the sidebar.

Conclusion

Deploying a Medusa server on AWS Elastic Beanstalk is easier with the help of CI/CD pipelines. Once you’re done, you can focus on adding new functionality to your Medusa server as custom endpoints, services or plugins.

Then, to push the changes to your server you can just push them to your GitHub repository. The configured pipeline will detect changes and start execution. Your application will then be updated with the new features.

To learn more about how to customize your store or how you can connect a storefront to your store, be sure to check out Medusa’s documentation.

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

An open source ecommerce platform for Nuxt.js

Carlos Padilla — Tue, 01 Mar 2022 13:00:34 +0000

Introduction

Medusa is an open source headless commerce engine in Node.js that allows you to build online stores through its API with just a few commands - link to repo. On the other hand, Nuxt.js is a front-end framework, built on top of Vue.js, that includes some features out-of-the-box such as server-side rendered sites, static sites, file system routing, data fetching, meta tags, SEO, and much more.

Through this guide, you will learn how to set up a starter storefront with Nuxt.js for the frontend part and link it with a Medusa server. To do that, first, you will create a Nuxt.js project and set up some simple components, pages and layout. Then, you will link the Nuxt.js project with the Medusa server to get some products from the API and display them on the home page, a product's page, and a product detail page.

You can find the final code at this GitHub repository.

If you have any problems underway in the setup, please reach out in the Medusa Discord.

Prerequisites

To follow along with this tutorial you need the following:

Node.js, it is recommended to have the latest LTS version installed.
One of the following package managers installed: npm, yarn, or npx (included by default with npm v5.2+).
A Medusa server is seeded with some dummy data to work with, so if this is not the case, please first read the QuickStart guide to set up a Medusa server and after that come back to continue.

Setting up the storefront

⚠️ This tutorial uses Nuxt v2.15.8 because at the time of writing this article there are two versions of Nuxt, but the newer one (Nuxt v3) is yet in beta state.

Install a Nuxt.js project

To install a Nuxt project, you can get started quickly with create-nuxt-app. Open your terminal and run the following command

// npx create-nuxt-app <project-name>
npx create-nuxt-app nuxtjs-storefront

It will ask you some questions. You can choose the options that best fit your development workflow, but to keep this tutorial simple, I recommend installing the project using the following options:

Run Nuxt.js project

Once the Nuxt.js project is created, change to the directory of the storefront

cd nuxtjs-storefront

And then run the following command

yarn dev

This command will run the storefront app by default at http://localhost:3000. To test it, open your browser and go to http://localhost:3000. You will get something like this:

Later on, you will change the default port to learn how to integrate your frontend with the Medusa server in a port that is not the default.

Make the storefront layout

Before you go into connecting the Medusa server with the storefront, you need to add some components and pages to the storefront. Open the storefront’s project in your preferred IDE.

You should see the following directories:

You will be focusing mainly on the components and pages directories to design the layout for the storefront.

Components

Components are what make up the different parts of your page. They can be reused and imported into your pages, layouts, and even other components.

The storefront you are creating will have the following components:

Logo
Navbar
Footer
Product card

Go to the components directory and delete the default components that come with the Nuxt.js installation. Then add the following files

Logo → components/App/Logo.vue

<template>
  <div class="h-16 flex items-center">
    <div class="ml-4 flex lg:ml-0 lg:mr-8">
      <nuxt-link to="/">
        <img class="h-8 w-auto" src="https://i.imgur.com/y3yU55v.png" alt=""/>
      </nuxt-link>
    </div>
  </div>
</template>

<script>
export default {
  name: 'AppLogo'
}
</script>

Navbar → components/App/Navbar.vue

<template>
  <div class="sticky top-0 z-20">
    <header class="relative bg-white">
      <nav class="px-4 sm:px-6 lg:px-8 border-b border-ui-medium flex items-center justify-between">
        <div class="flex items-center">
          <app-logo />
          <div class="hidden lg:flex lg:items-center">
            <div class="hidden flex-grow items-center justify-center lg:flex text-sm font-medium">
              <nuxt-link
                to="/"
                class="block mt-4 mr-4 lg:inline-block lg:mt-0 text-gray-700 hover:text-gray-600 last:mr-0"
              >
                Home
              </nuxt-link>
              <nuxt-link
                to="/products"
                class="block mt-4 mr-4 lg:inline-block lg:mt-0 text-gray-700 hover:text-gray-600 last:mr-0"
              >
                Products
              </nuxt-link>
            </div>
          </div>
        </div>

        <div class="flex items-center justify-end">
          <div class="hidden lg:flex">
            <div class="inline-block relative text-left">
              <div>
                <button
                  class="inline-flex justify-center w-full px-4 py-2 bg-white text-sm font-medium text-gray-700 hover:text-gray-600"
                  type="button"
                >
                  USA / USD
                </button>
              </div>
            </div><div class="relative inline-block text-left">
              <div>
                <button
                  class="inline-flex justify-center w-full px-4 py-2 text-sm font-medium text-gray-700 hover:text-gray-600"
                  type="button"
                >
                  Account
                </button>
              </div>
            </div>
          </div><div class="relative inline-block text-left">
            <div>
              <button
                class="inline-flex items-center justify-center w-full py-2 bg-white text-sm font-medium hover:opacity-1/2"
                type="button"
              >
                <svg width="40" height="41" viewBox="0 0 40 41" fill="none" xmlns="http://www.w3.org/2000/svg">
                  <path
                    fill-rule="evenodd"
                    clip-rule="evenodd"
                    d="M14.9968 16.2273C14.9921 16.1189 14.9888 16.0004 14.9877 15.8734C14.9826 15.2497 15.0333 14.4053 15.2648 13.551C15.4962 12.6975 15.9164 11.8043 16.6719 11.123C17.4366 10.4333 18.5016 10 19.9419 10C21.3822 10 22.4472 10.4333 23.212 11.123C23.9674 11.8043 24.3877 12.6975 24.619 13.551C24.8506 14.4053 24.9012 15.2497 24.8961 15.8734C24.8951 16.0004 24.8917 16.1189 24.887 16.2273H27.8836C29.0776 16.2273 30.0056 17.2667 29.8708 18.4531L28.7344 28.4531C28.6196 29.4638 27.7644 30.2273 26.7472 30.2273H13.1366C12.1194 30.2273 11.2643 29.4638 11.1494 28.4531L10.013 18.4531C9.87822 17.2667 10.8062 16.2273 12.0002 16.2273H14.9968ZM23.8859 16.2273C23.8912 16.1186 23.8951 15.9971 23.8962 15.8652C23.9008 15.2957 23.8535 14.5493 23.6538 13.8126C23.454 13.0752 23.1098 12.3775 22.5422 11.8656C21.984 11.3622 21.1673 11 19.9419 11C18.7165 11 17.8999 11.3622 17.3416 11.8656C16.774 12.3775 16.4299 13.0752 16.23 13.8126C16.0303 14.5493 15.983 15.2957 15.9877 15.8652C15.9888 15.9971 15.9926 16.1186 15.9979 16.2273H23.8859ZM12.0002 17.2273H27.8836C28.4806 17.2273 28.9446 17.747 28.8772 18.3402L27.7408 28.3402C27.6834 28.8455 27.2558 29.2273 26.7472 29.2273H13.1366C12.628 29.2273 12.2004 28.8455 12.143 28.3402L11.0066 18.3402C10.9392 17.747 11.4032 17.2273 12.0002 17.2273ZM15.4874 20.0455C15.8388 20.0455 16.1237 19.7605 16.1237 19.4091C16.1237 19.0576 15.8388 18.7727 15.4874 18.7727C15.1359 18.7727 14.851 19.0576 14.851 19.4091C14.851 19.7605 15.1359 20.0455 15.4874 20.0455ZM25.0328 19.4091C25.0328 19.7605 24.7479 20.0455 24.3965 20.0455C24.045 20.0455 23.7601 19.7605 23.7601 19.4091C23.7601 19.0576 24.045 18.7727 24.3965 18.7727C24.7479 18.7727 25.0328 19.0576 25.0328 19.4091Z"
                    fill="black"
                  /></svg>
                <span>0</span>
              </button>
            </div>
          </div>
        </div>
      </nav>
    </header>
  </div>
</template>

<script>
export default {
  name: 'NavBar'
}
</script>

Footer → components/App/Footer.vue

<template>
  <footer>
    <div class="bg-white px-4 pt-24 pb-4 sm:px-6 lg:px-8 border-t border-ui-medium flex items-center justify-between text-sm">
      <div class="flex items-center">
        <a class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700" href="/">Create return</a>
        <a class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700" href="/">FAQ</a>
        <a class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700" href="/">Terms &amp; Conditions</a>
      </div>
      <div class="flex items-center">
        <a href="https://www.github.com/medusajs" class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700">GitHub</a>
        <a href="https://www.twitter.com/medusajs" class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700">Twitter</a>
        <a href="https://discord.gg/ruGn9fmv9q" class="mr-3 last:mr-0 text-ui-dark hover:text-gray-700">Discord</a>
      </div>
    </div>
  </footer>
</template>

<script>
export default {
  name: 'AppFooter'
}
</script>

ProductCard → components/ProductCard.vue

<template>
  <div>
    <nuxt-link :to="`/products/${item.id}`">
      <div
        class="group relative"
      >
        <div class="w-full min-h-auto bg-gray-200 aspect-w-1 aspect-h-1 rounded-md overflow-hidden group-hover:opacity-75 lg:h-80 lg:aspect-none">
          <div class="w-auto h-full object-center object-cover bg-gray-100">
            <img
              alt=""
              :src="item.thumbnail"
            >
          </div>
        </div>
        <div class="mt-4 flex justify-between">
          <h3 class="text-sm text-gray-700 font-normal">
            {{ item.title }}
          </h3>
          <p class="text-sm font-semibold text-gray-900">
            from {{ lowestPrice.amount/100 }} {{ lowestPrice.currency_code.toUpperCase() }}
          </p>
        </div>
      </div>
    </nuxt-link>
  </div>
</template>

<script>
export default {
  name: 'ProductCard',
  props: {
    item: {
      type: Object,
      default () {
        return {
          id: 1,
          title: 'Kitchen Table',
          thumbnail: 'https://picsum.photos/600/600',
          variants: [{ prices: [{ amount: 0 }] }]
        }
      }
    }
  },
  computed: {
    lowestPrice () {
      const lowestPrice = this.item.variants.reduce((acc, curr) => {
        return curr.prices.reduce((lowest, current) => {
          if (lowest.amount > current.amount) {
            return current
          }
          return lowest
        })
      }, { amount: 0 })

      return lowestPrice || { amount: 10, currency_code: 'usd' }
    }
  }
}
</script>

Pay extra attention to the Logo, Navbar, and Footer components. They need to be inside a folder called App.

Pages

The pages directory contains your storefront views and routes. For this tutorial you will need only 3 pages:

Home page
Products page
Product detail page

On the pages directories, open the index.vue file and replace the code that is already there with this one

Index → /pages/index.vue

    <template>
      <div>
        <div class="bg-ui-light pb-12 lg:pb-0 w-full px-4 sm:px-6 lg:px-12">
          <div class="flex flex-col lg:flex-row items-center max-w-screen-2xl mx-auto">
            <div class="w-auto h-full object-center object-cover p-12">
              <img
                width="600"
                alt=""
                src="https://start.medusajs.com/static/9803c162c71fd1960d9d11253859c701/246b5/hero-merch.webp"
              >
            </div>
            <div>
              <h1 class="text-4xl">
                CLAIM YOUR MERCH
              </h1>
              <p class="mt-2 text-lg font-normal">
                Contribute to Medusa and receive free merch<br>as a token of our appreciation
              </p>
              <button class="btn-ui mt-4 min-w-full lg:min-w-0">
                Learn more
              </button>
            </div>
          </div>
        </div>

        <div
          v-if="products.length"
          class="container mx-auto px-8 py-16"
        >
          <div class="flex items-center justify-between mb-6">
            <p class="text-2xl font-semibold text-gray-700">
              Featured
            </p>
            <nuxt-link
              class="text-ui-dark flex items-center"
              to="/products"
            >
              <span class="mr-2 text-ui-dark">Browse all products</span>
              <svg
                width="16"
                height="8"
                viewBox="0 0 16 8"
                fill="none"
                xmlns="http://www.w3.org/2000/svg"
              >
                <path d="M15.3536 4.35355C15.5488 4.15829 15.5488 3.84171 15.3536 3.64645L12.1716 0.464466C11.9763 0.269204 11.6597 0.269204 11.4645 0.464466C11.2692 0.659728 11.2692 0.976311 11.4645 1.17157L14.2929 4L11.4645 6.82843C11.2692 7.02369 11.2692 7.34027 11.4645 7.53553C11.6597 7.7308 11.9763 7.7308 12.1716 7.53553L15.3536 4.35355ZM0 4.5H15V3.5H0V4.5Z" fill="#89959C" />
              </svg>
            </nuxt-link>
          </div>
          <div class="grid grid-cols-4 gap-8">
            <ProductCard
              v-for="product in products"
              :key="product.id"
              :item="product"
            />
          </div>
        </div>
      </div>
    </template>

    <script>
    export default {
      name: 'IndexPage',
        data () {
        return {
          products: [{
            id: 1,
            title: 'Kitchen Table',
            thumbnail: 'https://picsum.photos/600/600',
            variants: [{ prices: [{ amount: 0, currency_code: 'usd' }] }]
          }]
        }
      },
    }
    </script>

    <style>
      .btn-ui {
        @apply py-2 px-4 bg-ui-dark text-white text-sm font-medium rounded-md shadow;
        @apply focus:outline-none focus:ring-2 focus:ring-ui-dark focus:ring-opacity-75 disabled:bg-ui-medium;
      }
    </style>

This page will be the home for your storefront. It is composed of a hero header and a grid configured to show only four products. The only thing to do here once you connect the storefront to the Medusa server will be to put the ProductCard component in a v-for loop to display the products.

Now, you need to create a new directory called products which will hold inside the products page /pages/products/index.vue and the product detail page /pages/products/_id.vue. Add the following code to these pages.

Products page → /pages/products/index.vue

<template>
  <div class="container mx-auto p-8">
    <div class="w-full border-b border-ui-medium pb-6 mb-2 lg:mb-6 flex items-center justify-between">
      <h1 class="font-semibold text-3xl">
        All Products
      </h1>
    </div>

    <div
      v-if="products.length"
      class="grid grid-cols-4 gap-8 "
    >
      <ProductCard
        v-for="product in products"
        :key="product.id"
        :item="product"
      />
    </div>
  </div>
</template>

<script>
export default {
  name: 'ProductsIndex',
    data () {
    return {
      products: [{
        id: 1,
        title: 'Kitchen Table',
        thumbnail: 'https://picsum.photos/600/600',
        variants: [{ prices: [{ amount: 0, currency_code: 'usd' }] }]
      }]
    }
  },
}
</script>

This page is similar to the home page but without the hero header. Here you will show a grid with all the products sent by the Medusa server.

Product detail page → /pages/products/_id.vue

<template>
  <div class="container mx-auto p-8">
    <div class="flex flex-col lg:flex-row">
      <div class="lg:w-3/5 lg:pr-14">
        <div class="flex">
          <div class="hidden lg:flex flex-col items-center mr-4">
            <div class="w-auto h-full object-center object-cover px-4 space-y-4">
              <img
                v-for="image in product.images"
                :key="image.id"
                width="150"
                alt=""
                :src="image.url"
                class="cursor-pointer"
                @click="imageToShow = image.id"
              >
            </div>
          </div>

          <div class="h-auto w-full flex-1 flex flex-col rounded-lg overflow-hidden">
            <div class="w-auto h-full">
              <div
                v-for="image in product.images"
                :key="image.id"
              >
                <div v-if="image.id === imageToShow">
                  <img
                    alt=""
                    :src="image.url"
                    class=" w-full"
                  >
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>

      <div class="mt-8 lg:mt-0 lg:w-2/5 lg:max-w-xl">
        <h1 class="font-semibold text-3xl">
          {{ product.title }}
        </h1>
        <p v-if="product.variants" class="text-lg mt-2 mb-4">
          {{ product.variants[0].prices[0].amount/100 }} {{ product.variants[0].prices[0].currency_code }}
        </p>
        <p v-else>
          10 USD
        </p>
        <p class="font-light">
          {{ product.description }}
        </p>
        <div v-for="option in options" :key="option.id" class="mt-6">
          <div class="text-sm">
            <p class="font-medium mb-2">
              {{ option.title }}
            </p>
            <div>
              <button
                v-for="value in option.values"
                :key="value.id"
                class="bg-ui-dark text-white inline-flex items-center justify-center rounded-sm text-xs h-12 w-12 mr-2 last:mr-0 hover:bg-ui-dark hover:text-white"
              >
                {{ value.value }}
              </button>
            </div>
          </div>
        </div>
        <div class="inline-flex mt-12">
          <button class="btn-ui mr-2 px-12">
            Add to bag
          </button>
          <div class="flex items-center rounded-md px-4 py-2 shadow">
            <button>–</button>
            <span class="w-8 text-center">1</span>
            <button>+</button>
          </div>
        </div>
        <div class="mt-12">
          <div class="border-t last:border-b border-ui-medium py-6">
            <h3 class="-my-3 flow-root">
              <button
                class="py-3 bg-white w-full flex items-center justify-between text-sm text-gray-400 hover:text-gray-500"
                type="button"
                @click="showDetails = !showDetails"
              >
                <span class="font-medium text-gray-900">Details</span>
                <span class="ml-6 flex items-center">
                  <span>—</span>
                </span>
              </button>
            </h3>
            <div v-if="showDetails" class="pt-6">
              <div class="space-y-4 text-ui-dark text-sm">
                <ul class="list-inside list-disc space-y-2">
                  <li>Weight: {{ product.weight ? `${product.weight} g` : 'Unknown' }}</li>
                  <li>Width: {{ product.width ? `${product.width} cm` : 'Unknown' }}</li>
                  <li>Height: {{ product.height ? `${product.height} cm` : 'Unknown' }}</li>
                </ul>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script>
export default {
  name: 'ProductDetail',
  data () {
    return {
      showDetails: false,
      imageToShow: 'default_image',
      product: {
        id: 1,
        title: 'Medusa Coffee Mug',
        description: 'Every programmer\'s best friend.',
        thumbnail: '',
        variants: [{ prices: [{ amount: 0, currency_code: 'usd' }] }],
        images: [
          { id: 'default_image', url: 'https://picsum.photos/600/400' },
          { id: 'another_image', url: 'https://picsum.photos/600/400?id=100' }
        ]
      }
    }
  },
  computed: {
    lowestPrice () {
      const lowestPrice = this.product.variants.reduce((acc, curr) => {
        return curr.prices.reduce((lowest, current) => {
          if (lowest.amount > current.amount) {
            return current
          }
          return lowest
        })
      }, { amount: 0 })

      return lowestPrice || { amount: 10, currency_code: 'usd' }
    },
    options () {
      if (this.product.options) {
        return this.product.options.map((option) => {
          option.values = option.values.reduce((acc, curr) => {
            if (!acc.find(val => val.value === curr.value)) {
              return [...acc, { ...curr }]
            }
            return acc
          }, [])

          return option
        })
      }
    }
  }
}
</script>

On this page, you will display all the information related to a specific product. For example, sizes, images, price, description, variants, etc...

⚠️ The three pages include a product object on the data function to showcase the design while there isn’t a server to send requests. Once you connect the storefront with the Medusa server, the data coming from the server will replace the data in the product object.

Layouts

Layouts are a great help when you want to have a basic structure for your Nuxt app. For example, to include a navbar and footer that will be shown on all the pages of the app. By default, a Nuxt project doesn't come with layouts, but it is easy to add them to your project.

To have a default layout on your storefront, create a layouts directory in the root of the project, and inside it, add a new file called default.vue with the following code:

<template>
  <div class="min-h-screen flex flex-col">
    <app-navbar />

    <main class="flex-1">
      <Nuxt />
    </main>

    <app-footer />
  </div>
</template>

<script>
export default {
  name: 'DefaultLayout'
}
</script>

Because the layout file was named default.vue, the layout will automatically be applied to all the pages on the storefront.

Styling

Replace the content of windi.config.ts in the root of your Nuxt.js project with the following:

import { defineConfig } from '@windicss/plugin-utils'

export default defineConfig({
  /**
   * Write windi classes in html attributes.
   * @see https://windicss.org/features/attributify.html
   */
  attributify: true,
  theme: {
    extend: {
      fontSize: {
        '2xs': '0.5rem'
      },
      maxWidth: {
        '1/4': '25%',
        '1/2': '50%',
        '3/4': '75%'
      },
      maxHeight: {
        review: 'calc(100vh - 10rem)'
      },
      boxShadow: {
        DEFAULT:
          '0 2px 5px 0 rgba(60, 66, 87, 0.08), 0 0 0 1px rgba(60, 66, 87, 0.16), 0 1px 1px rgba(0, 0, 0, 0.12)',
        error:
          '0 2px 5px 0 rgba(255, 155, 155, 0.08), 0 0 0 1px rgba(255, 155, 155, 0.70), 0 1px 1px rgba(0, 0, 0, 0.12)'
      },
      colors: {
        green: {
          DEFAULT: '#56FBB1'
        },
        blue: {
          DEFAULT: '#0A3149'
        },
        ui: {
          light: '#F7F7FA',
          DEFAULT: '#EEF0F5',
          medium: '#D9DFE8',
          dark: '#89959C'
        }
      }
    }
  }
})

Change the Default Port

Now, you will change the port where the storefront app runs by default (port 3000). To do that, open the nuxt.config.js file and add the following right after the ssr property

server: {
  port: 3333
},

After that, run the following command to see in the browser what you have achieved with the components, pages, and layout that you just set up until this part of the tutorial.

yarn dev

Open your browser and go to the URL localhost:3000. You should see something like this:

The storefront just shows static data for now. You will link the storefront with the Medusa server in the next section.

Link Medusa server with storefront

To link the server with the storefront, first, open up your Medusa project in your IDE, then open the .env file where all your environment variables are set up.

Add the variable STORE_CORS with the value of the URL where your storefront will be running. Remember that you changed the default port on the storefront, therefore the URL is http://localhost:3333.

STORE_CORS=http://localhost:3333

After this, your Medusa server will be ready to receive a request from your storefront and send back responses if everything works as expected.

⚠️ The medusa server is running by default in port 9000, so the URL to use on the storefront to send requests is http://localhost:9000.

Testing connection with Medusa server

To be able to list the products on the home page you need to test if you can send requests from your storefront to the Medusa server and receive some data to show on the front-end.

⚠️ Be sure the @nuxtjs/axios module is installed in your storefront project. If it’s not, then you need to install it following these instructions.

Once the project has the axios module, you need to change the base URL for the axios module that you’ll use to make the requests to the server.

Open the nuxt.config.js file and look for the axios property. Change the baseURL property to match the URL where the medusa server will be running:

axios: {
  baseURL: 'http://localhost:9000/'
},

With this change, you don’t have to type the full URL each time you need to make an HTTP request to the Medusa server. So, instead of this:

$axios.$get('http://localhost:9000/store/products')

You will do this:

$axios.$get('/store/products')

If the server URL changes in the future, you only need to come back to one place and update that just one time, and everything will be working fine.

To fetch data from the API, this tutorial uses the fetch function that Nuxt.js offers as part of the core.

Open the file /pages/index.vue and add the fetch function in the script section:

async fetch () {
    try {
      const { products } = await this.$axios.$get('/store/products')
            console.log(products)
      this.products = products
    } catch (e) {
      // eslint-disable-next-line no-console
      console.log('The server is not responding')
    }
  }

This function receives just one parameter $axios which is a service that allows making an HTTP request to the Medusa server. So, inside the function, a request is sent to the endpoint /store/products to obtain the list of products from the Medusa server. Then, the list of products is returned.

To test this out, run the following command in the terminal to start the medusa server:

medusa develop

And start the storefront server:

yarn dev

Open your browser and go to the URL localhost:3000. Then, open the Web Developer Tools.

If you find something like this in the console tab then your connection to the Medusa server is working. Otherwise, check that you follow all the steps and are not missing anything.

🧠 Remember, the URL where your storefront app is running has to be the same that was set up on STORE_CORS variable on the medusa server.

Display Products on the Home Page

Now is time to render the products result returned from the Medusa server on the storefront.

In the same file /pages/index.vue, update the fetch function to the following,

async fetch () {
    try {
        const { products } = await this.$axios.$get('/store/products')
        this.products = products.splice(0, 4)
    } catch(e) {
        // eslint-disable-next-line no-console
        console.log('The server is not responding')
  }
}

With this update, the data coming back from the server replaces the products array with only four products to display on the homepage.

The v-for applied on the ProductCard iterates the products array and passes to the component, as a prop, a product with all the properties specified on the Medusa API for that endpoint.

If you check the storefront on the browser it should look something like this:

Display Products on The Products Page

In the navigation bar, there is a “Products” link. If you click on it, you will be redirected to the products page, but there will be only one static product. Let’s fix that to display all the products in your Medusa server on the page.

Open the /pages/products/index.vue file, go to the script section and add the following fetch function

async fetch () {
  try {
    const { products } = await this.$axios.$get('/store/products')
    this.products = products
  } catch (e) {
    // eslint-disable-next-line no-console
    console.log('The server is not responding')
  }
}

Check the products page in your browser and you should get something like this:

Display Product Details

The last page to update is the product detail page. If you click on any product on the home page or the products page, it will take you to the product’s details page, but you won’t see any details at all. To fix it, you need to request a specific product to the Medusa server so you can get all the product info.

Open the file /pages/products/_id.vue and add the following fetch function

aasync fetch () {
  try {
    const { product } = await this.$axios.$get(`/store/products/${this.$route.params.id}`)
    this.product = product
    this.imageToShow = this.product.images[0].id
  } catch (e) {
    // eslint-disable-next-line no-console
    console.log('The server is not responding')
  }
},

If you go again to your browser and click on any product, you will be taken to the product details page like before, but this time you’ll see all details rendered on the page.

Conclusion

As you learned in this tutorial it is very easy to make a storefront from zero with Nuxt.js and integrate it with your Medusa server.

The next steps for you would be to check the Medusa API to learn about all the different requests that you can call from your storefront to turn your Nuxt.js storefront into a full-fledged online store.

For example, you can implement the Cart functionality. The process would involve making the pages or components on the Nuxt.js app and then making the respective requests to the Medusa server to get the data to render on the storefront.

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