docs: document admin environment variables (medusajs#11313)

Author: shahednasser

www/apps/book/app/learn/customization/customize-admin/route/page.mdx

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

www/apps/book/app/learn/customization/customize-admin/widget/page.mdx

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

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

@@ -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).
+

www/apps/book/app/learn/fundamentals/admin/tips/page.mdx

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

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

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

www/apps/book/generated/edit-dates.mjs

@@ -50,7 +50,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": "2024-11-19T16:37:47.251Z",
   "app/learn/fundamentals/api-routes/http-methods/page.mdx": "2024-10-21T13:30:21.367Z",
-  "app/learn/fundamentals/admin/tips/page.mdx": "2025-01-27T08:45:19.023Z",
+  "app/learn/fundamentals/admin/tips/page.mdx": "2025-02-05T09:07:52.584Z",
   "app/learn/fundamentals/api-routes/cors/page.mdx": "2024-12-09T13:04:04.357Z",
   "app/learn/fundamentals/admin/ui-routes/page.mdx": "2024-12-09T16:44:40.198Z",
   "app/learn/fundamentals/api-routes/middlewares/page.mdx": "2024-12-09T13:04:03.712Z",
@@ -88,8 +88,8 @@ export const generatedEditDates = {
   "app/learn/customization/extend-features/extend-create-product/page.mdx": "2025-01-06T11:18:58.250Z",
   "app/learn/customization/custom-features/page.mdx": "2024-12-09T10:46:28.593Z",
   "app/learn/customization/customize-admin/page.mdx": "2024-12-09T11:02:38.801Z",
-  "app/learn/customization/customize-admin/route/page.mdx": "2025-02-04T07:35:04.523Z",
-  "app/learn/customization/customize-admin/widget/page.mdx": "2025-01-27T08:45:19.022Z",
+  "app/learn/customization/customize-admin/route/page.mdx": "2025-02-05T09:09:11.472Z",
+  "app/learn/customization/customize-admin/widget/page.mdx": "2025-02-05T09:10:18.163Z",
   "app/learn/customization/extend-features/define-link/page.mdx": "2024-12-09T11:02:39.346Z",
   "app/learn/customization/extend-features/page.mdx": "2024-12-09T11:02:39.244Z",
   "app/learn/customization/extend-features/query-linked-records/page.mdx": "2024-12-09T11:02:39.519Z",
@@ -102,7 +102,7 @@ export const generatedEditDates = {
   "app/learn/introduction/architecture/page.mdx": "2025-01-16T10:25:10.780Z",
   "app/learn/fundamentals/data-models/infer-type/page.mdx": "2024-12-09T15:54:08.713Z",
   "app/learn/fundamentals/custom-cli-scripts/seed-data/page.mdx": "2024-12-09T14:38:06.385Z",
-  "app/learn/fundamentals/environment-variables/page.mdx": "2024-12-09T11:00:57.428Z",
+  "app/learn/fundamentals/environment-variables/page.mdx": "2025-02-05T09:15:49.196Z",
   "app/learn/build/page.mdx": "2024-12-09T11:05:17.383Z",
   "app/learn/deployment/general/page.mdx": "2024-11-25T14:33:50.439Z",
   "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2024-11-25T16:19:32.169Z",
@@ -115,5 +115,6 @@ export const generatedEditDates = {
   "app/learn/fundamentals/plugins/page.mdx": "2025-01-22T10:14:10.433Z",
   "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-03T17:04:24.479Z"
+  "app/learn/fundamentals/module-links/query-context/page.mdx": "2025-02-03T17:04:24.479Z",
+  "app/learn/fundamentals/admin/environment-variables/page.mdx": "2025-02-05T09:05:33.334Z"
 }

www/apps/book/generated/sidebar.mjs

@@ -789,14 +789,23 @@ export const generatedSidebar = [
             "children": [],
             "chapterTitle": "3.9.2. Admin UI Routes"
           },
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "type": "link",
+            "path": "/learn/fundamentals/admin/environment-variables",
+            "title": "Environment Variables",
+            "children": [],
+            "chapterTitle": "3.9.3. Environment Variables"
+          },
           {
             "loaded": true,
             "isPathHref": true,
             "type": "link",
             "path": "/learn/fundamentals/admin/constraints",
             "title": "Constraints",
             "children": [],
-            "chapterTitle": "3.9.3. Constraints"
+            "chapterTitle": "3.9.4. Constraints"
           },
           {
             "loaded": true,
@@ -805,7 +814,7 @@ export const generatedSidebar = [
             "path": "/learn/fundamentals/admin/tips",
             "title": "Tips",
             "children": [],
-            "chapterTitle": "3.9.4. Tips"
+            "chapterTitle": "3.9.5. Tips"
           }
         ],
         "chapterTitle": "3.9. Admin Development"

www/apps/book/sidebar.mjs

@@ -456,6 +456,11 @@ export const sidebar = sidebarAttachHrefCommonOptions([
             path: "/learn/fundamentals/admin/ui-routes",
             title: "Admin UI Routes",
           },
+          {
+            type: "link",
+            path: "/learn/fundamentals/admin/environment-variables",
+            title: "Environment Variables",
+          },
           {
             type: "link",
             path: "/learn/fundamentals/admin/constraints",

www/apps/resources/app/integrations/guides/sanity/page.mdx

@@ -1454,8 +1454,8 @@ To configure the JS SDK, create the file `src/admin/lib/sdk.ts` with the followi
 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",
   },

www/apps/resources/app/js-sdk/page.mdx

@@ -48,8 +48,8 @@ For admin customizations, create this file at `src/admin/lib/config.ts`.
 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",
   },
@@ -78,6 +78,12 @@ export const sdk = new Medusa({
   </CodeTab>
 </CodeTabs>
 
+<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).
+
+</Note>
+
 ### JS SDK Configurations
 
 The `Medusa` initializer accepts as a parameter an object with the following properties: