Module Configuration

View source

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.

nuxt.config.ts

export default defineNuxtConfig({
  movk: {
    prefix: 'My' // Components become MyAutoForm, MyDatePicker, etc.
  }
})

`Theme`

The theme module centrally manages colors, radius, fonts and icon sets, and provides options to the ThemePicker component and useTheme composable. All fields are configured under movk.theme.

Runtime capabilities of the theme system (dynamic switching, CSS export) are documented in the theme docs; for interactive tuning see the ThemePicker component.

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'.

fonts

ThemeFontConfig[]

ThemePicker font options; when provided, completely replaces the built-in list. Each item is { name, href? }, where href falls back to Google Fonts at runtime if omitted.

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 Options

nuxt.config.ts

export default defineNuxtConfig({
  movk: {
    theme: {
      fonts: [
        { name: 'Alibaba PuHuiTi', href: 'https://cdn.mhaibaraai.cn/fonts/alibaba-puhuiti.css' },
        { name: 'Inter' } // No href, falls back to Google Fonts
      ]
    }
  }
})

API

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

See the API docs for full usage of the API system.

Basic Configuration

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:

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',
          headers: {
            'X-API-Key': 'your-api-key'
          }
        }
      }
    }
  }
})

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.

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:

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
        }
      }
    }
  }
})

Auth Options

enabled

boolean

Whether to enable auth. Defaults to false.

tokenSource

'session'

Token source, retrieved from the nuxt-auth-utils session. 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'.

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.

`response`

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

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:

nuxt.config.ts

export default defineNuxtConfig({
  movk: {
    api: {
      toast: {
        // Enable notifications globally
        enabled: true,
        // Success notification config
        success: {
          show: true,
          color: 'success',
          duration: 3000
        },
        // 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 }

Success notification configuration.

error

Partial<Toast> & { show?: boolean }

Error notification configuration.

Configuration Priority

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

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

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

Environment Variables

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

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
          }
        }
      }
    }
  }
})

.env

EXTERNAL_API_URL=https://api.example.com
EXTERNAL_API_KEY=your-api-key

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

Installation

Install and configure the Movk Nuxt module in a Nuxt 4 project.

Vue / Vite

Use Movk standalone components, theming and composables in a plain Vue + Vite project without Nuxt.