How to Add a File Service Plugin to Your Medusa Store?
Tags: medusajs, opensource, ecommerce, plugin
Published: 2023-04-26 21:31:00

<!-- wp:paragraph -->
<p>Headless commerce has been out there for a long while with Medusa being one of the best alternatives to <a href="https://www.shopify.com" target="_blank" rel="noreferrer noopener">Shopify</a>. Medusa’s composable architecture allows you to build a store with any framework or language of your choice hence providing a full customization ability. Medusa equally allows you to build a unique ecommerce experience by providing a set of tools and essential building blocks developers can add up to create a powerful ecommerce website. It offers out-of-the-box features like customer, product, shipping, tax and region management, and RMA Flow. In today’s tutorial, you will learn how to add a file service plugin in order to be able to add products to your Medusa store via the <a href="https://docs.medusajs.com/admin/quickstart" target="_blank" rel="noreferrer noopener">admin dashboard</a></p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>What is Medusa</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Medusa is an <a href="https://www.learn-dev-tools.blog/what-does-open-source-software-mean-a-beginners-guide/">open-source</a> set of tools that allow you to build amazing and reliable ecommerce websites. With more than <a href="https://github.com/medusajs/medusa" target="_blank" rel="noreferrer noopener">17.8k stars and 1.3k forks on GitHub</a>, this headless commerce solution comes with a handful of commerce modules from basic to advanced and is freely available. Its <a href="https://docs.medusajs.com/" target="_blank" rel="noreferrer noopener">well-written documentation</a> also contributes to its success as there are step-by-step guidelines on how to add a module or plugins. Some popular plugins among others are payments, notifications, search and file service plugins.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>What is a File Service Plugin</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>A file service plugin allows you to host files like images used in Medusa. You may face issues if you don’t use or set up a file service for your Medusa store properly. Medusa offers three different ways to manage file storage; S3, <a href="https://docs.medusajs.com/plugins/file-service/minio" target="_blank" rel="noreferrer noopener">MinIo</a> and <a href="https://docs.medusajs.com/plugins/file-service/spaces" target="_blank" rel="noreferrer noopener">Spaces</a>. This tutorial solely focuses on S3 file storage to store images and files uploaded in Medusa.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>S3 or Simple Storage Service is an object storage used to store and retrieve any amount of data from anyway and at any time. We will use Amazon S3 for this demonstration. </p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>How to upload files into your Medusa store</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Amazon keeps data as objects within a bucket. An object consists of a file and optional data that describes it. To store a file, you need to upload it in a bucket(Buckets are the containers for objects), once uploaded, you can <a href="https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-policy.html" target="_blank" rel="noreferrer noopener">set permissions on the object</a>. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Now let’s get you to upload files in your Medusa projects quickly.</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>Prerequisites</h3>
<!-- /wp:heading -->

<!-- wp:list -->
<ul><!-- wp:list-item -->
<li><a href="https://www.learn-dev-tools.blog/how-to-build-a-medusa-webshop-with-one-command/">A Medusa store</a>. A Medusa project is basically divided into three components; a storefront, an admin dashboard and a <a href="https://docs.medusajs.com/development/backend/install" target="_blank" rel="noreferrer noopener">Medusa </a><a href="https://docs.medusajs.com/development/backend/install">Backend</a></li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li>An <a href="https://console.aws.amazon.com/console/home?nc2=h_ct&amp;src=header-signin" target="_blank" rel="noreferrer noopener">AWS account</a></li>
<!-- /wp:list-item --></ul>
<!-- /wp:list -->

<!-- wp:paragraph -->
<p>If you have everything set up then follow the steps below to add a File Service Plugin to Your Medusa Store.</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>Step 1: Create an S3 Bucket</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Login into your AWS account, search and<strong> select S3</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":467,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/select-s3.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-467"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the next page, Click on <strong>Create bucket</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":451,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/image-1-1024x138.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-451"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the window that opens, provide the information necessary to create your bucket.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>General Configuration</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Provide a name to your bucket and leave the default region or choose another one per your requirements.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":452,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/image-2.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-452"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p><strong>Object Ownership</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>For ownership, allow objects in the bucket to be owned by your account.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":482,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/object-owner.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-482"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the Block Public Access settings, uncheck <strong>Block</strong> all public Access. Doing this will show a warning message check the box in the message as in the image.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":480,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/allows.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-480"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>As for the Bucket versioning, tags, default encryption and advanced settings, leave the default settings or change them per your project requirements and click on <strong>Create bucket</strong>.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":481,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/other-settings.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-481"/></figure>
<!-- /wp:image -->

