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

www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx

@@ -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

@@ -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

@@ -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>
-      <Table.HeaderCell>Description</Table.HeaderCell>
+        Environment Variable
-      <Table.HeaderCell>Default</Table.HeaderCell>
+      </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>
-      <Table.Cell>The host to run the Medusa application on.</Table.Cell>
+        `HOST`
-      <Table.Cell> `localhost` </Table.Cell>
+      </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>
-      <Table.Cell>The port to run the Medusa application on.</Table.Cell>
+        `PORT`
-      <Table.Cell> `9000` </Table.Cell>
+      </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

@@ -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/resources/app/js-sdk/page.mdx

@@ -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

@@ -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",