---
title: "Module Configuration"
description: "Configure component prefix, theme colors, fonts, API endpoints, auth strategy, response parsing rules and Toast notification behavior."
canonical_url: "https://nuxt.mhaibaraai.cn/en/docs/getting-started/configuration"
---
# Module Configuration

> Configure component prefix, theme colors, fonts, API endpoints, auth strategy, response parsing rules and Toast notification behavior.

## Introduction

Movk Nuxt uses `movk` as the configuration key in `nuxt.config.ts`:

## `Prefix`

- **Type**: `string`
- **Default**: `'M'`

Component prefix, used to avoid naming conflicts with other component libraries.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    prefix: 'My' // Components become MyAutoForm, MyDatePicker, etc.
  }
})
```

## `Theme`

The theme module centrally manages colors, radius, icon sets and fonts. The first three provide options to the `ThemePicker` component and `useTheme` composable, while the font is injected at build time. All fields are configured under `movk.theme`.

> [!NOTE]
> See: /docs/getting-started/theme
> 
> Runtime capabilities of the theme system (dynamic switching, CSS export) are documented in the theme docs; for interactive tuning see the 
> 
> ThemePicker
> 
>  component.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    theme: {
      enabled: true
    }
  }
})
```

**enabled** (`boolean`): Whether to enable the theme module (appConfig defaults, theme plugin, ThemePicker component registration). Defaults to true. When disabled, ThemePicker is no longer registered.

**colors** (`string[]`): List of color aliases available to components, passed through to @nuxt/ui's theme.colors. Defaults to ['primary', 'secondary', 'success', 'info', 'warning', 'error'].

**defaultVariants** (`object`): Component default variants, passed through to @nuxt/ui's theme.defaultVariants.

**prefix** (`string`): Tailwind CSS utility class prefix, passed through to @nuxt/ui's theme.prefix. For example 'tw'.

**font** (`string | ThemeFontOption`): Global font. For built-in fonts the name is enough ('Alibaba PuHuiTi', 'OPPO Sans') and the module injects the stylesheet, a preconnect and a --font-sans carrying the Chinese fallback stack at build time; for self-hosted fonts use the { name, href } form to supply the stylesheet URL. When omitted, --font-sans is not injected and the font is controlled entirely by your project's CSS @theme.Font name, which must match the font-family declared by @font-face in the stylesheet character for character.URL of the font's entry CSS. For example '/fonts/my-font.css'. Optional for built-in fonts. A font that is neither built in nor given this field triggers no request at all.

**radius** (`number`): Default radius (in rem). When omitted, --ui-radius is not injected and the @nuxt/ui default or your project CSS applies. For example 0.5.

**radiuses** (`number[]`): ThemePicker radius options (in rem). Defaults to [0, 0.125, 0.25, 0.375, 0.5].

**neutralColors** (`string[]`): ThemePicker neutral color options.

### Custom Font

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    theme: {
      // Built-in fonts only need the name
      font: 'Alibaba PuHuiTi'
      // Self-hosted fonts supply the entry CSS URL
      // font: { name: 'My Font', href: '/fonts/my-font.css' }
    }
  }
})
```

## `Icon`

Controls whether the module's own icons enter the `@nuxt/icon` build-time bundle.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    icon: {
      clientBundle: true
    }
  }
})
```

**clientBundle** (`boolean`): Whether to inject the icons used by movk components and the built-in icon sets into the build-time bundle. Defaults to true. When disabled, those icons are fetched on demand at runtime.

