docs: document admin environment variables (#11313)

2025-02-05 11:47:07 +02:00
1 parent 98236c8262
commit d348204fe5
@@ -156,8 +156,8 @@ If you didn't follow the [previous chapter](../widget/page.mdx), create the file
 import Medusa from "@medusajs/js-sdk"

 export const sdk = new Medusa({
-  baseUrl: "http://localhost:9000",
-  debug: process.env.NODE_ENV === "development",
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
@@ -170,6 +170,8 @@ You initialize the SDK passing it the following options:
 - `debug`: Whether to enable logging debug messages. This should only be enabled in development.
 - `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard.

+Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in [this chapter](../../../fundamentals/admin/environment-variables/page.mdx).
+
 You can now use the SDK to send requests to the Medusa server.

 <Note>
@@ -29,8 +29,8 @@ So, you'll start by configuring the JS SDK. Create the file `src/admin/lib/sdk.t
 import Medusa from "@medusajs/js-sdk"

 export const sdk = new Medusa({
-  baseUrl: "http://localhost:9000",
-  debug: process.env.NODE_ENV === "development",
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
@@ -43,6 +43,8 @@ You initialize the SDK passing it the following options:
 - `debug`: Whether to enable logging debug messages. This should only be enabled in development.
 - `auth.type`: The authentication method used in the client application, which is `session` in the Medusa Admin dashboard.

+Notice that you use `import.meta.env` to access environment variables in your customizations because the Medusa Admin is built on top of Vite. Learn more in [this chapter](../../../fundamentals/admin/environment-variables/page.mdx).
+
 You can now use the SDK to send requests to the Medusa server.

 <Note>
@@ -0,0 +1,70 @@
+export const metadata = {
+  title: `${pageNumber} Environment Variables in Admin Customizations`,
+}
+
+# {metadata.title}
+
+In this chapter, you'll learn how to use environment variables in your admin customizations.
+
+## How to Set Environment Variables
+
+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:
+
+```plain
+VITE_MY_API_KEY=sk_123
+```
+
+---
+
+## How to Use Environment Variables
+
+To access or use an environment variable starting with `VITE_`, use the `import.meta.env` object.
+
+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">API Key: {import.meta.env.VITE_MY_API_KEY}</Heading>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineWidgetConfig({
+  zone: "product.details.before",
+})
+
+export default ProductWidget
+```
+
+In this example, you display the API key in a widget using `import.meta.env.VITE_MY_API_KEY`.
+
+### Type Error on import.meta.env
+
+If you receive a type error on `import.meta.env`, create the file `src/admin/vite-env.d.ts` with the following content:
+
+```ts title="src/admin/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+This file tells TypeScript to recognize the `import.meta.env` object and enhances the types of your custom environment variables.
+
+---
+
+## Check Node Environment in Admin Customizations
+
+To check the current environment, Vite exposes two variables:
+
+- `import.meta.env.DEV`: Returns `true` if the current environment is development.
+- `import.meta.env.PROD`: Returns `true` if the current environment is production.
+
+Learn more about other Vite environment variables in the [Vite documentation](https://vite.dev/guide/env-and-mode).
+
@@ -24,14 +24,16 @@ First, create the file `src/admin/lib/config.ts` to setup the SDK for use in you
 import Medusa from "@medusajs/js-sdk"

 export const sdk = new Medusa({
-  baseUrl: "http://localhost:9000",
-  debug: process.env.NODE_ENV === "development",
+  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
 })
 ```

+Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](../environment-variables/page.mdx).
+
 <Note>

 Learn more about the JS SDK's configurations [this documentation](!resources!/js-sdk#js-sdk-configurations).
@@ -94,3 +94,11 @@ In the `medusa-config.ts` file of your Medusa application, you'll find a `loadEn
 This function is responsible for loading the correct `.env` file based on the value of `process.env.NODE_ENV`.

 To ensure that the correct `.env` file is loaded as shown in the table above, only specify `development`, `production`, `staging` or `test` as the value of `process.env.NODE_ENV` or as the parameter of `loadEnv`.
+
+---
+
+## Environment Variables for Admin Customizations
+
+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).