asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: editing and general fixes of medusa's learning resources (#7261)

Browse Source 
* docs: editing and general fixes of medusa's learning resources

* fix build script

* update ui dependency

* fix build

* adjust next.js steps
This commit is contained in:
Shahed Nasser
2024-05-13 18:55:11 +03:00
committed by GitHub
parent 803e4aad02
commit 7cb90f8e82
79 changed files with 488 additions and 1707 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/_plugins/storage/local/page.mdx
+127
View File
@@ -0,0 +1,127 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Local File Storage Plugin`,
}
# {metadata.title}
## Features
The Local File Storage plugin allows you to upload media assets, such as product images, to a local directory. This is useful during development.
<Note title="Tip">
For production, it's recommended to use a storage plugin that hosts your images on a third-party service. This storage plugin doesn't handle advanced features such as presigned URLs.
</Note>
---
## Install the Local File Storage Plugin
To install the Local File Storage plugin, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install @medusajs/file-local
```
Next, add the plugin into the `plugins` array in `medusa-config.js`:
```js title="medusa-config.js"
const plugins = [
// ...
{
resolve: `@medusajs/file-local`,
options: {
// optional
},
},
]
```
### Local File Storage Plugin Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`upload_dir`
</Table.Cell>
<Table.Cell>
A string indicating the relative path to upload the files to.
</Table.Cell>
<Table.Cell>
`uploads/images`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`backend_url`
</Table.Cell>
<Table.Cell>
A string indicating the URL of your Medusa application. This is helpful if you deploy your application or change the port used.
</Table.Cell>
<Table.Cell>
`http://localhost:9000`
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Test the Plugin
To test the plugin, start the Medusa application:
```bash npm2yarn
npm run dev
```
Then, upload a product image either using the [Medusa Admin](!user-guide!/products/manage#manage-product-media) or the [Admin API routes](https://docs.medusajs.com/api/admin#uploads_postuploads).
---
## Next.js Starter Configuration
If you’re using the [Next.js Starter storefront](../../../nextjs-starter/page.mdx), add the following option to the exported object in `next.config.js`:
```js title="next.config.js"
const { withStoreConfig } = require("./store-config")
// ...
module.exports = withStoreConfig({
// ...
images: {
domains: [
// ...
"{medusa_domain}",
],
},
})
```
This adds the Medusa application's domain name into the configured images domain names. If you don't add the configuration, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
Make sure to replace `{medusa_domain}` with the domain of your Medusa application. For example, `localhost`.
www/apps/resources/app/_plugins/storage/minio/page.mdx
+296
View File
@@ -0,0 +1,296 @@
import { Table } from "docs-ui"
export const metadata = {
title: `MinIO Plugin`,
}
# {metadata.title}
## Features
[MinIO](https://min.io/) is an open-source object storage server compatible with the Amazon S3 API. It allows users to store photos, videos, backups, and more.
With the MinIO plugin, you'll benefit from basic and advanced storage functionalities, including public and private uploads, and presigned URLs.
---
## Install the MinIO Plugin
<Note type="check">
- [Install MinIO](https://min.io/docs/minio/linux/index.html).
- Change port to `9001` using the [console address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-console-address) and [address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-address) CLI options.
- [MinIO bucket with public access policy](https://min.io/docs/minio/linux/administration/console/managing-objects.html#creating-buckets).
- [MinIO access and secret access key](https://min.io/docs/minio/linux/administration/console/security-and-access.html#id1)
</Note>
To install the MinIO plugin, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install medusa-file-minio
```
Next, add the plugin into the `plugins` array in `medusa-config.js`:
export const highlights = [
["6", "bucket", "The bucket to upload files to."],
["7", "access_key_id", "The MinIO access key."],
["8", "secret_access_key", "The MinIO secret access key."],
["9", "endpoint", "The URL of your MinIO server."],
]
```js title="medusa-config.js" highlights={highlights}
const plugins = [
// ...
{
resolve: `medusa-file-minio`,
options: {
bucket: process.env.MINIO_BUCKET,
access_key_id: process.env.MINIO_ACCESS_KEY,
secret_access_key: process.env.MINIO_SECRET_KEY,
endpoint: process.env.MINIO_ENDPOINT,
},
},
]
```
### MinIO Plugin Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`bucket`
</Table.Cell>
<Table.Cell>
A string indicating the bucket to upload files to.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`access_key_id`
</Table.Cell>
<Table.Cell>
A string indicating the [MinIO access key](https://min.io/docs/minio/linux/administration/console/security-and-access.html#id1).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`secret_access_key`
</Table.Cell>
<Table.Cell>
A string indicating the [MinIO secret access key](https://min.io/docs/minio/linux/administration/console/security-and-access.html#id1).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`endpoint`
</Table.Cell>
<Table.Cell>
A string indicating the URL of your MinIO server.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`private_bucket`
</Table.Cell>
<Table.Cell>
A string indicating the bucket to use for private media, such as the CSV file of exported products.
</Table.Cell>
<Table.Cell>
Required if you're using import/export features that require a private bucket.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`private_access_key_id`
</Table.Cell>
<Table.Cell>
A string indicating the MinIO access key to use for private uploads.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
The value of `access_key_id`.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`private_secret_access_key`
</Table.Cell>
<Table.Cell>
A string indicating the MinIO secret access key to use for private uploads.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
The value of `secret_access_key`.
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`download_url_duration`
</Table.Cell>
<Table.Cell>
A number indicating the expiry time of presigned URLs in seconds.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`60`
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
MINIO_BUCKET=<BUCKET>
MINIO_ACCESS_KEY=<ACCESS_KEY>
MINIO_SECRET_KEY=<SECRET_KEY>
MINIO_ENDPOINT=<ENDPOINT>
```
---
## Test the Plugin
To test the plugin, start the Medusa application:
```bash npm2yarn
npm run dev
```
Then, upload a product image either using the [Medusa Admin](!user-guide!/products/manage#manage-product-media) or the [Admin API routes](https://docs.medusajs.com/api/admin#uploads_postuploads).
---
## Next.js Starter Template Configuration
If you’re using the [Next.js Starter storefront](../../../nextjs-starter/page.mdx), add the following option to the exported object in `next.config.js`:
```jsx title="next.config.js"
const { withStoreConfig } = require("./store-config")
// ...
module.exports = withStoreConfig({
// ...
images: {
domains: [
// ...
"{minio_domain}",
],
},
})
```
This adds the MinIO domain into the configured images domain names. If you don't add the configuration, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
Make sure to replace `{minio_domain}` with the MinIO domain. For example, `127.0.0.1`.
www/apps/resources/app/_plugins/storage/s3/page.mdx
+363
View File
@@ -0,0 +1,363 @@
import { Table, DetailsList } from "docs-ui"
import AclErrorSection from "../../../troubleshooting/_sections/other/s3-acl.mdx"
export const metadata = {
title: `S3 Plugin`,
}
# {metadata.title}
## Features
[Amazon S3](https://aws.amazon.com/s3/) is a cloud storage service that offers scalable object storage. It allows users to store and retrieve images, videos, and other media types.
With the S3 plugin, you'll benefit from basic and advanced storage functionalities, including public and private uploads, and presigned URLs.
---
## Preparations
<Note type="check">
- [AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin).
- [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) with the "Public Access setting" enabled.
- [AWS user with AmazonS3FullAccess permissions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html).
- [AWS user access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey)
</Note>
### Bucket Policies
Change your [bucket's policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html) to the following:
```json
{
"Version": "2012-10-17",
"Id": "Policy1397632521960",
"Statement": [
{
"Sid": "Stmt1397633323327",
"Effect": "Allow",
"Principal": {
"AWS": "*"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::{bucket_name}/*"
}
]
}
```
Make sure to replace `{bucket_name}` with the name of the bucket you created.
---
## Install the S3 Plugin
To install the MinIO plugin, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install medusa-file-s3
```
Next, add the plugin into the `plugins` array in `medusa-config.js`:
export const highlights = [
["6", "bucket", "The bucket to upload files to."],
["7", "s3_url", "The URL to the bucket."],
["8", "access_key_id", "The AWS user's access key ID."],
["9", "secret_access_key", "The AWS user's secret access key."],
["10", "region", "The bucket's region code."],
]
```js title="medusa-config.js" highlights={highlights}
const plugins = [
// ...
{
resolve: `medusa-file-s3`,
options: {
bucket: process.env.S3_BUCKET,
s3_url: process.env.S3_URL,
access_key_id: process.env.S3_ACCESS_KEY_ID,
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
region: process.env.S3_REGION,
},
},
]
```
### S3 Plugin Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`bucket`
</Table.Cell>
<Table.Cell>
A string indicating the bucket to upload files to.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`s3_url`
</Table.Cell>
<Table.Cell>
A string indicating the URL to your bucket. It’s in the form `https://<BUCKET_NAME>.s3.<REGION>.amazonaws.com`, where `<BUCKET_NAME>` is the name of the bucket and the `<REGION>` is the region the bucket is created in.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`access_key_id`
</Table.Cell>
<Table.Cell>
A string indicating the AWS user's access key ID.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`secret_access_key`
</Table.Cell>
<Table.Cell>
A string indicating the AWS user's secret access key.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`region`
</Table.Cell>
<Table.Cell>
A string indicating the region code of your bucket. For example, `us-east-1`.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`prefix`
</Table.Cell>
<Table.Cell>
A string indicating a prefix to apply on stored file names. If supplied, a `/` is added at the end of the prefix.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`download_file_duration`
</Table.Cell>
<Table.Cell>
A number indicating the expiry time of presigned URLs in seconds.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
[S3's default expiration time](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html#PresignedUrl-Expiration)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`cache_control`
</Table.Cell>
<Table.Cell>
A string indicating [how long objects remain in the CloudFront's cache](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html).
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`max-age=31536000` (a year)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`aws_config_object`
</Table.Cell>
<Table.Cell>
An object of [AWS Configurations](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) passed to all requests.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
S3_BUCKET=<YOUR_BUCKET_NAME>
S3_URL=<YOUR_BUCKET_URL>
S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
S3_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
S3_REGION=<YOUR_BUCKET_REGION>
```
---
## Test the S3 Plugin
To test the plugin, start the Medusa application:
```bash npm2yarn
npm run dev
```
Then, upload a product image either using the [Medusa Admin](!user-guide!/products/manage#manage-product-media) or the [Admin API routes](https://docs.medusajs.com/api/admin#uploads_postuploads).
---
## Next.js Starter Template Configuration
If you’re using the [Next.js Starter storefront](../../../nextjs-starter/page.mdx), add the following option to the exported object in `next.config.js`:
```jsx title="next.config.js"
const { withStoreConfig } = require("./store-config")
// ...
module.exports = withStoreConfig({
// ...
images: {
domains: [
// ...
"{s3_domain}",
],
},
})
```
This adds the S3's domain into the configured images domain names. If you don't add the configuration, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
Make sure to replace `{s3_domain}` with the S3 domain which is of the format `<BUCKET_NAME>.s3.<REGION>.amazonaws.com`.
---
## Troubleshooting
<DetailsList
sections={[
{
title: 'Error: AccessControlListNotSupported: The bucket does not allow ACLs',
content: <AclErrorSection />
}
]}
/>
www/apps/resources/app/_plugins/storage/spaces/page.mdx
+282
View File
@@ -0,0 +1,282 @@
import { Table, DetailsList } from "docs-ui"
import AclErrorSection from "../../../troubleshooting/_sections/other/s3-acl.mdx"
export const metadata = {
title: `Spaces Plugin`,
}
# {metadata.title}
## Features
[DigitalOcean Spaces](https://www.digitalocean.com/products/spaces) is an object storage service provided by DigitalOcean. Spaces is designed to make it easy and cost-effective to store medias such as images, videos, and more.
With the DigitalOcean plugin, you'll benefit from basic and advanced storage functionalities, including public and private uploads, and presigned URLs.
---
## Install the Spaces Plugin
<Note type="check">
- [DigitalOcean account](https://cloud.digitalocean.com/registrations/new)
- [DigitalOcean Spaces bucket](https://docs.digitalocean.com/products/spaces/how-to/create/)
- [DigitalOcean Spaces access and secret access keys](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys)
</Note>
To install the Spaces plugin, run the following command in the directory of your Medusa application:
```bash npm2yarn
npm install medusa-file-spaces
```
Next, add the plugin into the `plugins` array in `medusa-config.js`:
export const highlights = [
["6", "bucket", "The bucket to upload files to."],
["7", "spaces_url", "Either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket."],
["8", "access_key_id", "The Spaces access key."],
["9", "secret_access_key", "The Spaces secret access key."],
["10", "region", "The region your Spaces Object Storage bucket is in."],
["11", "endpoint", "The Spaces Origin Endpoint."],
]
Then, add the following environment variables:
```js title="medusa-config.js" highlights={highlights}
const plugins = [
// ...
{
resolve: `medusa-file-spaces`,
options: {
bucket: process.env.SPACE_BUCKET,
spaces_url: process.env.SPACE_URL,
access_key_id: process.env.SPACE_ACCESS_KEY_ID,
secret_access_key: process.env.SPACE_SECRET_ACCESS_KEY,
region: process.env.SPACE_REGION,
endpoint: process.env.SPACE_ENDPOINT,
},
},
]
```
### Spaces Plugin Options
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Option</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Required</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>
`bucket`
</Table.Cell>
<Table.Cell>
A string indicating the bucket to upload files to.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`spaces_url`
</Table.Cell>
<Table.Cell>
A string indicating either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`access_key_id`
</Table.Cell>
<Table.Cell>
A string indicating the [Spaces access key](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`secret_access_key`
</Table.Cell>
<Table.Cell>
A string indicating the [Spaces secret access key](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys).
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`region`
</Table.Cell>
<Table.Cell>
A string indicating the region your Spaces Object Storage bucket is in. If you're unsure, you can find it in the Origin Endpoint whose format is `https://<bucket-name>.<region>.digitaloceanspaces.com`. For example, `nyc3`.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`endpoint`
</Table.Cell>
<Table.Cell>
A string indicating the Spaces Origin Endpoint.
</Table.Cell>
<Table.Cell>
Yes
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`download_url_duration`
</Table.Cell>
<Table.Cell>
A number indicating the expiry time of presigned URLs in seconds.
</Table.Cell>
<Table.Cell>
No
</Table.Cell>
<Table.Cell>
`60`
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
### Environment Variables
Make sure to add the necessary environment variables for the above options in `.env`:
```bash
SPACE_URL=<YOUR_SPACE_URL>
SPACE_BUCKET=<YOUR_SPACE_NAME>
SPACE_REGION=<YOUR_SPACE_REGION>
SPACE_ENDPOINT=<YOUR_SPACE_ENDPOINT>
SPACE_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
SPACE_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
```
---
## Test the Plugin
To test the plugin, start the Medusa application:
```bash npm2yarn
npm run dev
```
Then, upload a product image either using the [Medusa Admin](!user-guide!/products/manage#manage-product-media) or the [Admin API routes](https://docs.medusajs.com/api/admin#uploads_postuploads).
---
## Next.js Starter Template Configuration
If you’re using the [Next.js Starter storefront](../../../nextjs-starter/page.mdx), add the following option to the exported object in `next.config.js`:
```jsx title="next.config.js"
const { withStoreConfig } = require("./store-config")
// ...
module.exports = withStoreConfig({
// ...
images: {
domains: [
// ...
"{spaces_domain}",
],
},
})
```
This adds the Spaces domain into the configured images domain names. If you don't add the configuration, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
Make sure to replace `{spaces_domain}` with the Spaces domain. It's of the format `<bucket-name>.<region>.digitaloceanspaces.com` or `<bucket-name>.<region>.cdn.digitaloceanspaces.com`