Troubleshooting

View source

Resolve common issues you may run into when using Movk Nuxt Docs, including Google Fonts access, removing the pnpm shamefully-hoist setting, installing Tailwind CSS as a peer dependency, approving build scripts, and Vercel deployment OOM (out-of-memory) errors, with detailed solutions.

Font loading issues

Google Fonts not accessible in certain network environments

The @nuxt/fonts module fetches font metadata from fonts.google.com by default. In a network environment where Google is not accessible, the following warning appears when the dev server starts:

terminal

Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left.

Fix: switch the font provider to bunny (a privacy-friendly, Google Fonts–compatible alternative):

nuxt.config.ts

export default defineNuxtConfig({
  fonts: {
    families: [
      { name: 'Public Sans', global: true, provider: 'bunny' }
    ]
  }
})

@nuxt/fonts supports multiple font providers. See the official documentation for details.

pnpm and .npmrc configuration issues

shamefully-hoist removed

Starting from v1.10.0, the project no longer includes the shamefully-hoist=true setting in .npmrc.

shamefully-hoist hoists all dependencies to the root of node_modules, breaking pnpm's strict dependency isolation. This can lead to accidental access to undeclared dependencies, version conflicts, and unstable builds.

Delete `.npmrc`

Delete the .npmrc file in your project (if it exists).

Reinstall dependencies

pnpm install

Add any missing dependencies

If you encounter "dependency not found" errors, add the missing packages to the dependencies field in package.json.

See the official pnpm documentation to learn more about shamefully-hoist

Tailwind CSS as a peer dependency

Tailwind CSS has been moved from a direct dependency to peerDependencies, so theme users need to install it manually:

pnpm add -D tailwindcss

Styling customization issues

Custom CSS configuration

~~Starting from v1.10.0, app/assets/css/main.css is no longer required~~. If you need custom styles:

You need to install @nuxt/ui first:

pnpm add @nuxt/ui

Then configure it in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    // Custom theme configuration
  }
})

Add global styles in app/assets/css/main.css and reference it in nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  css: ['~/assets/css/main.css']
})

Dependency installation issues

Peer dependencies warning

Install the missing peer dependency to resolve it:

pnpm add -D tailwindcss@^4.1.0

Build script approval

Starting from pnpm v10, dependency lifecycle scripts (such as postinstall) are not run by default. This project requires approval for the following dependencies that include native modules:

Package	Purpose	Required
`better-sqlite3`	SQLite database (used by the MCP server)	Yes
`sharp`	Image processing (used by @nuxt/image)	Yes

pnpm approve-builds

Select the packages listed above from the list to approve them.

Add the following to pnpm-workspace.yaml in the project root:

pnpm-workspace.yaml

onlyBuiltDependencies:
  - better-sqlite3
  - sharp

Add the following to package.json:

package.json

{
  "pnpm": {
    "onlyBuiltDependencies": [
      "better-sqlite3",
      "sharp"
    ]
  }
}

These settings only affect the development environment. The published package does not carry this configuration over, so consumers need to configure it themselves.

Learn more about build script approval

Nitro prerendering issues

unist-util-visit package not found

The LLMs integration in @nuxt/content dynamically imports unist-util-visit via import("unist-util-visit") when Nitro prerenders /llms-full.txt. pnpm's strict dependency isolation means the Nitro output directory (docs/node_modules/.cache/) cannot resolve a package that only exists in the layer's dependency chain.

Explicitly declare the missing runtime dependencies in the consumer project's package.json:

package.json

{
  "dependencies": {
    "unist-util-visit": "^5.1.0",
    "@nuxtjs/mdc": "^0.20.1"
  }
}

Use .npmrc to hoist specific packages to the root:

.npmrc

public-hoist-pattern[]=unist-util-visit
public-hoist-pattern[]=@nuxtjs/mdc

After adding it, run pnpm install for the configuration to take effect.

Vercel deployment issues

Output Directory not found

This error is usually not an output directory configuration problem. When Nuxt builds with the vercel preset, Nitro automatically generates the .vercel/output/ directory (in the Vercel Build Output API format), which Vercel recognizes automatically, so there is no need to configure outputDirectory manually.

The most common cause of this error is running out of memory (OOM) during the build, which leaves .vercel/output/ incomplete, so Vercel falls back to looking for the default dist directory.

You can confirm whether it is an OOM by looking at the end of the Vercel build log:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Or:

At least one "Out of Memory" ("OOM") event was detected during the build.

Increase the Node.js heap memory limit via buildCommand in vercel.json:

vercel.json

{
  "buildCommand": "NODE_OPTIONS='--max-old-space-size=7168' pnpm run build",
  "framework": null,
  "installCommand": "pnpm install --frozen-lockfile"
}

The build container for Vercel's Hobby plan has 8 GB of memory, while Node.js's default heap limit is about 4 GB. Setting --max-old-space-size=7168 (7 GB) provides ample memory for the Nitro build and prerendering.

If you still hit OOM after increasing memory, consider:

Upgrading to the Vercel Pro plan for a larger build container
Reducing the number of prerendered routes

Internationalization

Movk Nuxt Docs ships built-in multilingual support powered by @nuxtjs/i18n with an opt-in design. Without configuration it runs single-language; once configured it enables localized routing, per-locale content collections, a language switcher, and multilingual SEO.

Configure your documentation site

A complete reference for customizing SEO metadata, header navigation, footer credits, sidebar navigation filtering, and the AI Chat interface via app.config.ts, as well as configuring module-level options such as GitHub integration, component metadata generation, Mermaid diagrams, and accessibility via nuxt.config.ts.