diff --git a/www/apps/book/app/learn/customization/customize-admin/route/page.mdx b/www/apps/book/app/learn/customization/customize-admin/route/page.mdx index 349bdd45dfb9d..31e37c144fa2f 100644 --- 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. diff --git a/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx b/www/apps/book/app/learn/customization/customize-admin/widget/page.mdx index 547c5f473d87c..2e62ce68ae93c 100644 --- 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. diff --git a/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx b/www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx new file mode 100644 index 0000000000000..153cc1d01a6cd --- /dev/null +++ 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 ( + +
+ API Key: {import.meta.env.VITE_MY_API_KEY} +
+ + ) +} + +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" +/// +``` + +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). + diff --git a/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx b/www/apps/book/app/learn/fundamentals/admin/tips/page.mdx index 7def7227504d6..84cc4e22c2870 100644 --- 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). + Learn more about the JS SDK's configurations [this documentation](!resources!/js-sdk#js-sdk-configurations). diff --git a/www/apps/book/app/learn/fundamentals/environment-variables/page.mdx b/www/apps/book/app/learn/fundamentals/environment-variables/page.mdx index 5a0b131d12bd5..5dc29d15cc075 100644 --- 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). diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 4c447477679f9..a5ad7aa439db1 100644 --- 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" } \ No newline at end of file diff --git a/www/apps/book/generated/sidebar.mjs b/www/apps/book/generated/sidebar.mjs index c7be8c2f329c1..40e40afda09e6 100644 --- 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" diff --git a/www/apps/book/sidebar.mjs b/www/apps/book/sidebar.mjs index 6343ef8f81848..81ab8f5052bf9 100644 --- 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", diff --git a/www/apps/resources/app/integrations/guides/sanity/page.mdx b/www/apps/resources/app/integrations/guides/sanity/page.mdx index f5aac1a0ceb1d..8673b0eeb1dbc 100644 --- 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", }, diff --git a/www/apps/resources/app/js-sdk/page.mdx b/www/apps/resources/app/js-sdk/page.mdx index b9970b4c4ceb0..b91c00495392a 100644 --- 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({ + + +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). + + + ### JS SDK Configurations The `Medusa` initializer accepts as a parameter an object with the following properties: diff --git a/www/apps/resources/app/plugins/guides/wishlist/page.mdx b/www/apps/resources/app/plugins/guides/wishlist/page.mdx index d338f68ea2b3c..c62830b76f47e 100644 --- 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", }, diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 2657c28b6b4d8..fee304bb461b5 100644 --- 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",