<!-- wp:heading {"level":3} -->
<h3>Step 2: Manage Policies</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>The next step consists of managing your created bucket policies.<strong> </strong>Head to the page of your bucket and open the <strong>permission tab. </strong>Then scroll down to the bucket policy section, click on edit, add the code below and<strong> Save.</strong></p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>{
 "Version": "2012-10-17",
 "Id": "Policy1397632521960",
 "Statement": &#91;
   {
     "Sid": "Stmt1397633323327",
     "Effect": "Allow",
     "Principal": {
       "AWS": "*"
     },
     "Action": "s3:GetObject",
     "Resource": "arn:aws:s3:::&lt;YOUR_BUCKET_NAME>/*"
   }
 ]
}</code></pre>
<!-- /wp:code -->

<!-- wp:image {"id":479,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/bucket-poly-1024x459.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-479"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Replace <code>&lt;YOUR_BUCKET_NAME></code> with the name of your bucket. Here it is <strong><code>medusastorebucket</code></strong></p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>Step 3: Attach a Policy</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>In your account navigate to <a href="https://us-east-1.console.aws.amazon.com/iamv2/home?region=us-east-1#/home" target="_blank" rel="noreferrer noopener">IAM</a><strong> and select Access Management->Policies in the left menu.</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":478,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/policies.png" alt="How to Add a File Service Plugin to Your Medusa Store" class="wp-image-478"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>If this is your first time choosing a policy, then you will see a Welcome to Manage Policies Page and select get started else choose<strong> Create policy. </strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":477,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/create-poly-1024x126.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-477"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Then select the JSON tab and add the following code:</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>{
  "Version": "2012-10-17",
  "Statement" : &#91;
    {
      "Effect" : "Allow",
      "Action" : &#91;
        "action-statement"
      ],
      "Resource" : &#91;
        "resource-statement"
      ]
    },
    {
      "Effect" : "Allow",
      "Action" : &#91;
        "action-statement"
      ],
      "Resource" : &#91;
        "resource-statement"
      ]
    }
  ]
}</code></pre>
<!-- /wp:code -->

