docs: document using env vars in plugins (#12618)
This commit is contained in:
Shahed Nasser
@@ -14,6 +14,12 @@ To learn how environment variables are generally loaded in Medusa based on your
|
||||
|
||||
## How to Set Environment Variables
|
||||
|
||||
<Note>
|
||||
|
||||
This only applies to customizations in a Medusa project. For plugins, refer to the [Environment Variables in Plugins](#environment-variables-in-plugins) section.
|
||||
|
||||
</Note>
|
||||
|
||||
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:
|
||||
@@ -81,3 +87,38 @@ Learn more about other Vite environment variables in the [Vite documentation](ht
|
||||
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
|
||||
|
||||
As explained in the [previous section](#environment-variables-in-production), environment variables are inlined into the build. This presents a limitation for plugins, where you can't use environment variables.
|
||||
|
||||
Instead, only the following global variable is available in plugins:
|
||||
|
||||
- `__BACKEND_URL__`: The URL of the Medusa backend, as set in the [Medusa configurations](../../../configurations/medusa-config/page.mdx#backendurl).
|
||||
- `__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](../../../configurations/medusa-config/page.mdx#storefronturl).
|
||||
|
||||
You can use those variables in your Medusa Admin customizations of a plugin. 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">Backend URL: {__BACKEND_URL__}</Heading>
|
||||
</div>
|
||||
</Container>
|
||||
)
|
||||
}
|
||||
|
||||
export const config = defineWidgetConfig({
|
||||
zone: "product.details.before",
|
||||
})
|
||||
|
||||
export default ProductWidget
|
||||
```
|
||||
|
||||
@@ -20,7 +20,10 @@ Do not install Tanstack Query as that will cause unexpected errors in your devel
|
||||
|
||||
First, create the file `src/admin/lib/config.ts` to setup the SDK for use in your customizations:
|
||||
|
||||
```ts
|
||||
<CodeTabs>
|
||||
<CodeTab label="Medusa Project" value="medusa-project">
|
||||
|
||||
```ts title="src/admin/lib/config.ts"
|
||||
import Medusa from "@medusajs/js-sdk"
|
||||
|
||||
export const sdk = new Medusa({
|
||||
@@ -32,7 +35,24 @@ export const sdk = new Medusa({
|
||||
})
|
||||
```
|
||||
|
||||
Notice that you use `import.meta.env` to access environment variables in your customizations, as explained in [this chapter](../environment-variables/page.mdx).
|
||||
</CodeTab>
|
||||
<CodeTab label="Medusa Plugin" value="medusa-plugin">
|
||||
|
||||
```ts title="src/admin/lib/config.ts"
|
||||
import Medusa from "@medusajs/js-sdk"
|
||||
|
||||
export const sdk = new Medusa({
|
||||
baseUrl: __BACKEND_URL__ || "/",
|
||||
auth: {
|
||||
type: "session",
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
</CodeTab>
|
||||
</CodeTabs>
|
||||
|
||||
Notice that you use `import.meta.env` in a Medusa project to access environment variables in your customizations, whereas in a plugin you use the global variable `__BACKEND_URL__` to access the backend URL. You can learn more in the [Admin Environment Variables](../environment-variables/page.mdx) chapter.
|
||||
|
||||
<Note>
|
||||
|
||||
|
||||
@@ -107,7 +107,7 @@ To ensure that the correct `.env` file is loaded as shown in the table above, on
|
||||
|
||||
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).
|
||||
Learn more in the [Admin Environment Variables](../admin/environment-variables/page.mdx) chapter.
|
||||
|
||||
---
|
||||
|
||||
@@ -124,111 +124,187 @@ You should opt for setting configurations in `medusa-config.ts` where possible.
|
||||
<Table>
|
||||
<Table.Header>
|
||||
<Table.Row>
|
||||
<Table.HeaderCell>Environment Variable</Table.HeaderCell>
|
||||
<Table.HeaderCell>Description</Table.HeaderCell>
|
||||
<Table.HeaderCell>Default</Table.HeaderCell>
|
||||
<Table.HeaderCell>
|
||||
Environment Variable
|
||||
</Table.HeaderCell>
|
||||
<Table.HeaderCell>
|
||||
Description
|
||||
</Table.HeaderCell>
|
||||
<Table.HeaderCell>
|
||||
Default
|
||||
</Table.HeaderCell>
|
||||
</Table.Row>
|
||||
</Table.Header>
|
||||
<Table.Body>
|
||||
<Table.Row>
|
||||
<Table.Cell>`HOST`</Table.Cell>
|
||||
<Table.Cell>The host to run the Medusa application on.</Table.Cell>
|
||||
<Table.Cell> `localhost` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`HOST`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The host to run the Medusa application on.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
`localhost`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`PORT`</Table.Cell>
|
||||
<Table.Cell>The port to run the Medusa application on.</Table.Cell>
|
||||
<Table.Cell> `9000` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`PORT`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The port to run the Medusa application on.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
`9000`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`DATABASE_URL`</Table.Cell>
|
||||
<Table.Cell>
|
||||
`DATABASE_URL`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The URL to connect to the PostgreSQL database. Only used if [projectConfig.databaseUrl](../../configurations/medusa-config/page.mdx#databaseurl) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> `postgres://localhost/medusa-starter-default` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`postgres://localhost/medusa-starter-default`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`STORE_CORS`</Table.Cell>
|
||||
<Table.Cell>
|
||||
`STORE_CORS`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
URLs of storefronts that can access the Medusa backend's Store APIs. Only used if [projectConfig.http.storeCors](../../configurations/medusa-config/page.mdx#http-storeCors-1-1) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> `http://localhost:8000` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`http://localhost:8000`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`ADMIN_CORS`</Table.Cell>
|
||||
<Table.Cell>
|
||||
URLs of admin dashboards that can access the Medusa backend's Admin APIs. Only used if [projectConfig.http.adminCors](../../configurations/medusa-config/page.mdx#http-adminCors-1-2) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> `http://localhost:7000,http://localhost:7001,http://localhost:5173` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`http://localhost:7000,http://localhost:7001,http://localhost:5173`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`AUTH_CORS`</Table.Cell>
|
||||
<Table.Cell>
|
||||
URLs of clients that can access the Medusa backend's authentication routes. Only used if [projectConfig.http.authCors](../../configurations/medusa-config/page.mdx#http-authCors-1-0) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> `http://localhost:7000,http://localhost:7001,http://localhost:5173` </Table.Cell>
|
||||
<Table.Cell>
|
||||
`http://localhost:7000,http://localhost:7001,http://localhost:5173`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`JWT_SECRET`</Table.Cell>
|
||||
<Table.Cell>
|
||||
A random string used to create authentication tokens in the http layer. Only used if [projectConfig.http.jwtSecret](../../configurations/medusa-config/page.mdx#http-jwtSecret-1-3) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`COOKIE_SECRET`</Table.Cell>
|
||||
<Table.Cell>
|
||||
`COOKIE_SECRET`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
A random string used to create cookie tokens in the http layer. Only used if [projectConfig.http.cookieSecret](../../configurations/medusa-config/page.mdx#http-cookieSecret-1-5) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`MEDUSA_BACKEND_URL`</Table.Cell>
|
||||
<Table.Cell>
|
||||
`MEDUSA_BACKEND_URL`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The URL to the Medusa backend. Only used if [admin.backendUrl](../../configurations/medusa-config/page.mdx#backendurl) isn't set in `medusa-config.ts`.
|
||||
</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`DB_HOST`</Table.Cell>
|
||||
<Table.Cell>The host for the database. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
|
||||
<Table.Cell>`localhost`</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`DB_USERNAME`</Table.Cell>
|
||||
<Table.Cell>The username for the database. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`DB_PASSWORD`</Table.Cell>
|
||||
<Table.Cell>The password for the database user. It's used when generating migrations for a plugin, and when running integration tests.</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`DB_TEMP_NAME`</Table.Cell>
|
||||
<Table.Cell>The database name to create for integration tests.</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`LOG_LEVEL`</Table.Cell>
|
||||
<Table.Cell>
|
||||
The allowed levels to log. Learn more in [this doumentation](../../debugging-and-testing/logging/page.mdx#log-levels).
|
||||
\-
|
||||
</Table.Cell>
|
||||
<Table.Cell>`silly`</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`LOG_FILE`</Table.Cell>
|
||||
<Table.Cell>
|
||||
The file to save logs in. By default, logs aren't saved in any file. Learn more in [this documentation](../../debugging-and-testing/logging/page.mdx).
|
||||
`DB_HOST`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The host for the database. It's used when generating migrations for a plugin, and when running integration tests.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
`localhost`
|
||||
</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>`MEDUSA_DISABLE_TELEMETRY`</Table.Cell>
|
||||
<Table.Cell>
|
||||
Whether to disable analytics data collection. Learn more in [this documentation](../../resources/usage/page.mdx).
|
||||
`DB_USERNAME`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The username for the database. It's used when generating migrations for a plugin, and when running integration tests.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
`DB_PASSWORD`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The password for the database user. It's used when generating migrations for a plugin, and when running integration tests.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
`DB_TEMP_NAME`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The database name to create for integration tests.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
`LOG_LEVEL`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The allowed levels to log. Learn more in the [Logging](../../debugging-and-testing/logging/page.mdx#log-levels) chapter.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
`silly`
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
`LOG_FILE`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
The file to save logs in. By default, logs aren't saved in any file. Learn more in the [Logging](../../debugging-and-testing/logging/page.mdx) chapter.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
</Table.Row>
|
||||
<Table.Row>
|
||||
<Table.Cell>
|
||||
`MEDUSA_DISABLE_TELEMETRY`
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
Whether to disable analytics data collection. Learn more in the [Usage](../../resources/usage/page.mdx) chapter.
|
||||
</Table.Cell>
|
||||
<Table.Cell>
|
||||
\-
|
||||
</Table.Cell>
|
||||
<Table.Cell> \- </Table.Cell>
|
||||
</Table.Row>
|
||||
</Table.Body>
|
||||
</Table>
|
||||
|
||||
Reference in New Issue
Block a user