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

2025-05-26 18:50:05 +03:00
parent 1f5f50010a
commit e7cf2219b6
7 changed files with 18015 additions and 17797 deletions
@@ -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
+```
@@ -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>