<!-- wp:image {"id":476,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/jsontab-1024x477.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-476"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Substitute the <code>action-statement</code> and <code>resource-statement</code> per your requirement and click on <code>Next:tag</code></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Learn more about <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html" target="_blank" rel="noreferrer noopener">Policies and permissions</a></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Tags are optional so you can skip this step and click on the review button to review your policy.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":485,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/namepolicy-1024x511.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-485"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Next, provide a name and description for your policy then click on <strong>Create policy</strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Now that you have created your policy, you need to attach it to a user group, navigate to<strong> </strong><a href="https://console.aws.amazon.com/iam/" target="_blank" rel="noreferrer noopener"><strong>Amazon console</strong></a><strong> </strong>and choose<strong> User Groups</strong>. Select the name of the group then open the <strong>Permission tab</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":475,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/permission-1024x313.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-475"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Choose <strong>Add permission </strong>and then<strong> attach policies</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":474,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/attach.png" alt="How to Add a File Service Plugin to Your Medusa Store" class="wp-image-474"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the window that opens, select the policy you want to attach and click on add permission at the bottom of the page<strong>.</strong></p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Step 4: Get Your Access Key</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>You need to obtain your access key in order to integrate the S3 Plugin into your project. You will need two elements; <code>Access Key ID</code> and <code>Secret Access Key</code>.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>To get your AWS Access Key ID and Secret Access Key, head to your <a href="https://console.aws.amazon.com/iam/" target="_blank" rel="noreferrer noopener">Amazon console</a> on the left navigation, and choose <strong>Users. </strong></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Choose your<strong> IAM user name </strong>and open the<strong> Security credentials tab</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":472,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/secur-1024x184.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-472"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>Scroll down to Access Keys and click on <strong>Create Access Key</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image -->
<figure class="wp-block-image"><img src="blob:https://www.learn-dev-tools.blog/6003cf47-0cbc-4767-abed-beb4a0ece755" alt="How to Add a File Service Plugin to Your Medusa Store?"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the next window, you will be asked to choose where you want to use the access key. Check<strong> Local code </strong>if you are working in a local dev environment.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":470,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/local.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-470"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>By choosing local a warning message will appear asking you if you understand the recommendation. Check the box and click on the next button.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Finally, add a tag description if you like to add one and click on <strong>Create access key</strong></p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":469,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/createk.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-469"/></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>In the next window, you will see your Access and Secret Access key. Kindly copy and paste it somewhere on your PC since you will use it in the next step or download the CSV file. </p>
<!-- /wp:paragraph -->

<!-- wp:image {"id":468,"sizeSlug":"full","linkDestination":"none"} -->
<figure class="wp-block-image size-full"><img src="https://www.learn-dev-tools.blog/wp-content/uploads/2023/04/keys.png" alt="How to Add a File Service Plugin to Your Medusa Store?" class="wp-image-468"/></figure>
<!-- /wp:image -->

<!-- wp:heading {"level":3} -->
<h3>Step 5: Install the S3 Plugin</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Now that you have set up your bucket and created your access keys, it’s time to install the S3 plugin. To do so head to your Medusa backend folder and install it with the following command:</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>yarn add medusa-file-s3</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>Or</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>npm install medusa-file-s3</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>Then open your <code>.env</code> file and add the following</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>S3_URL=&lt;YOUR_BUCKET_URL>
S3_BUCKET=&lt;YOUR_BUCKET_NAME>
S3_REGION=&lt;YOUR_BUCKET_REGION>
S3_ACCESS_KEY_ID=&lt;YOUR_ACCESS_KEY_ID>
S3_SECRET_ACCESS_KEY=&lt;YOUR_SECRET_ACCESS_KEY></code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>Where</p>
<!-- /wp:paragraph -->

<!-- wp:list -->
<ul><!-- wp:list-item -->
<li><code>&lt;YOUR_BUCKET_URL></code> is the URL of your bucket. It is in the form <code>https://&lt;BUCKET_NAME>.s3.&lt;REGION>.amazonaws.com</code>. Where <code>&lt;BUCKET_NAME></code> is the name of your bucket, <code>&lt;REGION></code> the region.</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><code>&lt;YOUR_BUCKET_NAME></code> is the name of the bucket created</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><code>&lt;YOUR_BUCKET_REGION></code> the region of your bucket</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li>&lt;YOUR_ACCESS_KEY_ID> is your Access Key</li>
<!-- /wp:list-item -->

<!-- wp:list-item -->
<li><code>&lt;YOUR_SECRET_ACCESS_KEY></code> is your Secret Key</li>
<!-- /wp:list-item --></ul>
<!-- /wp:list -->

<!-- wp:paragraph -->
<p>Finally in your <code>medusa-config.js</code> add the following code:</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>const plugins = &#91;
  // ...
  {
    resolve: `medusa-file-s3`,
    options: {
        s3_url: process.env.S3_URL,
        bucket: process.env.S3_BUCKET,
        region: process.env.S3_REGION,
        access_key_id: process.env.S3_ACCESS_KEY_ID,
        secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
    },
  },
]</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>Note that if you have many storage plugins configured, then the last plugin declared will be used. So if you want S3 to be used make sure it's the last storage plugin added.</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>Step 6: Testing the Plugin</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Now that you have successfully added your plugin. It's time to test to make sure that everything is in the right place. You can use <a href="https://docs.medusajs.com/api/store" target="_blank" rel="noreferrer noopener">REST APIs</a> or the Medusa Admin to test.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Navigate to your admin and backend folders respectively and run the following command:</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>// admin 
yarn run start

// backend
yarn run start</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>The default admin email and password are <code>admin@medusa-test.com</code> and <code>supersecret</code> respectively. Open your admin panel with <code>http://localhost:7000/</code></p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>In the menu click on <strong>Products</strong> then <strong>Add Product</strong>. Provide details for your product and publish it.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Lastly, you need to add a configuration in your storefront that adds the S3 bucket domain name into the configured images’ domain names if you are using <a href="https://docs.medusajs.com/starters/nextjs-medusa-starter" target="_blank" rel="noreferrer noopener">NextJS storefront</a>. If you don't do it you will receive the following error <a href="https://nextjs.org/docs/messages/next-image-unconfigured-host" target="_blank" rel="noreferrer noopener">next/image Un-configured Host</a>. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>So in your <code>next.config.js</code> add the following:</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>const { withStoreConfig } = require("./store-config")

// ...

module.exports = withStoreConfig({
  // ...
  images: {
    domains: &#91;
      // ...
      "&lt;BUCKET_NAME>.s3.amazonaws.com",
    ],
  },
})</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p><code>&lt;BUCKET_NAME></code> represents the name of your bucket. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Run your storefront with <code>yarn run dev</code> to check if the new products you added are there and proceed to the next phase of your project.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p> </p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Conclusion</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>This marks the end of this tutorial, hopefully, you were able to add a file service plugin to your Medusa store. To get the best of Medusa, consider adding payment services, search and notifications services.</p>
<!-- /wp:paragraph -->