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

docs: document using env vars in plugins (#12618)

Browse Source
This commit is contained in:
Shahed Nasser
2025-05-26 18:50:05 +03:00
committed by GitHub
parent 1f5f50010a
commit e7cf2219b6
7 changed files with 18015 additions and 17797 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx
+41
View File
@@ -14,6 +14,12 @@ To learn how environment variables are generally loaded in Medusa based on your
## How to Set Environment Variables
<Note>
This only applies to customizations in a Medusa project. For plugins, refer to the [Environment Variables in Plugins](#environment-variables-in-plugins) section.
</Note>
The Medusa Admin is built on top of [Vite](https://vite.dev/). To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with `VITE_`.
For example:
@@ -81,3 +87,38 @@ Learn more about other Vite environment variables in the [Vite documentation](ht
When you build the Medusa application, including the Medusa Admin, with the `build` command, the environment variables are inlined into the build. This means that you can't change the environment variables without rebuilding the application.
For example, the `VITE_MY_API_KEY` environment variable in the example above will be replaced with the actual value during the build process.
---
## Environment Variables in Plugins
As explained in the [previous section](#environment-variables-in-production), environment variables are inlined into the build. This presents a limitation for plugins, where you can't use environment variables.
Instead, only the following global variable is available in plugins:
- `__BACKEND_URL__`: The URL of the Medusa backend, as set in the [Medusa configurations](../../../configurations/medusa-config/page.mdx#backendurl).
- `__BASE__`: The base path of the Medusa Admin. (For example, `/app`).
- `__STOREFRONT_URL__`: The URL of the Medusa Storefront, as set in the [Medusa configurations](../../../configurations/medusa-config/page.mdx#storefronturl).
You can use those variables in your Medusa Admin customizations of a plugin. For example:
```tsx highlights={[["8"]]}
import { defineWidgetConfig } from "@medusajs/admin-sdk"
import { Container, Heading } from "@medusajs/ui"
const ProductWidget = () => {
return (
<Container className="divide-y p-0">
<div className="flex items-center justify-between px-6 py-4">
<Heading level="h2">Backend URL: {__BACKEND_URL__}</Heading>
</div>
</Container>
)
}
export const config = defineWidgetConfig({
zone: "product.details.before",
})
export default ProductWidget
```
www/apps/book/app/learn/fundamentals/admin/tips/page.mdx
+22 -2
View File
@@ -20,7 +20,10 @@ Do not install Tanstack Query as that will cause unexpected errors in your devel
First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
```ts
<CodeTabs>
<CodeTab label="Medusa Project" value="medusa-project">
```ts title="src/admin/lib/config.ts"
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
@@ -32,7 +35,24 @@ export const sdk = new Medusa({
})
```
Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](../environment-variables/page.mdx).
</CodeTab>
<CodeTab label="Medusa Plugin" value="medusa-plugin">
```ts title="src/admin/lib/config.ts"
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
baseUrl: __BACKEND_URL__ || "/",
auth: {
type: "session",
},
})
```
</CodeTab>
</CodeTabs>
Notice that you use `import.meta.env` in a Medusa project to access environment variables in your customizations, whereas in a plugin you use the global variable `__BACKEND_URL__` to access the backend URL. You can learn more in the [Admin Environment Variables](../environment-variables/page.mdx) chapter.
<Note>
www/apps/book/app/learn/fundamentals/environment-variables/page.mdx
+128 -52
View File
@@ -107,7 +107,7 @@ To ensure that the correct `.env` file is loaded as shown in the table above, on
Since the Medusa Admin is built on top of [Vite](https://vite.dev/), you prefix the environment variables you want to use in a widget or UI route with `VITE_`. Then, you can access or use them with the `import.meta.env` object.
Learn more in [this documentation](../admin/environment-variables/page.mdx).
Learn more in the [Admin Environment Variables](../admin/environment-variables/page.mdx) chapter.
---
@@ -124,111 +124,187 @@ You should opt for setting configurations in `medusa-config.ts` where possible.
<Table>
<Table.Header>
<Table.Row>
<Table.HeaderCell>Environment Variable</Table.HeaderCell>
<Table.HeaderCell>Description</Table.HeaderCell>
<Table.HeaderCell>Default</Table.HeaderCell>
<Table.HeaderCell>
Environment Variable
</Table.HeaderCell>
<Table.HeaderCell>
Description
</Table.HeaderCell>
<Table.HeaderCell>
Default
</Table.HeaderCell>
</Table.Row>
</Table.Header>
<Table.Body>
<Table.Row>
<Table.Cell>`HOST`</Table.Cell>
<Table.Cell>The host to run the Medusa application on.</Table.Cell>
<Table.Cell> `localhost` </Table.Cell>
<Table.Cell>
`HOST`
</Table.Cell>
<Table.Cell>
The host to run the Medusa application on.
</Table.Cell>
<Table.Cell>
`localhost`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`PORT`</Table.Cell>
<Table.Cell>The port to run the Medusa application on.</Table.Cell>
<Table.Cell> `9000` </Table.Cell>
<Table.Cell>
`PORT`
</Table.Cell>
<Table.Cell>
The port to run the Medusa application on.
</Table.Cell>
<Table.Cell>
`9000`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`DATABASE_URL`</Table.Cell>
<Table.Cell>
`DATABASE_URL`
</Table.Cell>
<Table.Cell>
The URL to connect to the PostgreSQL database. Only used if [projectConfig.databaseUrl](../../configurations/medusa-config/page.mdx#databaseurl) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> `postgres://localhost/medusa-starter-default` </Table.Cell>
<Table.Cell>
`postgres://localhost/medusa-starter-default`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`STORE_CORS`</Table.Cell>
<Table.Cell>
`STORE_CORS`
</Table.Cell>
<Table.Cell>
URLs of storefronts that can access the Medusa backend's Store APIs. Only used if [projectConfig.http.storeCors](../../configurations/medusa-config/page.mdx#http-storeCors-1-1) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> `http://localhost:8000` </Table.Cell>
<Table.Cell>
`http://localhost:8000`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`ADMIN_CORS`</Table.Cell>
<Table.Cell>
URLs of admin dashboards that can access the Medusa backend's Admin APIs. Only used if [projectConfig.http.adminCors](../../configurations/medusa-config/page.mdx#http-adminCors-1-2) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> `http://localhost:7000,http://localhost:7001,http://localhost:5173` </Table.Cell>
<Table.Cell>
`http://localhost:7000,http://localhost:7001,http://localhost:5173`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`AUTH_CORS`</Table.Cell>
<Table.Cell>
URLs of clients that can access the Medusa backend's authentication routes. Only used if [projectConfig.http.authCors](../../configurations/medusa-config/page.mdx#http-authCors-1-0) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> `http://localhost:7000,http://localhost:7001,http://localhost:5173` </Table.Cell>
<Table.Cell>
`http://localhost:7000,http://localhost:7001,http://localhost:5173`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`JWT_SECRET`</Table.Cell>
<Table.Cell>
A random string used to create authentication tokens in the http layer. Only used if [projectConfig.http.jwtSecret](../../configurations/medusa-config/page.mdx#http-jwtSecret-1-3) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> \- </Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`COOKIE_SECRET`</Table.Cell>
<Table.Cell>
`COOKIE_SECRET`
</Table.Cell>
<Table.Cell>
A random string used to create cookie tokens in the http layer. Only used if [projectConfig.http.cookieSecret](../../configurations/medusa-config/page.mdx#http-cookieSecret-1-5) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> \- </Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`MEDUSA_BACKEND_URL`</Table.Cell>
<Table.Cell>
`MEDUSA_BACKEND_URL`
</Table.Cell>
<Table.Cell>
The URL to the Medusa backend. Only used if [admin.backendUrl](../../configurations/medusa-config/page.mdx#backendurl) isn't set in `medusa-config.ts`.
</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`DB_HOST`</Table.Cell>
<Table.Cell>The host for the database. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
<Table.Cell>`localhost`</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`DB_USERNAME`</Table.Cell>
<Table.Cell>The username for the database. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`DB_PASSWORD`</Table.Cell>
<Table.Cell>The password for the database user. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`DB_TEMP_NAME`</Table.Cell>
<Table.Cell>The database name to create for integration tests.</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`LOG_LEVEL`</Table.Cell>
<Table.Cell>
The allowed levels to log. Learn more in [this doumentation](../../debugging-and-testing/logging/page.mdx#log-levels).
\-
</Table.Cell>
<Table.Cell>`silly`</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`LOG_FILE`</Table.Cell>
<Table.Cell>
The file to save logs in. By default, logs aren't saved in any file. Learn more in [this documentation](../../debugging-and-testing/logging/page.mdx).
`DB_HOST`
</Table.Cell>
<Table.Cell>
The host for the database. It's used when generating migrations for a plugin, and when running integration tests.
</Table.Cell>
<Table.Cell>
`localhost`
</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>`MEDUSA_DISABLE_TELEMETRY`</Table.Cell>
<Table.Cell>
Whether to disable analytics data collection. Learn more in [this documentation](../../resources/usage/page.mdx).
`DB_USERNAME`
</Table.Cell>
<Table.Cell>
The username for the database. It's used when generating migrations for a plugin, and when running integration tests.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`DB_PASSWORD`
</Table.Cell>
<Table.Cell>
The password for the database user. It's used when generating migrations for a plugin, and when running integration tests.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`DB_TEMP_NAME`
</Table.Cell>
<Table.Cell>
The database name to create for integration tests.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`LOG_LEVEL`
</Table.Cell>
<Table.Cell>
The allowed levels to log. Learn more in the [Logging](../../debugging-and-testing/logging/page.mdx#log-levels) chapter.
</Table.Cell>
<Table.Cell>
`silly`
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`LOG_FILE`
</Table.Cell>
<Table.Cell>
The file to save logs in. By default, logs aren't saved in any file. Learn more in the [Logging](../../debugging-and-testing/logging/page.mdx) chapter.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
</Table.Row>
<Table.Row>
<Table.Cell>
`MEDUSA_DISABLE_TELEMETRY`
</Table.Cell>
<Table.Cell>
Whether to disable analytics data collection. Learn more in the [Usage](../../resources/usage/page.mdx) chapter.
</Table.Cell>
<Table.Cell>
\-
</Table.Cell>
<Table.Cell> \- </Table.Cell>
</Table.Row>
</Table.Body>
</Table>
www/apps/book/generated/edit-dates.mjs
+3 -3
View File
@@ -43,7 +43,7 @@ export const generatedEditDates = {
"app/learn/fundamentals/scheduled-jobs/execution-number/page.mdx": "2024-10-21T13:30:21.371Z",
"app/learn/fundamentals/api-routes/parameters/page.mdx": "2025-02-14T08:34:03.184Z",
"app/learn/fundamentals/api-routes/http-methods/page.mdx": "2024-10-21T13:30:21.367Z",
"app/learn/fundamentals/admin/tips/page.mdx": "2025-03-11T08:54:12.028Z",
"app/learn/fundamentals/admin/tips/page.mdx": "2025-05-26T14:58:56.390Z",
"app/learn/fundamentals/api-routes/cors/page.mdx": "2025-03-11T08:54:26.281Z",
"app/learn/fundamentals/admin/ui-routes/page.mdx": "2025-02-24T09:35:11.752Z",
"app/learn/fundamentals/api-routes/middlewares/page.mdx": "2025-05-09T07:56:04.125Z",
@@ -93,7 +93,7 @@ export const generatedEditDates = {
"app/learn/introduction/architecture/page.mdx": "2025-05-21T14:31:51.644Z",
"app/learn/fundamentals/data-models/infer-type/page.mdx": "2025-03-18T07:41:01.936Z",
"app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2024-12-09T14:38:06.385Z",
"app/learn/fundamentals/environment-variables/page.mdx": "2025-03-11T08:55:03.343Z",
"app/learn/fundamentals/environment-variables/page.mdx": "2025-05-26T15:06:07.800Z",
"app/learn/build/page.mdx": "2025-04-25T12:34:33.914Z",
"app/learn/deployment/general/page.mdx": "2025-04-17T08:29:09.878Z",
"app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2024-11-25T16:19:32.169Z",
@@ -106,7 +106,7 @@ export const generatedEditDates = {
"app/learn/customization/reuse-customizations/page.mdx": "2025-01-22T10:01:57.665Z",
"app/learn/update/page.mdx": "2025-01-27T08:45:19.030Z",
"app/learn/fundamentals/module-links/query-context/page.mdx": "2025-02-12T16:59:20.963Z",
"app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-03-25T13:32:19.713Z",
"app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-05-26T15:02:25.624Z",
"app/learn/fundamentals/api-routes/parse-body/page.mdx": "2025-04-17T08:29:10.145Z",
"app/learn/fundamentals/admin/routing/page.mdx": "2025-02-24T09:50:37.495Z",
"app/learn/resources/contribution-guidelines/admin-translations/page.mdx": "2025-02-11T16:57:46.726Z",
www/apps/book/public/llms-full.txt
+17803 -17737
View File
File diff suppressed because it is too large Load Diff
www/apps/resources/app/js-sdk/page.mdx
+17 -2
View File
@@ -42,7 +42,7 @@ For admin customizations, create this file at `src/admin/lib/config.ts`.
</Note>
<CodeTabs group="sdk-project">
<CodeTab label="Admin" value="admin">
<CodeTab label="Admin (Medusa project)" value="admin-medusa-project">
```ts title="src/admin/lib/config.ts"
import Medusa from "@medusajs/js-sdk"
@@ -54,6 +54,21 @@ export const sdk = new Medusa({
type: "session",
},
})
```
</CodeTab>
<CodeTab label="Admin (Medusa Plugin)" value="admin-medusa-plugin">
```ts title="src/admin/lib/config.ts"
import Medusa from "@medusajs/js-sdk"
export const sdk = new Medusa({
baseUrl: __BACKEND_URL__ || "/",
debug: import.meta.env.DEV,
auth: {
type: "session",
},
})
```
</CodeTab>
@@ -80,7 +95,7 @@ export const sdk = new Medusa({
<Note title="Tip">
In the Medusa Admin you use `import.meta.env` to access environment variables becaues the Medusa Admin is built on top of [Vite](https://vitejs.dev/). Learn more in [this documentation](!docs!/learn/fundamentals/admin/environment-variables).
In Medusa Admin customizations that are created in a Medusa project, you use `import.meta.env` to access environment variables, whereas in customizations built in a Medusa plugin, you use the global variable `__BACKEND_URL__` to access the backend URL. You can learn more in the [Admin Environment Variables](!docs!/learn/fundamentals/admin/environment-variables) chapter.
</Note>
www/apps/resources/generated/edit-dates.mjs
+1 -1
View File
@@ -2168,7 +2168,7 @@ export const generatedEditDates = {
"app/commerce-modules/store/links-to-other-modules/page.mdx": "2025-04-17T16:03:16.419Z",
"app/examples/page.mdx": "2025-04-17T08:50:17.036Z",
"app/medusa-cli/commands/build/page.mdx": "2024-11-11T11:00:49.665Z",
"app/js-sdk/page.mdx": "2025-03-28T09:50:07.617Z",
"app/js-sdk/page.mdx": "2025-05-26T15:08:16.590Z",
"references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.apiKey/page.mdx": "2025-05-20T07:51:40.924Z",
"references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.campaign/page.mdx": "2025-05-20T07:51:40.925Z",
"references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.claim/page.mdx": "2025-05-20T07:51:40.925Z",