From 81fea66ef3b2da54784a17943fba77a1f08d6885 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 30 May 2023 20:31:57 +0300 Subject: [PATCH] docs: added documentation for local file service (#4162) * docs: added documentation for local file service * fixed eslint errors * change local file service package name --- docs/content/development/backend/install.mdx | 45 ++++---- docs/content/plugins/file-service/local.md | 105 +++++++++++++++++++ docs/content/plugins/file-service/minio.md | 2 +- docs/content/plugins/file-service/s3.md | 2 +- docs/content/plugins/overview.mdx | 12 +-- packages/medusa-file-local/README.md | 8 +- www/docs/sidebars.js | 10 ++ 7 files changed, 152 insertions(+), 32 deletions(-) create mode 100644 docs/content/plugins/file-service/local.md diff --git a/docs/content/development/backend/install.mdx b/docs/content/development/backend/install.mdx index 112203c3f7..6ef3298b16 100644 --- a/docs/content/development/backend/install.mdx +++ b/docs/content/development/backend/install.mdx @@ -4,6 +4,8 @@ addHowToData: true --- import Feedback from '@site/src/components/Feedback'; +import DocCardList from '@theme/DocCardList'; +import Icons from '@theme/Icon'; # Install Medusa Backend @@ -83,26 +85,23 @@ You can access `/health` to get health status of your backend. ## Next Steps -### Learn about the Architecture - -Medusa backend is made up of different resources that make it a powerful server. Get an overview of them in the [Medusa Architecture Overview](../fundamentals/architecture-overview.md) documentation. - -### Set Up Development Environment - -For an optimal experience developing with Medusa and to make sure you can use its advanced functionalities, you'll need to install more tools such as PostgreSQL. - -Follow [this documentation to learn how to set up your development environment](../../development/backend/prepare-environment.mdx). - -### Backend Configurations - -It's important to configure your Medusa backend properly and learn how environment variables are loaded. - -You can learn more about configuring your backend and loading environment variables in the [Configure your Backend documentation](../../development/backend/configurations.md). - -### File Service Plugin - -To upload product images to your Medusa backend, you must install and configure one of the following file service plugins: - -- [MinIO](../../plugins/file-service/minio.md) (Recommended for local development) -- [S3](../../plugins/file-service/s3.md) -- [DigitalOcean Spaces](../../plugins/file-service/spaces.md) + diff --git a/docs/content/plugins/file-service/local.md b/docs/content/plugins/file-service/local.md new file mode 100644 index 0000000000..6415aafbdc --- /dev/null +++ b/docs/content/plugins/file-service/local.md @@ -0,0 +1,105 @@ +--- +description: 'Learn how to install the local file service to upload images and assets locally on your Medusa backend.' +addHowToData: true +--- + +# Local File Storage + +This document will guide you through installing the local file storage plugin on your Medusa backend. + +## Overview + +To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products. + +Medusa provides three different options to handle your file storage. The local file storage plugin makes it easy to upload file assets locally during development. + +:::note + +For production, it's recommended to use a file service plugin that hosts your images on a third-party service. This file service doesn't handle advanced features such as private uploads, which means you can't use it for functionalities like import or export products. Check [the file service plugins](./index.mdx) for available other options to use. + +::: + +--- + +## Prerequisites + +A Medusa backend is required to be set up before following along with this document. You can follow the [quickstart guide](../../development/backend/install.mdx) to get started in minutes. + +--- + +## Plugin Installation + +In the directory of your Medusa backend, run the following command to install the local file service plugin: + +```bash npm2yarn +npm install @medusajs/file-local +``` + +Then, configure your `medusa-config.js` to include the plugin with the required options: + +```js title=medusa-config.js +const plugins = [ + // ... + { + resolve: `@medusajs/file-local`, + options: { + // optional + }, + }, +] +``` + +:::caution + +If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used. + +::: + +### Options + +You can pass the plugin the following options: + +- `upload_dir`: a string indicating the relative path to upload the files to. By default, it's `uploads/images`. +- `backend_url`: a string indicating the URL of your backend. This is helpful if you deploy your backend or change the port used. By default, it's `http://localhost:9000`. + +--- + +## Test it Out + +Run your Medusa backend alongside the [Medusa Admin](../../admin/quickstart.mdx) to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored locally in your backend. + +The files will be stored under the `upload_dir` specified in the plugin options (if no option is specified, they'll be stored in the `uploads/images` directory by default.) + +--- + +## Next.js Storefront Configuration + +If you’re using a [Next.js](../../starters/nextjs-medusa-starter.mdx) storefront, you need to add an additional configuration that adds the backend's domain name into the configured images domain names. This is because all URLs of product images will be from the Medusa backend. + +If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host). + +In `next.config.js` add the following option in the exported object: + +```jsx title=next.config.js +const { withStoreConfig } = require("./store-config") + +// ... + +module.exports = withStoreConfig({ + // ... + images: { + domains: [ + // ... + "", + ], + }, +}) +``` + +Where `` is the URL of your backend. If you're running the backend locally, the value would be `localhost`. + +--- + +## See Also + +- Check out [more plugins](../overview.mdx) you can add to your store. diff --git a/docs/content/plugins/file-service/minio.md b/docs/content/plugins/file-service/minio.md index ecbcc28cc8..1b3e604b8f 100644 --- a/docs/content/plugins/file-service/minio.md +++ b/docs/content/plugins/file-service/minio.md @@ -9,7 +9,7 @@ This document will guide you through installing the MinIO file service plugin on ## Overview -To manage images in Medusa, you need a file service plugin responsible for hosting. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products. +To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products. Medusa provides three different options to handle your file storage. This document will focus on setting up [MinIO](https://min.io) on your local machine and connecting Medusa to it. diff --git a/docs/content/plugins/file-service/s3.md b/docs/content/plugins/file-service/s3.md index 7664e7a007..7108e5bbfb 100644 --- a/docs/content/plugins/file-service/s3.md +++ b/docs/content/plugins/file-service/s3.md @@ -9,7 +9,7 @@ In this document, you’ll learn how to install the [S3 plugin](https://github.c ## Overview -To manage images in Medusa, you need a file service plugin responsible for hosting the images. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products. +To upload and manage file assets in Medusa, you need a file service plugin responsible for hosting the files. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products. Medusa provides three different options to handle your file storage. This document focuses on using [S3](https://aws.amazon.com/s3/) to store images and files uploaded to the Medusa backend. diff --git a/docs/content/plugins/overview.mdx b/docs/content/plugins/overview.mdx index 921156c5d3..5e3cf9f454 100644 --- a/docs/content/plugins/overview.mdx +++ b/docs/content/plugins/overview.mdx @@ -26,7 +26,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'Analytics', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official Analytics plugins.' + description: 'Check out official Analytics plugins.' } }, { @@ -35,7 +35,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'CMS', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official CMS plugins.' + description: 'Check out official CMS plugins.' } }, { @@ -44,7 +44,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'Notifications', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official Notifications plugins.' + description: 'Check out official Notifications plugins.' } }, { @@ -53,7 +53,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'Payment', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official Payment plugins.' + description: 'Check out official Payment plugins.' } }, { @@ -62,7 +62,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'Search', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official Search plugins.' + description: 'Check out official Search plugins.' } }, { @@ -71,7 +71,7 @@ Interested in creating a plugin? Learn more in the [Create Plugin documentation] label: 'File Service', customProps: { icon: Icons['squares-plus-solid'], - description: 'Check out available official File Service plugins.' + description: 'Check out official File Service plugins.' } }, ]} /> diff --git a/packages/medusa-file-local/README.md b/packages/medusa-file-local/README.md index b791f51091..6848b0d300 100644 --- a/packages/medusa-file-local/README.md +++ b/packages/medusa-file-local/README.md @@ -31,7 +31,13 @@ npm install @medusajs/file-local ```js const plugins = [ // ... - `@medusajs/file-local` + { + resolve: `@medusajs/file-local`, + options: { + upload_dir: 'uploads/images', // optional + backend_url: 'http://localhost:9000' // optional + } + }, ] ``` diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 463dd31f57..4291fd161c 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -2150,6 +2150,16 @@ module.exports = { "Learn how to integrate Spaces with the Medusa backend.", }, }, + { + type: "doc", + id: "plugins/file-service/local", + label: "Local File Storage", + customProps: { + iconName: "bolt-solid", + description: + "Learn how to use local file storage in your Medusa backend", + }, + }, ], }, ],