import { Table } from "docs-ui"

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.

To learn how environment variables are generally loaded in Medusa based on your application's environment, check out this chapter.

How to Set Environment Variables

This only applies to customizations in a Medusa project. For plugins, refer to the Environment Variables in Plugins section.

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:

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:

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:

/// <reference types="vite/client" />

declare const __BASE__: string
declare const __BACKEND_URL__: string
declare 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.

Predefined Environment Variables

You can further customize the Medusa Admin behavior using the following predefined environment variables. You can set the environment variables in your .env file or in your deployment platform.

The following pre-defined environment variables are available starting Medusa v2.12.0.

  `ADMIN_AUTH_TYPE`

  </Table.Cell>
  <Table.Cell>

  A string indicating the authentication method that the JS SDK instance uses in the Medusa Admin. Possible values are `session` and `jwt`. Learn more in the [JS SDK Authentication guide](!resources!/js-sdk/auth/overview).

  </Table.Cell>
  <Table.Cell>

  `session`

  </Table.Cell>
</Table.Row>
<Table.Row>
  <Table.Cell>
  
  `ADMIN_JWT_TOKEN_STORAGE_KEY`

  </Table.Cell>
  <Table.Cell>

  A string indicating the key used to store the authentication JWT token in the browser's local storage. Only applicable if `ADMIN_AUTH_TYPE` is set to `jwt`.

  </Table.Cell>
  <Table.Cell>

  `medusa_auth_token`

  </Table.Cell>
</Table.Row>

</Table.Body>

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

Environment variable support in plugins is available starting Medusa v2.11.0. Refer to the Medusa versions prior to v2.11.0 section for more details if you're using an earlier version.

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:

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.MY_API_KEY}</Heading>
      </div>
    </Container>
  )
}

export const config = defineWidgetConfig({
  zone: "product.details.before",
})

export default ProductWidget

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

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:

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">Backend URL: {__BACKEND_URL__}</Heading>
      </div>
    </Container>
  )
}

export const config = defineWidgetConfig({
  zone: "product.details.before",
})

export default ProductWidget

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

/// <reference types="vite/client" />

declare const __BACKEND_URL__: string
declare const __BASE__: string
declare const __STOREFRONT_URL__: string

For Medusa versions prior to v2.11.0

As explained in the Environment Variables in Production section, environment variables are inlined into the build. This presents a limitation for plugins, where you can't use environment variables.

Instead, you can use the Plugin Global Variables described above to access the backend URL, base path, and storefront URL.