--- title: "Troubleshooting" description: "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." canonical_url: "https://docs.mhaibaraai.cn/en/docs/getting-started/troubleshooting" --- # Troubleshooting > 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 `@nuxt/ui` registers `@nuxt/fonts` automatically, and that 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: ```text [terminal] Could not fetch from https://fonts.google.com/metadata/fonts. Will retry in 1000ms. 3 retries left. ``` This theme already sets `ui.fonts: false` to disable that module, so you should not hit this warning. If you re-enabled it in your own `nuxt.config.ts`, turn it back off: ```typescript [nuxt.config.ts] export default defineNuxtConfig({ ui: { fonts: false } }) ``` Fonts are instead declared as `--font-sans` in the `@theme` block of `app/assets/css/main.css`, with the stylesheet loaded statically from `app.head.link` in `nuxt.config.ts` — all served straight from SSR. > [!WARNING] > > Chinese fonts are split by > > unicode-range > > , and a single family easily runs to hundreds of shards. Do not hand them to > > @nuxt/fonts > > — it downloads every shard into the build output at build time, losing both on-demand loading and the CDN cache shared across projects. ## 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`. > [!CAUTION] > > 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 ```bash pnpm install ``` #### Add any missing dependencies If you encounter "dependency not found" errors, add the missing packages to the `dependencies` field in `package.json`. > [!WARNING] > See: https://pnpm.io/npmrc#shamefully-hoist > > 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: ```bash 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: ```bash pnpm add @nuxt/ui ``` Then configure it in `nuxt.config.ts`: ```typescript [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`: ```typescript [nuxt.config.ts] export default defineNuxtConfig({ css: ['~/assets/css/main.css'] }) ``` ## Dependency installation issues ### Peer dependencies warning ```text WARN Issues with peer dependencies found ├─┬ @movk/nuxt-docs │ └── ✕ missing peer tailwindcss@4.x ``` > [!TIP] > > Install the missing peer dependency to resolve it: > > ```bash > 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
```bash 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: ```yaml [pnpm-workspace.yaml] onlyBuiltDependencies: - better-sqlite3 - sharp ``` Add the following to `package.json`: ```json [package.json] { "pnpm": { "onlyBuiltDependencies": [ "better-sqlite3", "sharp" ] } } ``` > [!NOTE] > > These settings only affect the development environment. The published package does not carry this configuration over, so consumers need to configure it themselves. > [!WARNING] > See: https://pnpm.io/settings#onlybuiltdependencies > > Learn more about build script approval ## Nitro prerendering issues ### unist-util-visit package not found ```text Cannot find package 'unist-util-visit' imported from .../prerender/chunks/nitro/nitro.mjs Did you mean to import "unist-util-visit/index.js"? ``` > [!WARNING] > > 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`: ```json [package.json] { "dependencies": { "unist-util-visit": "^5.1.0", "@nuxtjs/mdc": "^0.20.1" } } ``` Use `.npmrc` to hoist specific packages to the root: ```text [.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 ```text Error: No Output Directory named "dist" found after the Build completed. ``` 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. > [!CAUTION] > > 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: ```text FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory ``` Or: ```text At least one "Out of Memory" ("OOM") event was detected during the build. ``` > [!TIP] > > Increase the Node.js heap memory limit via `buildCommand` in `vercel.json`: > > ```json [vercel.json] > { > "buildCommand": "NODE_OPTIONS='--max-old-space-size=7168' pnpm run build", > "framework": null, > "installCommand": "pnpm install --frozen-lockfile" > } > ``` > [!NOTE] > > 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 ## Sitemap See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.