TLDR

• Create a Neon Postgres db and copy connection string.
• Scaffold a Medusa project in your terminal:

npx create-medusa-app@latest --with-nextjs-starter --db-url "postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require"

• Visit localhost:8000 to view your storefront and localhost:7001 to view your Store Admin Dashboard
• GitHub Repo

Introduction

In this guide, you will learn how to set up and build an ecommerce store using Medusa ecommerce toolkit and Neon Postgres. Medusa comes with a backend server, a store admin dashboard and a storefront made using Next.js. You will configure Medusa to use a Postgres database powered by Neon.

Prerequisites

To follow along you will need:

• Node.js 16.14.0 or later
• A Neon Postgres account

Create PostgreSQL Database for Medusa store on Neon

Using a serverless Postgres database powered by Neon lets you scale down to zero, which helps you save on compute costs.

To get started, go to the Neon console and create a project. This creates a Postgres database.

Copy the Connection String of your database in the Connection Details panel.

The Neon connection string will have the following format:

postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require

• <user> is the database user.
• <password> is the database user’s password.
• <endpoint_hostname>.neon.tech is the host with neon.tech as the top-level domain (TLD).
• <port> is the Neon port number. The default port number is 5432.
• <dbname> is the name of the database. neondb is the default database created with each Neon project if you do not define your own.
• ?sslmode=require is an optional query parameter that enforces SSL mode for better security when connecting to the Postgres instance.

Save the connection string somewhere safe.

Create a new Medusa commerce application

Medusa is a toolkit for developers to create digital commerce applications. In its simplest form, Medusa is a Node.js backend with the core API, plugins, and modules installed through npm.

create-medusa-app is a command that facilitates creating a Medusa ecosystem. It installs the Medusa backend and admin dashboard, along with the necessary configurations to run the backend.

If you want to connect to a Neon database, you must use the --db-url option with its value being the connection string to your Neon database. The connection string you saved in the previous step

In your terminal, run the following command:

npx create-medusa-app@latest --with-nextjs-starter --db-url "postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require"

Specify project name

After running the command, you will be asked first to enter the name of your project, which is used to create the directory holding your Medusa backend. You can use the default my-medusa-store or enter another project name.

Specify admin email

You'll then be prompted to enter an admin email for your admin user. You'll be using this admin email later to login to your admin dashboard. You can use the default admin@medusa-test.com or enter any other email.

After specifying the project name as well as admin email, the Next.js Medusa starter storefront will be installed along with the Medusa backend. This will install the storefront under the <PROJECT_NAME>-storefront directory, where <PROJECT_NAME> is the name of the project you specified earlier.

Log into Medusa Admin Dashboard

Once the project is prepared, the Medusa backend will start. Visit localhost:7001 to view the admin dashboard in your browser. You'll then be asked to enter a password for the admin email you entered earlier, as well as other account information.

Once you're logged in, you can start using Medusa!

View Storefront

Visit localhost:8000 to view your Next.js storefront:

Build Project

Stop the Medusa project in your terminal CTRL + C. Open the Medusa backend directory:

cd my-medusa-store

Build your Medusa server and admin:

npm run build

Wait for the build to execute, after completion start your Medusa server and admin:

npm run start

Visit localhost:7001 once again in your browser to confirm if the build was successful.

Build Next.js Storefront

In a new terminal session, open the folder containing your storefront:

cd my-medusa-store-storefront

Build your storefront:

npm run build

Wait for the build to execute, after completion start your Medusa storefront:

npm run start

Visit localhost:8000 once again in your browser to confirm if build was successful.

Conclusion

In this guide, you've successfully set up a complete ecommerce solution using Medusa, Next.js, and Neon Postgres. You now have a powerful backend, an intuitive admin dashboard, and a sleek Next.js storefront - all powered by a serverless Postgres database. This setup provides a solid foundation for building and scaling your online store.

Next Steps

In an upcoming tutorial we will look at deploying the Medusa store.

Author

Mark Munyaka

GitHub: @Marktawa

Twitter: @McMunyaka

Hire Me

If you found this guide helpful and would like assistance in setting up your own Medusa-powered ecommerce store, I would be happy to help!
As an experienced Medusa and Next.js developer, I can provide the following services:

• Initial setup and configuration of your Medusa backend and Next.js storefront
• Deployment of your Medusa store on AWS, Railway, Digital Ocean and any other platform
• Integration with Neon Postgres, Stripe, Meilisearch, SendGrid, and other plugins
• Customization and branding of your store's design and functionality
• Ongoing maintenance, updates, and feature enhancements
• Performance optimization and scaling guidance

To discuss your project and get a quote, please feel free to contact me on markmunyakapro@gmail.com or connect with me on LinkedIn or Discord. I look forward to hearing from you!

Sponsor

Support my passion for sharing development knowledge by making a donation to my Buy Me a Coffee account. Your contribution helps me create valuable content and resources. Thank you for your support!

Buy Me A Coffee