import type { AgentTarget, SetupAgentsChange, SetupAgentsResult } from '@maz-ui/node' import type { Nuxt } from 'nuxt/schema' import type { MazUiNuxtOptions } from './types' import { createRequire } from 'node:module' import { dirname, join, resolve } from 'node:path' import process from 'node:process' import { fileURLToPath } from 'node:url' import { detectAgentTargets, findProjectPackage, readPackageVersion, resolveAgentDocsDir, setupAgents } from '@maz-ui/node' import { capitalize } from '@maz-ui/utils/helpers/capitalize' import { getErrorMessage } from '@maz-ui/utils/helpers/getErrorMessage' import { addCustomTab } from '@nuxt/devtools-kit' import { addComponent, addImports, addPlugin, addTemplate, createResolver, defineNuxtModule, resolvePath, useLogger, } from '@nuxt/kit' import { defu } from 'defu' import { renderTranslationsMessages, TRANSLATIONS_MESSAGES_TEMPLATE } from './translations-messages' type MazUiComposables = keyof typeof import('maz-ui/composables') type Composables = Omit< Record, 'useAos' | 'useDialog' | 'useToast' | 'useWait' | 'useMazIconProps' > declare module 'nuxt/schema' { interface NuxtConfig { mazUi?: MazUiNuxtOptions } interface NuxtOptions { mazUi: MazUiNuxtOptions } interface PublicRuntimeConfig { mazUi: Required> } } type ComponentNames = keyof typeof import('maz-ui/components') const COMPONENT_NAMES: Omit< Record, 'useMazDialogConfirm' | 'mazSidebarKey' > = { MazAccordion: true, MazAlert: true, MazAnimatedCounter: true, MazAnimatedElement: true, MazAnimatedText: true, MazAvatar: true, MazBackdrop: true, MazBadge: true, MazBottomSheet: true, MazBtn: true, MazBtnGroup: true, MazCard: true, MazCardSpotlight: true, MazCarousel: true, MazChart: true, MazCheckbox: true, MazChecklist: true, MazContainer: true, MazCircularProgressBar: true, MazCodeHighlight: true, MazDialog: true, MazDialogConfirm: true, MazDrawer: true, MazDropdown: true, MazDropzone: true, MazExpandAnimation: true, MazFullscreenLoader: true, MazGallery: true, MazIcon: true, MazInput: true, MazInputCode: true, MazInputNumber: true, MazInputPhoneNumber: true, MazInputPrice: true, MazInputTags: true, MazLazyImg: true, MazLink: true, MazLoadingBar: true, MazMarkdownEditor: true, MazPagination: true, MazDatePicker: true, MazPullToRefresh: true, MazRadio: true, MazRadioButtons: true, MazReadMore: true, MazReadingProgressBar: true, MazSelect: true, MazSelectCountry: true, MazSkeleton: true, MazSlider: true, MazSpinner: true, MazStepper: true, MazSwitch: true, MazSidebar: true, MazSidebarMenu: true, MazSidebarMenuItem: true, MazSidebarMenuSub: true, MazSidebarFooter: true, MazSidebarHeader: true, MazSidebarContent: true, MazSidebarGroup: true, MazSidebarMenuButton: true, MazSidebarSeparator: true, MazSidebarTrigger: true, MazTable: true, MazTableCell: true, MazTableRow: true, MazTableTitle: true, MazTabs: true, MazTabsBar: true, MazTabsContent: true, MazTabsContentItem: true, MazTicker: true, MazTimeline: true, MazTextarea: true, MazUiProvider: true, MazWindowMockup: true, MazPopover: true, } const _dirname = dirname(fileURLToPath(import.meta.url)) const pluginComposables: Record<'useTheme' | 'useTranslations', true> = { useTheme: true, useTranslations: true, } const mazUiComposables: Omit, 'useAos' | 'useDialog' | 'useToast' | 'useWait' | 'useMazIconProps'> = { useIdleTimeout: true, useDrag: true, useReadingTime: true, useFormField: true, useWindowSize: true, useBreakpoints: true, useUserVisibility: true, useStringMatching: true, useTimer: true, useFormValidator: true, useDisplayNames: true, useFreezeValue: true, useInjectStrict: true, useDropzone: true, useInstanceUniqId: true, useMountComponent: true, useSwipe: true, usePullToRefresh: true, useMutationObserver: true, useSidebar: true, } const defaults = { general: { autoImportPrefix: '', defaultMazIconPath: '', devtools: true, preventIosInputZoom: false, }, css: { injectCss: true, }, theme: { preset: 'maz-ui', strategy: 'runtime', darkModeStrategy: 'class', colorMode: 'auto', mode: 'both', }, translations: { locale: 'en', fallbackLocale: 'en', preloadFallback: true, }, defaults: {}, flags: 'cdn', components: { autoImport: true, }, plugins: { aos: false, dialog: false, toast: false, wait: false, }, composables: { ...pluginComposables, ...mazUiComposables, } satisfies Composables, directives: { vZoomImg: false, vLazyImg: false, vClickOutside: false, vFullscreenImg: false, vTooltip: false, }, agents: { rules: false, mcp: false, }, } satisfies Required function formatAgentsLog(applied: SetupAgentsChange[], result: SetupAgentsResult, options: { rules: boolean, mcp: boolean, requestedTargets?: AgentTarget[] }): string { const files = applied.map(change => [change.file, `(${change.action})`].join(' ')).join(', ') const messages = [`AI agents configured for maz-ui: ${files}.`] // An explicit target list is a choice: AGENTS.md is only suggested for the detected agents if (options.rules && !options.requestedTargets && !result.targets.includes('agents-md')) { const suggestedTargets = [...result.targets, 'agents-md'].map(target => ['\'', target, '\''].join('')).join(', ') messages.push(`AGENTS.md not written: no agent that reads it was detected (Cursor, Copilot, Codex, Windsurf, Gemini CLI, Zed...). If your team uses one, set mazUi.agents.targets: [${suggestedTargets}].`) } if (options.mcp && !result.localMcpServer) messages.push('The MCP server runs through npx: add @maz-ui/mcp to the devDependencies of the project root to start it in about a second, at the version of your lockfile.') return messages.join(' ') } /** Version of the `@maz-ui/mcp` installed for the app, pinned in the `npx` command when the project root does not install it */ function installedMcpVersion(rootDir: string): string | undefined { const mcpDir = findProjectPackage(rootDir, '@maz-ui/mcp') return mcpDir ? readPackageVersion(mcpDir) : undefined } /** Version of the maz-ui that Node.js resolves from a file, `undefined` when it does not resolve */ function resolveMazUiVersion(from: string): string | undefined { try { return readPackageVersion(dirname(createRequire(from).resolve('maz-ui/package.json'))) } catch { return undefined } } /** * The plugins of the module import the maz-ui of the module, the auto-imported components and composables the maz-ui * of the app: two versions are two copies, and the components of one do not see the defaults provided by the other */ function checkMazUiVersion(rootDir: string | undefined) { if (!rootDir) return const appVersion = resolveMazUiVersion(join(rootDir, 'package.json')) const moduleVersion = resolveMazUiVersion(import.meta.url) if (appVersion && moduleVersion && appVersion !== moduleVersion) { useLogger('maz-ui').warn(`The app installs maz-ui ${appVersion} and @maz-ui/nuxt uses maz-ui ${moduleVersion}: two copies of maz-ui are loaded, and the options of the module (\`mazUi.general\`, \`mazUi.plugins\`...) may not apply to the components. Install the same version of maz-ui and @maz-ui/nuxt.`) } } function syncAgents(agents: MazUiNuxtOptions['agents'], nuxt: Nuxt) { if (!agents || !(nuxt.options.dev || nuxt.options._prepare) || process.env.CI || nuxt.options.test) { return } const logger = useLogger('@maz-ui/mcp') try { const { rootDir, workspaceDir } = nuxt.options const { targets: requestedTargets, rules = true, mcp = true, dir, paths } = typeof agents === 'object' ? agents : {} // In a monorepo, the agents start at the workspace root, not in the Nuxt app const projectDir = dir ? resolve(rootDir, dir) : (workspaceDir || rootDir) const targets = requestedTargets ?? detectAgentTargets(projectDir) if (targets.length === 0 || (!rules && !mcp)) return const mazUiDir = findProjectPackage(rootDir, 'maz-ui') const result = setupAgents({ rootDir: projectDir, targets, rules, mcp, paths, mcpVersion: installedMcpVersion(rootDir), ...(mazUiDir ? { docsDir: resolveAgentDocsDir(mazUiDir), } : {}), }) const applied = result.changes.filter(change => ['create', 'update', 'remove'].includes(change.action)) if (applied.length > 0) { logger.info(formatAgentsLog(applied, result, { rules, mcp, requestedTargets })) } } catch (error) { logger.warn(`Could not configure the AI agents for maz-ui: ${getErrorMessage(error)}`) } } function addMazUiComposableImport({ name, from, prefix = '', }: { name: string from: string prefix: string }) { addImports({ from, name, as: `use${capitalize(prefix)}${name.replace('use', '')}`, }) } export default defineNuxtModule({ meta: { name: 'maz-ui', configKey: 'mazUi', compatibility: { nuxt: '>=3.4.0 <5.0.0', }, }, defaults, /* eslint-disable complexity, sonarjs/cognitive-complexity */ setup(options, nuxt) { const { resolve } = createResolver(import.meta.url) nuxt.options.build.transpile.push('maz-ui', '@maz-ui/themes', '@maz-ui/translations') checkMazUiVersion(nuxt.options.rootDir) const { agents, ...moduleOptions } = defu( nuxt.options.runtimeConfig.public.mazUi, options, defaults, ) // The messages go through a template, not the runtime config (serialized in the payload of every page) const { messages: translationsMessages, ...translationsOptions } = moduleOptions.translations ?? {} moduleOptions.translations = translationsOptions nuxt.options.runtimeConfig.public.mazUi = moduleOptions addTemplate({ filename: TRANSLATIONS_MESSAGES_TEMPLATE, getContents: () => renderTranslationsMessages( translationsMessages, path => resolvePath(path), message => useLogger('maz-ui').warn(message), ), }) // AI agents syncAgents(agents, nuxt) // CSS if (moduleOptions.css.injectCss) { nuxt.options.css.unshift('maz-ui/style.css') } // cssnano's `postcss-calc` cannot parse the relative OKLCh values maz-ui // emits (`oklch(from X clamp(0, calc(l - .05), 1) c h)`) and floods // production builds with harmless "Lexical error" warnings. Disable only // its `calc` optimization; the rest of the minification is untouched. Left // alone if the user explicitly disabled cssnano. nuxt.options.postcss ??= { plugins: {}, order: [] } nuxt.options.postcss.plugins ??= {} const postcssPlugins = nuxt.options.postcss.plugins if (postcssPlugins.cssnano !== false) { const current = typeof postcssPlugins.cssnano === 'object' && postcssPlugins.cssnano !== null ? postcssPlugins.cssnano : {} postcssPlugins.cssnano = { ...current, preset: [ 'default', { calc: false }, ], } } // Plugins addPlugin(resolve(_dirname, './runtime/plugins/theme')) addPlugin(resolve(_dirname, './runtime/plugins/translations')) addPlugin(resolve(_dirname, './runtime/plugins/maz-link-component')) // Flags: a URL template is a plain default, the local flags need their loader (only imported by this plugin) const flags = moduleOptions.flags if (flags && flags !== 'cdn' && flags !== 'local') { moduleOptions.defaults = { ...moduleOptions.defaults, global: { flagSrc: flags, ...moduleOptions.defaults.global }, } } if (flags === 'local') { addPlugin(resolve(_dirname, './runtime/plugins/local-flags')) } else if (Object.keys(moduleOptions.defaults).length > 0) { addPlugin(resolve(_dirname, './runtime/plugins/defaults')) } // Components if (moduleOptions.components.autoImport) { for (const name of Object.keys(COMPONENT_NAMES)) { addComponent({ name, filePath: `maz-ui/components/${name}`, }) } } // Plugins const autoImportPrefix = moduleOptions.general.autoImportPrefix if (moduleOptions.plugins.aos) { addPlugin(resolve(_dirname, './runtime/plugins/aos')) addImports({ name: 'useAos', from: resolve(_dirname, './runtime/composables/useAos'), as: `use${capitalize(autoImportPrefix)}Aos`, }) const injectAosCSS = typeof moduleOptions.plugins.aos === 'object' && typeof moduleOptions.plugins.aos.injectCss === 'boolean' ? moduleOptions.plugins.aos.injectCss : true if (injectAosCSS) { nuxt.options.css = ['maz-ui/aos.css', ...nuxt.options.css] } } if (moduleOptions.plugins.toast) { addPlugin(resolve(_dirname, './runtime/plugins/toast')) addImports({ name: 'useToast', from: resolve(_dirname, './runtime/composables/useToast'), as: `use${capitalize(autoImportPrefix)}Toast`, }) } if (moduleOptions.plugins.dialog) { addPlugin(resolve(_dirname, './runtime/plugins/dialog')) addImports({ name: 'useDialog', from: resolve(_dirname, './runtime/composables/useDialog'), as: `use${capitalize(autoImportPrefix)}Dialog`, }) } if (moduleOptions.plugins.wait) { addPlugin(resolve(_dirname, './runtime/plugins/wait')) addImports({ name: 'useWait', from: resolve(_dirname, './runtime/composables/useWait'), as: `use${capitalize(autoImportPrefix)}Wait`, }) } // Directives if (moduleOptions.directives.vZoomImg) { addPlugin(resolve(_dirname, './runtime/plugins/v-zoom-img')) } if (moduleOptions.directives.vLazyImg) { addPlugin(resolve(_dirname, './runtime/plugins/v-lazy-img')) } if (moduleOptions.directives.vClickOutside) { addPlugin(resolve(_dirname, './runtime/plugins/v-click-outside')) } if (moduleOptions.directives.vFullscreenImg) { addPlugin(resolve(_dirname, './runtime/plugins/v-fullscreen-img')) } if (moduleOptions.directives.vTooltip) { addPlugin(resolve(_dirname, './runtime/plugins/v-tooltip')) } // Composables const allowedMazUiComposables = Object.keys(moduleOptions.composables).filter(composable => mazUiComposables[composable as keyof typeof mazUiComposables]) for (const composable of allowedMazUiComposables) { addMazUiComposableImport({ name: composable, from: `maz-ui/composables/${composable}`, prefix: autoImportPrefix, }) } if (moduleOptions.composables.useTheme) { addImports({ name: 'useTheme', from: '@maz-ui/themes', as: `use${capitalize(autoImportPrefix)}Theme`, }) } if (moduleOptions.composables.useTranslations) { addImports({ name: 'useTranslations', from: '@maz-ui/translations', as: `use${capitalize(autoImportPrefix)}Translations`, }) } // Maz Icon Path if (moduleOptions.general.defaultMazIconPath) { addPlugin(resolve(_dirname, './runtime/plugins/maz-icon-path')) } // iOS input zoom if (moduleOptions.general.preventIosInputZoom) { addPlugin(resolve(_dirname, './runtime/plugins/prevent-ios-input-zoom.client')) } // Devtools if (moduleOptions.general.devtools) { addCustomTab({ name: 'maz-ui', title: 'maz-ui', icon: 'https://maz-ui.com/img/icons/android-chrome-512x512.png', view: { type: 'iframe', src: 'https://maz-ui.com', }, }) } }, })