> [!NOTE]
> See: /docs/getting-started/theme
> 
> See Theme · Icon Sets for switching icon sets and installing the 
> 
> @iconify-json/*
> 
>  packages.

## API

The API system provides complete request wrapping and auth management, configured via the `api` option.

> [!NOTE]
> See: /docs/api
> 
> See the API docs for full usage of the API system.

### Basic Configuration

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      // Whether to enable API functionality
      enabled: true,
      // Default endpoint name
      defaultEndpoint: 'default',
      // Whether to enable debug mode
      debug: false
    }
  }
})
```

**enabled** (`boolean`): Whether to enable API functionality. Defaults to true.

**defaultEndpoint** (`string`): Default endpoint name. Defaults to 'default'.

**debug** (`boolean`): Whether to enable debug mode; when enabled, request logs are printed to the console. Defaults to false.

### `endpoints`

Supports configuring multiple API endpoints, each with its own independent configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      endpoints: {
        // Default endpoint
        default: {
          baseURL: '/api'
        },
        // Admin endpoint
        admin: {
          baseURL: '/admin-api',
          auth: {
            tokenType: 'Bearer'
          }
        },
        // Third-party API
        external: {
          baseURL: 'https://api.example.com',
          // Injected on the server only
          headers: {
            'X-Secret-Key': process.env.EXTERNAL_SECRET_KEY
          },
          // Injected on both server and client
          publicHeaders: {
            'X-Api-Version': '2'
          }
        }
      }
    }
  }
})
```

#### Endpoint Options

**baseURL** (`string`) *required*: Base URL of the endpoint.

**alias** (`string`): Endpoint alias.

**headers** (`Record<string, string>`): Default request headers for this endpoint. Server-side only; not exposed to the client.

**publicHeaders** (`Record<string, string>`): Public request headers for this endpoint. Stored in the public runtimeConfig and injected on both server and client. Keys of the same name are overridden by headers. Use for non-secret constant headers only.

**auth** (`Partial<ApiAuthConfig>`): Auth configuration for this endpoint, merged with the global config.

**toast** (`Partial<ApiToastConfig>`): Toast configuration for this endpoint, merged with the global config.

**response** (`Partial<ApiResponseConfig>`): Response configuration for this endpoint, merged with the global config.

### `auth`

Configure automatic auth behavior, integrated with `nuxt-auth-utils`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      auth: {
        // Enable auth
        enabled: true,
        // Token source
        tokenSource: 'session',
        // Path to token in session
        sessionTokenPath: 'user.accessToken',
        // Token type
        tokenType: 'Bearer',
        // Header name
        headerName: 'Authorization',
        // 401 unauthorized handling config
        unauthorized: {
          // Redirect to login page on 401
          redirect: true,
          loginPath: '/login',
          // Clear session on 401
          clearSession: true
        }
      }
    }
  }
})
```

When calling a third-party API directly from the browser, put the credential in `runtimeConfig.public` and point at it:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      llmApiKey: ''
    }
  },
  movk: {
    api: {
      auth: {
        enabled: true,
        tokenSource: 'public-runtime-config',
        tokenPath: 'llmApiKey',
        tokenType: 'Bearer',
        unauthorized: {
          redirect: false
        }
      }
    }
  }
})
```

```bash [.env]
NUXT_PUBLIC_LLM_API_KEY=your-api-key
```

> [!WARNING]
> 
> Values from 
> 
> public-runtime-config
> 
>  and 
> 
> publicHeaders
> 
>  are shipped to the browser along with the page, and any visitor can read them. Use them only when the credential is designed to be public, or its scope is narrow enough to accept the exposure. Account-level keys belong behind a server-side proxy.

#### Auth Options

**enabled** (`boolean`): Whether to enable auth. Defaults to false.

**tokenSource** (`'session' | 'public-runtime-config'`): Token source. 'session' retrieves it from the nuxt-auth-utils session; 'public-runtime-config' retrieves it from runtimeConfig.public, for credentials that are meant to be exposed in the browser. Defaults to 'session'.

**sessionTokenPath** (`string`): Path to the token in the session. For example 'token' maps to session.token, 'user.token' maps to session.user.token. Defaults to 'token'.

**tokenPath** (`string`): Path to the token in runtimeConfig.public, dot-notation supported. Only applies when tokenSource is 'public-runtime-config'. Defaults to 'apiToken'.

**tokenType** (`'Bearer' | 'Basic' | 'Custom'`): Token type. Defaults to 'Bearer'.

**customTokenType** (`string`): Custom token type value, used when tokenType is 'Custom'.

**headerName** (`string`): Header name. Defaults to 'Authorization'.

**unauthorized** (`ApiUnauthorizedConfig`): Configuration for handling 401 unauthorized errors.Whether to automatically redirect to the login page on a 401 error. Defaults to true.Login page path. Defaults to '/login'.Whether to automatically clear the session on a 401 error. Defaults to true.

### `response`

Configure API response parsing rules, including business status code determination, data unwrapping fields and message extraction:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      response: {
        // Successful status code list
        successCodes: [200, 0],
        // Status code field name
        codeKey: 'code',
        // Message field name
        messageKey: 'message',
        // Data field name
        dataKey: 'data'
      }
    }
  }
})
```

#### Response Configuration Options

**successCodes** (`(number | string)[]`): Successful status code list; a code value in the response is considered successful if it is in this list. Defaults to [200, 0].

**codeKey** (`string`): Field name for the status code in the response. Defaults to 'code'.

**messageKey** (`string`): Field name for the message in the response. Defaults to 'message'.

**dataKey** (`string`): Field name for the data in the response. Defaults to 'data'.

### `toast`

Configure global Toast notification behavior:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      toast: {
        // Enable notifications globally
        enabled: true,
        // Success notification config
        success: {
          show: true,
          color: 'success',
          duration: 3000,
          // Only notify on mutating requests, stay quiet on GET
          methods: ['POST', 'PUT', 'PATCH', 'DELETE']
        },
        // Error notification config
        error: {
          show: true,
          color: 'error',
          duration: 3000
        }
      }
    }
  }
})
```

#### Toast Options

**enabled** (`boolean`): Whether to enable notifications globally. Defaults to true.

**success** (`Partial<Toast> & { show?: boolean, methods?: string[] }`): Success notification configuration. show: false disables it; methods restricts it to the listed HTTP methods (case-insensitive), and omitting the field means no restriction.

**error** (`Partial<Toast> & { show?: boolean, methods?: string[] }`): Error notification configuration. show: false disables it; methods works the same way, and is usually left unset so errors surface on every method.

> [!NOTE]
> 
> enabled
> 
> , 
> 
> show
> 
>  and 
> 
> methods
> 
>  are all global-level switches that a single request can override. Precedence: request-level 
> 
> show
> 
>  > request-level 
> 
> successMessage
> 
>  / 
> 
> errorMessage
> 
>  > global 
> 
> success.show
> 
>  / 
> 
> error.show
> 
>  / 
> 
> methods
> 
>  > global 
> 
> enabled
> 
> . So when a toast is globally disabled or the method misses the whitelist, both 
> 
> toast: { success: { show: true } }
> 
>  and 
> 
> toast: { successMessage: 'Saved' }
> 
>  still show it.

> [!TIP]
> 
> methods
> 
>  only belongs in the global or endpoint config — a single request has exactly one method, so request-level 
> 
> toast
> 
>  does not accept the field. An endpoint-level 
> 
> methods
> 
>  replaces the global one instead of merging the arrays.

## Configuration Priority

Configuration is merged in the following priority order (later overrides earlier):

1. **Module built-in defaults** - Default config defined in `api-defaults.ts`
2. **Global config** - `movk.api.auth`, `movk.api.toast`, `movk.api.response`
3. **Endpoint config** - `movk.api.endpoints[name].auth`, etc.
4. **Request-level config** - `toast` option in `useApiFetch`, etc.

```ts
// Example: request-level config overrides global config
const { data } = await useApiFetch('/users', {
  toast: {
    successMessage: 'Fetched successfully', // Overrides global config
    error: false // Disable error notifications
  }
})
```

Request headers are layered in the following order (later overrides earlier):

1. **Endpoint publicHeaders** - Injected on both server and client
2. **Endpoint headers** - Injected on the server only, overrides matching `publicHeaders` keys
3. **Request-level headers** - Passed to `$api` or `useApiFetch`
4. **Auth injection** - Written by the `onRequest` interceptor under `headerName`, highest priority

## Environment Variables

For sensitive configuration (such as API keys), use environment variables:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  movk: {
    api: {
      endpoints: {
        external: {
          baseURL: process.env.EXTERNAL_API_URL,
          headers: {
            'X-API-Key': process.env.EXTERNAL_API_KEY
          }
        }
      }
    }
  }
})
```

```bash [.env]
EXTERNAL_API_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key
```

> [!WARNING]
> 
> Never write sensitive information (such as API keys or passwords) directly in configuration files; always use environment variables.


## Sitemap

See the full [sitemap](https://nuxt.mhaibaraai.cn/sitemap.md) for all pages.