4.4. Environment Variables in Admin Customizations

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. To set an environment variable that you want to use in a widget or UI route, prefix the environment variable with VITE_.

For example:

Code
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:

Code
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3
4const ProductWidget = () => {5  return (6    <Container className="divide-y p-0">7      <div className="flex items-center justify-between px-6 py-4">8        <Heading level="h2">API Key: {import.meta.env.VITE_MY_API_KEY}</Heading>9      </div>10    </Container>11  )12}13
14export const config = defineWidgetConfig({15  zone: "product.details.before",16})17
18export 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:

src/admin/vite-env.d.ts
1/// <reference types="vite/client" />2
3declare const __BASE__: string4declare const __BACKEND_URL__: string5declare const __STOREFRONT_URL__: string

This file tells TypeScript to recognize the import.meta.env object and enhances the types of your custom environment variables.

Note that the __BASE__, __BACKEND_URL__, and __STOREFRONT_URL__ variables are global variables available in your admin customizations. Learn more in the Tips for Admin Customizations chapter.

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.

Environment Variables in Production#

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#

For plugins, you can use environment variables without a prefix. Then, Medusa applications that use the plugin can set the environment variable with the PLUGIN_ prefix.

For example, you can create a widget in your plugin that uses the MY_API_KEY environment variable:

Code
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3
4const ProductWidget = () => {5  return (6    <Container className="divide-y p-0">7      <div className="flex items-center justify-between px-6 py-4">8        <Heading level="h2">API Key: {import.meta.env.MY_API_KEY}</Heading>9      </div>10    </Container>11  )12}13
14export const config = defineWidgetConfig({15  zone: "product.details.before",16})17
18export default ProductWidget

Then, in the Medusa application that uses the plugin, set the environment variable with the PLUGIN_ prefix:

Terminal
❯PLUGIN_MY_API_KEY=sk_123

The MY_API_KEY environment variable in the plugin will be replaced with the value of PLUGIN_MY_API_KEY during the build process of the Medusa application.

Global Variables in Plugins#

Plugins also have the following global variables available:

• __BACKEND_URL__: The URL of the Medusa backend, as set in the Medusa configurations.
• __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.

You can use those variables in your Medusa Admin customizations of a plugin. For example:

Code
1import { defineWidgetConfig } from "@medusajs/admin-sdk"2import { Container, Heading } from "@medusajs/ui"3
4const ProductWidget = () => {5  return (6    <Container className="divide-y p-0">7      <div className="flex items-center justify-between px-6 py-4">8        <Heading level="h2">Backend URL: {__BACKEND_URL__}</Heading>9      </div>10    </Container>11  )12}13
14export const config = defineWidgetConfig({15  zone: "product.details.before",16})17
18export default ProductWidget

To fix possible type errors, create the file src/admin/vite-env.d.ts and add the global variables:

src/admin/vite-env.d.ts
1/// <reference types="vite/client" />2
3declare const __BACKEND_URL__: string4declare const __BASE__: string5declare const __STOREFRONT_URL__: string

For Medusa versions prior to v2.11.0#