@medusajs/file 2.22.0-snapshot-20261020204851 → 2.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/AGENTS.md +85 -0
  2. package/README.md +99 -1
  3. package/package.json +8 -4
package/AGENTS.md ADDED
@@ -0,0 +1,85 @@
1
+ # @medusajs/file
2
+
3
+ File Module (`Modules.FILE`, container key `"file"`). A stateless facade over exactly one File Module Provider (Local, S3, or custom) for uploading, reading, and deleting files. It stores nothing in the database; a file's `id` is the provider's file key.
4
+
5
+ ## Using this package
6
+
7
+ - Registered by default via `defineConfig` as `@medusajs/medusa/file` with `@medusajs/medusa/file-local` (id `local`); on Medusa Cloud with `@medusajs/medusa/file-s3`.
8
+ - Overriding the module replaces the default provider:
9
+
10
+ ```ts
11
+ module.exports = defineConfig({
12
+ modules: [
13
+ {
14
+ resolve: "@medusajs/medusa/file",
15
+ options: {
16
+ providers: [
17
+ {
18
+ resolve: "@medusajs/medusa/file-s3",
19
+ id: "s3",
20
+ options: {
21
+ file_url: process.env.S3_FILE_URL,
22
+ access_key_id: process.env.S3_ACCESS_KEY_ID,
23
+ secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
24
+ region: process.env.S3_REGION,
25
+ bucket: process.env.S3_BUCKET,
26
+ },
27
+ },
28
+ ],
29
+ },
30
+ },
31
+ ],
32
+ })
33
+ ```
34
+
35
+ - Resolve: `container.resolve(Modules.FILE)` (`IFileModuleService`). Prefer `uploadFilesWorkflow` / `deleteFilesWorkflow` from `@medusajs/medusa/core-flows` in routes.
36
+
37
+ ```ts
38
+ const fileModule = container.resolve(Modules.FILE)
39
+
40
+ const { id, url } = await fileModule.createFiles({
41
+ filename: "report.csv",
42
+ mimeType: "text/csv",
43
+ content: Buffer.from(csv).toString("base64"), // base64 string
44
+ access: "private",
45
+ })
46
+
47
+ const file = await fileModule.retrieveFile(id) // url is a presigned download URL
48
+ const buffer = await fileModule.getAsBuffer(id)
49
+ ```
50
+
51
+ ### Service methods (`src/services/file-module-service.ts`)
52
+
53
+ - `createFiles(data | data[])` -> `{ id, url }`
54
+ - `deleteFiles(id | ids)`
55
+ - `retrieveFile(id)`, `listFiles({ id })`, `listAndCountFiles({ id })`: return presigned download URLs
56
+ - `getUploadFileUrls({ filename, mimeType?, access? })`: presigned upload URLs (provider must implement `getPresignedUploadUrl`)
57
+ - Streams and buffers: `getDownloadStream(id)`, `getAsBuffer(id)`, `getUploadStream({ filename, mimeType, ... })` -> `{ writeStream, promise, url, fileKey }`
58
+ - `getProvider()`: the internal `FileProviderService`
59
+
60
+ - No data models, no emitted events. The joiner config declares a `File` entity, but nothing links to it in `link-modules`.
61
+ - Custom providers extend `AbstractFileProviderService` from `@medusajs/framework/utils`.
62
+ - Docs: https://docs.medusajs.com/resources/infrastructure-modules/file.md, https://docs.medusajs.com/resources/infrastructure-modules/file/local.md, https://docs.medusajs.com/resources/infrastructure-modules/file/s3.md
63
+
64
+ ## Architecture
65
+
66
+ - `src/loaders/providers.ts`: registers each provider as `fs_<identifier>_<id>` (static `identifier` from the provider class, e.g. `localfs`) and appends to `file_providers_identifier`.
67
+ - `src/services/file-provider-service.ts`: picks the single container key starting with `fs_` and forwards every call to it.
68
+
69
+ ## Development
70
+
71
+ ```bash
72
+ yarn build
73
+ yarn test # src/services/__tests__/file.spec.ts
74
+ yarn test:integration # integration-tests/__tests__/module.spec.ts (fixture provider in integration-tests/__fixtures__/providers)
75
+ yarn test:integration -t "<test name>"
76
+ ```
77
+
78
+ ## Gotchas
79
+
80
+ - Exactly one provider is allowed: `FileProviderService` throws "File module should be initialized with exactly one provider" for zero or several.
81
+ - The loader reads `options.providers` (array), but the exported `FileModuleOptions` type declares a singular `provider`. Configure with `providers`.
82
+ - `listFiles` / `listAndCountFiles` throw `INVALID_DATA` unless filtered by `id`; there is no way to enumerate stored files.
83
+ - `createFiles` does not validate MIME types or size (see the TODO in the service).
84
+ - `getUploadFileUrls` throws if the provider lacks `getPresignedUploadUrl` or `filename` is missing.
85
+ - `package.json` has `migration:*` scripts, but the module has no models or `mikro-orm.config.dev.ts`; don't run them.
package/README.md CHANGED
@@ -1 +1,99 @@
1
- # File Module
1
+ <p align="center">
2
+ <a href="https://www.medusajs.com">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
5
+ <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
6
+ <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
7
+ </picture>
8
+ </a>
9
+ </p>
10
+ <h1 align="center">
11
+ @medusajs/file
12
+ </h1>
13
+
14
+ <h4 align="center">
15
+ <a href="https://docs.medusajs.com">Documentation</a> |
16
+ <a href="https://www.medusajs.com">Website</a>
17
+ </h4>
18
+
19
+ <p align="center">
20
+ Building blocks for digital commerce
21
+ </p>
22
+ <p align="center">
23
+ <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
24
+ <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
25
+ </a>
26
+ <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
27
+ <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
28
+ </a>
29
+ <a href="https://discord.gg/xpCwq3Kfn8">
30
+ <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
31
+ </a>
32
+ <a href="https://twitter.com/intent/follow?screen_name=medusajs">
33
+ <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
34
+ </a>
35
+ </p>
36
+
37
+ File Module for Medusa: uploads, retrieves, and deletes files such as product images and import/export files. Storage is delegated to a File Module Provider, so you can swap local storage for S3 or another service without changing your code. It ships with `@medusajs/medusa` and is registered by default; resolve it in your code with `container.resolve(Modules.FILE)`.
38
+
39
+ ## At a glance
40
+
41
+ | | |
42
+ | --- | --- |
43
+ | Package | `@medusajs/file` |
44
+ | Type | Infrastructure Module |
45
+ | Module key | `Modules.FILE` (`"file"`) |
46
+ | Registered by default | Yes (with the Local provider; S3 provider on Medusa Cloud) |
47
+
48
+ ## Providers
49
+
50
+ The module must be configured with exactly one provider. Official providers:
51
+
52
+ | Package | Register with |
53
+ | --- | --- |
54
+ | [`@medusajs/file-local`](../providers/file-local) | `@medusajs/medusa/file-local` |
55
+ | [`@medusajs/file-s3`](../providers/file-s3) | `@medusajs/medusa/file-s3` |
56
+
57
+ ## Installation
58
+
59
+ No installation needed. The module ships with `@medusajs/medusa`.
60
+
61
+ ## Usage
62
+
63
+ To change the provider, register the module in `medusa-config.ts` with the provider you want:
64
+
65
+ ```ts
66
+ import { defineConfig } from "@medusajs/framework/utils"
67
+
68
+ module.exports = defineConfig({
69
+ // ...
70
+ modules: [
71
+ {
72
+ resolve: "@medusajs/medusa/file",
73
+ options: {
74
+ providers: [
75
+ {
76
+ resolve: "@medusajs/medusa/file-s3",
77
+ id: "s3",
78
+ options: {
79
+ // provider options
80
+ },
81
+ },
82
+ ],
83
+ },
84
+ },
85
+ ],
86
+ })
87
+ ```
88
+
89
+ ## Configuration
90
+
91
+ | Option | Type | Description | Default |
92
+ | --- | --- | --- | --- |
93
+ | `providers` | `{ resolve: string, id: string, options?: Record<string, unknown> }[]` | The file provider to use. Must contain exactly one provider. | Local provider (`id: "local"`) |
94
+
95
+ ## Resources
96
+
97
+ - [File Module](https://docs.medusajs.com/resources/infrastructure-modules/file)
98
+ - [Local File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/local)
99
+ - [S3 File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file/s3)
package/package.json CHANGED
@@ -1,15 +1,19 @@
1
1
  {
2
2
  "name": "@medusajs/file",
3
- "version": "2.22.0-snapshot-20261020204851",
3
+ "version": "2.22.0",
4
4
  "description": "Medusa File module",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "files": [
8
8
  "dist",
9
+ "AGENTS.md",
9
10
  "!dist/**/__tests__",
10
11
  "!dist/**/__mocks__",
11
12
  "!dist/**/__fixtures__"
12
13
  ],
14
+ "llms": "https://docs.medusajs.com/llms.txt",
15
+ "llmsFull": "https://docs.medusajs.com/llms-full.txt",
16
+ "mcpServer": "https://docs.medusajs.com/mcp",
13
17
  "engines": {
14
18
  "node": ">=22.22.0"
15
19
  },
@@ -39,10 +43,10 @@
39
43
  "orm:cache:clear": "MIKRO_ORM_CLI_CONFIG=./mikro-orm.config.dev.ts MIKRO_ORM_ALLOW_GLOBAL_CLI=true medusa-mikro-orm cache:clear"
40
44
  },
41
45
  "devDependencies": {
42
- "@medusajs/framework": "2.22.0-snapshot-20261020204851",
43
- "@medusajs/test-utils": "2.22.0-snapshot-20261020204851"
46
+ "@medusajs/framework": "2.22.0",
47
+ "@medusajs/test-utils": "2.22.0"
44
48
  },
45
49
  "peerDependencies": {
46
- "@medusajs/framework": "2.22.0-snapshot-20261020204851"
50
+ "@medusajs/framework": "2.22.0"
47
51
  }
48
52
  }