docs: document admin environment variables (#11313)

2025-02-05 11:47:07 +02:00
parent 98236c8262
commit d348204fe5
12 changed files with 127 additions and 22 deletions
--- a/www/apps/book/app/learn/customization/customize-admin/route/page.mdx
+++ b/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>
--- a/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx
+++ b/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>
--- a/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx
+++ b/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).
+
--- a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx
+++ b/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).
--- a/www/apps/book/app/learn/fundamentals/environment-variables/page.mdx
+++ b/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).
--- a/www/apps/book/generated/edit-dates.mjs
+++ b/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"
 }
--- a/www/apps/book/generated/sidebar.mjs
+++ b/www/apps/book/generated/sidebar.mjs
@@ -789,6 +789,15 @@ 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,
@@ -796,7 +805,7 @@ export const generatedSidebar = [
            "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"
--- a/www/apps/book/sidebar.mjs
+++ b/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",
--- a/www/apps/resources/app/integrations/guides/sanity/page.mdx
+++ b/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",
  },
--- a/www/apps/resources/app/js-sdk/page.mdx
+++ b/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:
--- a/www/apps/resources/app/plugins/guides/wishlist/page.mdx
+++ b/www/apps/resources/app/plugins/guides/wishlist/page.mdx
@@ -1992,8 +1992,8 @@ To initialize the JS SDK, create the file `src/admin/lib/sdk.ts` with the follow
 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",
  },
--- a/www/apps/resources/generated/edit-dates.mjs
+++ b/www/apps/resources/generated/edit-dates.mjs
@@ -2178,7 +2178,7 @@ export const generatedEditDates = {
  "app/commerce-modules/store/links-to-other-modules/page.mdx": "2024-12-24T14:58:24.038Z",
  "app/examples/page.mdx": "2025-02-04T07:36:39.956Z",
  "app/medusa-cli/commands/build/page.mdx": "2024-11-11T11:00:49.665Z",
-  "app/js-sdk/page.mdx": "2024-12-12T11:41:51.152Z",
+  "app/js-sdk/page.mdx": "2025-02-05T09:12:11.479Z",
  "references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.apiKey/page.mdx": "2025-01-13T18:05:58.463Z",
  "references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.campaign/page.mdx": "2024-12-26T11:37:18.121Z",
  "references/js_sdk/admin/Admin/properties/js_sdk.admin.Admin.claim/page.mdx": "2025-01-13T18:05:58.348Z",
@@ -3147,7 +3147,7 @@ export const generatedEditDates = {
  "references/types/HttpTypes/interfaces/types.HttpTypes.AdminBatchProductVariantRequest/page.mdx": "2024-12-09T13:21:34.309Z",
  "references/types/WorkflowTypes/ProductWorkflow/interfaces/types.WorkflowTypes.ProductWorkflow.ExportProductsDTO/page.mdx": "2025-01-13T18:05:55.538Z",
  "app/contribution-guidelines/admin-translations/page.mdx": "2024-11-14T08:54:15.369Z",
-  "app/integrations/guides/sanity/page.mdx": "2025-02-04T07:36:48.007Z",
+  "app/integrations/guides/sanity/page.mdx": "2025-02-05T09:10:44.478Z",
  "references/api_key/types/api_key.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.715Z",
  "references/auth/types/auth.FindConfigOrder/page.mdx": "2024-11-25T17:49:28.887Z",
  "references/cart/types/cart.FindConfigOrder/page.mdx": "2024-11-25T17:49:29.455Z",
@@ -5864,7 +5864,7 @@ export const generatedEditDates = {
  "references/core_flows/types/core_flows.ThrowUnlessPaymentCollectionNotePaidInput/page.mdx": "2025-01-17T16:43:25.819Z",
  "references/core_flows/types/core_flows.ValidatePaymentsRefundStepInput/page.mdx": "2025-01-17T16:43:26.128Z",
  "references/core_flows/types/core_flows.ValidateRefundStepInput/page.mdx": "2025-01-17T16:43:26.124Z",
-  "app/plugins/guides/wishlist/page.mdx": "2025-01-23T11:59:10.008Z",
+  "app/plugins/guides/wishlist/page.mdx": "2025-02-05T09:12:22.965Z",
  "app/plugins/page.mdx": "2025-01-22T09:36:37.745Z",
  "app/admin-components/components/data-table/page.mdx": "2025-01-22T16:01:01.279Z",
  "references/order_models/variables/order_models.Order/page.mdx": "2025-01-27T11:43:58.788Z",