The project's environment variable configuration is located in the application directory under `.env`, `.env.development`, `.env.production`.
The rules are consistent with [Vite Env Variables and Modes](https://vitejs.dev/guide/env-and-mode.html). The format is as follows:
```bash
.env # Loaded in all environments
.env.local # Loaded in all environments, but ignored by git
.env.[mode] # Only loaded in the specified mode
.env.[mode].local # Only loaded in the specified mode, but ignored by git
```
::: tip
- Only variables starting with `VITE_` will be embedded into the client-side package. You can access them in the project code like this:
```ts
console.log(import.meta.env.VITE_PROT);
```
- Variables starting with `VITE_GLOB_*` will be added to the `_app.config.js` configuration file during packaging. :::
:::
## Environment Configuration Description
::: code-group
```bash [.env]
# Application title
VITE_APP_TITLE=Vben Admin
# Application namespace, used as a prefix for caching, store, etc., to ensure isolation
VITE_APP_NAMESPACE=vben-web-antd
```
```bash [.env.development]
# Port Number
VITE_PORT=5555
# Public Path for Resources, must start and end with /
VITE_BASE=/
# API URL
VITE_GLOB_API_URL=/api
# Whether to enable Nitro Mock service, true to enable, false to disable
VITE_NITRO_MOCK=true
# Whether to open devtools, true to open, false to close
VITE_DEVTOOLS=true
# Whether to inject global loading
VITE_INJECT_APP_LOADING=true
```
:::
## Dynamic Configuration in Production Environment
When executing `pnpm build` in the root directory of the monorepo, a `dist/_app.config.js` file will be automatically generated in the corresponding application and inserted into `index.html`.
`_app.config.js` is a dynamic configuration file that allows for modifications to the configuration dynamically based on different environments after the project has been built. The content is as follows:
`_app.config.js` is used for projects that need to dynamically modify configurations after packaging, such as API endpoints. There's no need to repackage; you can simply modify the variables in `/dist/_app.config.js` after packaging, and refresh to update the variables in the code. A `js` file is used to ensure that the configuration file is loaded early in the order.
### Usage
To access the variables inside `_app.config.js`, you need to use the `useAppConfig` method provided by `@vben/hooks`.
To add a new dynamically modifiable configuration item, simply follow the steps below:
- First, add the variable that needs to be dynamically configurable in the `.env` file or the corresponding development environment configuration file. The variable must start with `VITE_GLOB_*`, for example:
The `useAppConfig` method should only be used within the application and not be coupled with the internals of a package. The reason for passing `import.meta.env` and `import.meta.env.PROD` is to avoid such coupling. A pure package should avoid using variables specific to a particular build tool.
:::
## Preferences
The project offers a wide range of preference settings for dynamically configuring various features of the project:
If you cannot find documentation for a setting, you can try configuring it yourself and then click `Copy Preferences` to override the project defaults. The configuration file is located in the application directory under `preferences.ts`, where you can override the framework's default configurations to achieve custom settings.
```ts
import { useAppConfig } from '@vben/hooks';
import { defineOverridesPreferences } from '@vben/preferences';
/**
*@description Project configuration file
* Only a part of the configuration in the project needs to be covered, and unnecessary configurations do not need to be covered. The default configuration will be automatically used
/** Whether to hide breadcrumbs when there is only one */
hideOnlyOne: boolean;
/** Whether the home icon in breadcrumbs is visible */
showHome: boolean;
/** Whether the icon in breadcrumbs is visible */
showIcon: boolean;
/** Breadcrumb style */
styleType: BreadcrumbStyleType;
}
interface CopyrightPreferences {
/** Copyright company name */
companyName: string;
/** Link to the copyright company's site */
companySiteLink: string;
/** Copyright date */
date: string;
/** Whether copyright is visible */
enable: boolean;
/** ICP number */
icp: string;
/** Link to the ICP */
icpLink: string;
}
interface FooterPreferences {
/** Whether the footer is visible */
enable: boolean;
/** Whether the footer is fixed */
fixed: boolean;
}
interface HeaderPreferences {
/** Whether the header is enabled */
enable: boolean;
/** Whether the header is hidden, css-hidden */
hidden: boolean;
/** Header display mode */
mode: LayoutHeaderModeType;
}
interface LogoPreferences {
/** Whether the logo is visible */
enable: boolean;
/** Logo URL */
source: string;
}
interface NavigationPreferences {
/** Navigation menu accordion mode */
accordion: boolean;
/** Whether the navigation menu is split, only effective in layout=mixed-nav */
split: boolean;
/** Navigation menu style */
styleType: NavigationStyleType;
}
interface SidebarPreferences {
/** Whether the sidebar is collapsed */
collapsed: boolean;
/** Whether to show title when sidebar is collapsed */
collapsedShowTitle: boolean;
/** Whether the sidebar is visible */
enable: boolean;
/** Menu auto-expand state */
expandOnHover: boolean;
/** Whether the sidebar extension area is collapsed */
extraCollapse: boolean;
/** Whether the sidebar is hidden - css */
hidden: boolean;
/** Sidebar width */
width: number;
}
interface ShortcutKeyPreferences {
/** Whether shortcut keys are enabled globally */
enable: boolean;
/** Whether the global lock screen shortcut is enabled */
globalLockScreen: boolean;
/** Whether the global logout shortcut is enabled */
globalLogout: boolean;
/** Whether the global preferences shortcut is enabled */
globalPreferences: boolean;
/** Whether the global search shortcut is enabled */
globalSearch: boolean;
}
interface TabbarPreferences {
/** Whether dragging of multiple tabs is enabled */
dragable: boolean;
/** Whether multiple tabs are enabled */
enable: boolean;
/** Tab height */
height: number;
/** Whether tab caching is enabled */
keepAlive: boolean;
/** Whether tabs are persistent */
persist: boolean;
/** Whether icons in multiple tabs are enabled */
showIcon: boolean;
/** Whether to show the maximize button */
showMaximize: boolean;
/** Whether to show the more button */
showMore: boolean;
/** Whether to show the refresh button */
showRefresh: boolean;
/** Tab style */
styleType: TabsStyleType;
}
interface ThemePreferences {
/** Built-in theme name */
builtinType: BuiltinThemeType;
/** Destructive color */
colorDestructive: string;
/** Primary color */
colorPrimary: string;
/** Success color */
colorSuccess: string;
/** Warning color */
colorWarning: string;
/** Current theme */
mode: ThemeModeType;
/** Radius */
radius: string;
/** Whether to enable semi-dark header (only effective when theme='light') */
semiDarkHeader: boolean;
/** Whether to enable semi-dark sidebar (only effective when theme='light') */
semiDarkSidebar: boolean;
}
interface TransitionPreferences {
/** Whether page transition animations are enabled */
enable: boolean;
// /** Whether page loading loading is enabled */
loading: boolean;
/** Page transition animation */
name: PageTransitionType | string;
/** Whether page loading progress animation is enabled */
progress: boolean;
}
interface WidgetPreferences {
/** Whether fullscreen widgets are enabled */
fullscreen: boolean;
/** Whether global search widget is enabled */
globalSearch: boolean;
/** Whether language switch widget is enabled */
languageToggle: boolean;
/** Whether lock screen functionality is enabled */
lockScreen: boolean;
/** Whether notification widget is displayed */
notification: boolean;
/** Whether sidebar show/hide widget is displayed */
sidebarToggle: boolean;
/** Whether theme switch widget is displayed */
themeToggle: boolean;
}
interface Preferences {
/** Global configuration */
app: AppPreferences;
/** Header configuration */
breadcrumb: BreadcrumbPreferences;
/** Copyright configuration */
copyright: CopyrightPreferences;
/** Footer configuration */
footer: FooterPreferences;
/** Breadcrumb configuration */
header: HeaderPreferences;
/** Logo configuration */
logo: LogoPreferences;
/** Navigation configuration */
navigation: NavigationPreferences;
/** Shortcut key configuration */
shortcutKeys: ShortcutKeyPreferences;
/** Sidebar configuration */
sidebar: SidebarPreferences;
/** Tab bar configuration */
tabbar: TabbarPreferences;
/** Theme configuration */
theme: ThemePreferences;
/** Animation configuration */
transition: TransitionPreferences;
/** Widget configuration */
widget: WidgetPreferences;
}
```
:::
::: warning Warning
- The `overridesPreferences` method only needs to override a part of the configurations in the project. There's no need to override configurations that are not needed; they will automatically use the default settings.
- Any configuration item can be overridden. You just need to override it within the `overridesPreferences` method. Do not modify the default configuration file.
