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

docs: rename Architectural Modules to Infrastructure Modules (#12212)

Browse Source 
* docs: rename Architectural Modules to Infrastructure Modules

* generate again
This commit is contained in:
Shahed Nasser
2025-04-17 13:20:43 +03:00
committed by GitHub
parent 8618e6ee38
commit eb73bdb478
149 changed files with 12165 additions and 12145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/resources/app/infrastructure-modules/file/local/page.mdx
+107
View File
@@ -0,0 +1,107 @@
import { Table } from "docs-ui"
export const metadata = {
title: `Local File Module Provider`,
}
# {metadata.title}
The Local File Module Provider stores files uploaded to your Medusa application in the `/uploads` directory.
<Note type="warning">
The Local File Module Provider is only for development purposes. Use the [S3 File Module Provider](../s3/page.mdx) in production instead.
</Note>
---
## Register the Local File Module
<Note>
The Local File Module Provider is registered by default in your application.
</Note>
Add the module into the `providers` array of the File Module:
<Note>
The File Module accepts one provider only.
</Note>
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
// ...
module.exports = {
// ...
modules: [
{
resolve: "@medusajs/medusa/file",
options: {
providers: [
{
resolve: "@medusajs/medusa/file-local",
id: "local",
options: {
// provider options...
},
},
],
},
},
],
}
```
### Local File Module 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>
The directory to upload files to. Medusa exposes the content of the `static` directory publically. If you change the directory, it must be served and publically accessible.
</Table.Cell>
<Table.Cell>
`static`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`backend_url`
</Table.Cell>
<Table.Cell>
The URL that serves the files.
</Table.Cell>
<Table.Cell>
`http://localhost:9000/static`
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
www/apps/resources/app/infrastructure-modules/file/page.mdx
+96
View File
@@ -0,0 +1,96 @@
import { CardList } from "docs-ui"
export const metadata = {
title: `File Module`,
}
# {metadata.title}
In this document, you'll learn about the File Module and its providers.
## What is the File Module?
The File Module exposes the functionalities to upload assets, such as product images, to the Medusa application. Medusa uses the File Module in its core commerce features for all file operations, and you can use it in your custom features as well.
---
## How to Use the File Module?
You can use the File Module as part of the [workflows](!docs!/learn/fundamentals/workflows) you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.
In a step of your workflow, you can resolve the File Module's service and use its methods to upload files, retrieve files, or delete files.
For example:
```ts
import { Modules } from "@medusajs/framework/utils"
import {
createStep,
createWorkflow,
StepResponse,
WorkflowResponse,
} from "@medusajs/framework/workflows-sdk"
const step1 = createStep(
"step-1",
async ({}, { container }) => {
const fileModuleService = container.resolve(
Modules.FILE
)
const { url } = await fileModuleService.retrieveFile("image.png")
return new StepResponse(url)
}
)
export const workflow = createWorkflow(
"workflow-1",
() => {
const url = step1()
return new WorkflowResponse(url)
}
)
```
In the example above, you create a workflow that has a step. In the step, you resolve the service of the File Module from the [Medusa container](!docs!/learn/fundamentals/medusa-container).
Then, you use the `retrieveFile` method of the File Module to retrieve the URL of the file with the name `"image.png"`. The URL is then returned as a response from the step and the workflow.
---
### What is a File Module Provider?
A File Module Provider implements the underlying logic of handling uploads and downloads of assets, such as integrating third-party services. The File Module then uses the registered File Module Provider to handle file operations.
<Note>
Only one File Module Provider can be registered at a time. If you register multiple providers, the File Module will throw an error.
</Note>
By default, Medusa uses the [Local File Module](./local/page.mdx). This module uploads files to the `uploads` directory of your Medusa application.
This is useful for development. However, for production, it’s highly recommended to use other File Module Providers, such as the S3 File Module Provider. You can also [Create a File Provider](/references/file-provider-module).
<CardList
items={[
{
title: "Local",
href: "/infrastructure-modules/file/local",
badge: {
variant: "neutral",
children: "For Development"
}
},
{
title: "AWS S3 (and Compatible APIs)",
href: "/infrastructure-modules/file/s3",
badge: {
variant: "green",
children: "For Production"
}
}
]}
/>
www/apps/resources/app/infrastructure-modules/file/s3/page.mdx
+427
View File
@@ -0,0 +1,427 @@
import S3BucketAcl from "../../../troubleshooting/_sections/s3/aws-bucket-acl.mdx"
import CloudflareChecksum from "../../../troubleshooting/_sections/s3/cloudflare-checksum.mdx"
import { Table, Tabs, TabsList, TabsContent, TabsContentWrapper, TabsTrigger, DetailsList } from "docs-ui"
export const metadata = {
title: `S3 File Module Provider`,
}
# {metadata.title}
The S3 File Module Provider integrates Amazon S3 and services following a compatible API (such as MinIO or DigitalOcean Spaces) to store files uploaded to your Medusa application.
---
## Prerequisites
<Tabs defaultValue="aws">
<TabsList>
<TabsTrigger value="aws">AWS S3</TabsTrigger>
<TabsTrigger value="minio">MinIO</TabsTrigger>
<TabsTrigger value="spaces">DigitalOcean Spaces</TabsTrigger>
<TabsTrigger value="supabase">Supabase S3 Storage</TabsTrigger>
<TabsTrigger value="cloudflare">Cloudflare R2</TabsTrigger>
</TabsList>
<TabsContentWrapper>
<TabsContent value="aws">
- [AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin).
- Create [AWS user with AmazonS3FullAccess permissions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html).
- Create [AWS user access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey).
- Create [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) with the "Public Access setting" enabled:
1. On your bucket's dashboard, click on the Permissions tab.
2. Click on the Edit button of the Block public access (bucket settings) section.
3. In the form that opens, don't toggle any checkboxes and click the "Save changes" button.
4. Confirm saving the changes by entering `confirm` in the pop-up that shows.
5. Back on the Permissions page, scroll to the Object Ownership section and click the Edit button.
6. In the form that opens:
- Choose the "ACLs enabled" card.
- Click on the "Save changes" button.
7. Back on the Permissions page, scroll to the "Access Control List (ACL)" section and click on the Edit button.
8. In the form that opens, enable the Read permission for "Everyone (public access)".
9. Check the "I understand the effects of these changes on my objects and buckets." checkbox.
10. Click on the "Save changes" button.
</TabsContent>
<TabsContent value="minio">
- [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.
- Create MinIO access and secret access key:
- Go to User -> Access Keys
- Click on the Create Access Keys button.
- Click on the Create button.
- Copy the keys of the pop-up. Make sure to copy the secret key as it won't be shown again.
- Create a [MinIO bucket](https://min.io/docs/minio/linux/administration/console/managing-objects.html#creating-buckets) with public access policy. To add the policy:
- Go to the bucket's dashboard from Administrator -> Buckets.
- Under the Summary section, click on the pencil icon next to Access Policy.
- In the pop-up, choose Custom from the dropdown.
- In the editor, enter the following:
```json highlights={[["15", "{bucketname}", "Replace with the bucket's name."]]}
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"s3:GetObject"
],
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Resource": [
"arn:aws:s3:::{bucketname}/*"
]
}
]
}
```
Make sure to replace `{bucket_name}` with the name of the bucket you created. You can edit the access policy under the Summary section of your bucket's dashboard.
</TabsContent>
<TabsContent value="spaces">
- Create [DigitalOcean account](https://cloud.digitalocean.com/registrations/new).
- Create [DigitalOcean Spaces bucket](https://docs.digitalocean.com/products/spaces/how-to/create/).
- Create [DigitalOcean Spaces access and secret access keys](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys).
</TabsContent>
<TabsContent value="supabase">
- [Supabase account](https://supabase.com/dashboard/sign-in) with a project.
- Create [New Public S3 bucket](https://supabase.com/docs/guides/storage/buckets/creating-buckets?queryGroups=language&language=dashboard).
- Create [New S3 Access Keys](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys).
- Create [Storage Policy](https://supabase.com/docs/guides/storage/security/access-control).
1. On your bucket's dashboard, click on Policies under the Configuration sidebar.
2. Click on New Policy under "Other policies under storage.objects".
3. Click get started quickly, choose "insert access for authenticated users only", and click the "Use this template" button.
4. Click ALL for "Allowed Operations", click the "Review" button, then the "Save policy" button.
</TabsContent>
<TabsContent value="cloudflare">
1. Create a [Cloudflare account](https://dash.cloudflare.com/sign-up).
2. Set up your R2 bucket:
- Navigate to R2 Object Storage in your dashboard. You may need to provide your credit-card information.
- Click "Create bucket"
- Enter a unique bucket name
- Select "Automatic" for location
- Choose "Standard" for storage class
- Confirm by clicking "Create bucket"
3. Configure public access:
- On your bucket's dashboard, click on the Settings tab.
- Scroll down to the Public Access section, and click on "Allow Access" in the "R2.dev subdomain" card.
- Type 'allow' to confirm
- Copy the Public R2.dev Bucket URL for your `S3_FILE_URL`
4. Retrieve credentials:
- [Go to API tokens page](https://dash.cloudflare.com/?to=/:account/r2/api-tokens):
- Select "Create API token"
- Edit the "R2 Token" name
- Under Permissions, select Object Read & Write permission types
- You can optionally specify the buckets that this API token has access to under the "Specify bucket(s)" section.
- Once done, click the "Create API Token" button.
- You'll receive an access key ID and a secret access key. Save them to use them later for the `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` environment variables.
</TabsContent>
</TabsContentWrapper>
</Tabs>
---
## Register the S3 File Module
Add the module into the `providers` array of the File Module:
<Note>
The File Module accepts one provider only.
</Note>
```ts title="medusa-config.ts"
import { Modules } from "@medusajs/framework/utils"
// ...
module.exports = {
// ...
modules: [
// ...
{
resolve: "@medusajs/medusa/file",
options: {
providers: [
{
resolve: "@medusajs/medusa/file-s3",
id: "s3",
options: {
file_url: process.env.S3_FILE_URL,
access_key_id: process.env.S3_ACCESS_KEY_ID,
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
region: process.env.S3_REGION,
bucket: process.env.S3_BUCKET,
endpoint: process.env.S3_ENDPOINT,
// other options...
},
},
],
},
},
],
}
```
### Additional Configuration for MinIO and Supabase
If you're using MinIO or Supabase, set `forcePathStyle` to `true` in the `additional_client_config` object.
For example:
```ts title="medusa-config.ts"
module.exports = defineConfig({
// ...
modules: [
{
resolve: "@medusajs/medusa/file",
options: {
providers: [
{
resolve: "@medusajs/medusa/file-s3",
id: "s3",
options: {
// ...
additional_client_config: {
forcePathStyle: true,
},
},
},
],
},
},
],
})
```
### S3 File Module 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>
`file_url`
</Table.Cell>
<Table.Cell>
The base URL to upload files to.
- For AWS S3, the endpoint is of the format `https://{bucket}.s3.{region}.amazonaws.com`
- For MinIO, it's the URL to the MinIO server with the bucket's name. For example, `https://{server-domain}/{bucket}`. Locally, it may be something like `http://192.168.0.123:9001/{bucket}`.
- For DigitalOcean Spaces, it's either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
- for Supabase, it's `https://{uniqueID}.supabase.co/storage/v1/object/public/{bucket}`. You can retrieve the `uniqueID` from [Storage Settings](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys) page in the Endpoint URL.
- For Cloudflare R2, it's `Public R2.dev Bucket URL`.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`access_key_id`
</Table.Cell>
<Table.Cell>
The AWS or (S3 compatible) user's access key ID.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`secret_access_key`
</Table.Cell>
<Table.Cell>
The AWS or (S3 compatible) user's secret access key.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`region`
</Table.Cell>
<Table.Cell>
The bucket's region code.
For MinIO, use `us-east-1`.
For Cloudflare, use `auto`.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`bucket`
</Table.Cell>
<Table.Cell>
The bucket's name.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`endpoint`
</Table.Cell>
<Table.Cell>
The URL to the AWS S3 (or compatible S3 API) server.
- For AWS S3, the endpoint is of the format `https://s3.{region}.amazonaws.com`
- For MinIO, it's the URL to the MinIO server. For example, locally, it may be something like `http://192.168.0.123:9001`.
- For DigitalOcean Spaces, it's the Spaces Origin Endpoint of the format `https://{region}.digitaloceanspaces.com`.
- For Supabase, it's the Endpoint URL in the [Storage Settings](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys).
- For Cloudflare, it's `https://{your-account-id}.r2.cloudflarestorage.com`.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`prefix`
</Table.Cell>
<Table.Cell>
A string to prefix each uploaded file's name.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`cache_control`
</Table.Cell>
<Table.Cell>
A string indicating how long objects remain in the AWS S3 (or compatible S3 API) cache.
</Table.Cell>
<Table.Cell>
`public, max-age=31536000`
</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>
`3600` (An hour)
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`additional_client_config`
</Table.Cell>
<Table.Cell>
Any additional configurations to pass to the S3 client.
Refer to [this AWS API reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) for a full list of accepted configuration.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
</Table.Body>
</Table>
---
## Troubleshooting
<DetailsList
sections={[
{
title: "AWS: The bucket does not allow ACLs (Enabling public access to bucket)",
content: <S3BucketAcl />
},
{
title: "Cloudflare: Checksum error",
content: <CloudflareChecksum />
}
]}
/>